Post-#1002 structure campaign: collapse single-impl Protocol seams and dict-shaped boundaries

[phernandez]

The adversarial review of #1002 produced ~40 design findings that were deliberately deferred from the merge (the review itself rated them non-blocking). The correctness work is done; this tracks the structural cleanup as one campaign so it doesn't dissolve into drive-by refactors.

Categories (per-finding detail in the review artifact / PR threads):

• Over-abstraction (~16): single-implementation Protocol + Default dataclass + build_default factory towers (accepted-note repositories, read-repair capability lattice ~20 Protocols, note-content reconciler chain, ProjectDeleteRepositories, index-file metadata source tower). ~211 Protocol classes remain; the interim collapse waves removed ~15.
• Type honesty (~10): object-typed protocol properties re-validated with isinstance/str() at consumers; residual cast(AcceptedNoteMutationChange, ...) sites; int | str | None project ids.
• Boundary validation (~6): dict[str, object] HTTP payloads hand-serialized where Pydantic models exist (directory-delete response, project-delete acceptance, read-repair response).
• Control flow (3): six repositories or build_default_...() hidden fallbacks in accepted_note_write_runner; move-eligibility rule duplicated between change_planning and the snapshot; 175-line apply_project_index_move_batch without section headers.
• Layering (2): repository→indexing and models→runtime upward imports; runtime/indexing/index three-way split with duplicated module basenames.
• Helper sprawl (2): _session_scope re-implemented in five services with divergent semantics.

Several are interlocking (fixing the object-typed properties shrinks three others; collapsing the repository towers kills much of the Protocol count) — worth sequencing rather than parallelizing.

🤖 Generated with Claude Code

[claude]

Claude finished @phernandez's task in 1m 43s —— View job

---

Triage complete

• Read issue and gather context
• Classify issue type/priority/component/complexity
• Check for duplicate issues
• Apply labels
• Post triage summary

Classification

• Type: Enhancement — architectural/structural cleanup (tech-debt reduction), not a bug or new feature. No refactor/tech-debt label exists in this repo, so applied enhancement as the closest fit.
• Priority: Medium — the underlying refactor(core): add shared runtime orchestration #1002 review explicitly rated all ~40 deferred findings as non-blocking; this is quality-of-structure work, not a functional defect.
• Component: Doesn't map cleanly to the CLI/MCP/database/cloud/docs/testing split — it spans repository/, models/, sync/, and internal runtime/indexing layering across the core package. No component label applied since none fit without being misleading.
• Complexity: Complex — six categories of findings (~40 total) across over-abstraction, type honesty, boundary validation, control flow, layering, and helper sprawl. The issue itself notes several are interlocking and recommends sequencing rather than parallelizing, which rules out a single mechanical PR.

Labels applied

• enhancement

Note: this repo's actual label set (bug, cloud, documentation, enhancement, needs investigation, On Hold, python, v1.0, validated) doesn't include the priority/component/complexity taxonomy (medium, complex, mcp, cli, etc.) referenced in the triage instructions, so those couldn't be applied as labels — captured above as classification text instead.

Duplicate check

Searched for related open/closed issues (single-impl Protocol, over-abstraction, Protocol collapse) — no duplicates found. This tracking issue is the first to consolidate the deferred #1002 review findings.

On implementation

This issue is a tracking/campaign issue, not a request for a specific code change — it explicitly says the correctness work is done and this just tracks future structural cleanup, recommending the ~40 findings be sequenced rather than parallelized or tackled in one shot. Given that, I haven't attempted to implement any of the collapses here. Recommend breaking this into individual issues/PRs per category (or per interlocking cluster, as noted: object-typed properties → shrinks 3 other findings; repository tower collapse → kills much of the Protocol count) so each can be reviewed and landed independently. Happy to pick up a specific sub-item if one is opened or referenced directly.