Skip to content

chore: document type system conventions + enforce ABC/Protocol rules (AC-492)#590

Merged
jayscambler merged 2 commits intomainfrom
chore/standardize-abc-protocol
Mar 31, 2026
Merged

chore: document type system conventions + enforce ABC/Protocol rules (AC-492)#590
jayscambler merged 2 commits intomainfrom
chore/standardize-abc-protocol

Conversation

@jayscambler
Copy link
Copy Markdown
Contributor

Summary

Documents the type system conventions that emerged from the cleanup sweep and adds contract tests to enforce them going forward.

Changes

CONTRIBUTING.md — new "Type System Conventions" section

Codifies the conventions already established by PRs #576-589:

  • ABC vs Protocol — ABC for internal hierarchies with shared implementation, Protocol for duck-typed external integration points
  • Dict typesdict[str, Any] as sole convention (not dict[str, object]), prefer TypedDict for known shapes
  • Collection paramsSequence[X] for read-only list params, Mapping[str, X] for read-only dict params
  • Type aliasesLlmFn, StrEnum import style, logger naming

test_interface_conventions.py — 2 contract tests

  1. test_protocols_do_not_use_abstractmethod — Protocol classes shouldn't have @abstractmethod (it's redundant for structural typing)
  2. test_abc_classes_have_abstractmethod — ABC classes must have at least one @abstractmethod (otherwise use Protocol)

Both tests pass on current code — the convention is already followed.

Verification

  • ruff check src — all checks passed
  • mypy src — zero errors
  • pytest tests/ — all tests pass (including 2 new convention tests)

Issue

Resolves AC-492

…(AC-492)

Added 'Type System Conventions' section to CONTRIBUTING.md covering:
- ABC vs Protocol boundaries
- dict[str, Any] as sole dict convention
- Sequence/Mapping for read-only params
- LlmFn type alias
- StrEnum import style
- Logger naming

Added test_interface_conventions.py with 2 contract tests:
- Protocols don't use @AbstractMethod (redundant)
- ABC classes have at least one @AbstractMethod

Current codebase already follows the convention — tests pass on existing code.

2 files changed
@linear
Copy link
Copy Markdown

linear bot commented Mar 31, 2026

@jayscambler jayscambler merged commit 35f3073 into main Mar 31, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant