chore: remove vulture-flagged dead code, add whitelist

- plain.py: drop `or True` short-circuit + unreachable return; drop now-unused _HASH_HINTS
- ingester.py: drop unused `current_position` param from _flush_batch
- vulture_whitelist.py: document remaining false positives (FastAPI Depends side-effects, IMAP uid_mode where UID==seq)

decnet/canary/instrumenters/plain.py

@@ -19,7 +19,6 @@ from __future__ import annotations
 from decnet.canary.base import CanaryArtifact, CanaryContext, CanaryInstrumenter
 
 
-_HASH_HINTS = (b"\n#", b"#!/", b"---\n", b"version:", b"FROM ")
 _SLASH_HINTS = (b"//", b"function ", b"const ", b"let ", b"var ")
 _SEMI_HINTS = (b"[default]", b"[section]", b"\n[")
 
@@ -32,8 +31,6 @@ def _comment_prefix(blob: bytes) -> bytes:
         return b"// "
     # Default to # — the most common comment glyph across config files
     # we'd plausibly canary.
-    if any(h in head for h in _HASH_HINTS) or True:
-        return b"# "
     return b"# "
 
 

decnet/web/ingester.py

@@ -131,7 +131,7 @@ async def _run_loop(
                         time.monotonic() - _batch_started >= _max_wait_s
                     ):
                         _flushed = len(_batch)
-                        _position = await _flush_batch(repo, _batch, _position, _bus)
+                        _position = await _flush_batch(repo, _batch, _bus)
                         _batch.clear()
                         _batch_started = time.monotonic()
                         await _publish_batch(_bus, _flushed, _position)
@@ -139,7 +139,7 @@ async def _run_loop(
             # Flush any remainder collected before EOF / partial-line break.
             if _batch:
                 _flushed = len(_batch)
-                _position = await _flush_batch(repo, _batch, _position, _bus)
+                _position = await _flush_batch(repo, _batch, _bus)
                 await _publish_batch(_bus, _flushed, _position)
 
         except Exception as _e:
@@ -174,7 +174,6 @@ async def _publish_batch(bus: Any, flushed: int, position: int) -> None:
 async def _flush_batch(
     repo: BaseRepository,
     batch: list[tuple[dict[str, Any], int]],
-    current_position: int,
     bus: Any = None,
 ) -> int:
     """Commit a batch of log rows and return the new file position.
@@ -182,8 +181,8 @@ async def _flush_batch(
     If the enclosing task is being cancelled, bail out without touching
     the DB — the session factory may already be disposed during lifespan
     teardown, and awaiting it would stall the worker.  The un-flushed
-    lines stay uncommitted; the next startup re-reads them from
-    ``current_position``.
+    lines stay uncommitted; the next startup re-reads them from the
+    last persisted position.
     """
     _task = asyncio.current_task()
     if _task is not None and _task.cancelling():

vulture_whitelist.py

@@ -0,0 +1,22 @@
+"""Vulture whitelist — names that look unused but aren't.
+
+Run via:
+
+    vulture decnet vulture_whitelist.py --min-confidence 80
+
+Each entry suppresses a known false positive. Add a comment with the
+file:line and the reason so future-you can revisit.
+"""
+
+# FastAPI auth dependencies — `Depends()` runs for the side effect
+# (auth/RBAC enforcement) even when the injected value is unused inside
+# the handler body. Vulture can't see that.
+viewer  # decnet/web/router/canary/api_tokens.py:176, 198, 284 — Depends(require_viewer)
+admin   # any handler with admin: dict = Depends(require_admin) where the body doesn't read it
+user    # any handler with user: dict = Depends(require_user) where the body doesn't read it
+
+# IMAP stub — UID SEARCH vs sequence SEARCH is a real protocol
+# differentiator, but in this honeypot stub UID == seq number (see the
+# "UID == sequence number" comment at the top of the email fixtures), so
+# the parameter is intentionally a no-op.
+uid_mode  # decnet/templates/imap/server.py:646