Dead-code audit: findings + cleanup tracker

[Aybook]

Tracker for the dead-code audit (2026-07-16). Scope decided up front: our code only (core/, scripts/, hub/hub.c, build glue) — vendored deps (lua/, luasocket/, luasec/, …) are report-only. Conservative on contract surface: anything in docs/PLUGIN_API.md or core/scripts.lua's SANDBOX_GLOBALS stays even if unused internally, because third-party hubowner plugins we never see can reach it.

Method: 10 parallel agents on disjoint axes, then main-thread synthesis. Every finding below is file:line-anchored; each still needs re-derivation from source before removal (§1a.4) — the audit already produced three wrong calls, see "Lessons" at the bottom.

Already fixed (the audit's real yield so far)

These were not dead code — they fell out while looking:

• fix(ci): install zlib dev package on all three release legs #441 — release.yml installed zlib dev on no leg while find_package(ZLIB REQUIRED) is unconditional. The first v3.2.0 tag would have failed the aarch64 build at configure. Merged.
• fix(scripts): resolve plugin lang lookups; guard the class repo-wide #442 — etc_cmdlog read lang.failmsg1/2, keys are msg_denied/msg_nofile → German hubs saw English. Second instance of the class, so the guard is now repo-wide (tests/unit/plugin_lang_test.lua, 68 plugins). Found a third (cmd_delreg). Merged.
• fix(cmd_ban): reject a bantime below 1 instead of silently losing the ban #443 — +ban nick X -5 stored bantime = -300, the login expiry check pruned it → target kicked once, walked back in, while help promised "ban forever". Merged.
• hub_runtime: total runtime resets on every upgrade (mutable state lives in core/hci.lua) #445 — core/hci.lua is mutable state under shipped core/ → every upgrade zeroes the hub's lifetime runtime counter. Open.
• docs: correct hci, the event-loop backend, and the logsafe cross-reference #446 — doc currency: hci mislabelled a dormant module; select() described as the loop after Hub event loop hits FD_SETSIZE=1024 Linux limit (select -> poll port) #310; HTTP_API.md cited http.lua:logsafe (caps at 80, zero callers) for the 512-byte truncation actually done by http_router.lua:logsafe_body. Merged.
• feat(cmd_ban): permanent ban via "+ban nick <NICK> permanent" #444 — permanent-ban feature (+ban nick X permanent), raised while fixing fix(cmd_ban): reject a bantime below 1 instead of silently losing the ban #443. Open.

---

PR 1 — core/hub.lua dead file-scope locals (highest value)

Why first: hub.lua's main chunk sits at Lua's 200-local cap, and CLAUDE.md §3 therefore freezes file-scope locals ("any new top-level local fails the build"). These 19 are declared and never used — removing them frees 19 slots and un-freezes the file. Smallest diff, biggest structural win.

Declared-and-never-referenced (each verified whole-file, matches are the declaration plus comment prose only):

Line	Local	Note
167	tablesize	last consumer was the PING UC field; #179 replaced it
177	loadfile
183	io
194	table_concat	hub_user_object has its own
211	adclib_hash	moved to hub_dispatch (Phase 6d)
214	adclib_hashpas	"
217	adclib_createsalt	"
218	adclib_hasholdpas	"
269	types_check	types.add / types_utf8 are separate and live
272	util_difftime	moved to hub_dispatch
305	killuser	never assigned; body is the commented block at 1120-1158
310	usercount	never assigned — see below
322	isuseronline	assigned at 1025, never called
336-339	_verify, _normal, _protocol, _identify	never assigned; the four state tables live in hub_dispatch since Phase 6d
342	_G	trap, see below
394	_cfg_nick_change	never assigned/read. The nick_change FEATURE is live (cfg key read by cmd_nickchange / hub_inf_manager) — only hub.lua's stale cache slot is dead

_G removal trap (would be a #353-class boot crash): local _G (342) + _G = _G (525) must go together. Delete only the local and line 525 becomes a bare global write → the restricted env raises "attempt to write undeclared var" at hub load. Delete both or neither.

Riding along:

• hub.lua:1025-1043 isuseronline() — 19 lines, defined, never called, deliberately commented out of the export at 1276. Strict superset of the live isnickonline/iscidonline/issidonline trio.
• hub.lua:1120-1158 killuser — 39 commented-out lines whose only purpose is to justify a dead local slot.
• hub.lua:310 + :1263 — hub.usercount is a nil export. Never assigned anywhere in the repo's history (git log -S"usercount = function" is empty), so { usercount = nil } never creates the key and pairs(hub) never sees it. Any plugin calling it gets "attempt to call a nil value". Not contract surface — a 15-year-old broken stub. 2 lines.

PR 2 — core/doc.lua, whole module (309 lines)

Commented out of _core (init.lua:121 --"doc",), its doc.export() call site commented out (init.lua:328), its own 19 doc.add(...) payload lines sit inside a --[[ ]] block so even if loaded it would document nothing, its output target docs/documentation.txt does not exist, zero use "doc" anywhere, not in SANDBOX_GLOBALS, not in PLUGIN_API.md. Untouched since the SourceForge migration. install(DIRECTORY core/) is wholesale so no build change needed.

Nuance: it is a deliberate disable (two separate comment-outs), so it is a maintainer call whether to keep it as a dormant design artifact. PLUGIN_API.md supersedes it.

Also: init.lua:202 --"test", references core/test.lua, which does not exist. 1 line.

PR 3 — core/server.lua (~180 lines; contains judgement calls)

• :1019-1056 addclient + :247-290 wrapclient + :80 socket_tcp — no in-tree caller (the source says so itself at :1025-1028); wrapclient is called only by addclient. server is not in SANDBOX_GLOBALS so it is not plugin-reachable. ~85 lines. Judgement call: this is the only outbound-TCP convenience wrapper; http_client does outbound via socket + server.addtimer instead. Two latent bugs die with it (ignored wrapclient return → handler = nil on the timeout path; unguarded failure(...) when listeners.failure is nil).
• :914-955 the handler.starttls / deferred-TLS branch — starttls is never called. Inside it: needtls (516/918/950) written never read; handler.receivedata = handler.handshake / dispatchdata = handler.handshake (952-953) assign nil because handler.handshake does not exist; local shutdown (480) assigned 936/967, never called. ~45 lines. Judgement call: removes the STARTTLS seam. The no-op sub-defects inside are worth fixing regardless of what happens to the block.
• :1185-1203 getsettings / changesettings — exported, zero callers anywhere. ~20 lines.
• :1214-1216 stats — exported, zero callers; cascade: _readtraffic / _sendtraffic (163-164, incremented 708/788) are read only there. ~10 lines. Note handler.getstats (the per-connection twin, :544) is LIVE (cmd_userinfo.lua:212) — do not confuse them.
• :633-636 handler.pattern + the dead pattern parameter threaded through wrapclient / wrapserver / wrapconnection / addclient and p.pattern at :1138 — no caller ever supplies it; vestige of Phase 8 replacing LuaSocket's "*l" with the iostream pipeline.
• Unused accessors, zero call sites: handler.bufferlen (637-641), handler.id (531-533 + 369-371), handler.dispatch (534-536), handler.disconnect (537-539), handler.socket (401-403). ~20 lines. Live siblings that must not be touched: handler.ssl, handler.getsslinfo, handler.setlistener, the server-handler shutdown, handler.getstats.
• Unused module locals: :125 stop (never assigned), :81 socket_bind, :66 table_remove (tick() calls table.remove directly), :92+:103-104 signal / signal_set / signal_get. 6 lines.
• :249 / :300 — the disconnect binding in wrapclient / wrapserver is unused (wrapconnection's at :487 is live — do not touch).

PR 4 — dead unreachable branches (no-ops, but they are landmines)

All confirmed by executing the shapes under the hub's Lua 5.4.8, not by reading:

• core/util.lua:927-930 + 948-951 — encode/decode's else branches are unreachable (local str = tostring( str ) above makes if str then always true, tostring(nil) is the truthy string "nil"). Worse: the dead branch reads tbl, undeclared in that scope — under the restricted env it would raise "attempt to read undeclared var" instead of returning (nil, err). Disarmed only by being unreachable. util.encode/decode themselves are contract (PLUGIN_API §5.3) — keep the functions, drop the branches.
• core/util.lua:638-641, 671-674, 743-746, 747-750 — four dead tonumber-shadow type guards (formatseconds, formatbytes, difftime ×2). Same shape Fix type check for number in util.lua #439 "fixed": local t = tonumber( t ) + if not t then return guarantees a number, so the type check can never fire either way. Pure no-op deletions. Do not touch convertepochdate (791-793) / generatepass (702-703) — same shadow but correctly written and reachable.
• core/adc.lua:353-354 — duplicate FC / TO keys in the SCH np table (same class as the Refactor bool function in adc.lua #438 bool dup). Both writes store the identical value, so unlike Refactor bool function in adc.lua #438 this is provably behaviour-neutral. Hygiene only — must not be sold as a fix.

PR 5 — small dead locals across the rest (~60 lines, trivially reviewable)

core/cfg.lua Phase-6c extraction leftovers (470, 488-489, 491-496, 528+540 — 11 lines; note removing the types_* set also orphans local types = use "types", which currently triggers types.lua's load — safe because cfg_defaults.lua:42 does the same, but say so in the PR body) · core/scripts.lua (31, 43, 56, 59, 87, 330 — 7 lines) · core/util.lua (90, 104, 130, 136, 140+204, 190 — 7 lines) · core/hub_dispatch.lua:68 · core/hub_user_object.lua:52-53, 293, 632 · core/hub_bot_object.lua:34, 94, 311 · core/hbri.lua:70+72 (+ the now-false hbri_test.lua:35-38 stub/comment) · core/adc.lua:45, 47, 59, 62, 82 + :1127-1128 (parse-local shadows of the module-level _contextsend/_contextdirect) · core/ratelimit.lua:35 · core/ipmatch.lua:69, 70, 72 · core/blocklist.lua:100 + :191 + agg.last_seen (235/254, written never read — LRU vestiges) · core/whitelist.lua:240-247 _rebuild_indices (copy-pasted from blocklist, whose only caller is a bulk_replace whitelist deliberately does not have) · core/http.lua:57/125-131/215 logsafe (+ its orphaned string_sub/string_gsub) · core/http_events.lua:68/363-364 _max_size, :322 types_str · core/http_router.lua:66, 73 · core/http_filter.lua:52 · core/cfg_secret.lua:66, 69, 70, 80 + is_active (264-266/320, whose only consumer is itself a dead local at cfg_users.lua:59) · core/cfg_users.lua:62, 69+74 · core/secrets.lua:52 · core/sysinfo.lua:34 · core/out.lua:16, 35 · core/types.lua:14, 15, 39, 40 · core/util.lua:535-539 (savetbl builds and sorts a tmp that is never read, then calls iterate(tbl) which rebuilds it — runs on every user.tbl save)

PR 6 — plugins (~57 lines)

Dead exports not in the PLUGIN_API §8 contract table: etc_report.lua:73-82+:91 broadcast() (whole function; 96 callers use report.send, zero use .broadcast) · etc_usercommands.lua:89 format · bot_opchat.lua:399 bot · cmd_ban.lua:1259 bans_path. Plus 17 dead local X = lang.Y or "..." locals and their now-orphaned lang keys (40 lines), and 2 never-looked-up lang keys (cmd_reg ucmd_passwort, etc_userlogininfo msg_ccpm_1/2/3).

Reported, deliberately NOT removed

• CONTRACT / sandbox-reachable: usr_uptime.tbl, etc_trafficmanager.add, mmdb.MAX_FILE_SIZE, hmac.BLOCK_SIZE/sha256_bytes, whitelist.reload, util.handlebom, secrets.list_secret_keys, ipmatch.family/normalize, user.getblom, hub_bot_object.lua:252-256 bot.reply (the stub must stay — removing it turns a silent no-op into a nil-call crash for unseen plugins; only its 5 commented body lines are dead).
• Vendored (merge-cost on dep bumps): luasocket/src/usocket.c:106-118 socket_select() — newly orphaned on POSIX by our own Hub event loop hits FD_SETSIZE=1024 Linux limit (select -> poll port) #310 patch; :42-73 the SOCKET_SELECT variant of socket_waitfd (macro never defined anywhere); luasec/src/luasocket/ — 5 uncompiled .c files, but its headers are LIVE (luasec/CMakeLists.txt:29-32 puts them on the include path and ssl.c includes them), a latent ODR trap worth its own issue.
• Not dead, coverage gaps instead: http_events has no unit test at all despite carrying the long-poll deadline logic that already flaked (feat(cfg)!: flip kill_wrong_ips default from true to false #332/fix(http_events): use socket.gettime for long-poll deadline (#263) #334); etc_whitelist._list_filter_spec/_SOURCE_ENUM lack the assertions their etc_blocklist twins have.

Clean — no findings

Lua 5.1→5.4 migration leftovers: zero (Phase 3 left no compat scaffolding). Unused plugin helper functions: zero of 336. en/de lang-file key drift: zero. Plugins missing from cfg.tbl: zero. Dead cfg toggles: zero. Read-but-undefined cfg keys in-repo: zero. hub/hub.c: essentially clean (all 7 lua_register globals live, all 12 statics called). Dead cfg keys: no_cid_taken, ranks, owner_rank, use_ping, op_rank/admin_rank (cfg_defaults.lua 731/736/778/4872/768/773) — reachable via GET /v1/config, so PUT /v1/config/use_ping returns 200 and does nothing. Always-true validator: ssl_params (cfg_defaults.lua:4439) is the only one of 448 that never rejects — arguably deliberate (nested TLS table), report only.

Lessons from the audit itself (why every finding needs re-derivation)

Three agent calls were wrong, all caught by verifying against source:

1. "Drop [-]? from cmd_ban's parser" — no-op. %S+ already matches -5 (verified in Lua). The gap was validation, not parsing.
2. "core/hci.lua is a dead stub" — the opposite: live runtime state, and chasing it found hub_runtime: total runtime resets on every upgrade (mutable state lives in core/hci.lua) #445.
3. My own first lang test asserted type(v) == "string" → 149 false positives of 151 hits (ucmd_menu*, month_name, pics are legitimately tables); my second enumerated via io.popen("ls") → passes vacuously under a native Windows Lua (cmd.exe has no ls).

Also: an audit agent overwrote the repo's real CMakeLists.txt with a 4-line zlib probe and left a b/ build dir behind. Restored from git; future fan-outs get read-only agents.

[Aybook]

Correction to PR 1's stated rationale (§1a.4)

PR 1 (#448) is implemented, but its premise in this issue is wrong and the text above should not be read as-is by whoever picks up PRs 2-6.

This issue says hub.lua's main chunk "sits at Lua's 200-local cap, and CLAUDE.md §3 therefore freezes file-scope locals", and that PR 1 "un-freezes the file". CLAUDE.md and docs/DEVELOPMENT.md said the same ("any new top-level local fails the build"). Measured, that was false:

$ luac -p -l core/hub.lua | sed -n 3p
dev:  0+ params, 191 slots, 1 upvalue, 187 locals, ...   -> 13 slots free
#448: 0+ params, 172 slots, 1 upvalue, 168 locals, ...   -> 32 slots free

The file was never frozen - it had 13 free slots, and a new top-level local compiled fine. The claim was true when it was written (#301, 2026-05-30) and quietly decayed as later work packed locals into tables. 187 - 168 = 19 confirms all 19 removed locals did count toward the cap, so the value of PR 1 stands; only the "un-freezes a frozen file" framing was wrong. #448 corrects both docs to state the constraint without a number that can rot again, and points at luac -p -l as the way to measure it.

Two corrections to this issue's PR 1 section, both found by re-deriving from source:

1. The _G trap is not the only one. local isuseronline (322) is assigned at 1025, so it has the identical shape: delete only the declaration and the assignment becomes a bare global write that init.lua's restricted env rejects at hub load. Both pairs had to go together. Worth assuming PRs 2-6 hide more of these - the check is "does this dead local still have an assignment left behind", and luac -p does not catch it. Only booting the hub does.
2. The usercount evidence was sloppy. This issue states git log -S"usercount = function" is empty. It is not - it returns two commits. Both are check_usercount() in a long-deleted example script (hub_cmd_injection.lua), a different identifier caught by an unscoped substring search. Scoped to core/hub.lua the search is empty, so the conclusion (never assigned, the export was always nil) holds - but the stated evidence did not support it.

That makes five wrong calls from this audit so far (the three in "Lessons" plus these two). The re-derivation requirement in the header is doing real work; keep it for PRs 2-6.

[Aybook]

PR 3 corrections (§1a.4) - read before starting PR 3b

PR 3 shipped as PR 3a (#450, 44 lines): only the part of this section that carries zero judgement. The rest needs these corrections first.

1. The handler accessors are NOT removable - the stated rationale is a non-sequitur

This section lists handler.bufferlen / id / dispatch / disconnect / socket as removable because "server is not in SANDBOX_GLOBALS so it is not plugin-reachable".

That forecloses server.X access, but says nothing about an object handed to a plugin by reference. user:client() returns wrapconnection's handler verbatim, and docs/PLUGIN_API.md documents it twice - under §"Network" (user:client() -> "Underlying socket handler") and in its type glossary, where handler is the only type not linked to an enumerated method section: it is defined as "A wrapped socket from core/server.lua". The doc delegates the surface to the source.

The decisive evidence: getstats appears nowhere in docs/, yet the bundled cmd_userinfo.lua:212 depends on it via user:client():getstats(). So "PLUGIN_API.md does not enumerate the handler's methods" cannot mean "the methods are not contract" - if it could, getstats would be equally removable and +userinfo would break. bufferlen and pattern are setters; a third-party plugin may be tuning buffers through them.

id, dispatch, disconnect, bufferlen, pattern stay per this tracker's own conservative-on-contract-surface rule.

2. The list silently spans two different objects

handler.socket (and the first of the two handler.id definitions this section cites) live on wrapserver's handler, not wrapconnection's. user:client():socket() would be a nil call - wrapconnection never defines .socket. The wrapserver handler reaches no plugin route (add_server_handler is a hub.lua local; addserver's return goes into a private _servers table).

So those two are genuinely dead - but on "unreachable object", not on the contract argument. PR 3b should take them on that ground.

3. stop is dead, but not for the stated reason

":125 stop (never assigned)" is correct. Note a bare grep -c stop returns 3, not 1: the other two are the English word in comments. Same trap as the --"doc", / 200-\nlocals line-break misses elsewhere in this audit.

4. Two confusions this file sets for anyone reading the section

• Two traffic-counter pairs, one character apart. Per-connection readtraffic/sendtraffic feed the live handler.getstats; module-wide _readtraffic/_sendtraffic fed the dead server.stats. Only the _-prefixed pair is dead. The section notes getstats is live but does not warn that the counters mirror the same split.
• Three disconnect bindings. wrapclient's and wrapserver's are dead; wrapconnection's is live. The section gets this right - keep it in view.

5. Cascade the section does not mention

stats() was also the reader of _readlistlen / _sendlistlen / _timerlistlen. All three keep independent live reads, so none went write-only - checked, no action needed. changesettings's removal likewise orphans nothing: local tonumber, added specifically for it (see the #162 entry in CHANGELOG), stays live via _handshake_sweep_interval.

---

Remaining for PR 3b (unchanged scope, corrected rationale)

• addclient + wrapclient + socket_tcp (~85 lines). Dead and buggy: the timeout branch discards wrapclient's return, so handler stays nil and the function returns nil, nil, id - a caller checking if not handler would read a successful in-progress connect as a failure. Note core/server.lua's own comment (from fix(server): honor hub_listen bind address (closes #186) #188) records that it was knowingly kept and fixed while caller-less, on "a divergent broken copy is a defect" grounds. That is a keep-it-correct decision, not a keep-it decision.
• The starttls branch (~45 lines), never called, plus its three no-op sub-defects (needtls written never read; receivedata / dispatchdata assigned from a non-existent handler.handshake, i.e. nil; shutdown assigned twice, never called).
• handler.socket + the wrapserver handler.id, per correction 2 above.

That is 9 wrong or imprecise calls from this audit so far. The re-derivation requirement in the header is earning its keep.