Skip to content

ROADMAP.md

Latest commit

 

History

History
183 lines (155 loc) · 11.1 KB

ROADMAP.md

File metadata and controls

183 lines (155 loc) · 11.1 KB
Raw

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 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.