chore(api): canon log follow-ups — hardening, unified 422, contract doc

- canon_log.py: stringify jsonschema error-path segments before sorting so a
  future schema mixing array indices and object keys can't TypeError (#1)
- main.py: RequestValidationError handler reshapes pydantic body failures into
  the same {"detail": {"canon_log_errors": [...]}} envelope as schema failures,
  so the client parses ONE 422 shape (#2a) + tests
- pytest.ini: filter the starlette/httpx TestClient deprecation → pristine output (#4)
- docs/canon-log.md: living contract for the client (Plan B) — schemas, the §7
  boundary, the unified error envelope, per-role injection (#3)

Full suite 26 passing, 0 warnings.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

api/app/canon_log.py

@@ -38,7 +38,9 @@ def _validator(schema_name: str) -> Draft202012Validator:
 
 def validation_errors(doc: dict, schema_name: str) -> list[str]:
     validator = _validator(schema_name)
-    return [e.message for e in sorted(validator.iter_errors(doc), key=lambda e: list(e.path))]
+    # Stringify path segments before sorting: a path can mix str property names
+    # and int array indices, which are not orderable against each other.
+    return [e.message for e in sorted(validator.iter_errors(doc), key=lambda e: [str(p) for p in e.path])]
 
 
 def validate_origin(doc: dict) -> list[str]:

api/app/main.py

@@ -7,6 +7,8 @@ Prompt routing, model selection, and logging land later.
 """
 
 from fastapi import Depends, FastAPI, HTTPException
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 
 from .canon_log import validate_canon_log
@@ -14,6 +16,16 @@ from .canon_log import validate_canon_log
 app = FastAPI(title="coc-rpg proxy", version="0.0.1")
 
 
+@app.exception_handler(RequestValidationError)
+async def unify_validation_errors(request, exc: RequestValidationError) -> JSONResponse:
+    """Reshape pydantic body-validation failures into the same envelope as a
+    canon-log schema failure, so the client parses ONE 422 shape (charter §11):
+    {"detail": {"canon_log_errors": [...]}}.
+    """
+    errors = [f"{'.'.join(str(loc) for loc in e['loc'])}: {e['msg']}" for e in exc.errors()]
+    return JSONResponse(status_code=422, content={"detail": {"canon_log_errors": errors}})
+
+
 class TurnRequest(BaseModel):
     canon_log: dict