@mc-and-his-agents/loom-installer 0.1.23 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mc-and-his-agents/loom-installer",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Node installer for Loom plugin and single-skill installation surfaces.",
   "type": "module",
   "bin": {

package/payload/manifest.json

@@ -2,9 +2,9 @@
   "schema_version": "loom-installer-payload/v1",
   "loom_version": "0.4.0",
   "source_repository": "https://github.com/MC-and-his-Agents/Loom",
-  "source_commit": "9ba44dcc76daf7e100edafd5943b99c4a69ba710",
+  "source_commit": "9ade7b1664d19d46002d8122e8c3eabba7cf6bf4",
   "source_ref": "main",
-  "built_at": "2026-04-26T23:19:03+08:00",
+  "built_at": "2026-04-26T23:38:43+08:00",
   "runtime": {
     "python_minimum": "3.10",
     "python_recommended": "3.11+"
@@ -628,13 +628,13 @@
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_init.py",
@@ -1213,13 +1213,13 @@
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_init.py",
@@ -1828,13 +1828,13 @@
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_init.py",
@@ -2443,13 +2443,13 @@
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_init.py",
@@ -3063,13 +3063,13 @@
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_init.py",
@@ -3678,13 +3678,13 @@
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_init.py",
@@ -4293,13 +4293,13 @@
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_init.py",
@@ -4908,13 +4908,13 @@
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_init.py",
@@ -5523,13 +5523,13 @@
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_init.py",
@@ -6138,13 +6138,13 @@
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 278763,
-      "sha256": "3b2257fddc37fdb514953500a38e94ca241a5889a5c6343b975db5a1109bbff4"
+      "bytes": 285470,
+      "sha256": "e834612a8da8cd22cc13679b61529bc0074d0399004f4e4f45540d6b8f314c9a"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 290661,
-      "sha256": "18c5dc39a4cd2982a40c729807b12c2b15efd41a2962719b5491b06dad83c028"
+      "bytes": 296133,
+      "sha256": "e8bc02d131b1007889b7f9b394b5b2d605c8bf790ba1baccc37da1e6aecbf46c"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_init.py",

package/payload/plugin/loom/skills/shared/scripts/loom_check.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import re
+import hashlib
 import shutil
 import subprocess
 import sys
@@ -1071,6 +1072,14 @@ def require_shadow_parity_payload(
             locator = surface_payload.get("locator")
             if not isinstance(locator, str) or not locator:
                 failures.append(Failure(category, f"{context} reports[{index}] `{surface_key}.locator` must be non-empty"))
+            if surface_payload.get("status") == "readable":
+                source_files = surface_payload.get("source_files")
+                source_sha256 = surface_payload.get("source_sha256")
+                if not isinstance(source_files, list) or not source_files:
+                    failures.append(Failure(category, f"{context} reports[{index}] `{surface_key}.source_files` must be non-empty for readable evidence"))
+                    source_files = []
+                if not isinstance(source_sha256, dict) or set(source_sha256) != set(source_files):
+                    failures.append(Failure(category, f"{context} reports[{index}] `{surface_key}.source_sha256` must match source_files exactly"))
 
 
 def require_host_lifecycle_payload(
@@ -5472,6 +5481,29 @@ def check_repo_interop_contracts(root: Path) -> list[Failure]:
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
 
+    def sha256_file(path: Path) -> str:
+        digest = hashlib.sha256()
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                digest.update(chunk)
+        return digest.hexdigest()
+
+    def write_shadow_evidence(target: Path, evidence: str, value_key: str, value: str, source: str) -> None:
+        source_path = target / source
+        source_path.parent.mkdir(parents=True, exist_ok=True)
+        if not source_path.exists():
+            write_json(source_path, {"value": value})
+        write_json(
+            target / evidence,
+            {
+                value_key: value,
+                "source_files": [source],
+                "source_sha256": {
+                    source: sha256_file(source_path),
+                },
+            },
+        )
+
     def install_interop(
         target: Path,
         *,
@@ -5484,17 +5516,21 @@ def check_repo_interop_contracts(root: Path) -> list[Failure]:
         (target / ".loom" / "shadow").mkdir(parents=True, exist_ok=True)
         (target / "native" / "status").mkdir(parents=True, exist_ok=True)
         for relative, payload in {
-            ".loom/shadow/admission-loom.json": {"result": "pass"},
-            ".loom/shadow/admission-repo.json": {"result": "pass"},
-            ".loom/shadow/review-loom.json": {"decision": "allow"},
-            ".loom/shadow/review-repo.json": {"decision": "allow"},
-            ".loom/shadow/merge-ready-loom.json": {"status": "pass"},
-            ".loom/shadow/merge-ready-repo.json": {"status": "pass"},
-            ".loom/shadow/closeout-loom.json": {"status": "done"},
-            ".loom/shadow/closeout-repo.json": {"status": "done"},
             "host/guardian-review.json": {"verdict": "allow"},
+            "native/status/admission.json": {"result": "pass"},
+            "native/status/review.json": {"decision": "allow"},
+            "native/status/merge-ready.json": {"status": "pass"},
+            "native/status/closeout.json": {"status": "done"},
         }.items():
             write_json(target / relative, payload)
+        write_shadow_evidence(target, ".loom/shadow/admission-loom.json", "result", "pass", ".loom/status/current.md")
+        write_shadow_evidence(target, ".loom/shadow/admission-repo.json", "result", "pass", "native/status/admission.json")
+        write_shadow_evidence(target, ".loom/shadow/review-loom.json", "decision", "allow", "host/guardian-review.json")
+        write_shadow_evidence(target, ".loom/shadow/review-repo.json", "decision", "allow", "native/status/review.json")
+        write_shadow_evidence(target, ".loom/shadow/merge-ready-loom.json", "status", "pass", "host/guardian-review.json")
+        write_shadow_evidence(target, ".loom/shadow/merge-ready-repo.json", "status", "pass", "native/status/merge-ready.json")
+        write_shadow_evidence(target, ".loom/shadow/closeout-loom.json", "status", "done", ".loom/status/current.md")
+        write_shadow_evidence(target, ".loom/shadow/closeout-repo.json", "status", "done", "native/status/closeout.json")
         if interop is not None:
             write_json(companion_dir / "interop.json", interop)
 
@@ -5641,7 +5677,8 @@ def check_repo_interop_contracts(root: Path) -> list[Failure]:
 
         mismatch_target = base / "mismatch"
         shutil.copytree(present_target, mismatch_target)
-        write_json(mismatch_target / ".loom/shadow/review-repo.json", {"decision": "block"})
+        write_json(mismatch_target / "native/status/review.json", {"decision": "block"})
+        write_shadow_evidence(mismatch_target, ".loom/shadow/review-repo.json", "decision", "block", "native/status/review.json")
         mismatch_payload, error = load_command_json(
             root,
             ["python3", "tools/loom_flow.py", "shadow-parity", "--target", str(mismatch_target), "--surface", "review"],
@@ -5716,6 +5753,93 @@ def check_repo_interop_contracts(root: Path) -> list[Failure]:
             if blocking_unreadable_payload.get("result") != "block":
                 failures.append(Failure("repo-interop", "`shadow-parity --blocking` must block unreadable surfaces"))
 
+        missing_hash_target = base / "missing-hash"
+        shutil.copytree(present_target, missing_hash_target)
+        write_json(
+            missing_hash_target / ".loom/shadow/review-repo.json",
+            {
+                "decision": "allow",
+                "source_files": ["native/status/review.json"],
+            },
+        )
+        missing_hash_payload, error = load_command_json(
+            root,
+            ["python3", "tools/loom_flow.py", "shadow-parity", "--target", str(missing_hash_target), "--surface", "review"],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity` missing hash sample failed: {error}"))
+        else:
+            require_shadow_parity_payload(
+                failures,
+                category="repo-interop",
+                context="`shadow-parity` missing hash sample",
+                payload=missing_hash_payload,
+                expected_reports=1,
+            )
+            reports = missing_hash_payload.get("reports")
+            if not isinstance(reports, list) or not reports or reports[0].get("result") != "unreadable":
+                failures.append(Failure("repo-interop", "`shadow-parity` missing hash sample must report `unreadable`"))
+
+        partial_hash_target = base / "partial-hash"
+        shutil.copytree(present_target, partial_hash_target)
+        write_json(
+            partial_hash_target / ".loom/shadow/review-repo.json",
+            {
+                "decision": "allow",
+                "source_files": ["native/status/review.json", "host/guardian-review.json"],
+                "source_sha256": {
+                    "native/status/review.json": sha256_file(partial_hash_target / "native/status/review.json"),
+                },
+            },
+        )
+        partial_hash_payload, error = load_command_json(
+            root,
+            ["python3", "tools/loom_flow.py", "shadow-parity", "--target", str(partial_hash_target), "--surface", "review"],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity` partial hash sample failed: {error}"))
+        else:
+            reports = partial_hash_payload.get("reports")
+            if not isinstance(reports, list) or not reports or reports[0].get("result") != "unreadable":
+                failures.append(Failure("repo-interop", "`shadow-parity` partial hash sample must report `unreadable`"))
+
+        hash_drift_target = base / "hash-drift"
+        shutil.copytree(present_target, hash_drift_target)
+        write_json(hash_drift_target / "native/status/review.json", {"decision": "changed-after-evidence"})
+        hash_drift_payload, error = load_command_json(
+            root,
+            ["python3", "tools/loom_flow.py", "shadow-parity", "--target", str(hash_drift_target), "--surface", "review"],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity` hash drift sample failed: {error}"))
+        else:
+            reports = hash_drift_payload.get("reports")
+            if not isinstance(reports, list) or not reports or reports[0].get("result") != "unreadable":
+                failures.append(Failure("repo-interop", "`shadow-parity` hash drift sample must report `unreadable`"))
+
+        rogue_target = base / "rogue"
+        shutil.copytree(present_target, rogue_target)
+        write_json(
+            rogue_target / ".loom/shadow/rogue.json",
+            {
+                "result": "pass",
+                "source_files": ["native/status/review.json"],
+                "source_sha256": {
+                    "native/status/review.json": sha256_file(rogue_target / "native/status/review.json"),
+                },
+            },
+        )
+        rogue_payload, error = load_command_json(
+            root,
+            ["python3", "tools/loom_flow.py", "shadow-parity", "--target", str(rogue_target), "--surface", "review"],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity` rogue evidence sample failed: {error}"))
+        else:
+            reports = rogue_payload.get("reports")
+            if not isinstance(reports, list) or not reports or reports[0].get("result") != "unreadable":
+                failures.append(Failure("repo-interop", "`shadow-parity` rogue evidence sample must report `unreadable`"))
+
     return failures
 
 

package/payload/plugin/loom/skills/shared/scripts/loom_flow.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import os
 import re
@@ -531,15 +532,110 @@ def load_repo_interop_contract(repo_interop: object, *, target_root: Path) -> tu
     return payload, []
 
 
-def normalized_shadow_value(path: Path) -> tuple[str | None, str | None]:
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def repo_relative_path(target_root: Path, relative: str) -> Path | None:
+    candidate = (target_root / relative).resolve()
+    try:
+        candidate.relative_to(target_root.resolve())
+    except ValueError:
+        return None
+    return candidate
+
+
+def validate_shadow_sources(payload: dict[str, Any], *, path: Path, target_root: Path) -> tuple[dict[str, Any], list[str]]:
+    source_files = payload.get("source_files")
+    source_sha256 = payload.get("source_sha256")
+    errors: list[str] = []
+    if not isinstance(source_files, list) or not source_files:
+        errors.append(f"shadow evidence `{path}` must declare non-empty `source_files`")
+        source_files = []
+    if not isinstance(source_sha256, dict) or not source_sha256:
+        errors.append(f"shadow evidence `{path}` must declare non-empty `source_sha256`")
+        source_sha256 = {}
+
+    normalized_sources: list[str] = []
+    for index, source in enumerate(source_files, start=1):
+        if not isinstance(source, str) or not source.strip():
+            errors.append(f"shadow evidence `{path}` source_files[{index}] must be a non-empty relative path")
+            continue
+        source = source.strip()
+        if Path(source).is_absolute() or ".." in Path(source).parts:
+            errors.append(f"shadow evidence `{path}` source `{source}` must stay inside the repository")
+            continue
+        source_path = repo_relative_path(target_root, source)
+        if source_path is None:
+            errors.append(f"shadow evidence `{path}` source `{source}` must stay inside the repository")
+            continue
+        if not source_path.exists() or source_path.is_dir():
+            errors.append(f"shadow evidence `{path}` source `{source}` must be an existing file")
+            continue
+        normalized_sources.append(source)
+
+    source_keys = set(normalized_sources)
+    hash_keys = {key for key in source_sha256.keys() if isinstance(key, str)}
+    if source_keys != hash_keys:
+        errors.append(f"shadow evidence `{path}` source_files and source_sha256 keys must match exactly")
+    for source in sorted(source_keys & hash_keys):
+        expected = source_sha256.get(source)
+        if not isinstance(expected, str) or not re.fullmatch(r"[0-9a-fA-F]{64}", expected):
+            errors.append(f"shadow evidence `{path}` source `{source}` must declare a 64-character sha256")
+            continue
+        actual = sha256_file(target_root / source)
+        if actual.lower() != expected.lower():
+            errors.append(f"shadow evidence `{path}` source `{source}` sha256 drifted")
+
+    return {
+        "source_files": normalized_sources,
+        "source_sha256": {source: source_sha256.get(source) for source in normalized_sources if isinstance(source_sha256.get(source), str)},
+    }, errors
+
+
+def declared_shadow_locators(interop_payload: dict[str, Any]) -> set[str]:
+    shadow_surfaces = interop_payload.get("shadow_surfaces")
+    declared: set[str] = set()
+    if not isinstance(shadow_surfaces, dict):
+        return declared
+    for entry in shadow_surfaces.values():
+        if not isinstance(entry, dict):
+            continue
+        for key in ("loom_locator", "repo_locator"):
+            value = entry.get(key)
+            if isinstance(value, str) and value.strip():
+                declared.add(value.strip())
+    return declared
+
+
+def undeclared_shadow_evidence_errors(target_root: Path, interop_payload: dict[str, Any]) -> list[str]:
+    shadow_root = target_root / ".loom/shadow"
+    if not shadow_root.exists():
+        return []
+    declared = declared_shadow_locators(interop_payload)
+    errors: list[str] = []
+    for path in sorted(shadow_root.glob("*.json")):
+        relative = path.relative_to(target_root).as_posix()
+        if relative == ".loom/shadow/shadow-parity.json":
+            continue
+        if relative not in declared:
+            errors.append(f"shadow evidence `{relative}` is not declared in repo interop shadow_surfaces")
+    return errors
+
+
+def normalized_shadow_value(path: Path, *, target_root: Path) -> tuple[dict[str, Any], str | None]:
     try:
         if path.is_dir():
-            return None, f"shadow parity locator points to a directory: {path}"
+            return {"normalized_value": None}, f"shadow parity locator points to a directory: {path}"
         raw_text = path.read_text(encoding="utf-8")
     except OSError as exc:
-        return None, f"cannot read shadow parity locator `{path}`: {exc.strerror or exc}"
+        return {"normalized_value": None}, f"cannot read shadow parity locator `{path}`: {exc.strerror or exc}"
     if not raw_text.strip():
-        return None, f"shadow parity locator is empty: {path}"
+        return {"normalized_value": None}, f"shadow parity locator is empty: {path}"
 
     try:
         payload = json.loads(raw_text)
@@ -547,21 +643,22 @@ def normalized_shadow_value(path: Path) -> tuple[str | None, str | None]:
         payload = None
 
     if isinstance(payload, dict):
+        source_evidence, source_errors = validate_shadow_sources(payload, path=path, target_root=target_root)
         for key in ("parity_value", "result", "decision", "status", "verdict", "value"):
             value = payload.get(key)
             if isinstance(value, (str, int, float, bool)) and str(value).strip():
-                return str(value).strip().lower(), None
-        return json.dumps(payload, ensure_ascii=False, sort_keys=True), None
+                return {**source_evidence, "normalized_value": str(value).strip().lower()}, "; ".join(source_errors) if source_errors else None
+        return {**source_evidence, "normalized_value": json.dumps(payload, ensure_ascii=False, sort_keys=True)}, "; ".join(source_errors) if source_errors else None
     if isinstance(payload, list):
-        return json.dumps(payload, ensure_ascii=False, sort_keys=True), None
+        return {"normalized_value": json.dumps(payload, ensure_ascii=False, sort_keys=True)}, f"shadow evidence `{path}` must be a JSON object with source_files/source_sha256"
     if isinstance(payload, (str, int, float, bool)) and str(payload).strip():
-        return str(payload).strip().lower(), None
+        return {"normalized_value": str(payload).strip().lower()}, f"shadow evidence `{path}` must be a JSON object with source_files/source_sha256"
 
     for line in raw_text.splitlines():
         stripped = line.strip()
         if stripped and not stripped.startswith("#"):
-            return stripped.lower(), None
-    return None, f"shadow parity locator does not expose a comparable value: {path}"
+            return {"normalized_value": stripped.lower()}, f"shadow evidence `{path}` must be a JSON object with source_files/source_sha256"
+    return {"normalized_value": None}, f"shadow parity locator does not expose a comparable value: {path}"
 
 
 def shadow_parity_report(
@@ -632,27 +729,42 @@ def shadow_parity_report(
     loom_path = target_root / str(loom_locator)
     repo_path = target_root / str(repo_locator)
 
-    loom_value, loom_error = normalized_shadow_value(loom_path)
-    repo_value, repo_error = normalized_shadow_value(repo_path)
+    loom_surface = {
+        "status": "missing",
+        "locator": str(loom_locator),
+        "normalized_value": None,
+    }
+    repo_surface = {
+        "status": "missing",
+        "locator": str(repo_locator),
+        "normalized_value": None,
+    }
+
+    global_errors = undeclared_shadow_evidence_errors(target_root, interop_payload)
+    loom_evidence, loom_error = normalized_shadow_value(loom_path, target_root=target_root)
+    repo_evidence, repo_error = normalized_shadow_value(repo_path, target_root=target_root)
+    loom_value = loom_evidence.get("normalized_value")
+    repo_value = repo_evidence.get("normalized_value")
 
     missing_inputs: list[str] = []
+    missing_inputs.extend(global_errors)
     if loom_error:
         missing_inputs.append(loom_error)
     if repo_error:
         missing_inputs.append(repo_error)
 
     loom_surface = {
+        **loom_evidence,
         "status": "readable" if loom_error is None else "missing",
         "locator": str(loom_locator),
-        "normalized_value": loom_value,
     }
     repo_surface = {
+        **repo_evidence,
         "status": "readable" if repo_error is None else "missing",
         "locator": str(repo_locator),
-        "normalized_value": repo_value,
     }
 
-    if loom_error or repo_error or loom_value is None or repo_value is None:
+    if global_errors or loom_error or repo_error or loom_value is None or repo_value is None:
         return {
             **empty_report,
             "summary": "shadow parity is unreadable because one or both declared surfaces cannot be normalized.",