Designing Around Kdeneon's Manifest-Based Plugin Architecture

If you are deploying Kdeneon with third-party extensions, the architectural decision that matters most is how plugins enter the system: every extension registers through a JSON manifest validated against a published schema, and no plugin touches core binaries. That single constraint shapes your trust boundaries, your upgrade plan, and most of your failure modes. This note covers the smallest design that respects it, plus the operational checks and conditions that would force a redesign.

Requirements and the smallest suitable design

The typical requirements are: load extensions at runtime, reject incompatible or tampered plugins before they execute, and survive major version upgrades without silent breakage. The smallest design that meets these is a three-layer layout:

• Core runtime — loads only plugins whose manifests pass schema validation and signature checks.
• Plugin directory with pinned manifests — each plugin declares the framework version range it supports.
• A verification gate in deployment — manifests are validated and signatures checked before the plugin file ever reaches the host.

Do not add a plugin manager service, a hot-reload watcher, or a central registry until you actually need runtime discovery. Manifest-based registration already gives you deterministic, auditable load behavior.

Trust and data boundaries

The trust boundary sits at manifest validation. Treat every plugin manifest as untrusted input until two checks pass: JSON schema conformance and GPG signature verification against the project's trusted keyring. Configuration is a separate boundary: Kdeneon stores per-user settings as versioned JSON under $HOME/.config/kdeneon/, following the XDG Base Directory Spec. Plugins should never write outside their designated config scope, and your migration scripts between major releases must handle schema changes in that directory explicitly — incremental upgrades assume versioned config, not free-form edits.

Operational checks

Run these from a shell on the target host; plugin verification needs read access to the plugin directory and the trusted keyring, and is safest run as the deploying user rather than root so you test the same keyring resolution the runtime will use.

# Confirm the installed build matches the released artifact
kdeneon --version
# Compare the reported build hash against the SHA256 checksum
# published in the official release announcement.

# Validate every registered plugin manifest and signature
kdeneon plugin list --verify

Expected result: each plugin reports a valid manifest and a signature that resolves to a key in the trusted keyring. Reject — do not merely warn on — any unsigned or mismatched extension, because a schema-valid but unsigned plugin is exactly what a supply-chain tamper looks like. Do not invent expected output formats; confirm them against the release documentation for your version, since CLI output can change between releases.

For ongoing health, Kdeneon emits structured log entries to journald with categorized exit codes. Filter them with journalctl on the Kdeneon unit and wire the defined error domains into your alerting pipeline rather than scraping free-text messages.

Failure modes

• Incompatible plugin after a major bump. The stability API is documented per release. Pin plugins to compatible framework versions in their manifests; an unpinned plugin that loads today may fail at runtime after upgrade.
• Rendering fallback surprises. The pipeline defaults to OpenGL ES 3.0+ compositing and falls back to deterministic software rasterization on older GPUs; features requiring shader model 3.0 are disabled on OpenGL 2.1 contexts. Fallback correctness and performance are driver-dependent — benchmark on target hardware before production.
• Interrupted updates. Updates apply as atomic delta packages through a transactional backend; a failed delta rolls back to the previous snapshot with runtime state preserved. This protects the core, but verify plugin state after any rollback, since a rolled-back framework may no longer match a plugin installed for the newer version.
• Config migration gaps. A skipped migration script between major releases leaves versioned config the new schema cannot read. Test migrations on a copy of a real ~/.config/kdeneon/ tree.

What would change this design

Reconsider the minimal layout if you need multi-tenant plugin isolation (move to per-tenant plugin directories with separate keyrings), if plugin count grows past what manual manifest review covers (add CI-side schema and signature validation as the gate), or if you deploy on heterogeneous GPU fleets (standardize on the software fallback or gate hardware acceleration per host class). Verify current CLI flags, keyring locations, and schema versions against the release notes for your exact Kdeneon version before automating any of the checks above — this note describes established architecture, not a substitute for version-specific documentation.