ADR-0038: Community Ecosystem Extensibility, Custom Plugin Hooks and Provider SDK v0.3.6
- Title: Community Ecosystem Extensibility, Custom Plugin Hooks and Provider SDK v0.3.6
- Status: Accepted
- Date: 2026-11-12
- Author: Community Core Team
Context
As the ZQK open-core platform expands, third-party contributors, plugin authors, and cloud ecosystem integrators require robust, isolated, and type-safe extensibility interfaces. Previously, custom integrations required internal package modifications or direct binary patching. Version v0.3.6 introduces a formal Provider SDK and lifecycle hook architecture enabling dynamic provider registration, isolated event interception, and AST-verified contract stability without breaking backward compatibility or compromising kernel security boundaries.
Decision
-
Provider SDK Abstraction Boundary: - Establish typed Go interfaces (
ProviderRegistry,LifecycleHookHandler,PluginContext) inpkg/communityandpkg/clihooks. - Provide deterministic hook registration for pre-execution, post-execution, telemetry emission, and failure interception. - Enforce fail-closed isolation: plugin failures must never crash the core kernel or corrupt CAS state. -
Validation & Boundary Protection: - Enforce bounded execution timeouts (max 5000ms default per hook invocation) with cancel-safe context propagation. - Require explicit semantic version compatibility declarations (
TargetEngineVersion) for all registered providers. - Disallow unsafe memory manipulation, unmanaged goroutine spawning, or unbuffered disk writes inside hook implementations. -
Ontological Traceability & Documentation: - Register all architectural contracts, test suites, and schema specifications directly in the Knowledge Kernel CAS. - Index this specification via
docman registerand verify compliance usingzqk-vet.
Consequences
- Third-party extensions and enterprise provider bridges can be developed independently using a stable, typed SDK.
- The core runtime remains protected against untrusted or crashing plugins via isolation sandboxes and strict timeouts.
- All extension hooks are discoverable, auditable, and covered by automated regression verification.