docs: fix 6 contradictions from CONTRADICTIONS_REPORT_20260627 (C5/C6/C17/C19/C2)

Six fixes for the c11_python doc sync (chronology row 3):

- C5 (Result notation): Result[str, ErrorInfo] -> Result[str] at
  docs/guide_ai_client.md lines 452 + 469; also error_handling.md
  line 801 (historical deprecation section).
- C6 (RAGChunk schema): docs/guide_models.md lines 343-349 corrected
  to match src/rag_engine.py:19-25 (id, document, path, score, metadata).
- C17 (type_aliases.md table): rewrote alias table to reflect post-2026-06-25
  reality (Metadata is @dataclass(frozen=True, slots=True) with 36 fields;
  11 per-aggregate dataclasses listed with source locations; removed
  stale 'underlying type is dict[str, Any]' claim at line 73 + the
  'keep Metadata as dict[str, Any]' claim at line 81).
- C19 (OBLITERATE principle): added 'OBLITERATE Principle' section to
  error_handling.md after Migration Playbook; clarified in Hard Rules
  that argument types that may be None (caller choice) are NOT banned.
- C2 (audit script name): docs/AGENTS.md references updated to point
  to scripts/audit_optional_returns.py (the all-src/ successor to
  scripts/audit_optional_in_3_files.py).

Also: docs/reports/CONTRADICTIONS_REPORT_20260627.md — the contradictions
index that drives these fixes. Kept for reference.

C16 + C18 were already addressed in commit 770c2fdb (python.md §10
Documented Exceptions table + §17.10 audit inventory).
This commit is contained in:
ed
2026-06-26 09:24:38 -04:00
parent 770c2fdb32
commit a101d34656
6 changed files with 426 additions and 38 deletions
+3 -2
View File
@@ -449,7 +449,7 @@ canonical reference is
All `_send_<vendor>_result()` functions (8 vendors: Gemini, Anthropic,
DeepSeek, MiniMax, Gemini CLI, Qwen, Llama, Grok — plus the
`_send_llama_native` Ollama adapter) return `Result[str, ErrorInfo]`. SDK
`_send_llama_native` Ollama adapter) return `Result[str]` with `errors: list[ErrorInfo]`. SDK
exceptions are caught at the boundary (`src/openai_compatible.py`,
`src/qwen_adapter.py`) and converted to `ErrorInfo` dataclasses. The
`_classify_<vendor>_error()` functions return `ErrorInfo` (not raise
@@ -466,7 +466,8 @@ meaning — do not overload `UNKNOWN` when a new failure mode surfaces
### Public API
- **`ai_client.send(...)`** — the public API. Returns
`Result[str, ErrorInfo]`. Accepts 13+ parameters including 8 callbacks.
`Result[str]` (with `errors: list[ErrorInfo]` as a side-channel field).
Accepts 13+ parameters including 8 callbacks.
Internally calls `_send_<vendor>()` for the active provider (the
vendor functions return `Result[str]` directly).