refactor: no comments left - one-line module docstrings, contracts on public fields only; jobs/job.py; example config and README

src/beaver_gateway/security/audit.py

@@ -1,32 +1,7 @@
 """Single entry point for writing :class:`AuditLog` rows.
 
-Every frontend ends up needing the same three-line pattern — open a DB
-session, append a row, swallow failures so the user-visible request
-still succeeds. Phase 4.3 inlined that pattern in the admin frontend
-under a private ``_audit()`` helper; Phase 4.4 lifts it here so the
-Messages and MCP frontends can call the same function and so the
-swallow-and-log policy lives in one place.
-
-The contract:
-
-* ``log(runtime, actor=..., kind=...)`` is fire-and-forget. It awaits
-  the DB write (so callers can ``await`` it before responding and get
-  ordering), but never raises — if the audit insert fails, the function
-  emits an ``exception`` log line and returns.
-* ``actor`` is a free-form string. By convention: ``"token:<name>"``
-  for bearer-authenticated traffic, ``"admin:<user>"`` for admin-UI
-  actions, ``"anon"`` for failed-auth paths we still want to record.
-* ``kind`` is a short tag — see :data:`KNOWN_KINDS` for the set the
-  current frontends emit; new tags don't need a code change here, the
-  column is free-form.
-* ``**detail`` is JSON-serialised by :func:`append_audit`. Keep it
-  small: paths, methods, status codes — not request bodies. Anything
-  passed here lands in ``AuditLog.detail_json`` verbatim.
-
-Why a thin wrapper rather than ``append_audit`` directly: callers want
-"write if you can, otherwise carry on", and pulling the try/except into
-every frontend was already starting to drift (admin had it, bearer
-frontends would have copy-pasted). One module, one policy.
+``log()`` is fire-and-forget: it awaits the DB write so callers get
+ordering, but never raises — failures are logged and swallowed.
 """
 
 from __future__ import annotations
@@ -43,15 +18,11 @@ if TYPE_CHECKING:
 _log = logging.getLogger("beaver_gateway.audit")
 
 
-# Tags currently emitted by the gateway. The set is informational —
-# ``AuditLog.kind`` is free-form so new code can introduce new tags
-# without touching this list — but listing them here gives the admin UI
-# and any downstream log consumers one canonical reference.
 KNOWN_KINDS: frozenset[str] = frozenset(
     {
-        "messages",  # POST /v1/messages accepted
-        "mcp_call",  # /mcp/<ns>/... proxied
-        "tool_call",  # a model's tool call seen by the PreToolUse hook
+        "messages",
+        "mcp_call",
+        "tool_call",
         "login_ok",
         "login_failed",
         "logout",
@@ -59,6 +30,7 @@ KNOWN_KINDS: frozenset[str] = frozenset(
         "token_revoke",
     }
 )
+"""Kinds the gateway currently emits; ``AuditLog.kind`` stays free-form."""
 
 
 async def log(
@@ -69,12 +41,12 @@ async def log(
     agent_name: str | None = None,
     **detail: Any,
 ) -> None:
-    """Best-effort audit insert. Never raises.
+    """Best-effort audit insert. Never raises; DB failures are logged.
 
-    Opens its own short-lived :class:`AsyncSession` so callers don't
-    have to thread one through. If the DB hiccups (table missing,
-    disk full, connection drop), we log and move on — the audit trail
-    is observability, not a hard precondition for serving the request.
+    ``actor`` is free-form (``"token:<name>"``, ``"admin:<user>"``,
+    ``"anon"``); ``kind`` is a short tag (see :data:`KNOWN_KINDS`); and
+    ``**detail`` is JSON-serialised into ``AuditLog.detail_json`` — keep
+    it small, not full request bodies.
     """
     try:
         async with runtime.db.session() as session: