Repository navigation
Description
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.rawas 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 | Nonemodel_info→ModelInfoDictcontext→BubbleContextDictrelevant_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— acceptBubble/Composer(or narrow union), not bareAny.
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_dictL51–60).
Acceptance Criteria
-
Bubble.raw(andComposer/WorkspaceLocalComposeras appropriate) non-public. - Accessor return types tightened (TypedDicts/concrete types).
-
raw_access.pysignatures tightened off bareAny. - Direct
.raw[...]reads outside model removed or funneled. - Schema-drift logging preserved.
-
mypy --strictgreen; CI green; PR approved.
Verification
cd C:\Users\Jasen\CppAliance\cppa-cursor-browser
.\.venv\Scripts\Activate.ps1
mypy --strict .
pytest -q
ruff check .
Activity