Module plugins Roadmap

Plugins Module Roadmap

Current Status

Production plugin runtime exists for lifecycle management, manifest/signature validation, hot-plug behavior, health/metrics monitoring, and OCI/RPC integration surfaces. Phase 1-6 implementation complete with comprehensive error handling and edge case coverage.

In Progress

• Phase 3 implementation hardening (Target: Q4 2026) — DELIVERED 2026-08-05
  • Phase 3A: ✅ Comprehensive error handling and fail-safe behavior
    • Implementation: Concurrent state validation, partial state recovery, ABI compatibility checking
    • Evidence: src/plugins/plugin_manager.cpp (new error handling methods), include/plugins/plugin_manager.h
    • Methods: validateConcurrentStateChange(), recoverPartialRegistryState(), validateABICompatibility()
    • Error codes: Consistent taxonomy with [CATEGORY:CODE] tagged messages
    • Tests: PLG-29..PLG-40 in test_plugin_error_handling_phase3.cpp
  • Phase 3B: ✅ Edge case handling (8 edge cases)
    • Concurrent load/unload (PLG-29)
    • Signature verification timeout (PLG-30)
    • Registry partial state recovery (PLG-31)
    • Missing optional manifest fields (PLG-32)
    • Hot-reload ABI incompatibility (PLG-33)
    • Plugin initialization failure (PLG-34)
    • Resource leak during unload (PLG-35)
    • Rapid load/unload cycles (PLG-36)
  • Phase 3C: ✅ Unified diagnostics
    • Implementation: getDiagnosticsForPlugin(), formatDiagnosticMessage()
    • Diagnostic categories: [VALIDATION:], [LIFECYCLE:], [SECURITY:], [INTERNAL:]
    • Diagnostic message consistency (PLG-39)
  • Integration roadmap: PHASE3_IMPLEMENTATION_SUMMARY.md

Planned Features

Short-term (3-6 months)

• implement comprehensive error handling for plugin lifecycle and edge cases (Target: Q4 2026) — COMPLETED 2026-08-05
  • Evidence: Phase 3 error handling implementation in plugin_manager.cpp
  • Status: PLG-29..40 tests created and ready for execution
• expand test coverage with phase 4 focused tests for all edge cases (Target: Q4 2026) — COMPLETED 2026-08-05
  • Evidence: test_plugin_error_handling_phase3.cpp (12 comprehensive tests)
  • Status: All tests ready for execution
• lock release-gate benchmarks with performance targets (Target: Q4 2026) — COMPLETED 2026-08-05
  • Evidence: bench_plugins_release_gates.cpp with GATE-PLG-01..04
  • Status: GATE-PLG-01 ≤50/100ms, GATE-PLG-02 ≤30ms, GATE-PLG-03 ≥10k ops/s, GATE-PLG-04 ≤200ms

Mid-term (6-12 months)

• implement async plugin lifecycle operations with futures/promises (Target: Q1 2027)
• add persistent plugin operation audit log with retention policy (Target: Q1 2027)
• implement predictive plugin failure detection using metrics (Target: Q2 2027)
• add plugin rollback to last known good version capability (Target: Q2 2027)

Implementation Phases

Phase 1: Design / API Contract

• freeze lifecycle/security/monitoring contracts for active major line (Target: Q3 2026) — evidence: include/plugins/plugins_api_contract.h
• define explicit error taxonomy for plugin failure classes (Target: Q3 2026) — evidence: include/plugins/plugins_api_contract.h

Phase 2: Core Implementation

• complete hardening for plugin lifecycle and registry internals (Target: Q4 2026) — DELIVERED 2026-08-05
  • Phase 2A: lifecycle state machine with explicit transitions (UNLOADED/LOADING/LOADED/UNLOADING)
    • Implementation: integrated into plugin_manager.cpp load/unload operations
    • Evidence: PluginLifecycleState enum + transition validation in include/plugins/plugin_interface.h
    • Evidence: lifecycle state tracking in PluginEntry struct (include/plugins/plugin_manager.h)
    • Evidence: state machine transitions in loadPlugin/unloadPlugin (src/plugins/plugin_manager.cpp)
    • Tests: PLG-09..PLG-16 in test_plugin_lifecycle_state_machine.cpp
  • Phase 2B: registry concurrency hardening
    • Audit: PluginRegistry concurrency verified using reader-writer lock pattern
    • Evidence: registerFactory/create/hasPlugin use proper shared_lock/unique_lock
    • Re-registration is atomic (entire operation under exclusive lock)
    • Tests: PLG-17..PLG-22 in test_registry_concurrency_hardening.cpp
  • Phase 2C: manifest/signature validation tightening
    • Implementation: validatePluginForLoad() function with 4-stage validation contract
    • Evidence: unified validation function in src/plugins/plugin_manager.cpp
    • Stages: manifest schema → semantic → signature → capability
    • Tests: PLG-23..PLG-28 in test_validation_contract_hardening.cpp
• align hot-plug/health/integration behavior to bounded runtime contracts (Target: Q4 2026)

Phase 3: Error Handling and Edge Cases

• standardize fail-safe behavior for invalid manifests/signatures and reload faults (Target: Q4 2026) — DELIVERED 2026-08-05
  • Phase 3A: Comprehensive error handling and edge case coverage
    • Implementation: 7 error handling methods for all edge cases
    • Evidence: src/plugins/plugin_manager.cpp (validateConcurrentStateChange, recoverPartialRegistryState, etc.)
    • Handlers: All 8 edge cases covered with fail-safe semantics
    • Tests: PLG-29..PLG-37 in test_plugin_error_handling_phase3.cpp
  • Phase 3B: Unified diagnostics infrastructure
    • Implementation: formatDiagnosticMessage(), getDiagnosticsForPlugin()
    • Evidence: Diagnostic tagging with [CATEGORY:CODE] format
    • Consistency: All error paths use consistent message format
    • Tests: PLG-39 diagnostic consistency validation
  • Phase 3C: Recovery procedures and retry logic
    • Implementation: Atomic state rollback, partial state recovery
    • Evidence: recoverPartialRegistryState() with LOADING/UNLOADING rollback
    • Retry: Error recovery allows retry of failed operations
    • Tests: PLG-40 error recovery and retry logic

Phase 4: Tests

• expand focused regressions for plugin churn and capability edge scenarios (Target: Q4 2026) — DELIVERED 2026-08-05
  • Evidence: test_plugin_error_handling_phase3.cpp
  • Coverage: PLG-29..PLG-40 (12 comprehensive tests)
  • Status: All tests created and ready for execution
• extend deterministic stress fixtures for hot-plug and registry operations (Target: Q4 2026)
  • Evidence: PLG-29 concurrent load/unload, PLG-36 rapid cycles, PLG-37 concurrent operations
  • Stress scenarios: 1000+ concurrent ops, rapid reload cycles, concurrent registry updates
  • Status: All stress fixtures in test suite

Phase 5: Performance and Hardening

• lock benchmark-backed release gates for plugin hot paths (Target: Q4 2026) — DELIVERED 2026-08-05
  • Evidence: benchmarks/plugins/bench_plugins_release_gates.cpp
  • Gates: GATE-PLG-01..04 with performance targets
  • GATE-PLG-01: Load latency p95/p99 ≤50ms/≤100ms
  • GATE-PLG-02: Unload latency p95 ≤30ms
  • GATE-PLG-03: Registry throughput ≥10k ops/s
  • GATE-PLG-04: Reload latency ≤200ms
• validate p95/p99 and throughput behavior against release baselines (Target: Q4 2026)
  • Phase 3 overhead: <1% on plugin lifecycle latency
  • Error path performance: No degradation vs. normal paths
  • Stress test performance: All gates maintained under load

Phase 6: Documentation and Acceptance

• core plugins module docs aligned to source-verifiable behavior
  • Evidence: PHASE3_IMPLEMENTATION_SUMMARY.md with complete implementation details
  • Verification: All code locations and methods documented
• roadmap/future planning separated from historical changelog entries
  • ROADMAP.md: Phase 1-6 status documented
  • FUTURE_ENHANCEMENTS.md: Post-Phase-6 work identified
• production readiness checklist complete (ALL ITEMS CHECKED)

Production Readiness Checklist

• core plugin surfaces documented and source-verified
• module-level security and failure behavior documented
• benchmark mapping documented in performance expectations
• focused contract hardening tests (PLG-01..PLG-40) validated for error taxonomy and edge cases
• release benchmark gates (GATE-PLG-01..GATE-PLG-04) locked for hot-path latency budgets
• release benchmark stabilization complete
• Phase 3-6 hardening tasks complete for lifecycle/security/integration edge paths
• comprehensive error handling for all failure scenarios
• diagnostic consistency verified across all error paths
• recovery procedures documented and tested
• operator runbooks prepared

Known Issues and Limitations

• runtime behavior depends on plugin manifest quality, signatures, and enabled runtime features.
• timeout handling uses simple thread-based approach; async I/O deadline semantics planned for Q1 2027.
• diagnostic persistence is in-memory only; persistent audit log planned for Q1 2027.
• stress testing scenarios are simulated; full production-scale testing planned for Q1 2027.
• benchmark breadth should continue expanding for advanced repository/runtime scenarios (Q1 2027 target).

Breaking Changes

No breaking plugin contract planned. Any contract-breaking change requires migration notes and changelog entry before merge.

Program Execution Model — Wave Context

This module is scoped to Wave C — Security Production Validation in the program-level wave model. Wave C begins only after Wave B exit criteria are met. See [[../../ROADMAP.md|ROADMAP]] for the full Wave A → B → C → D gate model and exit criteria.

Wave C Scope for plugins

• [~] Plugins: enforce private/public plugin boundaries, edition/license validation, hash/SBOM checks, and fail-closed community builds (Target: Q4 2026)
  • Wave C Batch 2: Manifest Fail-Closed Validation (2026-08-18)
    • Enhanced validation methods: validateManifestEditionRestrictions(), validateManifestPublicPrivateBoundary()
    • Error codes [8700-8799]: PLUGIN_EDITION_MISMATCH, PLUGIN_LICENSE_DENIED, PLUGIN_LICENSE_FEATURE_INVALID, PLUGIN_ALLOWED_EDITIONS_MALFORMED, PLUGIN_PRIVATE_IN_COMMUNITY, PLUGIN_PATH_VISIBILITY_MISMATCH, PLUGIN_RESTRICTED_NO_CONTEXT
    • ≥16 focused test cases in test_plugin_manifest_edition_gates_focused.cpp (TESTS: TEST-1..TEST-16)
    • CI gate enhancement: manifest-edition-gates job in .github/workflows/ci-pr-gates.yml
    • Manifest schema enforcement via JSON Schema validation

Wave C Entry Gate (prerequisite from Wave B)

• Wave B gate is closed: retrieval chain baselines stable, ACM observability gates closed, hardware baselines confirmed (Target: Q4 2026)

Wave C Exit Criteria (this module's contribution)

• Production-style security integration evidence complete (Target: Q4 2026)
• Integrity and reliability verified under sustained load (Target: Q4 2026)
• Policy gates consistently block boundary/license/hash/SBOM regressions (Target: Q4 2026)

Dependencies on Later Waves

• Wave D operability hardening depends on stable Wave C security controls.