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

src/beaver_gateway/backends/transcript.py

@@ -1,16 +1,7 @@
 """Anthropic messages <-> Agent SDK transcript entries.
 
-:func:`build_entries` renders a message list as the entries the Claude CLI
-itself writes (reference: ``t/spike_sdk/entries_reference.json``, CLI
-2.1.248 via ``import_session_to_store``): one ``user`` entry per prompt,
-one ``assistant`` entry per content block sharing a message id, one
-``user`` entry per ``tool_result`` parented on the matching ``tool_use``
-entry. Only ``user``/``assistant`` entries are produced - no attachments,
-titles or queue markers. Appending the result to a session store and
-resuming that session id seeds an external history into the SDK.
-
-:func:`messages_from_entries` is the projection back, used by tests and by
-anything that needs Anthropic-shape history out of a mirrored transcript.
+:func:`build_entries` renders a message list as entries the Claude CLI
+itself writes; :func:`messages_from_entries` is the projection back.
 """
 
 from __future__ import annotations
@@ -61,6 +52,14 @@ def build_entries(
     permission_mode: str = "bypassPermissions",
     now: datetime | None = None,
 ) -> list[dict[str, Any]]:
+    """Render ``messages`` as entries a session store can resume from.
+
+    One ``user`` entry per prompt, one ``assistant`` entry per content
+    block sharing a message id, one ``user`` entry per ``tool_result``
+    parented on the matching ``tool_use``. Appending the result to a
+    session store and resuming that session id seeds external history
+    into the SDK.
+    """
     stamp = (now or datetime.now(UTC)).strftime("%Y-%m-%dT%H:%M:%S.") + (
         f"{(now or datetime.now(UTC)).microsecond // 1000:03d}Z"
     )
@@ -293,8 +292,6 @@ def _zero_usage() -> dict[str, Any]:
     }
 
 
-# ---- repair, windows, projections ---------------------------------------
-
 _PROMPT_TYPES = ("user", "assistant")
 _INTERRUPTED = "interrupted"