fix(store): address review — malformed manifests, and suffixed versions

Both CodeRabbit findings on #433 verified against the code and fixed.

1. Malformed manifest sections raised instead of degrading. `requires` as a
   list hit AttributeError ('list' object has no attribute 'get') and
   `versions` as a mapping hit KeyError: 0. Both reproduced.

   This got worse with the sunset rule in the previous commit: that branch
   resolves the floor for *every* manifest on an untrustworthy core, where the
   old code returned early. One hand-edited or third-party file with the wrong
   shape would have taken down the whole install path rather than just itself.
   Container types are now validated and an unrecognised shape reads as "no
   declared floor".

2. Prerelease and build metadata leaked into the version numbers. The digit
   scrape parsed "3.2.0+build42" as (3, 2, 42) and "3.2.0-rc1" as (3, 2, 1) --
   a release candidate ranking above its own release. Both fed reject
   decisions, and the consequence was demonstrable: a plugin pinned to exactly
   "3.2.0" refused a core running 3.2.0+build42, which is that same version.

   The suggested remedy -- use the strict token parser -- would not have
   fixed it. _parse_strict validates the shape but delegates the numbers to
   parse_semver, so it returned the same (3, 2, 42). The bug is in the scrape,
   so suffixes are now dropped before it. Prereleases compare equal to their
   release rather than below it; full prerelease ordering is more than any
   caller needs and equal is far closer to right than what it did before.

parse_semver is shared with PluginLoader, so its suite was re-run: unchanged,
and it only ever gets more correct here.

Verified: 839 core unit tests pass, 21 of them new -- six malformed shapes,
five suffixed forms, and the two demonstrated regressions. The real-registry
sweep is unchanged at 0 of 42 refused across cores 1.0.0, 3.1.0, 3.2.0,
3.2.0+build42 and an unparseable string.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Udr6MfaFLUPhX5Fgo67Jf5

.github/workflows/release-version-check.yml

@@ -0,0 +1,40 @@
+name: Release version check
+
+# A release tag, the CHANGELOG, and src.__version__ must agree. They have not
+# always: v3.1.0 was tagged while src/__init__.py still said "1.0.0", which
+# silently exempted every device installed from that release from plugin
+# compatibility warnings. See docs/SPORTS_UNIFICATION.md (phase B4).
+on:
+  push:
+    tags: ["v*"]
+  release:
+    types: [published]
+  # Pre-flight: run this against the tag you are about to create.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to check (e.g. v3.2.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  version-matches-tag:
+    name: Tag matches src.__version__
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: "3.12"
+
+      # No dependencies: the script reads src/__init__.py and CHANGELOG.md only.
+      - name: Assert the tag, CHANGELOG and src.__version__ agree
+        run: python scripts/check_release_version.py "${TAG}"
+        env:
+          TAG: ${{ inputs.tag || github.ref_name }}

.github/workflows/test.yml

@@ -76,4 +76,7 @@ jobs:
             test/test_sports_core_promotions.py \
             test/test_sports_modes_promotions.py \
             test/test_sports_capabilities.py \
-            test/test_sports_scroll.py
+            test/test_sports_scroll.py \
+            test/test_version_consistency.py \
+            test/test_plugin_compatibility_gate.py \
+            test/test_install_preserves_existing.py

CHANGELOG.md

@@ -29,6 +29,21 @@ Adoption is deliberately staged: the modules below ship here, plugins adopt them
 behind guarded imports, and only then do the bundled copies go away. Nothing in
 this release changes what an existing plugin loads.
 
+**This is also the first release that *enforces* `ledmatrix_min_version`.**
+Before it, the floor was advisory — the loader logged a warning and continued,
+and the plugin store never compared the core version at all, so an update could
+deliver a plugin that could not run. From 3.2.0 the store refuses such an
+install. That matters for the sunset rule: a plugin may only delete its bundled
+fallback once the cores in the field actually enforce the floor, which means
+waiting for 3.2.0 to be widely installed rather than merely released. See
+`docs/SPORTS_UNIFICATION.md`, phase B6.
+
+One deliberate exception: a core reporting a version below `2.0.0` is treated as
+*unknown* rather than old and is never blocked. The v3.1.0 release ships
+`__version__ = "1.0.0"` (the tag was cut before the string was bumped), and
+nearly every published manifest floors at `2.0.0` — so blocking on that number
+would lock those users out of the plugin store entirely.
+
 ### Added
 - `src/element_style.py` — per-element style resolver backing the
   `x-style-elements` config-schema extension. Already consumed (behind guarded
@@ -71,8 +86,37 @@ this release changes what an existing plugin loads.
   override point — see `docs/SPORTS_UNIFICATION.md` for where the line falls
   and why.
 
+- `src/plugin_system/compatibility.py` — the single place that answers "can this
+  plugin run on this core?", shared by the loader (advisory, at load time) and
+  the store (blocking, at install/update time) so the two cannot drift. Reads
+  every spelling published manifests use, including the deprecated
+  `versions[].ledmatrix_min`. It does **not** yet evaluate `compatible_versions`,
+  which is the schema-required field and can express upper bounds; closing that
+  is tracked in `docs/SPORTS_UNIFICATION.md` before B6.
+- `scripts/check_release_version.py` and a `Release version check` workflow —
+  assert that a tag, the newest CHANGELOG heading and `src.__version__` agree,
+  on pushed `v*` tags and published releases. Runnable via `workflow_dispatch`
+  to check a tag *before* creating it. Added because `v3.1.0` was tagged six
+  weeks before `src/__init__.py` was bumped to match, which is why devices
+  installed from that release report `1.0.0`.
+
 ### Changed
 - `src/__init__.py` bumped to **3.2.0** — the number the sunset rule keys on.
+- **The plugin store refuses an incompatible install.**
+  `StoreManager.install_plugin` now checks the downloaded manifest's declared
+  floor against `src.__version__` and refuses when the plugin needs a newer
+  core. The check sits in `install_plugin` because `_reinstall_with_rollback`
+  calls it, so a refused *update* restores the version the user already had.
+  Refusal requires evidence: an undeclared floor, an unparseable version on
+  either side, or an untrustworthy core version all allow the install.
+- **A failed install no longer destroys the plugin it replaced.**
+  `install_plugin` previously deleted the existing plugin directory before
+  downloading, so any later failure — a dropped connection, a malformed
+  manifest, or the new compatibility refusal — left the user with nothing. The
+  existing copy is now set aside and restored if the install fails, matching
+  the protection `_reinstall_with_rollback` already gave the update path.
+- `web_interface.__version__` re-exports `src.__version__` instead of carrying
+  its own hardcoded `"3.0.0"`, which had drifted two majors from the core.
 - **Live games are no longer dropped when the feed omits a game clock.**
   `SportsLive._is_game_really_over` previously (in the baseball and UFC
   plugin lineages) coerced a missing or non-string clock to the literal
@@ -86,6 +130,12 @@ this release changes what an existing plugin loads.
   there means kickoff rather than expiry.
 
 ### Fixed
+- **Plugin updates could hang the web request thread.** The per-plugin reinstall
+  locks were non-reentrant, and `_reinstall_with_rollback` holds one across its
+  call to `install_plugin` — which now takes the same lock to protect the
+  set-aside/restore above. That nesting deadlocked
+  `update_plugin → _reinstall_with_rollback → install_plugin`, the standard
+  path for every monorepo plugin update. The locks are now `RLock`s.
 - `FontManager` resolves `assets/fonts` against the core install root instead
   of the process working directory, so font loading works when the process
   starts elsewhere (e.g. the plugin safety harness on CI).

src/plugin_system/compatibility.py

@@ -0,0 +1,253 @@
+"""One place that answers "can this plugin run on this core?".
+
+Two callers ask that question and they must not drift apart:
+
+- `PluginLoader._warn_if_incompatible` — at load time, **advisory**. A plugin
+  already on disk keeps loading regardless, because the guarded-import pattern
+  means most incompatibilities degrade rather than break.
+- `PluginStoreManager.install_plugin` — at install/update time, **blocking**.
+  This is the point where refusing costs the user nothing (they keep the
+  version they already had) and allowing can cost them a plugin that fails to
+  load with only a log line to explain it.
+
+## The trustworthiness problem
+
+The core's own `__version__` has not always been right. `v3.1.0` was tagged
+2026-05-31 while `src/__init__.py` still said `"1.0.0"`; the bump landed
+2026-07-12. Devices installed from that release report `1.0.0` — below the
+floor that essentially every published plugin declares.
+
+So a core reporting a version below `TRUSTWORTHY_FLOOR` is treated as
+**unknown, not old**: it neither warns nor blocks. Blocking on it would be far
+worse than the problem being solved — nearly every manifest in the ecosystem
+floors at `2.0.0`, so a strict gate would stop those users installing *any*
+plugin. They are unprotected until they update the core, which is also what
+fixes their version string. See `docs/SPORTS_UNIFICATION.md`, phase B4.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Optional, Tuple
+
+# Below this, the core's self-reported version is not evidence of anything.
+# See the module docstring.
+TRUSTWORTHY_FLOOR: Tuple[int, int, int] = (2, 0, 0)
+
+
+def parse_semver(value: Any) -> Optional[Tuple[int, int, int]]:
+    """Parse ``X.Y.Z`` (extra parts and suffixes ignored) into a comparable
+    3-tuple, or ``None`` when unparseable. A leading ``v`` is tolerated."""
+    if not isinstance(value, str):
+        return None
+    text = value.strip().lstrip('v')
+    # Drop the prerelease/build suffix before scraping digits. Without this the
+    # scrape pulls them into the numbers: "3.2.0+build42" parsed as (3, 2, 42)
+    # and "3.2.0-rc1" as (3, 2, 1) -- a release candidate ranking *above* its
+    # own release, and a build of 3.2.0 failing an exact "3.2.0" match.
+    #
+    # Prereleases compare equal to their release here rather than below it.
+    # Full prerelease ordering is more than any caller needs, and equal is far
+    # closer to right than the old behaviour.
+    for sep in ('+', '-'):
+        head, found, _tail = text.partition(sep)
+        if found:
+            text = head
+    parts = text.split('.')
+    try:
+        nums = [int(''.join(ch for ch in p if ch.isdigit()) or 0) for p in parts[:3]]
+    except ValueError:
+        return None
+    while len(nums) < 3:
+        nums.append(0)
+    return tuple(nums)  # type: ignore[return-value]
+
+
+# `parse_semver` is deliberately lenient — it strips non-digits and yields
+# (0, 0, 0) for a string with no numbers at all, which is fine for a floor
+# (a floor of 0.0.0 never blocks anything) but wrong for a range, where the
+# same leniency would turn an unreadable spec into a *refusal*. Range specs
+# are therefore validated against this first, so garbage reads as "no
+# evidence" rather than "incompatible".
+_VERSION_TOKEN = re.compile(r"^v?\d+(\.\d+){0,2}(-[\w.-]+)?(\+[\w.-]+)?$")
+
+
+def _parse_strict(value: str) -> Optional[Tuple[int, int, int]]:
+    """`parse_semver`, but ``None`` unless the string really looks like one."""
+    if not isinstance(value, str) or not _VERSION_TOKEN.match(value.strip()):
+        return None
+    return parse_semver(value)
+
+
+def _satisfies_range(core: Tuple[int, int, int], spec: str) -> Optional[bool]:
+    """Does ``core`` satisfy one `compatible_versions` entry?
+
+    Returns ``None`` when the spec cannot be parsed — the caller treats that as
+    "no evidence" rather than as a refusal, so an unrecognised spelling never
+    costs a user a working install.
+
+    Supports the forms `schema/manifest_schema.json` permits: `>=`, `<=`, `>`,
+    `<`, `~`, `^`, a bare exact version, and an inclusive `A - B` range.
+    Prerelease/build suffixes are tolerated and ignored, matching `parse_semver`.
+    """
+    spec = spec.strip()
+    if not spec:
+        return None
+
+    if " - " in spec:  # inclusive range, e.g. "2.0.0 - 3.1.0"
+        low_raw, _, high_raw = spec.partition(" - ")
+        low, high = _parse_strict(low_raw), _parse_strict(high_raw)
+        if low is None or high is None:
+            return None
+        return low <= core <= high
+
+    for op in (">=", "<=", ">", "<", "~", "^"):
+        if spec.startswith(op):
+            target = _parse_strict(spec[len(op):])
+            if target is None:
+                return None
+            if op == ">=":
+                return core >= target
+            if op == "<=":
+                return core <= target
+            if op == ">":
+                return core > target
+            if op == "<":
+                return core < target
+            if op == "~":
+                # Patch-level changes only: >=X.Y.Z, <X.(Y+1).0
+                return target <= core < (target[0], target[1] + 1, 0)
+            # "^": minor and patch changes: >=X.Y.Z, <(X+1).0.0
+            return target <= core < (target[0] + 1, 0, 0)
+
+    exact = _parse_strict(spec)
+    return None if exact is None else core == exact
+
+
+def satisfies_compatible_versions(
+    manifest: Dict[str, Any], core: Tuple[int, int, int]
+) -> Optional[bool]:
+    """Evaluate the manifest's `compatible_versions` array against ``core``.
+
+    The array is a set of *alternatives*: satisfying any one entry means the
+    plugin declares itself compatible. Returns ``None`` when the field is
+    absent or no entry could be parsed, so callers can distinguish "declared
+    incompatible" from "did not say".
+
+    This is the field `schema/manifest_schema.json` marks **required**, and it
+    is the only one that can express an upper bound — `ledmatrix_min_version`
+    is a floor and cannot say "not compatible with 4.x".
+    """
+    specs = manifest.get('compatible_versions')
+    if not isinstance(specs, list) or not specs:
+        return None
+
+    verdicts = [_satisfies_range(core, s) for s in specs if isinstance(s, str)]
+    parsed = [v for v in verdicts if v is not None]
+    if not parsed:
+        return None
+    return any(parsed)
+
+
+def declared_min_version(manifest: Dict[str, Any]) -> Optional[str]:
+    """The core version this plugin says it needs, or ``None`` if it doesn't say.
+
+    Checked in order of specificity. `ledmatrix_min` is the deprecated spelling
+    of `ledmatrix_min_version` (`store_manager._validate_manifest_fields` flags
+    it); both are read because a large share of published manifests still carry
+    the old one.
+
+    Container types are validated rather than assumed. A hand-edited or
+    third-party manifest can carry `requires` as a list or `versions` as a
+    mapping, and both used to raise out of here (`AttributeError` and
+    `KeyError` respectively). That now matters far more than it did: the
+    untrustworthy-core branch of :func:`check` calls this for *every* manifest,
+    so one malformed file would take down the install path rather than just
+    itself. A shape we do not recognise means "no declared floor".
+    """
+    declared = manifest.get('min_ledmatrix_version')
+    if not declared:
+        requires = manifest.get('requires')
+        if isinstance(requires, dict):
+            declared = requires.get('min_ledmatrix_version')
+    if declared:
+        return declared
+
+    versions = manifest.get('versions')
+    if isinstance(versions, list) and versions and isinstance(versions[0], dict):
+        return (versions[0].get('ledmatrix_min_version')
+                or versions[0].get('ledmatrix_min'))
+    return None
+
+
+def check(manifest: Dict[str, Any], core_version: str) -> Tuple[bool, Optional[str]]:
+    """Return ``(compatible, reason)``.
+
+    Two fields can say a plugin is incompatible and **the more restrictive
+    wins**:
+
+    - `compatible_versions` — the schema-required array of semver ranges, and
+      the only one that can express an upper bound.
+    - `ledmatrix_min_version` (or the deprecated `ledmatrix_min`) — the
+      per-release floor inside `versions[]`.
+
+    They agree across every published manifest today except `7-segment-clock`,
+    but they *can* disagree, and a plugin that says `["2.0.0 - 2.9.9"]` means
+    "not compatible with 3.x" no matter what its floor says.
+
+    ``compatible`` is False **only** on evidence: the core reports a parseable,
+    trustworthy version and a field genuinely excludes it. Every uncertain case
+    resolves to compatible — nothing declared, an unparseable version on either
+    side, or a core below `TRUSTWORTHY_FLOOR`. Refusing on a guess breaks a
+    working install, which is the more expensive mistake here.
+
+    ``reason`` is user-facing text, present only when incompatible.
+    """
+    current = parse_semver(core_version)
+    name = manifest.get('name') or manifest.get('id') or 'This plugin'
+
+    if current is None or current < TRUSTWORTHY_FLOOR:
+        # The version is not evidence of what this core HAS. But a floor above
+        # the ecosystem baseline says the plugin needs modules that arrived
+        # *after* 2.0.0 — and a core reporting below that either is the v3.1.0
+        # release (which ships __version__ = "1.0.0" and has none of the 3.2.0
+        # modules) or is genuinely ancient. Either way it will not have them.
+        #
+        # This is the only protection available to that population: they cannot
+        # be told apart from a real 1.0.0 install, so the gate cannot reason
+        # about them, and the *plugin's* guarded-import fallback disappears at
+        # the B6 sunset. Refusing the install leaves them on the version they
+        # already run instead of handing them one that fails to load.
+        #
+        # Floors at or below 2.0.0 are still allowed, which is every manifest
+        # published today — so this does not lock anyone out of the store.
+        declared = declared_min_version(manifest)
+        needed = parse_semver(declared)
+        if needed is not None and needed > TRUSTWORTHY_FLOOR:
+            return False, (
+                f"{name} requires LEDMatrix {declared} or newer. This system "
+                f"reports {core_version}, which is too old to identify "
+                f"reliably — update LEDMatrix, then install it."
+            )
+        return True, None
+
+    # Ranges first: they are the canonical field and can rule out a core that
+    # clears the floor.
+    if satisfies_compatible_versions(manifest, current) is False:
+        specs = ", ".join(
+            s for s in manifest.get('compatible_versions', []) if isinstance(s, str))
+        return False, (
+            f"{name} supports LEDMatrix {specs}, but this system is running "
+            f"{core_version}. Install a build in that range, or a plugin "
+            f"version that supports {core_version}."
+        )
+
+    declared = declared_min_version(manifest)
+    needed = parse_semver(declared)
+    if needed is not None and needed > current:
+        return False, (
+            f"{name} requires LEDMatrix {declared} or newer, but this system is "
+            f"running {core_version}. Update LEDMatrix first, then install it."
+        )
+
+    return True, None

src/plugin_system/plugin_loader.py

@@ -702,34 +702,25 @@ class PluginLoader:
         newer than the running core. Advisory only — never raises — so a
         plugin that guards optional features with try/except keeps working.
         """
-        declared = (
-            manifest.get('min_ledmatrix_version')
-            or manifest.get('requires', {}).get('min_ledmatrix_version')
-        )
-        if not declared:
-            versions = manifest.get('versions') or []
-            if versions and isinstance(versions[0], dict):
-                declared = (versions[0].get('ledmatrix_min_version')
-                            or versions[0].get('ledmatrix_min'))
-        needed = self._parse_semver(declared)
-        if needed is None:
+        from src import __version__ as core_version
+        from src.plugin_system import compatibility
+
+        compatible, _reason = compatibility.check(manifest, core_version)
+        if compatible:
+            # Distinguish "fine" from "couldn't tell" for anyone reading logs:
+            # a core below the trustworthy floor is skipped, not cleared.
+            current = compatibility.parse_semver(core_version)
+            if current is None or current < compatibility.TRUSTWORTHY_FLOOR:
+                self.logger.debug(
+                    "Skipping version compatibility check for %s: core __version__ "
+                    "(%s) is below the ecosystem floor", plugin_id, core_version)
             return
 
-        from src import __version__ as core_version
-        current = self._parse_semver(core_version)
-        # Anti-spam guard: if the core's own version number is stale (below
-        # the ecosystem floor every shipped plugin declares), comparing would
-        # warn on nearly everything — skip with a debug note instead.
-        if current is None or current < (2, 0, 0):
-            self.logger.debug(
-                "Skipping version compatibility check for %s: core __version__ "
-                "(%s) is below the ecosystem floor", plugin_id, core_version)
-            return
-        if needed > current:
-            self.logger.warning(
-                "Plugin %s declares min LEDMatrix version %s but this core is %s — "
-                "features it relies on may be missing; update the core or expect "
-                "degraded fallbacks", plugin_id, declared, core_version)
+        declared = compatibility.declared_min_version(manifest)
+        self.logger.warning(
+            "Plugin %s declares min LEDMatrix version %s but this core is %s — "
+            "features it relies on may be missing; update the core or expect "
+            "degraded fallbacks", plugin_id, declared, core_version)
 
     def load_plugin(
         self,

src/plugin_system/store_manager.py

@@ -149,18 +149,27 @@ class PluginStoreManager:
         # loser can end up renaming the winner's in-progress install aside
         # mid-download, stealing its own rollback safety net. Keyed by
         # plugin_id so unrelated plugins still update concurrently.
-        self._reinstall_locks: Dict[str, threading.Lock] = {}
+        # Reentrant: install_plugin takes this lock, and _reinstall_with_rollback
+        # holds it across its call to install_plugin. A plain Lock would
+        # self-deadlock on that nesting.
+        self._reinstall_locks: Dict[str, "threading.RLock"] = {}
         self._reinstall_locks_guard = threading.Lock()
 
         # Ensure plugins directory exists
         self.plugins_dir.mkdir(exist_ok=True)
 
-    def _get_reinstall_lock(self, plugin_id: str) -> threading.Lock:
-        """Lazily create (or fetch) the per-plugin reinstall lock."""
+    def _get_reinstall_lock(self, plugin_id: str):
+        """Lazily create (or fetch) the per-plugin reinstall lock.
+
+        Reentrant by necessity: `install_plugin` acquires it to protect its
+        set-aside/restore, and `_reinstall_with_rollback` holds it across its
+        own call to `install_plugin`. With a plain `Lock` that nesting
+        deadlocks the request thread.
+        """
         with self._reinstall_locks_guard:
             lock = self._reinstall_locks.get(plugin_id)
             if lock is None:
-                lock = threading.Lock()
+                lock = threading.RLock()
                 self._reinstall_locks[plugin_id] = lock
             return lock
 
@@ -1192,6 +1201,90 @@ class PluginStoreManager:
         return next((p for p in plugins if p.get('id') == plugin_id), None)
     
     def install_plugin(self, plugin_id: str, branch: Optional[str] = None) -> bool:
+        """Install a plugin, keeping any existing install until the new one is
+        known good.
+
+        `_install_plugin_impl` deletes the existing directory *before*
+        downloading, so every failure after that point — a dropped connection, a
+        malformed manifest, or the compatibility gate refusing the new version —
+        left the user with no plugin at all. `_reinstall_with_rollback` gives the
+        *update* path exactly this protection; a direct install had none, and the
+        compatibility gate added a new way to reach it.
+
+        Pass-through when nothing is installed, and when called from
+        `_reinstall_with_rollback`, which has already moved the old copy aside.
+
+        The aside name embeds '.standalone-backup-' so plugin discovery
+        (`plugin_manager._scan_directory_for_plugins`) skips it even though it
+        still holds a manifest.json.
+
+        Held under the per-plugin reinstall lock for the same reason
+        `_reinstall_with_rollback` is: the web UI runs Flask with
+        threaded=True, so a double-clicked Install button gives two threads the
+        same plugin_id. Interleaved, one thread's restore would delete the
+        other's freshly installed copy. The lock is reentrant because the
+        rollback path already holds it when it calls in here.
+        """
+        with self._get_reinstall_lock(plugin_id):
+            plugin_path = self.plugins_dir / plugin_id
+            if not plugin_path.exists():
+                return self._install_plugin_impl(plugin_id, branch)
+
+            backup_path = plugin_path.with_name(
+                f"{plugin_path.name}.standalone-backup-preinstall")
+            if backup_path.exists() and not self._safe_remove_directory(backup_path):
+                # Can't stage a safety net. Better to attempt the install than
+                # to refuse outright, which is what callers got before this
+                # existed.
+                self.logger.warning(
+                    "Could not clear stale pre-install backup for %s at %s; "
+                    "installing without a rollback net", plugin_id, backup_path)
+                return self._install_plugin_impl(plugin_id, branch)
+
+            try:
+                plugin_path.rename(backup_path)
+            except OSError as e:
+                self.logger.warning(
+                    "Could not set aside existing install of %s (%s); "
+                    "installing without a rollback net", plugin_id, e)
+                return self._install_plugin_impl(plugin_id, branch)
+
+            try:
+                installed = self._install_plugin_impl(plugin_id, branch)
+            except Exception:
+                self._restore_preinstall_backup(plugin_id, plugin_path, backup_path)
+                raise
+
+            if installed:
+                if not self._safe_remove_directory(backup_path):
+                    self.logger.warning(
+                        "Install of %s succeeded but the previous copy at %s "
+                        "could not be removed; it will be cleared on the next "
+                        "install", plugin_id, backup_path)
+                return True
+
+            self._restore_preinstall_backup(plugin_id, plugin_path, backup_path)
+            return False
+
+    def _restore_preinstall_backup(
+        self, plugin_id: str, plugin_path: Path, backup_path: Path
+    ) -> None:
+        """Put the previous install back after a failed (re)install."""
+        self.logger.error(
+            "Install of %s failed; restoring the previous version", plugin_id)
+        try:
+            if plugin_path.exists():
+                # Partial download debris from the failed install.
+                self._safe_remove_directory(plugin_path)
+            backup_path.rename(plugin_path)
+            self.logger.info("Restored previous install of %s", plugin_id)
+        except OSError as e:
+            self.logger.error(
+                "CRITICAL: could not restore %s from %s: %s. The previous "
+                "install is preserved there — rename it back manually.",
+                plugin_id, backup_path, e)
+
+    def _install_plugin_impl(self, plugin_id: str, branch: Optional[str] = None) -> bool:
         """
         Install a plugin from the official registry. Always installs the latest commit
         from the repository's default branch (or specified branch).
@@ -1333,6 +1426,26 @@ class PluginStoreManager:
                     self._safe_remove_directory(plugin_path)
                     return False
 
+                # Refuse a plugin that needs a newer core than this one. The
+                # registry carries no compatibility field, so the floor is only
+                # knowable once the files are down — checking here, before
+                # dependency installation, is the earliest possible point.
+                #
+                # Refusing costs the user nothing: on an update this returns
+                # False and _reinstall_with_rollback restores the version they
+                # already had. Allowing it costs them a plugin that raises
+                # ModuleNotFoundError at load and is reported only as one line
+                # in the journal. See docs/SPORTS_UNIFICATION.md (phase B4/B6).
+                from src import __version__ as core_version
+                from src.plugin_system import compatibility
+
+                compatible, reason = compatibility.check(manifest, core_version)
+                if not compatible:
+                    self.logger.error(
+                        "Refusing to install %s: %s", plugin_id, reason)
+                    self._safe_remove_directory(plugin_path)
+                    return False
+
                 if 'entry_point' not in manifest:
                     manifest['entry_point'] = 'manager.py'
                     manifest_modified = True

test/test_install_preserves_existing.py

@@ -0,0 +1,222 @@
+"""A failed (re)install must not destroy the working plugin it replaced.
+
+`_install_plugin_impl` deletes the existing plugin directory *before* it
+downloads anything, so any failure after that point used to leave the user with
+nothing. The update path was protected — `_reinstall_with_rollback` renames the
+old copy aside first — but a direct `install_plugin` was not, and the
+compatibility gate added a new way to fail late: a plugin whose declared floor
+exceeds the running core is now refused *after* the old copy is already gone.
+
+Concretely, without the wrapper: a user on core 3.1.0 with a working
+hockey-scoreboard clicks Install; the new manifest floors at 3.2.0; the gate
+refuses; the plugin they had is deleted. Floors are hand-written and can be
+over-declared, so this could remove a plugin that was working fine.
+"""
+
+import json
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from src.plugin_system.store_manager import PluginStoreManager
+
+
+@pytest.fixture
+def store(tmp_path):
+    plugins_dir = tmp_path / "plugin-repos"
+    plugins_dir.mkdir()
+    mgr = PluginStoreManager(plugins_dir=str(plugins_dir))
+    mgr.logger = MagicMock()
+    return mgr, plugins_dir
+
+
+def _existing_install(plugins_dir: Path, plugin_id: str, marker: str) -> Path:
+    path = plugins_dir / plugin_id
+    path.mkdir(parents=True)
+    (path / "manifest.json").write_text(
+        json.dumps({"id": plugin_id, "name": plugin_id, "class_name": "P",
+                    "display_modes": ["a"], "version": "1.0.0"}),
+        encoding="utf-8")
+    (path / "marker.txt").write_text(marker, encoding="utf-8")
+    return path
+
+
+class TestFailedInstallPreservesPrevious:
+    def test_failed_install_restores_the_old_copy(self, store, monkeypatch):
+        mgr, plugins_dir = store
+        path = _existing_install(plugins_dir, "hockey-scoreboard", "the-original")
+
+        monkeypatch.setattr(mgr, "_install_plugin_impl", lambda *a, **k: False)
+
+        assert mgr.install_plugin("hockey-scoreboard") is False
+        assert path.exists(), "the previous install must be restored"
+        assert (path / "marker.txt").read_text() == "the-original"
+
+    def test_raising_install_restores_and_reraises(self, store, monkeypatch):
+        mgr, plugins_dir = store
+        path = _existing_install(plugins_dir, "hockey-scoreboard", "the-original")
+
+        def boom(*a, **k):
+            raise RuntimeError("network died mid-install")
+
+        monkeypatch.setattr(mgr, "_install_plugin_impl", boom)
+
+        with pytest.raises(RuntimeError):
+            mgr.install_plugin("hockey-scoreboard")
+        assert path.exists()
+        assert (path / "marker.txt").read_text() == "the-original"
+
+    def test_successful_install_clears_the_backup(self, store, monkeypatch):
+        mgr, plugins_dir = store
+        _existing_install(plugins_dir, "hockey-scoreboard", "the-original")
+
+        def succeed(plugin_id, branch=None):
+            _existing_install(plugins_dir, plugin_id, "the-new-one")
+            return True
+
+        monkeypatch.setattr(mgr, "_install_plugin_impl", succeed)
+
+        assert mgr.install_plugin("hockey-scoreboard") is True
+        assert (plugins_dir / "hockey-scoreboard" / "marker.txt").read_text() == "the-new-one"
+        leftovers = [p.name for p in plugins_dir.iterdir() if "backup" in p.name]
+        assert not leftovers, f"backup left behind: {leftovers}"
+
+    def test_backup_name_is_invisible_to_plugin_discovery(self, store, monkeypatch):
+        """A backup that discovery can see becomes a duplicate plugin entry;
+        the marker '.standalone-backup-' is what makes it skip."""
+        mgr, plugins_dir = store
+        _existing_install(plugins_dir, "hockey-scoreboard", "the-original")
+
+        seen = {}
+
+        def capture(plugin_id, branch=None):
+            seen["dirs"] = sorted(p.name for p in plugins_dir.iterdir())
+            return False
+
+        monkeypatch.setattr(mgr, "_install_plugin_impl", capture)
+        mgr.install_plugin("hockey-scoreboard")
+
+        backups = [d for d in seen["dirs"] if d != "hockey-scoreboard"]
+        assert backups, "expected the old copy to be set aside during install"
+        for name in backups:
+            assert ".standalone-backup-" in name, (
+                f"{name} would be picked up by "
+                "plugin_manager._scan_directory_for_plugins as a real plugin")
+
+    def test_fresh_install_is_a_pass_through(self, store, monkeypatch):
+        """Nothing installed means nothing to protect; don't create stray dirs."""
+        mgr, plugins_dir = store
+        calls = []
+        monkeypatch.setattr(
+            mgr, "_install_plugin_impl",
+            lambda *a, **k: calls.append(a) or True)
+
+        assert mgr.install_plugin("brand-new") is True
+        assert calls, "the implementation must still be called"
+        assert list(plugins_dir.iterdir()) == []
+
+    def test_stale_backup_from_a_crash_does_not_block(self, store, monkeypatch):
+        mgr, plugins_dir = store
+        _existing_install(plugins_dir, "hockey-scoreboard", "the-original")
+        stale = plugins_dir / "hockey-scoreboard.standalone-backup-preinstall"
+        stale.mkdir()
+        (stale / "junk.txt").write_text("from a previous crash", encoding="utf-8")
+
+        monkeypatch.setattr(mgr, "_install_plugin_impl", lambda *a, **k: False)
+
+        assert mgr.install_plugin("hockey-scoreboard") is False
+        assert (plugins_dir / "hockey-scoreboard" / "marker.txt").read_text() == "the-original"
+
+
+class TestUpdatePathStillWorks:
+    def test_reinstall_with_rollback_is_not_double_wrapped(self, store, monkeypatch):
+        """_reinstall_with_rollback moves the plugin aside itself, so by the
+        time install_plugin runs there is nothing at the original path and the
+        wrapper must be a pass-through rather than staging a second backup."""
+        mgr, plugins_dir = store
+        path = _existing_install(plugins_dir, "hockey-scoreboard", "the-original")
+
+        observed = {}
+
+        def impl(plugin_id, branch=None):
+            observed["dirs"] = sorted(p.name for p in plugins_dir.iterdir())
+            return False
+
+        monkeypatch.setattr(mgr, "_install_plugin_impl", impl)
+
+        assert mgr._reinstall_with_rollback("hockey-scoreboard", path) is False
+        # Exactly one aside directory existed during the attempt — rollback's.
+        assert observed["dirs"] == ["hockey-scoreboard.standalone-backup-migrating"]
+        # And the user still has their plugin.
+        assert (plugins_dir / "hockey-scoreboard" / "marker.txt").read_text() == "the-original"
+
+
+class TestConcurrency:
+    """The web UI runs Flask threaded, so a double-clicked Install button puts
+    two threads on the same plugin_id. `_reinstall_with_rollback` already
+    guarded against this; the install wrapper has to as well, or one thread's
+    restore deletes the other's freshly installed copy."""
+
+    def test_rollback_calling_install_does_not_deadlock(self, store, monkeypatch):
+        """The rollback path holds the per-plugin lock across its call to
+        install_plugin. A non-reentrant lock would hang the request thread
+        forever — this test would time out rather than fail."""
+        import threading
+
+        mgr, plugins_dir = store
+        path = _existing_install(plugins_dir, "hockey-scoreboard", "the-original")
+        monkeypatch.setattr(
+            mgr, "_install_plugin_impl",
+            lambda pid, branch=None: bool(_existing_install(plugins_dir, pid, "new")))
+
+        done = threading.Event()
+        result = {}
+
+        def run():
+            result["ok"] = mgr._reinstall_with_rollback("hockey-scoreboard", path)
+            done.set()
+
+        t = threading.Thread(target=run, daemon=True)
+        t.start()
+        assert done.wait(timeout=10), (
+            "install_plugin deadlocked when called from _reinstall_with_rollback "
+            "— the per-plugin lock must be reentrant"
+        )
+        assert result["ok"] is True
+
+    def test_concurrent_installs_serialize(self, store, monkeypatch):
+        """Two threads installing the same plugin must not interleave their
+        set-aside/restore, and the survivor must be a complete install."""
+        import threading
+
+        mgr, plugins_dir = store
+        _existing_install(plugins_dir, "hockey-scoreboard", "the-original")
+
+        in_flight = []
+        overlap = []
+
+        def slow_impl(plugin_id, branch=None):
+            in_flight.append(1)
+            if len(in_flight) > 1:
+                overlap.append(1)
+            threading.Event().wait(0.05)
+            _existing_install(plugins_dir, plugin_id, "installed")
+            in_flight.pop()
+            return True
+
+        monkeypatch.setattr(mgr, "_install_plugin_impl", slow_impl)
+
+        threads = [threading.Thread(target=mgr.install_plugin,
+                                    args=("hockey-scoreboard",), daemon=True)
+                   for _ in range(2)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+            assert not t.is_alive(), "concurrent install hung"
+
+        assert not overlap, "two installs of the same plugin ran concurrently"
+        assert (plugins_dir / "hockey-scoreboard" / "marker.txt").exists()
+        leftovers = [p.name for p in plugins_dir.iterdir() if "backup" in p.name]
+        assert not leftovers, f"backup left behind: {leftovers}"

test/test_plugin_compatibility_gate.py

@@ -0,0 +1,430 @@
+"""The install/update gate, and the shared compatibility rules behind it.
+
+Before this existed, `ledmatrix_min_version` was decoration: the loader logged
+an advisory warning and the store never looked at the core version at all, so a
+routine store update happily delivered a plugin that could not run. Deleting a
+plugin's bundled fallback under those conditions would have handed un-updated
+users a scoreboard that fails to load with one line in the journal.
+
+The rules being pinned here, in priority order:
+
+1. Refuse only on **evidence**. Undeclared floor, unparseable version on either
+   side, or a core whose self-reported version is untrustworthy → allow. A
+   wrong refusal breaks a working install; a wrong allowance degrades to the
+   behavior we already had.
+2. A core below `TRUSTWORTHY_FLOOR` is *unknown*, not old. The v3.1.0 release
+   reports `1.0.0` while nearly every manifest floors at `2.0.0`; blocking on
+   that number would stop those users installing anything at all.
+3. The loader and the store must agree, because they read the same manifests.
+"""
+
+import json
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from src.plugin_system import compatibility
+
+
+# --------------------------------------------------------------------------
+# Floor resolution — every spelling published plugins actually use
+# --------------------------------------------------------------------------
+
+class TestDeclaredMinVersion:
+    def test_top_level_min_ledmatrix_version(self):
+        assert compatibility.declared_min_version(
+            {"min_ledmatrix_version": "3.2.0"}) == "3.2.0"
+
+    def test_requires_block(self):
+        assert compatibility.declared_min_version(
+            {"requires": {"min_ledmatrix_version": "3.1.0"}}) == "3.1.0"
+
+    def test_versions_array_new_spelling(self):
+        assert compatibility.declared_min_version(
+            {"versions": [{"ledmatrix_min_version": "3.2.0"}]}) == "3.2.0"
+
+    def test_versions_array_deprecated_spelling(self):
+        """Most published manifests still say `ledmatrix_min`; ignoring it
+        would silently exempt them from the gate."""
+        assert compatibility.declared_min_version(
+            {"versions": [{"ledmatrix_min": "2.0.0"}]}) == "2.0.0"
+
+    def test_absent(self):
+        assert compatibility.declared_min_version({"id": "x"}) is None
+
+    def test_requires_present_but_null(self):
+        assert compatibility.declared_min_version({"requires": None}) is None
+
+
+# --------------------------------------------------------------------------
+# The decision itself
+# --------------------------------------------------------------------------
+
+class TestCheck:
+    def test_blocks_when_plugin_needs_a_newer_core(self):
+        ok, reason = compatibility.check(
+            {"name": "Hockey Scoreboard", "min_ledmatrix_version": "3.2.0"}, "3.1.0")
+        assert ok is False
+        assert "3.2.0" in reason and "3.1.0" in reason
+        assert "Hockey Scoreboard" in reason
+
+    def test_allows_equal_version(self):
+        ok, _ = compatibility.check({"min_ledmatrix_version": "3.2.0"}, "3.2.0")
+        assert ok is True
+
+    def test_allows_newer_core(self):
+        ok, _ = compatibility.check({"min_ledmatrix_version": "3.2.0"}, "4.0.0")
+        assert ok is True
+
+    def test_allows_when_no_floor_declared(self):
+        ok, reason = compatibility.check({"id": "x"}, "3.2.0")
+        assert ok is True and reason is None
+
+    def test_untrustworthy_core_allows_todays_ecosystem_floor(self):
+        """The v3.1.0 release reports 1.0.0. Nearly every manifest floors at
+        2.0.0, so blocking *that* would stop those users installing any plugin
+        at all — strictly worse than the problem being solved.
+
+        A floor ABOVE 2.0.0 is refused instead; see
+        TestUntrustworthyCoreAndTheSunset for why that case is different."""
+        ok, reason = compatibility.check(
+            {"min_ledmatrix_version": "2.0.0"}, "1.0.0")
+        assert ok is True and reason is None
+
+    def test_unparseable_core_version_allows_the_ecosystem_floor(self):
+        """An unidentifiable core is treated exactly like an untrustworthy one:
+        today's 2.0.0 floor is allowed, a post-sunset floor is not."""
+        ok, _ = compatibility.check({"min_ledmatrix_version": "2.0.0"}, "not-a-version")
+        assert ok is True
+        ok, _ = compatibility.check({"min_ledmatrix_version": "3.2.0"}, "not-a-version")
+        assert ok is False
+
+    def test_unparseable_floor_allows(self):
+        ok, _ = compatibility.check({"min_ledmatrix_version": {"nope": 1}}, "3.2.0")
+        assert ok is True
+
+    def test_v_prefix_tolerated_on_both_sides(self):
+        ok, _ = compatibility.check({"min_ledmatrix_version": "v3.3.0"}, "v3.2.0")
+        assert ok is False
+
+    @pytest.mark.parametrize("floor,core,expected_ok", [
+        ("3.2.0", "3.2.1", True),
+        ("3.2.1", "3.2.0", False),
+        ("3.10.0", "3.9.0", False),   # numeric compare, not lexical
+        ("3.9.0", "3.10.0", True),
+    ])
+    def test_ordering(self, floor, core, expected_ok):
+        ok, _ = compatibility.check({"min_ledmatrix_version": floor}, core)
+        assert ok is expected_ok
+
+
+# --------------------------------------------------------------------------
+# The gate in install_plugin
+# --------------------------------------------------------------------------
+
+def _write_plugin(plugins_dir: Path, plugin_id: str, manifest: dict) -> Path:
+    path = plugins_dir / plugin_id
+    path.mkdir(parents=True)
+    (path / "manifest.json").write_text(json.dumps(manifest), encoding="utf-8")
+    (path / "manager.py").write_text("class P: pass\n", encoding="utf-8")
+    return path
+
+
+@pytest.fixture
+def store(tmp_path, monkeypatch):
+    """A PluginStoreManager whose download step is stubbed to drop a plugin
+    directory in place, so the test exercises the post-download validation
+    path without touching the network."""
+    from src.plugin_system.store_manager import PluginStoreManager
+
+    plugins_dir = tmp_path / "plugin-repos"
+    plugins_dir.mkdir()
+    mgr = PluginStoreManager(plugins_dir=str(plugins_dir))
+    mgr.logger = MagicMock()
+    return mgr, plugins_dir
+
+
+class TestInstallGate:
+    """`install_plugin` is the chokepoint: `_reinstall_with_rollback` calls it,
+    so gating there covers updates too, and a refused update restores the
+    version the user already had."""
+
+    def _install_with_manifest(self, store, manifest, core_version, monkeypatch):
+        mgr, plugins_dir = store
+        plugin_id = manifest["id"]
+
+        monkeypatch.setattr(
+            mgr, "get_plugin_info",
+            lambda *a, **k: {"repo": "https://example.invalid/r",
+                             "plugin_path": f"plugins/{plugin_id}",
+                             "branch": "main"})
+        # Stand in for the download: put the files where install_plugin expects.
+        monkeypatch.setattr(
+            mgr, "_install_from_monorepo",
+            lambda *a, **k: bool(_write_plugin(plugins_dir, plugin_id, manifest)))
+        monkeypatch.setattr(mgr, "_install_from_monorepo_api", lambda *a, **k: False)
+        monkeypatch.setattr(mgr, "_install_dependencies", lambda *a, **k: True)
+
+        import src
+        monkeypatch.setattr(src, "__version__", core_version)
+        return mgr.install_plugin(plugin_id), plugins_dir / plugin_id
+
+    def test_refuses_and_leaves_nothing_behind(self, store, monkeypatch):
+        manifest = {
+            "id": "needs-newer", "name": "Needs Newer", "class_name": "P",
+            "display_modes": ["a"], "min_ledmatrix_version": "9.9.9",
+        }
+        ok, path = self._install_with_manifest(store, manifest, "3.2.0", monkeypatch)
+
+        assert ok is False, "install must refuse a plugin that needs a newer core"
+        assert not path.exists(), (
+            "a refused install must not leave a half-installed directory — "
+            "plugin discovery would pick it up and fail to load it")
+
+    def test_allows_a_compatible_plugin(self, store, monkeypatch):
+        manifest = {
+            "id": "fine", "name": "Fine", "class_name": "P",
+            "display_modes": ["a"], "min_ledmatrix_version": "3.0.0",
+        }
+        ok, path = self._install_with_manifest(store, manifest, "3.2.0", monkeypatch)
+
+        assert ok is True
+        assert (path / "manifest.json").exists()
+
+    def test_untrustworthy_core_does_not_block_installs(self, store, monkeypatch):
+        """Regression guard for the worst possible outcome of this feature:
+        users on the v3.1.0 release (which reports 1.0.0) must not be locked
+        out of the plugin store entirely."""
+        manifest = {
+            "id": "floored", "name": "Floored", "class_name": "P",
+            "display_modes": ["a"], "versions": [{"ledmatrix_min": "2.0.0"}],
+        }
+        ok, path = self._install_with_manifest(store, manifest, "1.0.0", monkeypatch)
+
+        assert ok is True, (
+            "a core below the trustworthy floor must not block installs — "
+            "nearly every published manifest floors at 2.0.0")
+        assert (path / "manifest.json").exists()
+
+
+class TestLoaderAndStoreAgree:
+    """Both read the same manifests; a disagreement means one of them is
+    lying to the user."""
+
+    @pytest.mark.parametrize("manifest,core,expected", [
+        ({"min_ledmatrix_version": "3.2.0"}, "3.1.0", False),
+        ({"versions": [{"ledmatrix_min": "2.0.0"}]}, "3.2.0", True),
+        ({"versions": [{"ledmatrix_min_version": "9.0.0"}]}, "3.2.0", False),
+        ({}, "3.2.0", True),
+    ])
+    def test_same_verdict(self, manifest, core, expected):
+        from src.plugin_system.plugin_loader import PluginLoader
+
+        store_ok, _ = compatibility.check(manifest, core)
+        assert store_ok is expected
+
+        # The loader resolves the floor through the same helper, so a
+        # divergence in spelling handling would show up here.
+        loader_needed = compatibility.parse_semver(
+            compatibility.declared_min_version(manifest))
+        current = compatibility.parse_semver(core)
+        loader_would_warn = (
+            loader_needed is not None
+            and current is not None
+            and current >= compatibility.TRUSTWORTHY_FLOOR
+            and loader_needed > current
+        )
+        assert loader_would_warn is (not expected)
+        assert hasattr(PluginLoader, "_warn_if_incompatible")
+
+
+# --------------------------------------------------------------------------
+# compatible_versions — the schema-required field, and the only one that can
+# express an upper bound
+# --------------------------------------------------------------------------
+
+class TestCompatibleVersions:
+    @pytest.mark.parametrize("spec,core,expected", [
+        (">=2.0.0", "3.2.0", True),
+        (">=2.0.0", "1.9.9", False),
+        ("<=3.0.0", "3.2.0", False),
+        ("<=3.0.0", "2.9.0", True),
+        (">3.2.0", "3.2.0", False),
+        ("<4.0.0", "3.2.0", True),
+        ("3.2.0", "3.2.0", True),      # bare == exact match
+        ("3.2.0", "3.2.1", False),
+        ("~3.2.0", "3.2.9", True),     # patch-level only
+        ("~3.2.0", "3.3.0", False),
+        ("^3.2.0", "3.9.9", True),     # minor + patch
+        ("^3.2.0", "4.0.0", False),
+        ("2.0.0 - 3.2.0", "3.2.0", True),   # inclusive both ends
+        ("2.0.0 - 3.2.0", "2.0.0", True),
+        ("2.0.0 - 3.2.0", "3.2.1", False),
+        ("v3.2.0", "3.2.0", True),     # leading v tolerated
+        ("3.2.0-beta.1", "3.2.0", True),  # prerelease suffix ignored
+    ])
+    def test_range_forms(self, spec, core, expected):
+        got = compatibility.satisfies_compatible_versions(
+            {"compatible_versions": [spec]}, compatibility.parse_semver(core))
+        assert got is expected, f"{spec!r} vs {core}"
+
+    def test_array_is_alternatives_not_conjunction(self):
+        """Satisfying any one entry is enough — otherwise ['<2.0.0','>=3.0.0']
+        could never be satisfied by anything."""
+        m = {"compatible_versions": ["<2.0.0", ">=3.0.0"]}
+        assert compatibility.satisfies_compatible_versions(
+            m, compatibility.parse_semver("3.2.0")) is True
+
+    def test_absent_or_unparseable_is_no_evidence(self):
+        core = compatibility.parse_semver("3.2.0")
+        assert compatibility.satisfies_compatible_versions({}, core) is None
+        assert compatibility.satisfies_compatible_versions(
+            {"compatible_versions": []}, core) is None
+        assert compatibility.satisfies_compatible_versions(
+            {"compatible_versions": ["not a version"]}, core) is None
+        # One unparseable entry alongside a good one must not poison the result.
+        assert compatibility.satisfies_compatible_versions(
+            {"compatible_versions": ["garbage", ">=2.0.0"]}, core) is True
+
+
+class TestMoreRestrictiveWins:
+    def test_upper_bound_blocks_a_core_that_clears_the_floor(self):
+        """The gap this closes: the floor says 2.0.0 and the core is 3.2.0, so
+        the floor alone would allow it — but the plugin said it stops at 2.x."""
+        m = {"name": "Legacy Plugin",
+             "compatible_versions": ["2.0.0 - 2.9.9"],
+             "versions": [{"ledmatrix_min_version": "2.0.0"}]}
+        ok, reason = compatibility.check(m, "3.2.0")
+        assert ok is False
+        assert "2.0.0 - 2.9.9" in reason and "3.2.0" in reason
+
+    def test_floor_blocks_when_ranges_would_allow(self):
+        m = {"name": "Needs Newer",
+             "compatible_versions": [">=1.0.0"],
+             "versions": [{"ledmatrix_min_version": "9.9.9"}]}
+        ok, reason = compatibility.check(m, "3.2.0")
+        assert ok is False
+        assert "9.9.9" in reason
+
+    def test_both_satisfied_allows(self):
+        m = {"compatible_versions": [">=2.0.0"],
+             "versions": [{"ledmatrix_min_version": "2.0.0"}]}
+        assert compatibility.check(m, "3.2.0") == (True, None)
+
+    def test_untrustworthy_core_still_bypasses_both_checks(self):
+        """A core reporting 1.0.0 fails `>=2.0.0`, which 41 of 42 published
+        manifests declare. Blocking there would empty the plugin store for
+        exactly the users who cannot be helped by it."""
+        m = {"compatible_versions": [">=2.0.0"],
+             "versions": [{"ledmatrix_min_version": "2.0.0"}]}
+        assert compatibility.check(m, "1.0.0") == (True, None)
+
+
+class TestUntrustworthyCoreAndTheSunset:
+    """The population B6 would otherwise break.
+
+    A device installed from the v3.1.0 release reports `__version__ = "1.0.0"`.
+    The gate cannot tell it apart from a genuine 1.0.0 install, so it cannot
+    reason about what that core actually has — and at the B6 sunset the
+    plugin's guarded-import fallback is gone. Without this rule the store hands
+    those users a 3.2.0-floored plugin that fails to load, and nothing else in
+    the system protects them.
+
+    The rule: on an untrustworthy core, refuse a floor *above* the ecosystem
+    baseline, allow anything at or below it. Every manifest published today
+    floors at exactly 2.0.0, so nobody is locked out of the store.
+    """
+
+    UNTRUSTWORTHY = ["1.0.0", "0.9.0", "1.9.9"]
+
+    @pytest.mark.parametrize("core", UNTRUSTWORTHY)
+    def test_refuses_a_post_sunset_floor(self, core):
+        m = {"name": "Hockey Scoreboard",
+             "versions": [{"ledmatrix_min_version": "3.2.0"}]}
+        ok, reason = compatibility.check(m, core)
+        assert ok is False, (
+            f"core {core} must not receive a 3.2.0-floored plugin: after the "
+            "sunset there is no fallback and it will fail to load"
+        )
+        assert "3.2.0" in reason and core in reason
+
+    @pytest.mark.parametrize("core", UNTRUSTWORTHY)
+    def test_still_allows_todays_ecosystem_floor(self, core):
+        """Regression guard: every published manifest floors at 2.0.0. If this
+        starts refusing, those users lose the plugin store entirely."""
+        m = {"versions": [{"ledmatrix_min": "2.0.0"}]}
+        assert compatibility.check(m, core) == (True, None)
+
+    @pytest.mark.parametrize("core", UNTRUSTWORTHY)
+    def test_still_allows_an_undeclared_floor(self, core):
+        assert compatibility.check({"id": "x"}, core) == (True, None)
+
+    def test_trustworthy_core_below_the_floor_is_unaffected(self):
+        """A core that reports 3.1.0 is believable and already handled by the
+        ordinary comparison — not by this rule."""
+        m = {"name": "P", "versions": [{"ledmatrix_min_version": "3.2.0"}]}
+        ok, reason = compatibility.check(m, "3.1.0")
+        assert ok is False
+        assert "too old to identify" not in reason, (
+            "a believable version should get the ordinary message"
+        )
+
+
+class TestMalformedManifests:
+    """A manifest we cannot parse must read as "no declared floor", not raise.
+
+    This matters more since the untrustworthy-core branch of check() began
+    resolving the floor for *every* manifest: one hand-edited or third-party
+    file with the wrong shape would take down the whole install path rather
+    than just itself.
+    """
+
+    @pytest.mark.parametrize("manifest", [
+        {"requires": ["python>=3.9"]},          # a list, not a mapping
+        {"requires": "python>=3.9"},            # a bare string
+        {"versions": {"a": 1}},                 # a mapping, not a list
+        {"versions": "1.0.0"},                  # a bare string
+        {"versions": [None]},                   # a list of the wrong thing
+        {"versions": []},
+    ])
+    def test_shape_errors_read_as_no_floor(self, manifest):
+        assert compatibility.declared_min_version(manifest) is None
+        assert compatibility.check(manifest, "1.0.0") == (True, None)
+        assert compatibility.check(manifest, "3.2.0") == (True, None)
+
+    def test_a_valid_requires_block_still_works(self):
+        assert compatibility.declared_min_version(
+            {"requires": {"min_ledmatrix_version": "3.2.0"}}) == "3.2.0"
+
+
+class TestSuffixedVersions:
+    """Prerelease and build metadata must not leak into the numbers.
+
+    The digit scrape used to pull them in: "3.2.0+build42" became (3, 2, 42)
+    and "3.2.0-rc1" became (3, 2, 1) — a release candidate ranking above its
+    own release. Both fed reject decisions.
+    """
+
+    @pytest.mark.parametrize("text,expected", [
+        ("3.2.0", (3, 2, 0)),
+        ("3.2.0+build42", (3, 2, 0)),
+        ("3.2.0-rc1", (3, 2, 0)),
+        ("3.2.0-rc.1+build.9", (3, 2, 0)),
+        ("v3.2.0+build42", (3, 2, 0)),
+    ])
+    def test_suffixes_are_dropped(self, text, expected):
+        assert compatibility.parse_semver(text) == expected
+
+    def test_a_build_of_the_pinned_version_is_not_refused(self):
+        """The regression: an exact "3.2.0" pin refused a core running
+        3.2.0+build42, which is that same version."""
+        ok, reason = compatibility.check(
+            {"compatible_versions": ["3.2.0"]}, "3.2.0+build42")
+        assert ok is True, f"refused a build of the pinned version: {reason}"
+
+    def test_a_release_candidate_does_not_outrank_its_release(self):
+        m = {"versions": [{"ledmatrix_min_version": "3.2.0"}]}
+        assert compatibility.check(m, "3.2.0-rc1")[0] is True
+        # ...and still refuses something genuinely older.
+        assert compatibility.check(m, "3.1.0-rc1")[0] is False