feat(plugins): add deprecation compatibility matrix

Add manifest deprecation metadata, registry compatibility evaluation, CLI and dashboard warnings, suppressible version warnings, and install-time compatibility blocking.

Author: FTMahringer

.github/release-notes/v2.6.9-dev.md

@@ -0,0 +1,11 @@
+# v2.6.9-dev
+
+## Governance: Deprecation and compatibility matrix
+
+- Added manifest `deprecated` metadata validation with `since`, `reason`, and optional migration URL.
+- Added registry compatibility evaluation for plugin versions using `min_synapse` and `max_synapse`.
+- Added compatibility and deprecation warnings to the CLI registry commands.
+- Added store warning badges and detail panels for deprecated, incompatible, and updateable entries.
+- Added an admin policy toggle to suppress version warnings for frozen environments.
+- Blocked direct and bundle installs when the selected registry version is incompatible with the running SYNAPSE version.
+- Added Flyway migration `V22__plugin_governance_and_store_state.sql` so plugin/store signing and governance fields match the application model.

CHANGELOG.md

@@ -9,6 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [v2.6.9-dev] - 2026-05-19
+
+**Governance Deprecation & Compatibility Matrix**
+
+### Added
+- Manifest `deprecated` metadata with `since`, `reason`, and optional migration URL validation.
+- Registry compatibility matrix evaluation with per-version `min_synapse` and `max_synapse` support.
+- CLI compatibility inspection plus registry warnings for deprecated, incompatible, and outdated entries.
+- Store policy support for suppressing version warnings in frozen environments.
+- Flyway migration `V22__plugin_governance_and_store_state.sql` to align plugin and store governance fields with the current entity model.
+
+### Changed
+- Store entries are now enriched with compatibility and deprecation metadata before being returned to the dashboard and registry consumers.
+- Bundle installs now preserve registry manifest metadata and block incompatible versions before installation.
+- Direct plugin installs now reject incompatible registry versions before lifecycle install begins.
+- Dashboard store cards and details now surface deprecation, migration, incompatibility, and update guidance.
+
+### Fixed
+- The persisted plugin/store schema now matches the existing signing and governance fields instead of relying on unmigrated entity columns.
+
 ## [v2.6.8-dev] - 2026-05-19
 
 **Governance Reporting & Takedowns**

docs/roadmaps/SYNAPSE_V3_IMPLEMENTATION_ROADMAP.md

@@ -504,7 +504,7 @@ security controls. Completes the plugin platform story.
 - Existing installs: dashboard warning on takedown
 - **Exit**: Report filed → admin notified → plugin hidden on takedown
 
-#### v2.6.9-dev: Governance — Deprecation & Compatibility Matrix
+#### v2.6.9-dev: Governance — Deprecation & Compatibility Matrix (completed)
 - Manifest `deprecated` field (since, reason, migration URL)
 - Registry compatibility matrix (plugin version ↔ Synapse version ranges)
 - Store + CLI warnings on deprecated or incompatible versions

packages/cli/cmd/registry.go

@@ -29,6 +29,7 @@ var registryListCmd = &cobra.Command{
 	RunE: func(cmd *cobra.Command, args []string) error {
 		client := clientFromCmd(cmd)
 		rawJSON, _ := cmd.Flags().GetBool("json")
+		suppressWarnings, _ := cmd.Flags().GetBool("suppress-warnings")
 		query, _ := cmd.Flags().GetString("query")
 		source, _ := cmd.Flags().GetString("source")
 		entryType, _ := cmd.Flags().GetString("type")
@@ -66,6 +67,9 @@ var registryListCmd = &cobra.Command{
 				fmt.Sprint(entry["version"]),
 				fmt.Sprint(entry["source"]),
 			)
+			if !suppressWarnings {
+				printRegistryWarnings(entry)
+			}
 		}
 		return nil
 	},
@@ -78,6 +82,7 @@ var registryVersionsCmd = &cobra.Command{
 	RunE: func(cmd *cobra.Command, args []string) error {
 		client := clientFromCmd(cmd)
 		rawJSON, _ := cmd.Flags().GetBool("json")
+		suppressWarnings, _ := cmd.Flags().GetBool("suppress-warnings")
 
 		var resp []map[string]any
 		if err := client.Get("/api/registry/"+args[0]+"/versions", &resp); err != nil {
@@ -95,8 +100,54 @@ var registryVersionsCmd = &cobra.Command{
 			tuioutput.Row(
 				fmt.Sprint(version["version"]),
 				fmt.Sprint(version["min_synapse"]),
+				fmt.Sprint(version["max_synapse"]),
 				fmt.Sprint(version["artifact_url"]),
 			)
+			if !suppressWarnings {
+				printVersionWarnings(version)
+			}
+		}
+		return nil
+	},
+}
+
+var registryCompatibilityCmd = &cobra.Command{
+	Use:   "compatibility <pluginId>",
+	Short: "Show compatibility details for a registry entry",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		client := clientFromCmd(cmd)
+		rawJSON, _ := cmd.Flags().GetBool("json")
+		version, _ := cmd.Flags().GetString("version")
+
+		path := "/api/registry/" + args[0] + "/compatibility"
+		if version != "" {
+			path += "?version=" + url.QueryEscape(version)
+		}
+
+		var resp map[string]any
+		if err := client.Get(path, &resp); err != nil {
+			return err
+		}
+		if rawJSON {
+			tuioutput.JSON(resp)
+			return nil
+		}
+
+		tuioutput.Header("Registry Compatibility: " + args[0])
+		tuioutput.KV("Synapse", fmt.Sprint(resp["currentSynapseVersion"]))
+		tuioutput.KV("Version", fmt.Sprint(resp["selectedVersion"]))
+		tuioutput.KV("Compatible", fmt.Sprint(resp["compatible"]))
+		tuioutput.KV("Min", fmt.Sprint(resp["minimumSynapseVersion"]))
+		tuioutput.KV("Max", fmt.Sprint(resp["maximumSynapseVersion"]))
+		if resp["deprecated"] == true {
+			tuioutput.Warning(fmt.Sprintf("Deprecated since %v: %v", resp["deprecatedSince"], resp["deprecationReason"]))
+			if migrationURL := fmt.Sprint(resp["migrationUrl"]); migrationURL != "" && migrationURL != "<nil>" {
+				tuioutput.KV("Migration", migrationURL)
+			}
+		}
+		if resp["updateAvailable"] == true {
+			tuioutput.Warning(fmt.Sprintf("Recommended version: %v", resp["recommendedVersion"]))
 		}
 		return nil
 	},
@@ -293,6 +344,9 @@ func init() {
 	registryListCmd.Flags().String("source", "", "Filter by source")
 	registryListCmd.Flags().String("type", "", "Filter by type")
 	registryListCmd.Flags().Bool("compatible", false, "Only show entries compatible with this SYNAPSE version")
+	registryListCmd.Flags().Bool("suppress-warnings", false, "Hide compatibility and deprecation warnings")
+	registryVersionsCmd.Flags().Bool("suppress-warnings", false, "Hide compatibility and deprecation warnings")
+	registryCompatibilityCmd.Flags().String("version", "", "Specific plugin version to evaluate")
 
 	registryAddSourceCmd.Flags().String("id", "", "Source ID (defaults to a slug from name)")
 	registryAddSourceCmd.Flags().String("name", "", "Source display name")
@@ -310,6 +364,7 @@ func init() {
 	registryCmd.AddCommand(
 		registryListCmd,
 		registryVersionsCmd,
+		registryCompatibilityCmd,
 		registrySyncCmd,
 		registryStatusCmd,
 		registrySourcesCmd,
@@ -320,3 +375,32 @@ func init() {
 	commandfeatures.BindSubcommandListing(registryCmd)
 	rootCmd.AddCommand(registryCmd)
 }
+
+func printRegistryWarnings(entry map[string]any) {
+	meta, _ := entry["meta"].(map[string]any)
+	if meta == nil {
+		return
+	}
+	if compatibility, ok := meta["compatibility"].(map[string]any); ok {
+		if compatible, ok := compatibility["compatible"].(bool); ok && !compatible {
+			tuioutput.Warning(fmt.Sprintf("Incompatible with current SYNAPSE version: %v", entry["id"]))
+		} else if updateAvailable, ok := compatibility["update_available"].(bool); ok && updateAvailable {
+			tuioutput.Warning(fmt.Sprintf("Update recommended: %v -> %v", entry["version"], compatibility["recommended_version"]))
+		}
+	}
+	if deprecated, ok := meta["deprecated"].(map[string]any); ok {
+		tuioutput.Warning(fmt.Sprintf("Deprecated since %v: %v", deprecated["since"], deprecated["reason"]))
+	}
+}
+
+func printVersionWarnings(version map[string]any) {
+	if compatible, ok := version["compatible"].(bool); ok && !compatible {
+		tuioutput.Warning(fmt.Sprintf("Incompatible version: %v", version["version"]))
+	}
+	if deprecated, ok := version["deprecated"].(bool); ok && deprecated {
+		tuioutput.Warning(fmt.Sprintf("Deprecated since %v: %v", version["deprecated_since"], version["deprecation_reason"]))
+	}
+	if recommended, ok := version["recommended"].(bool); ok && recommended {
+		tuioutput.Warning(fmt.Sprintf("Recommended version: %v", version["version"]))
+	}
+}

packages/cli/cmd/registry_test.go

@@ -134,6 +134,47 @@ func TestRegistryAddSourceCommand(t *testing.T) {
 	}
 }
 
+func TestRegistryCompatibilityCommand(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/registry/legacy-provider/compatibility" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"pluginId":               "legacy-provider",
+			"currentSynapseVersion":  "2.6.9-dev",
+			"selectedVersion":        "1.0.0",
+			"minimumSynapseVersion":  ">=2.6.0",
+			"maximumSynapseVersion":  "<=2.6.9",
+			"compatible":             true,
+			"deprecated":             true,
+			"deprecatedSince":        "1.0.0",
+			"deprecationReason":      "Use provider-v2",
+			"migrationUrl":           "https://example.com/provider-v2",
+			"recommendedVersion":     "1.1.0",
+			"updateAvailable":        true,
+		})
+	}))
+	defer server.Close()
+
+	cmd, _, err := newIsolatedRootCommand()
+	if err != nil {
+		t.Fatalf("newIsolatedRootCommand: %v", err)
+	}
+
+	got := captureStdout(t, func() {
+		cmd.SetArgs([]string{"registry", "compatibility", "--host", server.URL, "legacy-provider"})
+		if err := cmd.Execute(); err != nil {
+			t.Fatalf("execute: %v", err)
+		}
+	})
+	if !strings.Contains(got, "Deprecated since 1.0.0") {
+		t.Fatalf("unexpected output: %q", got)
+	}
+	if !strings.Contains(got, "Recommended version: 1.1.0") {
+		t.Fatalf("unexpected output: %q", got)
+	}
+}
+
 func captureStdout(t *testing.T, fn func()) string {
 	t.Helper()
 

packages/cli/internal/output/print.go

@@ -12,6 +12,7 @@ const (
 	bold  = "\033[1m"
 	cyan  = "\033[36m"
 	green = "\033[32m"
+	yellow = "\033[33m"
 	red   = "\033[31m"
 	dim   = "\033[2m"
 )
@@ -32,6 +33,10 @@ func OK(msg string) {
 	fmt.Printf("%s✓%s %s\n", green, reset, msg)
 }
 
+func Warning(msg string) {
+	fmt.Printf("%s!%s %s\n", yellow, reset, msg)
+}
+
 func Error(msg string) {
 	fmt.Fprintf(os.Stderr, "%s✗%s %s\n", red, reset, msg)
 }

packages/core/pom.xml

@@ -15,7 +15,7 @@
 
     <groupId>dev.synapse</groupId>
     <artifactId>synapse-core</artifactId>
-    <version>2.6.8-dev</version>
+    <version>2.6.9-dev</version>
     <name>synapse-core</name>
     <description>SYNAPSE Spring Boot backend</description>
 

packages/core/src/main/java/dev/synapse/plugins/core/ManifestValidator.java

@@ -10,6 +10,7 @@
 import java.util.Locale;
 import java.util.Map;
 import java.util.regex.Pattern;
+import dev.synapse.plugins.loader.dependency.VersionConstraint;
 
 /**
  * Validates plugin manifests before install.
@@ -49,6 +50,9 @@ public ValidationResult validate(PluginManifest manifest) {
             errors.add("version must follow semver format (e.g. 1.0.0)");
         }
 
+        validateVersionConstraint("min_synapse", manifest.minSynapse(), errors);
+        validateVersionConstraint("max_synapse", manifest.maxSynapse(), errors);
+
         if (blank(manifest.author())) {
             errors.add("author is required");
         }
@@ -69,10 +73,22 @@ public ValidationResult validate(PluginManifest manifest) {
         }
 
         validateSignature(manifest, errors);
+        validateDeprecated(manifest, errors);
 
         return errors.isEmpty() ? ValidationResult.ok() : ValidationResult.fail(errors);
     }
 
+    private void validateVersionConstraint(String field, String value, List<String> errors) {
+        if (blank(value)) {
+            return;
+        }
+        try {
+            VersionConstraint.parse(value);
+        } catch (IllegalArgumentException e) {
+            errors.add(field + " must be a valid version constraint");
+        }
+    }
+
     private void validateMcp(PluginManifest manifest, List<String> errors) {
         if (manifest.mcp() == null || manifest.mcp().isEmpty()) {
             errors.add("mcp section is required for type mcp");
@@ -207,6 +223,29 @@ private void validateSignature(PluginManifest manifest, List<String> errors) {
         }
     }
 
+    private void validateDeprecated(PluginManifest manifest, List<String> errors) {
+        if (manifest.deprecated() == null || manifest.deprecated().isEmpty()) {
+            return;
+        }
+
+        String since = stringValue(manifest.deprecated().get("since"));
+        String reason = stringValue(manifest.deprecated().get("reason"));
+        String migrationUrl = stringValue(manifest.deprecated().get("migration_url"));
+
+        if (blank(since)) {
+            errors.add("deprecated.since is required when deprecated is present");
+        } else if (!VERSION_PATTERN.matcher(since).matches()) {
+            errors.add("deprecated.since must follow semver format (e.g. 1.0.0)");
+        }
+        if (blank(reason)) {
+            errors.add("deprecated.reason is required when deprecated is present");
+        }
+        if (!blank(migrationUrl) &&
+            !(migrationUrl.startsWith("http://") || migrationUrl.startsWith("https://"))) {
+            errors.add("deprecated.migration_url must start with http:// or https://");
+        }
+    }
+
     private String stringValue(Object value) {
         return value == null ? null : value.toString();
     }

packages/core/src/main/java/dev/synapse/plugins/core/PluginManifest.java

@@ -20,12 +20,14 @@ public record PluginManifest(
     String license,
     String description,
     String minSynapse,
+    String maxSynapse,
     List<String> tags,
     List<PluginDependency> dependencies,
     List<PluginDependency> softDependencies,
     Map<String, Object> skills,
     Map<String, Object> mcp,
     Map<String, Object> bundle,
+    Map<String, Object> deprecated,
     Map<String, Object> signature,
     Map<String, Object> configSchema,
     Map<String, Object> raw
@@ -66,12 +68,14 @@ public static PluginManifest fromMap(Map<String, Object> map) {
             str(map, "license"),
             str(map, "description"),
             str(map, "min_synapse"),
+            str(map, "max_synapse"),
             tags,
             hardDeps,
             softDeps,
             mapOf(map.get("skills")),
             mapOf(map.get("mcp")),
             mapOf(map.get("bundle")),
+            mapOf(map.get("deprecated")),
             mapOf(map.get("signature")),
             mapOf(map.get("config_schema")),
             map