Plugin architecture: Reference architecture

Defines how third-party or internal extensions register capabilities, declare permissions, isolate failures, and upgrade without breaking the host application core.

Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.

Decision

Extend the host through manifest-driven plugins that declare capabilities and permissions before load. The host enforces isolation so extension failures disable the extension, not the core product. Upgrades are semver-gated with automatic rollback when health checks fail after deployment.

Scope

• Extension manifest schema, capability types, and permission declarations.
• Load-time validation, user consent, and runtime isolation boundaries.
• Health probing, failure thresholds, and disable versus crash behavior.
• Upgrade, rollback, and host API compatibility guarantees.

Outside this block

• Marketplace billing and revenue share.
• Full sandbox hypervisor design for untrusted native code.
• Feature flag infrastructure (see related feature-flags block).

Contract

• Runtime calls require declared permissions; undeclared access attempts fail closed at runtime and are audited.
• Load-time manifest schema validation rejects packages with missing required fields before code executes.
• Host api_surface_version v1 maps to semver range >=1.0.0 <2.0.0 for compatibility checks.
• User-consent permissions block activation until an authorized admin approves the listed scope.
• Consecutive health failures beyond the profile threshold disable the extension while the host remains available.
• API compatibility ranges in the manifest must match the host published API surface version rules.
• Signed packages are required when verification_required is true. The host verifies the declared package digest and publisher key id against its configured trust store, including key expiry and revocation status; unknown, expired, revoked, mismatched, or invalid signatures block installation before code load.

Implementation guidance

• Validate manifests in CI for internal extensions and at install time for third-party packages.
• Keep publisher trust anchors outside plugin-controlled content. Version the host trust store, refresh revocation information under a fail-closed freshness policy, and bind the signature to the canonical package digest plus manifest identity and version.
• Run extensions in isolated workers with memory and CPU caps from the manifest.
• Expose host APIs through a stable versioned surface; document breaking changes within the profile notice window.
• Log capability invocations with extension id, permission used, and calling workspace id for audit.
• Publish a compatibility matrix alongside host API releases so publishers can test proactively.

Failure handling and safeguards

• On extension timeout, abort the invocation and count toward failure threshold without blocking unrelated hooks.
• Roll back to the last healthy version automatically when post-upgrade probes fail.
• Quarantine extensions with repeated permission violations pending publisher review and host security sign-off.
• If revocation status or the required trust-store version cannot be established, reject new installation or upgrade; do not accept a key merely because its identifier appears in the plugin manifest.

Verification and operations

• Monitor extension crash rate, disable events, and permission denial counts.
• Test compatibility matrix across host API versions in staging before marketplace publication.
• Audit installed extensions quarterly for stale permissions.
• Re-evaluate installed packages when a publisher key is revoked and disable affected packages according to the incident profile.

The executable-looking examples in this package are fixtures and acceptance contracts. Validate package structure before adoption; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Resource limits, thresholds, and sample extension id in example.yaml and plugin-manifest.yaml are profile choices, not universal defaults.
• Teams must provision signature trust anchors, key rotation and revocation feeds, and consent UX in their platform policies; the sample identifiers are fixtures only.

References

• No external normative source is required; this package defines an extension host contract.