P0 — prove every published plugin installs and loads against current Zara #211

New issue

Closed

opened 2026-09-08 02:03:14 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-08 02:03:14 +00:00

Owner

Goal

Establish a repository-level compatibility gate proving that every plugin currently published in plugins.json actually installs/imports/loads against the exact supported current Zara plugin API, rather than treating registry validity as proof of runtime compatibility.

Current published plugins include zara-agent-zero, zara-avatar, zara-discord, and zara-persona; the gate must automatically cover future registry entries as they are added.

Required compatibility matrix

For every registered plugin:

registry entry resolves to the real entrypoint/docs/directory;
Nix package builds;
bundled installer/installation layout is valid where the plugin ships one;
plugin can be discovered from Zara's configured plugin search path;
service plugins import and create_plugin() successfully against the supported Zara API v1 surface;
tool plugins register tools/skills successfully where applicable;
metadata name/version/API version agree with registry and runtime metadata;
startup/shutdown smoke is deterministic for service plugins using fake/local dependencies;
missing optional external services/devices produce explicit degraded/unavailable state rather than import/startup crashes;
writable runtime state is outside the Nix store;
no test requires network, real credentials, GUI, audio hardware, Discord, Agent Zero, or another live service.

Zara version contract

The test harness must make the Zara revision/API compatibility assumption explicit. Prefer testing against the repository's supported current Zara source/package contract rather than silently importing whatever happens to be on the host Python path.

When Zara core changes the plugin API, this gate should fail with a useful per-plugin compatibility error so plugins can be repaired before publishing more work.

Installer/Nix checks

validate nix build outputs for every registry package;
verify plugin files land under the documented share/zara/plugins/<name>/ layout;
verify installer dry-run/temp-home behavior where supported;
never write to the real operator home during tests.

TDD / acceptance

add a generated compatibility test that enumerates plugins.json
prove it can detect a deliberately incompatible fixture/metadata mismatch
all currently published plugins pass against the supported Zara API
missing optional backends degrade cleanly
compatibility failure names the plugin and violated contract
registry validator remains green
plugin unit suites remain green
package/install smoke passes in temporary locations
nix flake check includes the compatibility gate

This issue is the first priority before expanding the catalog with #50, #51, #52, or other new plugins.

## Goal Establish a repository-level compatibility gate proving that every plugin currently published in `plugins.json` actually installs/imports/loads against the exact supported current Zara plugin API, rather than treating registry validity as proof of runtime compatibility. Current published plugins include `zara-agent-zero`, `zara-avatar`, `zara-discord`, and `zara-persona`; the gate must automatically cover future registry entries as they are added. ## Required compatibility matrix For every registered plugin: - registry entry resolves to the real entrypoint/docs/directory; - Nix package builds; - bundled installer/installation layout is valid where the plugin ships one; - plugin can be discovered from Zara's configured plugin search path; - service plugins import and `create_plugin()` successfully against the supported Zara API v1 surface; - tool plugins register tools/skills successfully where applicable; - metadata name/version/API version agree with registry and runtime metadata; - startup/shutdown smoke is deterministic for service plugins using fake/local dependencies; - missing optional external services/devices produce explicit degraded/unavailable state rather than import/startup crashes; - writable runtime state is outside the Nix store; - no test requires network, real credentials, GUI, audio hardware, Discord, Agent Zero, or another live service. ## Zara version contract The test harness must make the Zara revision/API compatibility assumption explicit. Prefer testing against the repository's supported current Zara source/package contract rather than silently importing whatever happens to be on the host Python path. When Zara core changes the plugin API, this gate should fail with a useful per-plugin compatibility error so plugins can be repaired before publishing more work. ## Installer/Nix checks - validate `nix build` outputs for every registry package; - verify plugin files land under the documented `share/zara/plugins/<name>/` layout; - verify installer dry-run/temp-home behavior where supported; - never write to the real operator home during tests. ## TDD / acceptance - [ ] add a generated compatibility test that enumerates `plugins.json` - [ ] prove it can detect a deliberately incompatible fixture/metadata mismatch - [ ] all currently published plugins pass against the supported Zara API - [ ] missing optional backends degrade cleanly - [ ] compatibility failure names the plugin and violated contract - [ ] registry validator remains green - [ ] plugin unit suites remain green - [ ] package/install smoke passes in temporary locations - [ ] `nix flake check` includes the compatibility gate This issue is the first priority before expanding the catalog with #50, #51, #52, or other new plugins.

nsaspy closed this issue

2026-09-08 02:03:14 +00:00

nsaspy referenced this issue from a pull request that will close it,

2026-09-08 02:19:36 +00:00

coding: validate diff snapshot HEAD object IDs #375