llm: enforce Usage non-negative constraint per spec §6

Spec §6 documents `Usage` token counts as non-negative integers, but
the fields were plain `int | None` and silently accepted negatives.
Add `Field(ge=0)` so a malformed wire response surfaces as
`provider_invalid_response` (the `_parse_response` Usage build wraps
the resulting `ValidationError`, matching the existing
`AssistantMessage` pattern).

Author: chris-colinsky

src/openarmature/llm/openai.py

@@ -42,6 +42,7 @@
 from typing import Any, cast
 
 import httpx
+from pydantic import ValidationError
 
 from .errors import (
     ProviderAuthentication,
@@ -273,17 +274,23 @@ def _parse_response(self, payload: dict[str, Any]) -> Response:
             raise ProviderInvalidResponse(f"could not parse assistant message: {exc}") from exc
 
         # Usage is optional — build a Usage with all-None fields if
-        # the provider didn't report it.
+        # the provider didn't report it. Per spec §6, token counts MUST
+        # be non-negative integers; a wire response that violates that
+        # surfaces as ``provider_invalid_response`` rather than
+        # silently passing through.
         usage_wire_raw = payload.get("usage")
-        if isinstance(usage_wire_raw, dict):
-            usage_wire = cast("dict[str, Any]", usage_wire_raw)
-            usage = Usage(
-                prompt_tokens=usage_wire.get("prompt_tokens"),
-                completion_tokens=usage_wire.get("completion_tokens"),
-                total_tokens=usage_wire.get("total_tokens"),
-            )
-        else:
-            usage = Usage(prompt_tokens=None, completion_tokens=None, total_tokens=None)
+        try:
+            if isinstance(usage_wire_raw, dict):
+                usage_wire = cast("dict[str, Any]", usage_wire_raw)
+                usage = Usage(
+                    prompt_tokens=usage_wire.get("prompt_tokens"),
+                    completion_tokens=usage_wire.get("completion_tokens"),
+                    total_tokens=usage_wire.get("total_tokens"),
+                )
+            else:
+                usage = Usage(prompt_tokens=None, completion_tokens=None, total_tokens=None)
+        except ValidationError as exc:
+            raise ProviderInvalidResponse(f"invalid usage record: {exc}") from exc
 
         return Response(
             message=assistant_msg,

src/openarmature/llm/response.py

@@ -18,7 +18,7 @@
 
 from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 
 from .messages import AssistantMessage
 
@@ -38,9 +38,9 @@ class Usage(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    prompt_tokens: int | None
-    completion_tokens: int | None
-    total_tokens: int | None
+    prompt_tokens: int | None = Field(ge=0)
+    completion_tokens: int | None = Field(ge=0)
+    total_tokens: int | None = Field(ge=0)
 
 
 class Response(BaseModel):

tests/unit/test_llm_provider.py

@@ -38,6 +38,7 @@
     Tool,
     ToolCall,
     ToolMessage,
+    Usage,
     UserMessage,
     validate_message_list,
     validate_tools,
@@ -434,3 +435,50 @@ def _ok(_req: httpx.Request) -> httpx.Response:
             assert actual_t == expected_t
     finally:
         await provider.aclose()
+
+
+# ---------------------------------------------------------------------------
+# Usage non-negative constraint (spec §6: "non-negative integer or None")
+# ---------------------------------------------------------------------------
+
+
+def test_usage_negative_token_count_rejected_at_construction() -> None:
+    with pytest.raises(ValidationError):
+        Usage(prompt_tokens=-1, completion_tokens=0, total_tokens=0)
+
+
+async def test_complete_negative_usage_surfaces_as_invalid_response() -> None:
+    """A wire response carrying a negative token count MUST surface as
+    ``provider_invalid_response`` rather than silently passing through —
+    spec §6 token counts are non-negative integers."""
+
+    def _bad(_req: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={
+                "id": "x",
+                "object": "chat.completion",
+                "created": 0,
+                "model": "m",
+                "choices": [
+                    {
+                        "index": 0,
+                        "message": {"role": "assistant", "content": "ok"},
+                        "finish_reason": "stop",
+                    }
+                ],
+                "usage": {"prompt_tokens": -5, "completion_tokens": 1, "total_tokens": 1},
+            },
+        )
+
+    provider = OpenAIProvider(
+        base_url="http://test",
+        model="m",
+        api_key="k",
+        transport=httpx.MockTransport(_bad),
+    )
+    try:
+        with pytest.raises(ProviderInvalidResponse, match="invalid usage record"):
+            await provider.complete([UserMessage(content="hi")])
+    finally:
+        await provider.aclose()