Protocols Audit (2026-05-10)¶

This audit inventories every Protocol class under src/synthorg/, captures usage signals, and classifies each into a recommended action. The follow-up cleanup work is filed as separate issues; this document is the reference baseline they hyperlink back to.

Tracker: #1850 sub-task I (audit only). The cleanup itself is intentionally out of scope of the PR that ships this document.

Methodology¶

Generated mechanically by scripts/protocol_audit.py; regenerate with uv run python scripts/protocol_audit.py from the repo root against the commit recorded by the date in the title above. The script walks src/synthorg/ for every class X(...Protocol...): definition and records:

• Path + line of the class X(Protocol) line.
• @runtime_checkable decorator presence.
• Direct-inheritance count (impl): number of files matching class \w+\(.*\b<Name>\b in src/synthorg/. Captures the explicit-subclass case; does not capture pure structural-subtyping implementations (Python's default for Protocols), so impl=0 is neutral, not a removal signal on its own.
• Test-usage count (testuse): occurrences of the protocol name in tests/. A protocol with testuse=0 is rarely consumed by name in the test surface.

The counts are deliberately approximate: they're a triage tool, not a removal lockbox. Every REMOVE recommendation in the per-area tables below is a flag, not a pre-approved deletion: each follow-up issue must re-verify usage at cleanup time.

Important caveat on impl=0. The script's regex matches only explicit class X(ProtocolName): inheritance; it cannot detect Pythonic structural implementations (classes that satisfy the Protocol by shape without inheriting), factory dispatch dicts that return Protocol-typed values, or default-impl injection patterns. In practice, most flagged REMOVE rows turned out to be real plug-in surfaces once re-grepped at cleanup time. The 2026-05-11 cleanup (issue #1864) hand-reviewed every REMOVE row and reclassified 44 of 46 candidates back to KEEP after finding structural impls in sibling files, factory wiring, or vendor-agnostic injection design. See the Post-cleanup status (2026-05-11) section below.

Classification rules¶

• KEEP: leave the protocol unchanged. Applies when:
• impl ≥ 1 (explicit subclass present), or
• the name ends in a known plug-in suffix (Strategy, Backend, Provider, Repository, Repo, Store, Bus, Subscriber, Sink, Handler, Verifier, Resolver, Detector, Adjuster, Mutator, Adapter, Authenticator, Capability, Hook, Trigger, Guard, Policy, Engine, Plugin, Aggregator, Selector, Reformulator, Compressor, Reranker, Retriever, Worker, Estimator, Classifier, Grader, Decomposer, Calculator, Formatter, Scorer, Source, Loader, Reader, Manager, Dispatcher), or
• explicit factory-mapping registration (e.g. _*_FACTORIES discriminated MappingProxyType), or

• testuse ≥ 3 (regularly consumed by name in test code, typically as a typed mock seam or fixture parameter).

• MAKE-RUNTIME-CHECKABLE: flag for promotion to @runtime_checkable. Applies when the protocol is used at a runtime isinstance site or registered through a factory mapping that should validate at registration. The audit lists these as review-at-cleanup-time: each candidate needs a quick grep for isinstance(.*<Name>) to confirm the runtime check exists. Without that confirmation, leave as KEEP.

• REMOVE: flag for removal. Applies when:

• impl = 0 AND testuse = 0 AND the name is not in a public extension surface (no plug-in suffix, no factory registration), and

• the only consumer is a single private module that could absorb the concrete shape directly.

• REVIEW: needs human eyeballs. Applies to the handful of _PrivatePrefixed typing seams whose intent isn't obvious from name alone.

Summary¶

The 2026-05-10 snapshot counts in the original table were aggregated by hand and undercounted both the REMOVE and REVIEW rows. The table below reflects (a) the per-area row totals as they actually appear in the snapshot tables, and (b) the post-2026-05-11 cleanup outcome captured in the "Post-cleanup status" section.

@runtime_checkable decoration: 209 of 250 (84%). The 41 without the decorator are listed inline below; absence is not a defect on its own; only a few need it.

Per-area classification¶

Tables sort by recommendation (REMOVE first, then REVIEW, then KEEP). rc is 1 when @runtime_checkable is present.

src/synthorg/api/¶

src/synthorg/approval/¶

src/synthorg/backup/¶

src/synthorg/budget/¶

src/synthorg/client/¶

src/synthorg/communication/¶

src/synthorg/core/¶

src/synthorg/engine/¶

src/synthorg/hr/¶

src/synthorg/integrations/¶

src/synthorg/memory/¶

src/synthorg/meta/¶

src/synthorg/notifications/, observability/, ontology/¶

src/synthorg/persistence/¶

All 45 persistence protocols are listed; every one is a plug-in Repository / Backend / Store / Capability per docs/reference/persistence-boundary.md, so they all classify as KEEP. No REMOVE candidates. The single anomaly is IsDuplicate (private internal seam, classified REVIEW).

src/synthorg/providers/¶

src/synthorg/security/¶

src/synthorg/settings/, telemetry/, templates/, tools/¶

Cleanup history¶

The dated per-issue cleanup trail (the #1864 / #1865 deletions and re-flagged keeps, the #1891 pluggable-subsystem decisions, the follow-up cleanup issues, and the collaborator protocols added by #2315 / #2316) lives in the companion Protocols Audit Cleanup Log. This page keeps the evergreen per-area classification; the log keeps the history of how it got there.

The hr/ promotion protocols (PromotionApprovalStrategy, PromotionCriteriaStrategy, ModelMappingStrategy) and the security/trust/ TrustStrategy rows above are retained as the 2026-05-10 snapshot record: those modules were deleted when the agent seniority/promotion/trust model was replaced by operator-set org modes, so authority now derives from the role reporting graph (core/authority.py) rather than a promotion ladder or an earned-trust tier.

Out of scope¶

• Actually deleting any Protocol class (cleanup PRs).
• Adding @runtime_checkable decoration anywhere (separate pass; needs isinstance(_, <Name>) site survey).
• Auditing test-only Protocol definitions (tests/).
• Auditing third-party / vendored protocols.