[#20] refactor: ContentSource/FetchResult as tagged unions

[VGonPa]

Summary

Refactor ContentSource and FetchResult from "single class with optional fields" into pydantic discriminated unions, so success and failure are mutually exclusive variants enforced by both the runtime (pydantic) and the type system (mypy with the pydantic.mypy plugin).

• ContentSource = Annotated[Union[ContentSourceSuccess, ContentSourceFailure], BeforeValidator(...), Field(discriminator="outcome")]
• FetchResult = FetchSuccess | FetchFailure (in-memory only, not persisted)
• Wire-compatible discriminator: outcome: "success" | "failure"
• Backward-compatible deserialisation: legacy ok: bool records in existing data/items.json are normalised on read by a BeforeValidator on the union — no manual migration command required.
• Every consumer (fetch.py, fetch_x.py, extract/threads.py, generate.py, worksheet.py, executors/api.py, notes_io.py) now switches on the variant via isinstance instead of reading optional sentinel fields.

Closes #20.

Decisions on the four open questions (from the PRD)

1. Discriminator field name: outcome ("success" / "failure"). kind was taken by ContentSource.kind (external_article / x_article / …); ok as a literal was ambiguous next to its legacy boolean meaning. outcome is self-documenting in the JSON.
2. JSON wire compat for legacy records: A BeforeValidator wraps the discriminated union. It maps ok=True → outcome="success" (and drops failure-only fields), ok=False → outcome="failure" (and drops success-only fields). Legacy records with ok=False, failure_reason=None (one such record in Víctor's data/items.json — an HTTP 429) bucket to failure_reason="timeout", which preserves the fetch: retry transiently-failed items without --force #19 "auto-retry uncategorised failures" behaviour without an extra branch in _should_refetch. Round-trip verified against the real 1884-item corpus: 274 success + 43 failure sources, all migrated.
3. mypy enforcement: Enabled pydantic.mypy plugin (with init_typed = true, init_forbid_extra = true). A tests/type_probes/illegal_states.py probe contains four annotations that MUST be mypy errors; tests/test_type_safety.py shells out to mypy and asserts all four fire. This pins the "illegal states unrepresentable" invariant against future edits.
4. Content (wrapper): Not a discriminated union. It carries sources: list[ContentSource]; the inner type splits, the outer wrapper does not need to.

Quality gate

• Tests: 346 pass (up from 288 pre-fetch: retry transiently-failed items without --force #19, plus the post-rebase fetch: retry transiently-failed items without --force #19 truth-table tests rewritten to use the new variants).
• Coverage: 89% (above 78% threshold).
• Mypy: clean on src/xbrain (28 source files).
• Ruff, ruff-format, bandit, detect-secrets, interrogate: PASS.
• Vulture, radon: PASS / WARN (no new C grades; the existing one carries over).
• Deptry: WARN-only (pre-existing browser_cookie3 note).

Interaction with #19

origin/develop already carries #19's _should_refetch helper (merged before this branch was rebased). The helper was adapted to the new variant shape:

return all(
    isinstance(src, ContentSourceFailure)
    and src.failure_reason in _TRANSIENT_FAILURES
    for src in external
)

Behaviour is preserved bit-for-bit, including the "uncategorised failures get one auto-retry" semantic — that case is now satisfied at the data layer (legacy records migrate None → "timeout") rather than via a special branch in _should_refetch. All eight _should_refetch truth-table tests and the four fetch_pending integration tests pass after the rewrite.

Test plan

• uv run poe check — all 10 critical checks green
• Legacy items.json round-trip on real data (1884 items, 317 sources) — round-trip equality preserved
• mypy probe rejects the four illegal annotations (verified by tests/test_type_safety.py)
• All 346 tests pass, including the 13 new model / store / type-safety tests and the rebased fetch: retry transiently-failed items without --force #19 truth-table tests
• Manual: run xbrain generate after upgrade against a real data/items.json, diff the wiki — byte-identical output expected

🤖 Generated with Claude Code

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