cppa-cursor-browser: tighten Bubble abstraction with typed accessors and non-public raw field #128

Calendar Day

Wednesday, July 15, 2026 (PR 1 of 2 — Bubble boundary; land before PR 2)

Planned Effort

5 story points (Medium) — sprint item #4 (Test 5)

Companion PR: Wednesday PR 2 — raw-access de-duplication (#5). Both edit models/conversation.py + raw_access.py; sequence typing here, de-dup in #5.

Problem

The Bubble domain boundary is permeable. Bubble.raw: dict[str, Any] is public (L209); accessors return loosely-typed containers (metadata→dict[str, Any] L235–247, context L277–289, model_info L319–331, token_count L291–303, tool_results L375–387, relevant_files L249–261). models/raw_access.py free functions accept bubble: Any (L269, L284, L299, L221).

PR #94 added typed accessors + schema-drift logging but raw is still public and value types are still Any. mypy --strict (pyproject.toml L102–103) cannot enforce the domain boundary.

Goal

One merged PR making raw non-public, tightening accessor return types, and migrating call sites off direct .raw reads. Preserve PR #94 drift-warning philosophy (warn-don't-coerce).

Scope

Part A — Non-public raw

• Bubble.raw → private _raw + read-only accessor (or documented-internal).
• Repeat for Composer.raw / WorkspaceLocalComposer.raw as appropriate.
• Remove or funnel direct .raw[...] reads outside the model through accessors.

Part B — Tighten accessor return types

Where shape is known, replace dict[str, Any] / list[Any]:

• metadata → BubbleMetadataDict (or equivalent TypedDict)
• token_count → TokenCountDict | None
• model_info → ModelInfoDict
• context → BubbleContextDict
• relevant_files → list[str] (URIs)
• tool_results → concrete element type

Where full TypedDict is too heavy, at minimum concrete element types (e.g. list[str] not list[Any]).

Part C — Tighten raw_access.py signatures

• bubble_relevant_files, bubble_attached_file_uris, bubble_context, composer_headers — accept Bubble/Composer (or narrow union), not bare Any.

Part D — Preserve drift logging

• PR Add typed raw accessors with drift logging; migrate workspace tabs and resolver #94 schema-drift warnings unchanged.
• "Numeric-only createdAt, warn-don't-coerce" philosophy preserved (Composer.from_dict L51–60).

Acceptance Criteria

• Bubble.raw (and Composer/WorkspaceLocalComposer as appropriate) non-public.
• Accessor return types tightened (TypedDicts/concrete types).
• raw_access.py signatures tightened off bare Any.
• Direct .raw[...] reads outside model removed or funneled.
• Schema-drift logging preserved.
• mypy --strict green; CI green; PR approved.

Verification

cd C:\Users\Jasen\CppAliance\cppa-cursor-browser
.\.venv\Scripts\Activate.ps1
mypy --strict .
pytest -q
ruff check .