Fix: make the docs build strict without suppressions

mkdocs.yml

@@ -27,9 +27,25 @@ theme:
       scheme: slate
       toggle: { icon: material/weather-sunny, name: Switch to light mode }
 
+# A page absent from nav builds fine by default and only shows up as an INFO
+# line, so it silently disappears from the site's navigation. Promote it to a
+# warning, which --strict then treats as a failure.
+validation:
+  nav:
+    omitted_files: warn
+    not_found: warn
+
+# Deliberate omissions: these are accumulating logs and design sets, reached
+# through their own index pages rather than the sidebar. Listing every entry in
+# nav would bury the rest of the tree. Declaring them here keeps
+# omitted_files strict for everything else.
+not_in_nav: |
+  investigations/*
+  remote-l3-worker-design/*
+  troubleshooting/device-error-codes/*
+
 hooks:
   - docs/_hooks/repo_links.py
-  - docs/_hooks/griffe_filter.py
 
 plugins:
   - search

python/simpler/task_interface.py

@@ -30,7 +30,13 @@
 from enum import IntEnum
 from math import prod
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # Annotation-only: `CallableHandle` is imported lazily at its use site, and
+    # PEP 563 keeps these annotations as strings, so nothing is imported at
+    # runtime.
+    from .callable_identity import CallableHandle
 
 import _task_interface as _ti_module  # pyright: ignore[reportMissingImports]
 from _task_interface import (  # pyright: ignore[reportMissingImports]
@@ -1059,7 +1065,18 @@ def __init__(self):
         self._live_handles: dict[int, bytes] = {}
         self._next_handle_id = 0
 
-    def init(self, device_id, bins, log_level=None, log_info_v=None, prewarm_config=None, enable_sdma=False):
+    def init(
+        self,
+        device_id: int,
+        # Structurally typed: any object exposing the *_path attributes below.
+        # Not RuntimeBinaries — that lives in simpler_setup, which this package
+        # must not depend on.
+        bins: Any,
+        log_level: int | None = None,
+        log_info_v: int | None = None,
+        prewarm_config: CallConfig | None = None,
+        enable_sdma: bool = False,
+    ):
         """Attach the calling thread to ``device_id``, load the host runtime
         library, and cache platform binaries.
 
@@ -1253,7 +1270,13 @@ def register_callable(self, callable):
                 raise
         return handle
 
-    def run(self, handle, args, config=None, **kwargs):
+    def run(
+        self,
+        handle: CallableHandle,
+        args: ChipStorageTaskArgs,
+        config: CallConfig | None = None,
+        **kwargs: Any,
+    ):
         """Launch a callable previously returned by ``register_callable``.
 
         Args:

python/simpler/worker.py

@@ -4208,7 +4208,7 @@ def _validate_eligible_targets(self) -> None:
                     f"has no eligible dispatch target (needs {need})"
                 )
 
-    def init(self, prewarm_config=None, *, _startup_deadline: float | None = None) -> None:
+    def init(self, prewarm_config: CallConfig | None = None, *, _startup_deadline: float | None = None) -> None:
         """Initialize the worker and bring its whole subtree to READY.
 
         For an L3+ worker ``init`` is the single startup submission point: it