feat: version ai result schemas

README.md

@@ -43,7 +43,8 @@ Input can be either explicit messages:
 ```
 
 or compact `system` / `user` fields. The completed job result contains
-`content`, `model`, `usage` and `duration_ms`.
+`schema_version=ai.chat_result.v1`, `content`, `model`, `usage` and
+`duration_ms`.
 
 `call_analysis` and `transcript_summary` use the same input contract as
 `llm_chat`; callers may include domain metadata fields in `input`, but the
@@ -55,6 +56,9 @@ worker only reads chat fields such as `system`, `user`, `messages`,
 `/v1/audio/transcriptions` endpoint. The returned `segments` field stays
 compatible with telephony. If the provider returns one long segment, AI Service
 splits it into smaller transcript segments without inventing speaker labels.
+The completed job result contains
+`schema_version=ai.transcription_result.v1`, `provider`, `model`, `language`,
+`segments`, optional provider `attempts` and `duration_ms`.
 
 AI-server compose snippet for Whisper Large v3 lives in
 `deploy/ai-server/docker-compose.audio.yml`:
@@ -110,6 +114,20 @@ explicitly retryable categories while attempts remain.
 Domain services may still expose manual retry for terminal errors after the
 underlying data or prompt is corrected.
 
+## Result schemas
+
+AI Service result payloads are versioned with `schema_version`. Consumers should
+ignore unknown fields and reject only unsupported major schema names.
+
+Current schemas:
+
+- `ai.chat_result.v1`: `{schema_version, content, model, usage?, duration_ms}`.
+- `ai.transcription_result.v1`:
+  `{schema_version, provider?, model?, attempts?, language, segments, duration_ms}`.
+
+New optional fields may be added to a `v1` schema without a breaking change.
+Breaking shape changes require a new schema name.
+
 ## Configuration
 
 - `HTTP_HOST`, default `0.0.0.0`