Phased migration away from custom abstracts framework (implementer, abstraction, interface)

[phlax]

A phased plan for migration off the current custom abstracts (implementer, interface, abstraction) to a smaller, safer and more maintainable model that uses the stdlib abc+salvaged helpers.

Phase 1: Fix current abstracts issues

• Fix early return in add_docs (should be continue)
• Fix (or document+test) precedence direction in implementation_info
• Fix misleading TypeError message in abstract_info
• Correct @implementer return annotation and update affected call sites for better type safety
• Add/fix test for synthetic subclass oddities (slots, qualname, pickling)
• Encourage use of explicit class-keyword path over decorator (do not deprecate yet)

Phase 2: Add abstracts2

• New module that:
  • Exposes Abstraction, Interface as subclasses of abc.ABC
  • Provides @implements decorator (does no synthetic subclassing — mutates class directly; can replace both the decorator and class-keyword forms)
  • Offers interfacemethod helper that raises always (like today, but less magical)
  • Exposes provides(obj, iface) and implementations(iface) as future hooks for adapter/lookup registry
  • Has a trivial stub resolve(obj, iface) (identity if isinstance, else LookupError) — but signature and import are reserved for future use
• Tests to validate that all testable discipline enforced in current abstracts can be replicated by abstracts2+unittest

Phase 3: Migrate consumers

• Switch internal packages to import from abstracts2 (can be codemodded as most usage is mechanical)
• Clean up any use of the decorator form that relies on synthetic class (resolve test breakage for pickling, qualname, slots etc)
• Any places that need true adapter semantics can switch to using resolve() but this is not required in the migration plan

Phase 4 (later): Deprecate legacy abstracts

• Alias old abstracts to new API with DeprecationWarning
• Optionally remove after downstreams have migrated

---

Ticket is to plan and coordinate the migration (sub-issues can track each phase).