llm: clarify transient-set count and legacy finish_reason mapping

Two doc-only cleanups from PR #17 review:

- errors.py: TRANSIENT_CATEGORIES has three entries, not four —
  comment was off by one.
- providers/openai.py: tighten the comment on the
  `finish_reason: "function_call"` → `"tool_calls"` rename so it's
  clear this is a value rename (per spec §8.2 / conformance fixture
  005), not a message-field transformation. We do not translate the
  deprecated single `message.function_call` shape — none of the
  backends we currently target emit it.

Author: chris-colinsky

src/openarmature/llm/errors.py

@@ -31,8 +31,8 @@
 PROVIDER_INVALID_REQUEST = "provider_invalid_request"
 
 
-# Per spec §7 "Retry classification": these four categories are
-# *transient* — a retry MAY succeed. The other three
+# Per spec §7 "Retry classification": these three categories are
+# *transient* — a retry MAY succeed. The other four
 # (`provider_authentication`, `provider_invalid_model`,
 # `provider_invalid_request`, `provider_invalid_response`) are
 # non-transient and MUST NOT be retried by the default classifier.

src/openarmature/llm/providers/openai.py

@@ -253,8 +253,16 @@ def _parse_response(self, payload: dict[str, Any]) -> Response:
             raise ProviderInvalidResponse(f"response missing required fields: {exc}") from exc
         finish_reason: str = finish_reason_raw if isinstance(finish_reason_raw, str) else "error"
 
-        # Map OpenAI's legacy `function_call` to `tool_calls`; map any
-        # unknown finish_reason to `error` per §8.2.
+        # Per §8.2 (and conformance fixture 005's
+        # `function_call_legacy_finish_reason_mapping` case): the
+        # legacy `finish_reason: "function_call"` value MUST be
+        # normalized to the spec's `"tool_calls"`. This is a
+        # finish_reason *value* rename only — the assistant message's
+        # `tool_calls` list is already populated by
+        # ``_wire_to_assistant_message`` from the `tool_calls` field
+        # on the wire. We do NOT translate the deprecated single
+        # `message.function_call` shape (no backend we target emits
+        # it). Any other unknown finish_reason maps to `error`.
         if finish_reason == "function_call":
             finish_reason = "tool_calls"
         if finish_reason not in {"stop", "length", "tool_calls", "content_filter", "error"}: