plugin-scanner 2.2.115__tar.gz → 2.2.117__tar.gz

plugin_scanner-2.2.117/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+title: "HOL Guard"
+message: "If you reference HOL Guard, please cite this software repository. A scan is not a safety guarantee."
+type: software
+authors:
+  - name: "Hashgraph Online"
+url: "https://github.com/hashgraph-online/hol-guard"
+repository-code: "https://github.com/hashgraph-online/hol-guard"
+license: "Apache-2.0"
+identifiers:
+  - type: url
+    value: "https://hol.org/guard"
+    description: "HOL Guard product site."
+  - type: url
+    value: "https://huggingface.co/datasets/HashgraphOnline/hol-plugin-security"
+    description: "Related Hugging Face dataset (HOL Plugin Security). Runtime fixtures in that dataset are modeled, not live attacks. A scan is not a safety guarantee."

{plugin_scanner-2.2.115 → plugin_scanner-2.2.117}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.2.115
+Version: 2.2.117
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://hol.org/guard
 Project-URL: Security, https://hol.org/guard/security
@@ -512,6 +512,7 @@ See [`devcontainer-features/hol-guard/README.md`](devcontainer-features/hol-guar
 | :--- | :--- |
 | Codex | `.codex-plugin/plugin.json`, `marketplace.json`, `.agents/plugins/marketplace.json` |
 | Claude Code | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` |
+| DeepSeek Harness | `package.json` with `dsh.bundle`, declared patch file, and Cordis `apply(ctx)` runtime export |
 | Gemini CLI | `gemini-extension.json`, `commands/**/*.toml` |
 | Kimi Code | `kimi.plugin.json`, `.kimi-plugin/plugin.json`, declared skills, agents, commands, prompts, and MCP servers |
 | OpenCode | `opencode.json`, `opencode.jsonc`, `.opencode/commands`, `.opencode/plugins` |
@@ -555,6 +556,9 @@ plugin-scanner scan ./plugins-repo --ecosystem claude
 # Scan only native Kimi Code plugin surfaces
 plugin-scanner scan ./plugins-repo --ecosystem kimi
 
+# Scan a native DeepSeek Harness (DSH/Cordis) package
+plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness
+
 # List supported ecosystems
 plugin-scanner --list-ecosystems
 

{plugin_scanner-2.2.115 → plugin_scanner-2.2.117}/README.md

@@ -458,6 +458,7 @@ See [`devcontainer-features/hol-guard/README.md`](devcontainer-features/hol-guar
 | :--- | :--- |
 | Codex | `.codex-plugin/plugin.json`, `marketplace.json`, `.agents/plugins/marketplace.json` |
 | Claude Code | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` |
+| DeepSeek Harness | `package.json` with `dsh.bundle`, declared patch file, and Cordis `apply(ctx)` runtime export |
 | Gemini CLI | `gemini-extension.json`, `commands/**/*.toml` |
 | Kimi Code | `kimi.plugin.json`, `.kimi-plugin/plugin.json`, declared skills, agents, commands, prompts, and MCP servers |
 | OpenCode | `opencode.json`, `opencode.jsonc`, `.opencode/commands`, `.opencode/plugins` |
@@ -501,6 +502,9 @@ plugin-scanner scan ./plugins-repo --ecosystem claude
 # Scan only native Kimi Code plugin surfaces
 plugin-scanner scan ./plugins-repo --ecosystem kimi
 
+# Scan a native DeepSeek Harness (DSH/Cordis) package
+plugin-scanner scan ./dsh-plugin --ecosystem deepseek-harness
+
 # List supported ecosystems
 plugin-scanner --list-ecosystems
 

plugin_scanner-2.2.117/ci/test-suite-ratchet-baseline.json

@@ -0,0 +1,5 @@
+{
+  "maximum_collected_cases": 12802,
+  "maximum_test_source_lines": 292242,
+  "schema_version": 1
+}

{plugin_scanner-2.2.115 → plugin_scanner-2.2.117}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.2.115"
+version = "2.2.117"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.2.115 → plugin_scanner-2.2.117}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.2.115"
+version = "2.2.117"
 description = "Open-source antivirus and runtime protection for AI agents, tools, MCP servers, plugins, skills, and package installs."
 readme = "README.md"
 license = "Apache-2.0"

plugin_scanner-2.2.115/release-metadata/plugin-scanner-v2.2.115.toolchain.cdx.json → plugin_scanner-2.2.117/release-metadata/plugin-scanner-v2.2.117.toolchain.cdx.json

@@ -27,7 +27,7 @@
     "component": {
       "name": "hol-guard-release-toolchain",
       "type": "application",
-      "version": "2.2.115"
+      "version": "2.2.117"
     }
   },
   "specVersion": "1.6",

plugin_scanner-2.2.117/src/codex_plugin_scanner/checks/deepseek_harness.py

@@ -0,0 +1,70 @@
+"""DeepSeek Harness ecosystem checks."""
+
+from __future__ import annotations
+
+from ..deepseek_harness_support import validate_dsh_package
+from ..ecosystems.types import NormalizedPackage
+from ..models import CheckResult, Finding, Severity
+
+
+def _result(name: str, passed: bool, message: str, rule_id: str, description: str) -> CheckResult:
+    findings = (
+        ()
+        if passed
+        else (
+            Finding(
+                rule_id=rule_id,
+                severity=Severity.MEDIUM,
+                category="deepseek-harness",
+                title=message,
+                description=description,
+                remediation="Update the native DSH declaration in package.json.",
+                file_path="package.json",
+            ),
+        )
+    )
+    return CheckResult(
+        name=name, passed=passed, points=5 if passed else 0, max_points=5, message=message, findings=findings
+    )
+
+
+def run_deepseek_harness_checks(package: NormalizedPackage) -> tuple[CheckResult, ...]:
+    """Validate a native DSH package and its Cordis bundle declaration."""
+
+    validation = validate_dsh_package(package)
+    return (
+        _result(
+            "DSH package metadata",
+            validation.metadata_ok,
+            "DSH package metadata is valid"
+            if validation.metadata_ok
+            else "DSH package requires a name and semantic version",
+            "DSH_PACKAGE_METADATA_INVALID",
+            "package.json must declare a non-empty name and semantic version.",
+        ),
+        _result(
+            "DSH bundle declaration",
+            validation.bundle_ok,
+            "DSH bundle declaration is valid" if validation.bundle_ok else "dsh.bundle must be a non-empty object",
+            "DSH_BUNDLE_INVALID",
+            "Native DSH packages must declare at least one bundle entry.",
+        ),
+        _result(
+            "DSH bundle paths",
+            validation.patch_ok,
+            "DSH bundle paths are safe"
+            if validation.patch_ok
+            else "dsh.bundle.patch must reference a regular in-package file",
+            "DSH_BUNDLE_PATH_UNSAFE",
+            "The declared bundle patch is missing or escapes the package root.",
+        ),
+        _result(
+            "DSH Cordis runtime entry point",
+            validation.runtime_ok,
+            "DSH runtime exports apply(ctx)"
+            if validation.runtime_ok
+            else "DSH runtime entry point must export apply(ctx)",
+            "DSH_RUNTIME_APPLY_MISSING",
+            "package.json main/exports must reference a regular in-package module exporting Cordis apply(ctx).",
+        ),
+    )

{plugin_scanner-2.2.115 → plugin_scanner-2.2.117}/src/codex_plugin_scanner/cli.py

@@ -116,7 +116,7 @@ def _build_parser(program_name: str, *, program_mode: str) -> argparse.ArgumentP
     scan_parser.add_argument("--cisco-policy", choices=("permissive", "balanced", "strict"), default="balanced")
     scan_parser.add_argument(
         "--ecosystem",
-        choices=("auto", "codex", "claude", "gemini", "kimi", "opencode"),
+        choices=("auto", *list_supported_ecosystems(), "dsh", "deepseek_harness"),
         default="auto",
         help="Target one ecosystem explicitly or auto-detect all supported ecosystems.",
     )

plugin_scanner-2.2.117/src/codex_plugin_scanner/deepseek_harness_support.py

@@ -0,0 +1,318 @@
+"""Shared validation helpers for native DeepSeek Harness packages."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .ecosystems.types import NormalizedPackage
+from .path_support import is_safe_relative_path
+
+DSH_SEMVER_RE = re.compile(
+    "".join(
+        (
+            r"^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)",
+            r"(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?",
+            r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$",
+        )
+    )
+)
+
+_REGEX_PREFIX_TOKENS = frozenset(
+    {
+        "(",
+        "[",
+        "{",
+        "=",
+        ":",
+        ",",
+        ";",
+        "!",
+        "?",
+        "&&",
+        "||",
+        "=>",
+        "case",
+        "delete",
+        "do",
+        "else",
+        "in",
+        "instanceof",
+        "new",
+        "of",
+        "return",
+        "throw",
+        "typeof",
+        "void",
+        "yield",
+        "await",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DshValidation:
+    metadata_ok: bool
+    bundle_ok: bool
+    patch_ok: bool
+    runtime_ok: bool
+    runtime_path: str | None
+
+
+def _export_target(value: object) -> str | None:
+    """Resolve one Node package export target without selecting subpath exports."""
+
+    if isinstance(value, str):
+        stripped = value.strip()
+        return stripped or None
+    if isinstance(value, list):
+        for candidate in value:
+            if (resolved := _export_target(candidate)) is not None:
+                return resolved
+        return None
+    if not isinstance(value, dict):
+        return None
+
+    for condition in ("import", "require", "node", "default"):
+        if condition in value and (resolved := _export_target(value[condition])) is not None:
+            return resolved
+    for condition, candidate in value.items():
+        if not isinstance(condition, str) or condition == "types" or condition.startswith("."):
+            continue
+        if (resolved := _export_target(candidate)) is not None:
+            return resolved
+    return None
+
+
+def _runtime_path(manifest: dict[str, object]) -> str | None:
+    """Resolve the package root export, falling back to ``main`` only without ``exports``."""
+
+    if "exports" in manifest:
+        exports = manifest["exports"]
+        if isinstance(exports, dict):
+            if "." in exports:
+                return _export_target(exports["."])
+            if any(isinstance(key, str) and key.startswith(".") for key in exports):
+                return None
+        return _export_target(exports)
+    main = manifest.get("main")
+    if not isinstance(main, str):
+        return None
+    stripped = main.strip()
+    return stripped or None
+
+
+def _skip_quoted(source: str, index: int, quote: str) -> int:
+    """Skip one JavaScript string or template literal."""
+
+    index += 1
+    while index < len(source):
+        char = source[index]
+        if char == "\\":
+            index += 2
+            continue
+        index += 1
+        if char == quote:
+            break
+    return index
+
+
+def _skip_regex(source: str, index: int) -> int:
+    """Skip a JavaScript regex literal using a conservative lexical heuristic."""
+
+    index += 1
+    in_character_class = False
+    while index < len(source):
+        char = source[index]
+        if char == "\\":
+            index += 2
+            continue
+        if char == "[":
+            in_character_class = True
+        elif char == "]":
+            in_character_class = False
+        elif char == "/" and not in_character_class:
+            index += 1
+            while index < len(source) and source[index].isalpha():
+                index += 1
+            break
+        elif char in "\r\n":
+            break
+        index += 1
+    return index
+
+
+def _regex_can_start(tokens: list[str]) -> bool:
+    return not tokens or tokens[-1] in _REGEX_PREFIX_TOKENS
+
+
+def _javascript_tokens(source: str) -> tuple[str, ...]:
+    """Tokenize identifiers and punctuation while ignoring comments and literals."""
+
+    tokens: list[str] = []
+    index = 0
+    while index < len(source):
+        char = source[index]
+        following = source[index + 1] if index + 1 < len(source) else ""
+        if char == "/" and following == "/":
+            index += 2
+            while index < len(source) and source[index] not in "\r\n":
+                index += 1
+            continue
+        if char == "/" and following == "*":
+            end = source.find("*/", index + 2)
+            index = len(source) if end < 0 else end + 2
+            continue
+        if char == "/" and _regex_can_start(tokens):
+            index = _skip_regex(source, index)
+            continue
+        if char in {"'", '"', "`"}:
+            index = _skip_quoted(source, index, char)
+            continue
+        if char.isalpha() or char in {"_", "$"}:
+            end = index + 1
+            while end < len(source) and (source[end].isalnum() or source[end] in {"_", "$"}):
+                end += 1
+            tokens.append(source[index:end])
+            index = end
+            continue
+        if source.startswith(("=>", "&&", "||"), index):
+            tokens.append(source[index : index + 2])
+            index += 2
+            continue
+        if not char.isspace():
+            tokens.append(char)
+        index += 1
+    return tuple(tokens)
+
+
+def _matching_brace(tokens: tuple[str, ...], start: int) -> int | None:
+    """Return the matching closing brace index for a tokenized object or list."""
+
+    opening = tokens[start]
+    closing = {"{": "}", "(": ")", "[": "]"}.get(opening)
+    if closing is None:
+        return None
+    depth = 0
+    for index in range(start, len(tokens)):
+        if tokens[index] == opening:
+            depth += 1
+        elif tokens[index] == closing:
+            depth -= 1
+            if depth == 0:
+                return index
+    return None
+
+
+def _export_list_has_apply(entries: tuple[str, ...]) -> bool:
+    """Return whether an ESM export list exposes the name ``apply``."""
+
+    start = 0
+    while start < len(entries):
+        end = start
+        while end < len(entries) and entries[end] != ",":
+            end += 1
+        clause = entries[start:end]
+        if clause and clause[0] != "type":
+            if len(clause) == 1 and clause[0] == "apply":
+                return True
+            if len(clause) >= 3 and clause[-2:] == ("as", "apply"):
+                return True
+        start = end + 1
+    return False
+
+
+def _commonjs_object_has_apply(tokens: tuple[str, ...], start: int, end: int) -> bool:
+    """Return whether a top-level CommonJS export object declares an ``apply`` key."""
+
+    depth = 0
+    clause_start = start + 1
+    index = clause_start
+    while index <= end:
+        token = tokens[index] if index < end else ","
+        if token in {"{", "[", "("}:
+            depth += 1
+        elif token in {"}", "]", ")"}:
+            depth -= 1
+        elif depth == 0 and token == ",":
+            clause = tokens[clause_start:index]
+            if clause and clause[0] == "apply" and (len(clause) == 1 or clause[1] == ":"):
+                return True
+            clause_start = index + 1
+        index += 1
+    return False
+
+
+def _exports_apply(source: str) -> bool:
+    """Return true only when tokenized ESM or CommonJS syntax exports ``apply``."""
+
+    tokens = _javascript_tokens(source)
+    for index, token in enumerate(tokens):
+        tail = tokens[index:]
+        if token == "export":
+            declaration_index = 1
+            if len(tail) > 1 and tail[1] == "async":
+                declaration_index = 2
+            if (
+                len(tail) > declaration_index + 1
+                and tail[declaration_index] in {"function", "const", "let", "var", "class"}
+                and tail[declaration_index + 1] == "apply"
+            ):
+                return True
+            if len(tail) > 1 and tail[1] == "{":
+                close = _matching_brace(tail, 1)
+                if close is not None and _export_list_has_apply(tail[2:close]):
+                    return True
+        if tail[:4] == ("exports", ".", "apply", "="):
+            return True
+        if tail[:6] == ("module", ".", "exports", ".", "apply", "="):
+            return True
+        if tail[:4] == ("module", ".", "exports", "=") and len(tail) > 4 and tail[4] == "{":
+            close = _matching_brace(tail, 4)
+            if close is not None and _commonjs_object_has_apply(tail, 4, close):
+                return True
+    return False
+
+
+def validate_dsh_package(package: NormalizedPackage) -> DshValidation:
+    """Validate shared DSH metadata, bundle assets, and Cordis runtime surface."""
+
+    manifest = package.raw_manifest
+    name = manifest.get("name")
+    version = manifest.get("version")
+    metadata_ok = (
+        isinstance(name, str)
+        and bool(name.strip())
+        and isinstance(version, str)
+        and bool(DSH_SEMVER_RE.fullmatch(version))
+    )
+
+    dsh = manifest.get("dsh")
+    bundle = dsh.get("bundle") if isinstance(dsh, dict) else None
+    bundle_ok = isinstance(bundle, dict) and bool(bundle)
+    raw_patch = bundle.get("patch") if isinstance(bundle, dict) else None
+    patch = raw_patch.strip() if isinstance(raw_patch, str) else None
+    patch_target = package.root_path / patch if patch else None
+    patch_ok = False
+    if patch is not None and patch_target is not None:
+        patch_ok = (
+            is_safe_relative_path(package.root_path, patch, require_exists=True)
+            and patch_target.is_file()
+            and not patch_target.is_symlink()
+        )
+
+    runtime_path = _runtime_path(manifest)
+    runtime_target = package.root_path / runtime_path if runtime_path is not None else None
+    runtime_ok = False
+    if (
+        runtime_path is not None
+        and runtime_target is not None
+        and is_safe_relative_path(package.root_path, runtime_path, require_exists=True)
+        and runtime_target.is_file()
+        and not runtime_target.is_symlink()
+    ):
+        try:
+            runtime_ok = _exports_apply(runtime_target.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError):
+            runtime_ok = False
+    return DshValidation(metadata_ok, bundle_ok, patch_ok, runtime_ok, runtime_path)

plugin_scanner-2.2.117/src/codex_plugin_scanner/ecosystems/deepseek_harness.py

@@ -0,0 +1,76 @@
+"""DeepSeek Harness (DSH/Cordis) ecosystem adapter."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .base import iter_safe_recursive_files
+from .types import Ecosystem, NormalizedPackage, PackageCandidate
+
+
+def _load_json(path: Path) -> tuple[dict[str, object], str | None]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError, UnicodeError) as exc:
+        return {}, str(exc)
+    if not isinstance(payload, dict):
+        return {}, "package.json must contain a JSON object"
+    return payload, None
+
+
+class DeepSeekHarnessAdapter:
+    """Adapter for native DeepSeek Harness packages declared with ``package.json.dsh``."""
+
+    ecosystem_id = Ecosystem.DEEPSEEK_HARNESS
+
+    def detect(self, root: Path) -> list[PackageCandidate]:
+        candidates: list[PackageCandidate] = []
+        for manifest_path in iter_safe_recursive_files(root, root, "package.json"):
+            manifest, error = _load_json(manifest_path)
+            if error is not None:
+                continue
+            dsh = manifest.get("dsh")
+            if not isinstance(dsh, dict) or not isinstance(dsh.get("bundle"), dict):
+                continue
+            candidates.append(
+                PackageCandidate(
+                    ecosystem=Ecosystem.DEEPSEEK_HARNESS,
+                    package_kind="cordis-plugin",
+                    root_path=manifest_path.parent,
+                    manifest_path=manifest_path,
+                    detection_reason="found package.json with dsh.bundle",
+                )
+            )
+        return candidates
+
+    def parse(self, candidate: PackageCandidate) -> NormalizedPackage:
+        manifest, error = _load_json(candidate.manifest_path) if candidate.manifest_path else ({}, "missing manifest")
+        dsh = manifest.get("dsh") if isinstance(manifest.get("dsh"), dict) else {}
+        bundle = dsh.get("bundle") if isinstance(dsh, dict) and isinstance(dsh.get("bundle"), dict) else {}
+        components: dict[str, tuple[str, ...]] = {}
+        patch = bundle.get("patch") if isinstance(bundle, dict) else None
+        if isinstance(patch, str) and patch.strip():
+            components["bundle_patches"] = (patch,)
+        client = dsh.get("client") if isinstance(dsh, dict) else None
+        if isinstance(client, str) and client.strip():
+            components["clients"] = (client,)
+        name = manifest.get("name")
+        version = manifest.get("version")
+        return NormalizedPackage(
+            ecosystem=Ecosystem.DEEPSEEK_HARNESS,
+            package_kind=candidate.package_kind,
+            root_path=candidate.root_path,
+            manifest_path=candidate.manifest_path,
+            name=name if isinstance(name, str) else None,
+            version=version if isinstance(version, str) else None,
+            metadata={
+                key: value
+                for key in ("description", "license", "homepage")
+                if isinstance((value := manifest.get(key)), str)
+            },
+            components=components,
+            raw_manifest=manifest,
+            manifest_parse_error=error is not None,
+            manifest_parse_error_reason=error,
+        )

{plugin_scanner-2.2.115 → plugin_scanner-2.2.117}/src/codex_plugin_scanner/ecosystems/registry.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from .base import EcosystemAdapter
 from .claude import ClaudeAdapter
 from .codex import CodexAdapter
+from .deepseek_harness import DeepSeekHarnessAdapter
 from .gemini import GeminiAdapter
 from .kimi import KimiAdapter
 from .opencode import OpenCodeAdapter
@@ -17,6 +18,7 @@ def get_default_adapters() -> tuple[EcosystemAdapter, ...]:
     return (
         CodexAdapter(),
         ClaudeAdapter(),
+        DeepSeekHarnessAdapter(),
         GeminiAdapter(),
         KimiAdapter(),
         OpenCodeAdapter(),
@@ -31,6 +33,8 @@ def resolve_ecosystem(value: str | None) -> Ecosystem | None:
     lowered = value.strip().lower()
     if lowered in ("", "auto"):
         return None
+    if lowered in ("dsh", "deepseek_harness"):
+        lowered = Ecosystem.DEEPSEEK_HARNESS.value
     try:
         return Ecosystem(lowered)
     except ValueError:

{plugin_scanner-2.2.115 → plugin_scanner-2.2.117}/src/codex_plugin_scanner/ecosystems/types.py

@@ -12,6 +12,7 @@ class Ecosystem(str, Enum):
 
     CODEX = "codex"
     CLAUDE = "claude"
+    DEEPSEEK_HARNESS = "deepseek-harness"
     GEMINI = "gemini"
     KIMI = "kimi"
     OPENCODE = "opencode"

plugin_scanner-2.2.117/src/codex_plugin_scanner/guard/sqlite_recovery.py

@@ -0,0 +1,67 @@
+"""Bounded proof helpers for recovering an unusable Guard SQLite store."""
+
+from __future__ import annotations
+
+import sqlite3
+from contextlib import suppress
+from pathlib import Path
+from typing import Literal
+from uuid import uuid4
+
+FATAL_SQLITE_ERROR_MARKERS = (
+    "database disk image is malformed",
+    "database corruption",
+    "file is not a database",
+)
+SQLITE_IO_ERROR_MARKER = "disk i/o error"
+SQLiteStoreProbe = Literal["fatal", "healthy", "io", "unknown"]
+
+
+def _probe_sqlite_store(path: Path) -> SQLiteStoreProbe:
+    try:
+        with sqlite3.connect(path, timeout=0.1) as connection:
+            result = connection.execute("pragma quick_check").fetchone()
+    except sqlite3.DatabaseError as error:
+        message = str(error).lower()
+        if any(marker in message for marker in FATAL_SQLITE_ERROR_MARKERS):
+            return "fatal"
+        if SQLITE_IO_ERROR_MARKER in message:
+            return "io"
+        return "unknown"
+    return "healthy" if result == ("ok",) else "fatal"
+
+
+def _guard_home_accepts_sqlite_write(guard_home: Path) -> bool:
+    probe_path = guard_home / f"storage-probe-{uuid4().hex}.db"
+    try:
+        with sqlite3.connect(probe_path, timeout=0.1) as probe:
+            probe.execute("create table probe (value integer)")
+            probe.execute("insert into probe values (1)")
+        return probe_path.is_file()
+    except sqlite3.DatabaseError:
+        return False
+    finally:
+        with suppress(OSError):
+            probe_path.unlink()
+
+
+def sqlite_store_is_proven_unusable(
+    *,
+    path: Path,
+    guard_home: Path,
+    error: BaseException,
+    fatal_error: bool,
+) -> bool:
+    """Revalidate the current path before permitting destructive recovery."""
+
+    io_error = SQLITE_IO_ERROR_MARKER in str(error).lower()
+    if not fatal_error and not io_error:
+        return False
+    state = _probe_sqlite_store(path)
+    if state == "healthy":
+        return False
+    if state == "fatal":
+        return True
+    if state != "io" or not _guard_home_accepts_sqlite_write(guard_home):
+        return False
+    return _probe_sqlite_store(path) in {"fatal", "io"}