brain-of-reese/.agents/phases/todo/158_thinking_timeline/01_schema_segments.md

Task 01 — the validated ChatMessage.segments field (server)

Phase: 158_thinking_timeline · Story: n/a

Objective

Saved-chat writes accept the new optional segments array (a discriminated thinking/tool union with phase-83-style caps), omit it when absent so pre-phase records round-trip byte-identically, and reject malformed values at the extra="forbid" boundary.

Work

1. app/schemas.py:
   • ChatThinkingSegment (a BaseModel, beside ToolCall): kind: Literal["thinking"], text: str = Field(min_length=1, max_length=32_000) (HistoryTurn's cap, phase 83 — docstring cross-reference).
   • ChatToolSegment (a BaseModel): kind: Literal["tool"] + the EXACT ToolCall field set (name / argument / offset / limit / path / truncated / chars_shown / chars_total with their existing types and caps — mirror, do not weaken; docstring cross-references ToolCall as the shape source).
   • ChatSegment = Annotated[Union[ChatThinkingSegment, ChatToolSegment], Field(discriminator="kind")].
   • ChatMessage.segments: list[ChatSegment] | None = Field(default=None, max_length=50) — with the phase-83 voice comment (the cap sizing: far past any realistic turn — the round cap is 10 → ≤ 20 entries; 50 matches the tools cap).
   • The EXISTING wrap serializer (_drop_image_when_absent) gains the omission rule: after the two image pops, if self.segments is None: data.pop("segments", None) — ABSENT, never null (the phase-50 round-trip contract; the phase-122 SourceRef.image_url omission precedent, the phase-113 lesson applied up front: the field EXISTS so the boundary does NOT 422 the done-time auto-save carrying it).
   • The ChatMessage docstring gains the phase-158 paragraph (the shape, the omission rule, the extra="forbid" boundary) in the established voice; HistoryTurn and everything in app/rag/ is UNTOUCHED (the history wire stays {who, text, thinking}).
2. NO migration, NO router change (app/api/chats.py validates through ChatMessage — m.model_dump() + ChatMessage.model_validate(m) already carry the new field end to end, including the public shared read SharedChatOut.messages).

Testing & Quality

• Integration (extend tests/integration/test_chats_api.py — the file already pins the brain-record contract, phase 83/113/120/123/124):
  • a record WITH segments (one thinking entry + two tool entries carrying every additive field: offset/limit, path, truncated/chars_shown/chars_total) is accepted by POST /api/chats and round-trips through GET (the shape preserved, entry order preserved);
  • segments with 51 entries → 422; a thinking-segment text of 32 001 chars → 422; a segment with kind: "bogus" → 422; a record with a stray top-level key (e.g. "foo": 1) still → 422 (the extra="forbid" boundary intact);
  • a record WITHOUT segments (a pre-phase brain record, the full phase-113 shape) round-trips with the key ABSENT from the served JSON (never null — the byte-identity pin, the phase-50 contract);
  • the shared read path (the public read endpoint's messages) carries the segments of a saved record with them (the public shape, the phase-51 contract).
• Coverage: >90% on this task's new/modified code (the schema code is exercised by the integration tests).

Completion Criteria

• the three models + the field + the serializer rule land exactly as designed (a source check)
• the new integration tests are green; the EXISTING test_chats_api.py tests stay green unchanged
• uv run pytest tests/integration -q green; uv run ruff check . && uv run pyright clean
• no change in app/rag/, no migration, no router change (a git diff --stat scoped check)