Clear the gates this branch was failing on its own

Four gates were red on wave6 independently of the main merge.

TYPECHECK — 5 findings in signalwire/search/, present on this branch before the
merge (verified against pristine origin/wave6). Two shapes, both real:
  * `if not SentenceTransformer:` / `if not Presentation:` — the optional-dep
    shim leaves the name as the class or None, and a class object is always
    truthy, so the guard never fired the way it reads. Now `is None` /
    `is not None`.
  * `model.model_name = model_name` — torch's Module.__setattr__ is typed
    Tensor|Module, so stashing the name for cache identification is a
    third-party stub gap. Narrow `# type: ignore[assignment]` with the reason.
mypy is now clean over all 365 files.

REPO-LINT — the wave's new gate lints tests/ too: an unused `Awaitable,
Callable` import and a PERF401 append-loop, both in test_gateway.py. The loop is
now an async comprehension.

DOC-SURFACE — the floor is 100% here and coverage was 99.5%. Documented the
remaining 8: AgentServer's add_security_headers / health_check /
readiness_check, and ChatGateway's close / check_key / preflight / proxy /
stream. Real docstrings — check_key notes the compare_digest timing property,
stream notes that awaiting the body would swallow the keepalive padding the
service sends to survive intermediaries. Now 100.0% (1108/1108).

DOC-AUDIT — `get_stats` is a real SearchEngine method in signalwire/search/,
which is excluded from the oracle by design; added to DOC_AUDIT_IGNORE.md under
the Search-subsystem section that already names local_search_agent.py.

Verified with the paired porting-sdk wave6 branch: the full run-ci is green
except ROUTE-COLLISION, which fails only locally — python_route_registry.py
resolves the SDK through _sibling_root and lands on a relative path when the
registry runs with cwd=--repo. Handed an explicitly-built registry it reports
route-split=0, crud-dup=0, orphan-dto=0. CI's layout resolves it and has never
reported that gate.

Author: anthmFS

DOC_AUDIT_IGNORE.md

@@ -98,6 +98,7 @@ similarity_search: langchain/pinecone Pinecone.similarity_search — search comp
 build_index: real IndexBuilder.build_index (signalwire/search/index_builder.py) — Python-only search skill, absent from the cross-port surface
 build_index_from_sources: real IndexBuilder.build_index_from_sources (signalwire/search/index_builder.py) — Python-only search skill, absent from the cross-port surface
 migrate_sqlite_to_pgvector: real migration helper (signalwire/search/migration.py) — Python-only search skill, absent from the cross-port surface
+get_stats: real SearchEngine.get_stats (signalwire/search/search_engine.py) — Python-only search skill, absent from the cross-port surface
 argsort: numpy.argsort — DIY search example in docs/search_overview.md
 md: filename-extension regex false positive (matches `file.md (…`) in docs/search_overview.md processing listing
 do_search: user-defined method inside a caching example in docs/search_deployment.md

signalwire/signalwire/agent_server.py

@@ -80,6 +80,11 @@ def __init__(
         async def add_security_headers(
             request: Request, call_next: Callable[[Request], Awaitable[Response]]
         ) -> Response:
+            """Attach the standard hardening headers to every response.
+
+            Applied here rather than per-agent so a newly registered agent
+            cannot ship without them.
+            """
             response = await call_next(request)
             response.headers["X-Content-Type-Options"] = "nosniff"
             response.headers["X-Frame-Options"] = "DENY"
@@ -647,6 +652,11 @@ def _register_health_endpoints(self) -> None:
 
         @self.app.get("/health")
         def health_check() -> dict[str, Any]:
+            """Liveness probe: the process is up, plus what it is serving.
+
+            Returns the agent count and their routes, so a failed deploy that
+            registered nothing is visible from the probe itself.
+            """
             return {
                 "status": "ok",
                 "agents": len(self.agents),
@@ -655,6 +665,7 @@ def health_check() -> dict[str, Any]:
 
         @self.app.get("/ready")
         def readiness_check() -> dict[str, Any]:
+            """Readiness probe: the server is prepared to take traffic."""
             return {"status": "ready", "agents": len(self.agents)}
 
     def _run_server(self, host: str | None = None, port: int | None = None) -> None:

signalwire/signalwire/ai_chat/gateway.py

@@ -223,6 +223,11 @@ def effective_timeout(self) -> int:
         return self.conversation_timeout or SERVICE_DEFAULT_CONVERSATION_TIMEOUT
 
     async def close(self) -> None:
+        """Release the upstream HTTP session, if this gateway owns it.
+
+        A client passed in via `client=` belongs to the caller and is left
+        open; only a client the gateway built for itself is closed here.
+        """
         if self._owns_client:
             await self._client.close()
 
@@ -288,6 +293,17 @@ def check_origin(self, origin: str | None) -> None:
         raise GatewayRejection(403, "origin not allowed")
 
     def check_key(self, presented: str | None) -> None:
+        """Verify the publishable key the browser sent.
+
+        Compared with `hmac.compare_digest` rather than `==` so the check does
+        not leak the key a character at a time through timing.
+
+        Args:
+            presented: Key from the request, or None when the header is absent.
+
+        Raises:
+            GatewayRejection: 401 if the key is missing or does not match.
+        """
         if not presented or not hmac.compare_digest(presented, self.key):
             raise GatewayRejection(401, "bad key")
 
@@ -454,6 +470,12 @@ def _cors(origin: str | None) -> dict[str, str]:
 
         @router.options("/")
         async def preflight(request: Request) -> Response:
+            """Answer the CORS preflight for a listed origin.
+
+            Returns 204 with the allow headers when the origin passes, and a
+            bare 204 with no CORS headers when it does not — a browser then
+            refuses the real request without this ever seeing it.
+            """
             origin = request.headers.get("origin")
             headers = _cors(origin)
             if headers:
@@ -464,6 +486,13 @@ async def preflight(request: Request) -> Response:
 
         @router.post("/")
         async def proxy(request: Request) -> Response:
+            """The one route a browser calls: check, rewrite, forward, stream.
+
+            Verifies origin and key, replaces whatever the body claimed with
+            this gateway's own config_url and conversation id, forwards to the
+            chat service, and streams the reply back untouched. A newly minted
+            handle rides back on the `X-Chat-Handle` response header.
+            """
             origin = request.headers.get("origin")
             auth = request.headers.get("authorization", "")
             key = auth[7:] if auth.lower().startswith("bearer ") else None
@@ -522,6 +551,13 @@ async def proxy(request: Request) -> Response:
                 headers["X-Chat-Handle"] = minted
 
             async def stream() -> Any:
+                """Relay upstream bytes as they arrive, without decoding them.
+
+                The service pads a slow turn with whitespace so intermediaries
+                do not sever the connection. Awaiting the whole body here would
+                swallow that padding and recreate, inside the caller's own
+                stack, the very timeout the padding exists to survive.
+                """
                 async with self._client.raw_post(method, params) as resp:
                     async for chunk in resp.content.iter_any():
                         yield chunk

signalwire/signalwire/search/document_processor.py

@@ -364,7 +364,7 @@ def _extract_excel(self, file_path: str) -> str:
 
     def _extract_powerpoint(self, file_path: str) -> Any:
         """Extract text from PowerPoint files"""
-        if not Presentation:
+        if Presentation is None:
             return json.dumps(
                 {"error": "python-pptx not available for PowerPoint processing"}
             )

signalwire/signalwire/search/index_builder.py

@@ -165,7 +165,7 @@ def _extract_metadata_from_json_content(
     def _load_model(self) -> None:
         """Load embedding model (lazy loading)"""
         if self.model is None:
-            if not SentenceTransformer:
+            if SentenceTransformer is None:
                 raise ImportError(
                     "sentence-transformers is required for embedding generation. Install with: pip install sentence-transformers"
                 )

signalwire/signalwire/search/query_processor.py

@@ -291,8 +291,10 @@ def _get_cached_model(model_name: str | None = None) -> Any:
 
             logger.info(f"Loading sentence transformer model: {model_name}")
             model = SentenceTransformer(model_name)
-            # Store the model name for identification
-            model.model_name = model_name
+            # Store the model name for identification. torch's Module.__setattr__
+            # is typed for Tensor|Module, so stashing a plain str on the instance
+            # is a third-party-stub gap, not a real type error.
+            model.model_name = model_name  # type: ignore[assignment]
             # Evict oldest entry if cache is full
             if len(_model_cache) >= _MAX_MODEL_CACHE_SIZE:
                 oldest_key = next(iter(_model_cache))

signalwire/signalwire/search/search_service.py

@@ -528,9 +528,10 @@ def _load_resources(self) -> None:
                             )
                             try:
                                 model = SentenceTransformer(model_name)
-                                model.model_name = (
-                                    model_name  # Store for cache comparison
-                                )
+                                # Store for cache comparison; torch's
+                                # Module.__setattr__ is typed Tensor|Module, so a
+                                # plain str is a stub gap, not a real error.
+                                model.model_name = model_name  # type: ignore[assignment]
                                 self.models[model_name] = model
                             except Exception as e:
                                 logger.error(f"Failed to load model {model_name}: {e}")
@@ -552,7 +553,7 @@ def _load_resources(self) -> None:
         else:
             # SQLite backend - original behavior
             # Load model (shared across all indexes)
-            if self.indexes and SentenceTransformer:
+            if self.indexes and SentenceTransformer is not None:
                 # Get model name from first index
                 sample_index = next(iter(self.indexes.values()))
                 model_name = self._get_model_name(sample_index)

tests/unit/ai_chat/test_gateway.py

@@ -7,7 +7,7 @@
 """
 
 import json
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator
 from typing import Any
 
 import pytest
@@ -441,10 +441,8 @@ async def test_the_relay_streams_rather_than_collects(
     from fastapi.responses import StreamingResponse
 
     client = slow_gateway._client
-    chunks = []
     async with client.raw_post("chat", {"id": "c", "message": "hi"}) as resp:
-        async for chunk in resp.content.iter_any():
-            chunks.append(chunk)
+        chunks = [chunk async for chunk in resp.content.iter_any()]
     assert len(chunks) > 1, f"upstream body arrived in one piece: {chunks!r}"
     assert chunks[0].strip() == b"", "first chunk should be keepalive padding"