claude-code-chat-browser: Schema drift detection — mechanism to detect upstream Claude Code JSONL changes

[clean6378-max-it]

Calendar Day

Thursday, July 3, 2026 (PR 1 of 1)

Planned Effort

5 story points (Medium–High) — sprint item #5

Problem

The Claude Code JSONL format is append-only, version-dependent, and carries no published stability contract. When Anthropic ships a new Claude Code version that adds, renames, or restructures JSONL fields, this project has no mechanism to detect the change. The parser silently ignores unknown fields (safe) but also silently drops data from changed fields (not safe). Users may see incomplete or incorrectly rendered sessions without any indication that the upstream format has evolved.

Goal

One merged PR that fingerprints known JSONL field paths, warns on drift during parsing, surfaces a non-blocking UI banner, exposes a schema report endpoint/command, and commits a version-tracked schema_baseline.json with CI coverage.

Scope

Touch points

• utils/jsonl_parser.py — _collect_field_paths(record: dict) -> set[str] via recursive key traversal
• schema_baseline.json (new) — known (json_path, expected_type) pairs; committed to git
• Drift diff at parse completion — new paths → logging.warning() on claude_code_chat_browser.schema_drift; missing required paths → structural warning
• UI — dismissible amber banner on session list page for schema drift
• CLI command or GET /api/schema-report — returns {known_fields, new_fields, missing_fields}
• tests/fixtures/jsonl/unknown_field.jsonl — synthetic record with FutureToolXYZ tool type
• tests/ — CI test verifying warning is emitted for unknown field fixture

Out of scope

• Auto-updating schema_baseline.json on every parse (baseline updates are deliberate)
• Blocking parse on drift (warnings only)
• Tool dispatch registry changes (Tuesday scope)

Acceptance Criteria

• schema_baseline.json lists known field paths/types and is committed
• Parsing unknown field paths emits structured warning on claude_code_chat_browser.schema_drift logger
• Optional fields legitimately absent in some sessions do not trigger false-positive warnings
• Dismissible amber banner surfaces drift in the web UI (non-blocking)
• Schema report endpoint or CLI command returns known/new/missing field sets
• CI test with unknown_field.jsonl fixture verifies warning is emitted
• Full pytest, mypy --strict, and ruff pass
• PR approved by at least 1 reviewer

Verification

cd C:\Users\Jasen\CppAliance\claude-code-chat-browser
.\.venv\Scripts\Activate.ps1
pytest tests/ -k schema -q
pytest -q
mypy .

Manual: parse tests/fixtures/jsonl/unknown_field.jsonl — confirm warning logged and amber banner in UI.