Skip to content

SPEC-EVO-008 — Plugin System

Purpose

The plugin system permits controlled extension without weakening repository integrity or binding QLens to one domain.

Extension points

QLens MAY expose plugins for validators, importers, exporters, indexers, renderers, relationship providers, visualizations, query functions, and CLI commands.

Requirements

  1. Every plugin MUST declare a unique identifier, semantic version, supported QLens API range, permissions, and extension points.
  2. Plugins MUST NOT redefine core object types or core edge semantics.
  3. Canonical writes MUST pass through the same validation and transaction boundaries as first-party writes.
  4. Plugin failures MUST be isolated and clearly reported.
  5. Plugin output that becomes canonical MUST be reproducible or record its non-deterministic inputs.
  6. Plugins MUST NOT receive network, process, or filesystem permissions beyond their declared policy in managed environments.
  7. The plugin API MUST be versioned independently from the CLI presentation.
  8. A repository MUST be inspectable even when an optional plugin is unavailable.

Compatibility

Breaking plugin API changes MUST occur only at declared major-version boundaries or through a compatibility adapter with a documented removal schedule.

Acceptance criteria

  • Disabling a plugin does not corrupt canonical content.
  • Plugin-produced objects validate against registered contracts.
  • The doctor command reports incompatible and missing required plugins.
  • A malicious or broken plugin cannot bypass core OID and relationship checks through supported APIs.