claude-code-chat-browser: Add JSONL parser fuzz tests and macos-latest CI matrix

[clean6378-max-it]

Calendar Day

Wednesday, June 11, 2026

Planned Effort

8 story points (one PR) — combines sprint items #4 + #6:

Sprint item	Points	Topic
#4	5	Fuzz/adversarial testing for JSONL parser
#6	3	macOS CI in matrix

Depends on:

• Monday #1 — ruff + pip-audit job must run on macos-latest once matrix expands
• Tuesday #3 — narrowed TypedDicts define fuzz oracle (merge TypedDict PR before fuzz PR)

Out of scope: performance benchmarks (Thursday #7), frontend changes, parser API redesign.

Problem

1. Verification gap: ~4,500 lines of tests cover known-good JSONL and fixtures, but no fuzz or adversarial testing targets utils/jsonl_parser.py. Schema drift from upstream Claude Code is discovered via user reports, not CI.
2. Portability gap: CI runs on ubuntu-latest and windows-latest (Week 1) but not macos-latest, despite macOS setup docs and POSIX fcntl locking that differs from Windows msvcrt.

Goal

One merged PR that:

1. Adds Hypothesis fuzz tests proving parse_session does not crash on adversarial inputs.
2. Extends the CI matrix to macos-latest for all cross-platform test jobs (and Monday’s lint/audit job).
3. Keeps fuzz CI runtime under ~60 seconds via bounded example counts.

Scope

A — Fuzz / adversarial tests (5 pt)

Touch points: requirements-dev.txt, tests/test_parser_fuzz.py (new), optional tests/conftest.py / pyproject.toml Hypothesis profile, utils/jsonl_parser.py (fixes only if fuzz exposes bugs)

• Add hypothesis>=6.100.0 to dev dependencies.
• Create tests/test_parser_fuzz.py targeting parse_session(filepath) via temp .jsonl files.

Required strategy coverage:

Category	Approach
Malformed JSON lines	Random text lines, invalid JSON
Truncated lines	Partial JSON (concurrent-write simulation)
Unknown record types	type not in user/assistant/system/progress
Missing / extra fields	st.fixed_dictionaries with optional keys removed or added
Deep nesting	Recursive JSON dict/list strategies
Long lines	10k–50k char payloads inside JSON
Empty lines	Blank lines between records
Null bytes	Binary-safe write + UTF-8 decode with errors="replace"

Invariants:

• parse_session must not raise unhandled exceptions for any fuzzed file input.
• Acceptable: normal SessionDict return; skipped malformed lines (existing behavior).
• If SessionValidationError or similar structured errors appear, either harden processors or document as allowed — prefer hardening so fuzz passes cleanly.

Required explicit adversarial test:

• Unknown type value (e.g. totally-new-claude-record) plus one valid user line → session parses, entry_counts reflects unknown type, no crash.

CI budget:

• @settings(max_examples=200) per strategy (tune down if needed).
• CI profile via conftest.py when CI=true (e.g. max_examples=100).
• Full fuzz module should complete in < 60s on ubuntu-latest.

Ground truth for structured strategies: tests/test_jsonl_parser.py, parametrized tool fixtures, Tuesday TypedDict unions in models/.

B — macOS CI matrix (3 pt)

Touch points: .github/workflows/ci.yml, README.md or CONTRIBUTING.md

Add macos-latest to strategy.matrix.os for:

Job	macOS?
pytest	yes
integration-tests	yes
js-tests	yes
lint-and-audit (Monday)	yes
mypy	no (ubuntu-only)
prod-install-smoke	no (bash heredoc)

Requirements:

• All existing tests pass on macOS without new platform skips (unless genuine difference documented).
• fcntl.flock export lock path exercised on macOS (existing tests/test_export_state_store.py should suffice).
• Monday ruff + pip-audit steps pass on macOS runner.
• macOS job time ≤ 2× Ubuntu job (monitor first run; optimize example count if needed).

Docs: Note three-platform CI in README or CONTRIBUTING.

Acceptance Criteria

Fuzz (#4)

• tests/test_parser_fuzz.py exists using Hypothesis
• Strategies cover all categories listed in scope
• Parser does not raise unhandled exceptions on fuzzed inputs
• At least one adversarial test for unknown type with graceful degradation
• Fuzz tests run in CI with bounded iteration count; total fuzz time < ~60s on Ubuntu
• pytest -q passes locally and in CI

macOS CI (#6)

• macos-latest in CI matrix for pytest, integration, js-tests, lint-and-audit
• All tests pass on macOS without undocumented skips
• fcntl locking path verified on macOS CI
• ruff + pip-audit green on macOS
• README or CONTRIBUTING documents cross-platform CI

General

• mypy and ruff check . pass
• PR approved by at least 1 reviewer