fix: the leet near-miss floor was set three positions too high (#825)

[raeq]

Closes #825. Refs #762.

The defect

The leet branch has two sub-paths: the decode is a lexicon word, or the decode is one edit from one. The first has a floor of three; the second carried an uncommented >= 6 since #393.

leet_sub maps '1' to 'i', not 'l' — correct, since 1 looks like i in most faces. The consequence is that a 1-for-l substitution never decodes exactly, so the exact path can never see it and only the near-miss path can. Below six characters, that path does not run.

>>> disarm.inspect_anomalies("l0gin", lexicon=BRANDS).reason
'"l0gin" decodes to the word "login"'
>>> disarm.inspect_anomalies("1ogin", lexicon=BRANDS).reason
None                                   # same brand, same five letters, one digit each

Measured against the issue's table: 0 of 5 five-letter brands, 7 of 7 six-letter ones.

Choosing the new value

The issue argued the floor should go entirely, on the grounds that the exact path fires below it and produces false positives anyway. I measured that and it does not hold. Over 65 ordinary digit-bearing tokens (mp3, k8s, sha1, i18n, rtx4090, 1080p, …) against a 234k-word lexicon, plus 8 single-substitution brand spoofs:

floor	false positives / 65	spoofs caught / 8
3	22	8
4	12	8
5	5	7
6 (current)	4	3

The exact path contributes 4 of those 65 on its own, so removing the floor adds 18 new false positives — k8s → kos, b2b → bab, es6 → es. The floor is doing real work. It was set three positions too high, not wrongly present.

Five is the knee: one false positive more than six (top10, decode topio), and it more than doubles the spoofs caught. Four costs eight more to gain one (1yft, four letters).

After: 4 of 5 and 7 of 7. 1yft is the deliberate cost and has its own pinned test.

The table lives on the constant's doc comment, so the next person to touch the floor does not have to redo the measurement — which is why it had no comment in the first place.

Two rows of #726's table moved

gn0r3! and !dm1n were asserted clean, and the test named the six-character floor as the reason:

nearest()'s single-edit rescue declines them too because it requires a six-character decode.

That is a test freezing the floor's own defect as the correct answer. Both are one edit from the word they imitate — ignore and admin — and both are now reported. The test is inverted rather than deleted, and explains what changed.

Also

The near-miss path was undocumented. docs/user-guide/anomaly-detection.md described the exact path only, which predicts neither paypa1 firing nor app1e staying clean. Both paths and both floors are now on the page.

tests/test_leet_near_miss_floor.py pins both sides of the boundary — the four newly-caught spoofs, the seven that must not regress, 1yft below the floor, and eight short technical tokens that must not start firing. Its negative cases use a lexicon of one-edit neighbours rather than the decodes themselves; seeding the decode would have made them exact-path hits and measured the wrong path.

Full gate green: cargo test 723, pytest 6,275, doc tests 41 pages, clippy both feature sets, perf_lint.sh, cargo doc, mkdocs --strict. Gate is in the shared core, so every binding inherits it; no binding-specific work.

🤖 Generated with Claude Code

[github-actions]

📄 Docs preview: https://8eb3edc3.disarm-docs.pages.dev

[Copilot]

🟡 Changes recommended

The new near-miss floor test contains inaccurate decode commentary/test data and one updated assertion is weaker than necessary, reducing the regression value of the test suite.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR fixes a coverage gap in the inspect_anomalies leet detector by lowering the near-miss (1-edit) decode floor from 6 to 5, so short 1-for-l spoofs (which can’t hit the exact-decode path) are detected consistently across brand-length tokens. It also updates tests, documentation, and the changelog to reflect the two leet sub-paths and the rationale for the chosen threshold.

Changes:

• Lower leet near-miss decode minimum length to 5 via a named constant in the Rust core.
• Update and add pytest coverage to pin behavior on both sides of the new boundary (including previously “clean” cases that are now correctly reported).
• Document the near-miss leet path and record the fix and measurement rationale in docs and CHANGELOG.

File summaries

File	Description
src/anomalies.rs	Introduces NEAR_MISS_MIN_LEN = 5 and applies it to the leet near-miss (nearest) path with expanded rationale.
tests/test_leet_segmentation.py	Updates #726-related expectations for cases now caught via the near-miss path.
tests/test_leet_near_miss_floor.py	Adds new regression tests pinning the near-miss floor boundary and intended false-positive guards.
docs/user-guide/anomaly-detection.md	Updates leet documentation to describe both exact and near-miss paths and their floors.
CHANGELOG.md	Records the behavior change, rationale, and related test expectation updates.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.