chore: pre-PR cleanup sweep — strip archeology, tighten comments, drop dead narrative

Net delta across 61 files: -1629 LOC (1069 added, 2698 deleted). No
behavioral changes, no test count delta — 4789 tests passing before
and after.

Three parallel cleanup lanes worked the branch diff against main:

Dataplane substrate (~-1500 LOC across coordinator, engine_startup,
permissions, models, codec, scripts, transitions, lattices, ids,
errors, crash, connection, the Lua scripts, and the co-located
tests). Stripped multi-paragraph rationales describing the design,
shrunk module docstrings, removed historical narrative ("previously",
"we now", "before this"), collapsed multi-line in-body comment
blocks to one-liners. The genuinely load-bearing WHY comments
stayed (the cjson directive fallback, the NOSCRIPT coalescing note,
the asyncio-only contract on OneShotFlag, etc.).

Migrated callers (~-570 LOC across redis_program_storage, locking,
state_manager, archive_storage, bandit, fetcher, stats, sync,
mutation_operator, dag_runner, selectors, strict_chat_openai). One
real code smell fixed in coevolution/stats.py: replaced
`for idx, (db, prefix) in enumerate(...)` with a stale dangling
`del db, prefix` that referenced no log line. Dual-path narration
("when wired, route through dp; when None, fall back...") collapsed
across the storage / archive / bandit dispatch sites. The
backwards-compat-shim apology comments tightened to one line each.

Tests + entry-point + configs (~-340 LOC across the test tree,
run.py, pyproject.toml, .gitignore). Test docstrings collapsed,
internal-slug "covers C3" / "T-A4" references stripped, narrative
about prior bypass behaviour replaced with what-the-test-asserts-now.
pyproject.toml banned-import policy block tightened; every TID251
per-file-ignore verified live (zero stale entries). .gitignore left
alone (no narrative to strip).

Code-smell pattern surfaced across 5 files (NOT fixed in this
sweep; flagged for a follow-up): the `if self._dataplane is not
None: return await self._<op>_via_dataplane(...)` dispatch shape
duplicates in redis_program_storage.atomic_state_transition,
fast_state_transition, batch_transition_state, batch_transition_by_ids,
and archive_storage.add_elite. A small dispatch_if_dataplane helper
or a coordinator-mixin would centralise the branch + assert. A
sibling pattern across prompts/fetcher.py, coevolution/stats.py,
coevolution/sync.py for lazy-init owned/borrowed DataPlane could
deduplicate via an OwnedDataPlane container.

Out-of-lane finding (not fixed): errors.all_error_types() omits
EliteInvalidError from its tuple but the test only checks subclassing,
not exhaustiveness. One-line fix; counted as behavior change; left
for a follow-up.

Author: GrigoryEvko

gigaevo/database/program_storage.py

@@ -270,12 +270,9 @@ async def batch_transition_state(
         Subclasses may override with pipelined operations.
         Returns the number of programs transitioned.
 
-        Per-program FSM validation runs against the program's actual
-        current state rather than the caller-asserted ``old_state`` so
-        a diverged in-memory state (e.g. an upstream actor mutated the
-        program after this batch was assembled) surfaces as
-        :class:`ValueError` instead of leaking into a persisted blob
-        whose ``state`` field disagrees with the FSM.
+        Per-program FSM validation runs against each program's actual
+        current state so a diverged in-memory state surfaces as
+        :class:`ValueError` rather than being silently persisted.
         """
         old_enum = ProgramState(old_state)
         new_enum = ProgramState(new_state)

gigaevo/database/redis/locking.py

@@ -6,23 +6,12 @@
 token-CAS, so renew and release only mutate the key when its stored
 value still matches the holder's token.
 
-Two execution paths share the same lock-key shape:
-
-* **Dataplane-routed**: when a :class:`~gigaevo.dataplane.DataPlane` is
-  supplied at construction, the three Lua calls dispatch through
-  :meth:`gigaevo.dataplane.scripts.LuaRegistry.evalsha` so the SHA
-  cache, NOSCRIPT recovery, and :class:`ScriptLostError` escalation
-  policy are owned by a single registry shared with every other
-  coordinator-routed caller. The acquired lock is wrapped in a
-  :class:`~gigaevo.dataplane.crash.CrashWatchedHandle` so renewal
-  failure surfaces as a typed :class:`~gigaevo.dataplane.crash.CrashEvent`
-  the caller can pattern-match against, instead of forcing readers to
-  poll a private flag.
-
-* **Legacy direct-aioredis**: when ``dataplane`` is ``None`` the lock
-  reimplements ``SCRIPT LOAD`` + ``EVALSHA`` + ``NOSCRIPT`` retry
-  locally. This path stays in place for callers that have not yet
-  acquired a dataplane handle.
+When a :class:`~gigaevo.dataplane.DataPlane` is supplied the Lua calls
+dispatch through its :class:`LuaRegistry` and the lease is wrapped in a
+:class:`~gigaevo.dataplane.crash.CrashWatchedHandle` for typed
+renewal-loss observability. Without a dataplane the SCRIPT LOAD /
+EVALSHA / NOSCRIPT retry is handled locally and crash observability
+is unavailable.
 """
 
 from __future__ import annotations
@@ -79,10 +68,8 @@ def __init__(
         self._token: str | None = None
         self._renewal_task: asyncio.Task[None] | None = None
 
-        # Legacy direct-aioredis SHA cache. Populated lazily on the
-        # first :meth:`_evalsha` call when ``self._dataplane is None``;
-        # ignored on the dataplane-routed path where
-        # :class:`LuaRegistry` owns the cache.
+        # SHA cache for the dataplane-less path; ignored when a
+        # dataplane is wired (its LuaRegistry owns the cache).
         self._script_sources: dict[ScriptName, str] = {
             _SCRIPT_LOCK_ACQUIRE: load_lua_source(_SCRIPT_LOCK_ACQUIRE),
             _SCRIPT_LOCK_RENEW: load_lua_source(_SCRIPT_LOCK_RENEW),
@@ -91,12 +78,8 @@ def __init__(
         self._script_shas: dict[ScriptName, str] = {}
         self._reload_lock: asyncio.Lock | None = None
 
-        # Typed-control-flow channel for renewal-loss observability.
-        # Populated on :meth:`acquire`; the flag is signalled by the
-        # background renewer on token-CAS failure or transport error.
-        # Callers route lease-scoped operations through
-        # ``self._wrapped_lease.call(...)`` to convert the polled flag
-        # into a :class:`CrashEvent` branch.
+        # Crash-flag signalled by the background renewer on token-CAS
+        # failure or transport error; consumed via ``wrapped_lease``.
         self._lease_flag: OneShotFlag | None = None
         self._wrapped_lease: (
             CrashWatchedHandle[InstanceLease, str, InstanceLease] | None
@@ -114,15 +97,12 @@ def instance_id(self) -> str:
     def wrapped_lease(
         self,
     ) -> CrashWatchedHandle[InstanceLease, str, InstanceLease] | None:
-        """Typed crash-watched handle around the held lease.
-
-        ``None`` when the lock is not held or when the dataplane is not
-        wired (the legacy path has no shared :class:`InstanceLease`
-        vocabulary). On the dataplane-routed path the handle's
-        :meth:`CrashWatchedHandle.call` short-circuits to a
-        :class:`CrashEvent` once the background renewer has signalled
-        renewal loss, eliminating a Redis round-trip for the loss-detection
-        path.
+        """Crash-watched handle around the held lease, or ``None``.
+
+        ``None`` when the lock is not held or when no dataplane is
+        wired. Calls through the handle short-circuit to a
+        :class:`CrashEvent` once the background renewer signals
+        renewal loss.
         """
         return self._wrapped_lease
 
@@ -149,13 +129,9 @@ async def _load_sha(
         """SCRIPT LOAD ``name`` and refresh the SHA cache, coalesced.
 
         Concurrent NOSCRIPT recoveries for the same script collapse to
-        one SCRIPT LOAD round-trip: callers that wait on the lock find
-        the SHA refreshed by the first arrival and reuse it. The
-        ``stale_sha`` argument is the SHA that just raised NOSCRIPT;
-        when it differs from the cache we are looking at a peer's
-        already-installed result and skip the redundant LOAD.
-
-        Used only on the legacy direct-aioredis path.
+        a single SCRIPT LOAD: when ``stale_sha`` differs from the
+        cached entry a peer has already installed a fresh SHA and we
+        reuse it.
         """
         async with self._get_reload_lock():
             cached = self._script_shas.get(name)
@@ -176,17 +152,10 @@ async def _evalsha(
     ) -> int:
         """Invoke a lock script and coerce its return to ``int``.
 
-        Two dispatch paths, selected by whether the dataplane is wired:
-
-        * **Dataplane-routed**: delegates to
-          :meth:`LuaRegistry.evalsha`, which owns the SHA cache,
-          NOSCRIPT-reload retry, and :class:`ScriptLostError` escalation
-          policy. ``r`` is ignored.
-        * **Legacy**: replicates the SCRIPT LOAD + EVALSHA + NOSCRIPT
-          retry locally against the per-lock SHA cache.
-
-        Returns the script's integer return value (every instance-lock
-        script returns 1 / 0).
+        When a dataplane is wired, dispatches through its
+        :class:`LuaRegistry`; otherwise runs SCRIPT LOAD + EVALSHA +
+        NOSCRIPT retry against the local SHA cache. Every instance-lock
+        script returns 1 / 0.
         """
         if self._dataplane is not None:
             lua = self._dataplane._lua
@@ -247,11 +216,6 @@ async def _acquire(r: aioredis.Redis) -> bool:
 
         result = await self._conn.execute("acquire_instance_lock", _acquire)
         if self._dataplane is not None:
-            # Build an InstanceLease-shaped record so the standard
-            # dp.wrap_lease policy applies. The lease's ``token`` is the
-            # holder's instance id (the same value token-CAS'd by the
-            # underlying scripts); ``flag`` is signalled by the
-            # background renewer below on renewal loss.
             self._lease_flag = OneShotFlag()
             lease = InstanceLease(
                 token=LeaseToken(self._instance_id),
@@ -271,13 +235,9 @@ async def release(self) -> None:
 
         Token-CAS DEL: only deletes the key if its stored value still
         matches our instance id. Idempotent; an already-released or
-        already-lost lock is a silent no-op.
-
-        After ``release()`` returns the renewer is fully drained and the
-        local holder state (``is_held``, ``_token``) is cleared, even if
-        the Redis side errored — the caller's lock-holding posture ends
-        at the call site regardless of network reachability so a follow-
-        up acquire is not blocked by stale local state.
+        already-lost lock is a silent no-op. Local holder state is
+        cleared even when the Redis-side call errors, so a follow-up
+        acquire is not blocked by stale state.
         """
         if self._renewal_task:
             self._renewal_task.cancel()
@@ -355,16 +315,10 @@ async def observe_loss(
     ) -> CrashEvent[str, InstanceLease] | None:
         """Return a :class:`CrashEvent` iff the renewer has signalled loss.
 
-        ``None`` on the non-loss path (the typical case). The first call
-        after a loss returns a synthesized :class:`CrashEvent` carrying
-        the lock key as ``peer`` and the lost :class:`InstanceLease` as
-        ``resource``. Subsequent calls return ``None`` so observers do
-        not see the same loss twice.
-
-        Returns ``None`` unconditionally on the legacy direct-aioredis
-        path where ``wrapped_lease`` is unavailable; callers that need
-        crash-event observability MUST construct the lock with a
-        dataplane handle.
+        Single-shot: the first call after a loss returns a synthesized
+        :class:`CrashEvent` (lock key as ``peer``, lost
+        :class:`InstanceLease` as ``resource``); subsequent calls return
+        ``None``. Always ``None`` when no dataplane is wired.
         """
         if self._wrapped_lease is None:
             return None
@@ -374,8 +328,6 @@ async def _noop(_: InstanceLease) -> bool:
 
         _, evt = await self._wrapped_lease.call(_noop)
         if evt is not None:
-            # Consume the loss: clear the wrapper so a second observer
-            # does not see the same event a second time.
             self._wrapped_lease = None
             self._lease_flag = None
         return evt