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/¶

Post-cleanup status (2026-05-11)¶

Issue #1864 hand-reviewed every REMOVE row below. The verification protocol was: (1) re-grep the protocol name across src/synthorg/ and tests/, (2) inspect sibling files in the same directory for structural impls, (3) confirm whether a factory dispatch dict / config discriminator / multi-slot injection / vendor-agnostic design exists. The script's impl=0 reliably under-counts these patterns.

Deleted (2 protocols)¶

The script's classification matched reality: zero structural impls, zero consumers (or single-file Callable seam).

Audit re-flagged to KEEP (44 protocols)¶

Each retained protocol carries a one-line # <reason> design-rationale comment immediately above the class line describing the implementations, factory dispatch, and consumer wiring that justify keeping it. The categories below explain the structural patterns the audit script's regex missed; the in-code comments name the concrete impls/factories/consumers so future readers can verify the wiring without re-running the audit.

Categories of re-flag rationale:

1. Multiple structural impls in the same file or sibling file (impl count missed by the regex). Examples: ConfidenceFormatter (4 impls + _FORMATTERS factory in same file), ImpactScorer (3 impls), StrategicContextProvider (2 impls), CostTierResolver (2 impls + factory), ShadowTaskProvider (2 impls in shadow_providers.py), TimestampProvider (2 impls in same file), TraceHandler (NoopTraceHandler in same file + OtlpTraceHandler in sibling), TrustStrategy (4 strategy files + 117 test occurrences), 9 of 10 hr/ candidates (impl files named *_strategy.py), LocalModelManager (OllamaModelManager in same file).

2. Factory or registry dispatch that the script's regex cannot see. Examples: ConnectionAuthenticator (registry in connections/types/__init__.py), ConnectionHealthCheck (_CHECK_REGISTRY in prober.py), CaptureStrategy/PropagationStrategy/PruningStrategy (each backed by a per-area factory.py with 3 impls), OntologyInjectionStrategy (injection/factory.py), RiskTierClassifier (timeout/factory.py + engine/_security_factory), SandboxLifecycleStrategy (create_lifecycle_strategy config-discriminated factory with 3 impls).

3. Default-impl injection with safe fallback. Examples: MemoryArchivalStrategy (FullSnapshotStrategy default + OffboardingService injection), TaskReassignmentStrategy (QueueReturnStrategy default), AutonomyChangeStrategy (HumanOnlyPromotionStrategy), ReviewStage (ClientReviewStage + InternalReviewStage walked by ReviewPipeline), OutcomeStore, ConfidenceAdjuster, CIValidator, AnalyticsEmitter/Collector/RecommendationProvider (full telemetry trio with meta/telemetry/factory.py), DriftDetectionStrategy (LayeredDriftDetector), StepQualityClassifier (RuleBasedStepClassifier).

4. Vendor-agnostic public extension surface (no built-in impl by design; consumed via injection from MCP / user / external integration). Examples: JudgeEvaluator (debate/hybrid LLM judge), WebSearchProvider (threaded through tools/factory.py at 4 callsites), ShadowAgentRunner (production wires to AgentEngine.run via caller-supplied adapter), TunnelProvider (ngrok/cloudflared abstraction wired via IntegrationsBundle), OrgInflectionSink and AlertSink (downstream observability hooks).

5. Multi-impl injection points missed by the audit doc's own duplicate detection. ParticipantResolver@meeting/participant.py:56 was flagged as a "dead duplicate" of an alleged twin in meeting/protocol.py; the twin does not exist. The participant.py copy has 2 impls (PassthroughParticipantResolver, RegistryParticipantResolver) in the same file and 3 test files.

Issue #1865 outcomes (REVIEW pass + duplicate folds)¶

Issue #1865 closed out the 11 REVIEW rows, which cover 12 protocol names: 9 _PrivatePrefixed typing seams (the engine/coordination/dispatcher_types.py row lists 2 names in one snapshot entry), the non-prefixed IsDuplicate predicate in persistence/_shared/audit.py, and the 2 duplicate-named-pair REVIEW rows. The 5 retained protocols each carry a one-line # <reason> rationale comment naming the consumer that justifies the seam; the 7 deletions (5 single-consumer seam collapses plus 2 duplicate-pair folds) collapsed single-consumer seams or removed pure dead code.

Retained with rationale (5 protocols)¶

Each gets a one-line # <reason> design-rationale comment immediately above the class line.

Deleted (7 protocols)¶

Recommended next pass for scripts/protocol_audit.py¶

A follow-up issue should teach the audit script to (a) consult a manual override file (e.g. data/protocols_audit_overrides.yaml) keyed on path:line:name so KEEP decisions made here survive future regenerations, and (b) detect structural impls heuristically (same-file class X: siblings whose method names match the Protocol's, factory return type annotations) to reduce false-positive REMOVE flags.

Follow-up issues¶

The REMOVE and REVIEW candidates above are filed as separate cleanup issues against this audit doc. Each issue must re-verify usage at cleanup time; a REMOVE flag here is not pre-approval to delete. Per-area issue titles:

• [CLEANUP] Protocols audit follow-up: REMOVE pass for hr/
• [CLEANUP] Protocols audit follow-up: REMOVE pass for meta/chief_of_staff/ + meta/telemetry/
• [CLEANUP] Protocols audit follow-up: REMOVE pass for engine/strategy/ + engine/quality/ + engine/review/
• [CLEANUP] Protocols audit follow-up: REMOVE pass for memory/procedural/
• [CLEANUP] Protocols audit follow-up: REMOVE pass for security/ + integrations/connections/health/tunnel/ + ontology/ + tools/sandbox/web_search
• [CLEANUP] Protocols audit follow-up: REVIEW pass for _PrivatePrefixed typing seams
• [CLEANUP] Protocols audit follow-up: fold duplicate-named protocols (ConflictDetector, SignalAggregator)
• [CLEANUP] Protocols audit follow-up: meta-tracking issue umbrella

Each issue body links back to the specific rows in this document and requires the owner to (a) re-grep, (b) confirm no future-second-implementation plan, (c) collapse the consumer onto a concrete type or fold the duplicate.

Post-#1891 status (RFC: pluggable subsystem cleanup)¶

Issue #1891 ran a per-candidate keep / inline / refactor decision against the eight subsystems flagged as adding indirection without polymorphism, or sitting on the wrong dimension. Each decision is reflected in code; the eight commits live on refactor/pluggable-subsystem-cleanup.

Collaborator protocols added by #2315¶

Issue #2315 added six @runtime_checkable structural Protocols that decouple high-fan-in consumers from concrete collaborators (so the real class and the test doubles both satisfy a declared contract). They are consumer-decoupling seams, KEEP by design intent, and each is covered by tests/unit/_core/test_protocol_conformance.py. They postdate the 2026-05-10 snapshot above and are recorded here rather than in the historical per-area tables.

Collaborator protocols added by #2316¶

The api forward-ref hoist added three @runtime_checkable structural handles in workers/distributed_protocols.py. They give the construction-phase Phase1Result (in api/auto_wire_phase1.py) and the RuntimeStateSlice (in workers/state.py) a runtime-resolvable annotation for the optional synthorg[distributed] concrete types without importing them (those sit in the workers.config -> communication.config cold-import cycle). The real objects satisfy them structurally; KEEP by design intent.

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.