build(vendor): pin hellgraph + sovereign-vendor contract (campaign gap #7)

flake.nix

@@ -298,6 +298,8 @@
           mesh-runtime-contract = import ./tests/mesh-runtime-contract.nix { inherit pkgs; };
           mesh-package-contract = import ./tests/mesh-package-contract.nix { inherit pkgs; };
           mesh-host-runtime-contract = import ./tests/mesh-host-runtime-contract.nix { inherit pkgs; };
+
+          sovereign-vendor-contract = import ./tests/sovereign-vendor-contract.nix { inherit pkgs; };
           sourceos-shell-module-contract = import ./tests/sourceos-shell-module-contract.nix { inherit pkgs; };
           sourceos-shell-service-graph-contract = import ./tests/sourceos-shell-service-graph-contract.nix { inherit pkgs; };
           sourceos-shell-keyboard-equivalence-contract = import ./tests/sourceos-shell-keyboard-equivalence-contract.nix { inherit pkgs; };

tests/sovereign-vendor-contract.nix

@@ -0,0 +1,18 @@
+# Asserts the OS build pins its consumed (vendored) dependencies with integrity,
+# and that the verifier accepts the lock shape. hellgraph is consumed vendored,
+# never forked — this check fails the build if the pin is missing or malformed.
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.runCommand "sovereign-vendor-contract" {
+  nativeBuildInputs = [ pkgs.python3 pkgs.gnugrep ];
+} ''
+  lock=${../vendor/hellgraph.lock.json}
+  grep -q '"name": "hellgraph"' $lock
+  grep -q '"tag": "v0.4.45"' $lock
+  grep -q '"git_archive_tar"' $lock
+  grep -q '"reason"' $lock
+  grep -q '"license": "MIT"' $lock
+  # the verifier validates the lock shape (no checkout in the sandbox → shape-only)
+  python3 ${../tools/verify_vendor.py} --vendor-dir ${../vendor}
+  mkdir -p $out
+  echo validated > $out/result.txt
+''

tools/verify_vendor.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Verify vendored dependency pins for the OS build.
+
+Validates every vendor/*.lock.json has the required shape, and — when a local
+checkout is available (--checkout <path>) — recomputes the deterministic
+`git archive --format=tar <commit>` sha512 and asserts it matches the pinned hash.
+A pin that can't be verified is a build failure, not a warning.
+"""
+from __future__ import annotations
+import argparse, hashlib, json, subprocess, sys
+from pathlib import Path
+
+REQUIRED = ["name", "repo", "reason", "pin", "integrity"]
+
+
+def _archive_sha512(checkout: Path, commit: str) -> str:
+    tar = subprocess.run(["git", "-C", str(checkout), "archive", "--format=tar", commit],
+                         check=True, stdout=subprocess.PIPE).stdout
+    return hashlib.sha512(tar).hexdigest()
+
+
+def verify(lock, checkout):
+    errs = [f"missing key {k!r}" for k in REQUIRED if k not in lock]
+    if errs:
+        return errs
+    if "git_archive_tar" not in lock["integrity"]:
+        errs.append("integrity.git_archive_tar missing")
+    if checkout and checkout.exists() and not errs:
+        got = _archive_sha512(checkout, lock["pin"]["commit"])
+        want = lock["integrity"]["git_archive_tar"]
+        if got != want:
+            errs.append(f"integrity mismatch: got {got[:16]}... want {want[:16]}...")
+    return errs
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--vendor-dir", type=Path, default=Path(__file__).resolve().parents[1] / "vendor")
+    ap.add_argument("--checkout", type=Path)
+    a = ap.parse_args(argv)
+    locks = sorted(a.vendor_dir.glob("*.lock.json"))
+    if not locks:
+        print("no vendor locks found", file=sys.stderr)
+        return 1
+    bad = 0
+    for lp in locks:
+        lock = json.loads(lp.read_text())
+        errs = verify(lock, a.checkout)
+        if errs:
+            bad += 1
+            print(f"FAIL {lp.name}: {'; '.join(errs)}")
+        else:
+            hv = " (hash verified)" if a.checkout and a.checkout.exists() else " (shape ok)"
+            print(f"OK   {lp.name} -> {lock['name']} @ {lock['pin'].get('tag', lock['pin']['commit'][:12])}{hv}")
+    return 1 if bad else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vendor/hellgraph.lock.json

@@ -0,0 +1,19 @@
+{
+  "name": "hellgraph",
+  "repo": "https://github.com/SocioProphet/hellgraph",
+  "reason": "Consumed vendored, not forked: hellgraph is the System Graph substrate netwatch ingests into and the B11/E11 surface feeds read. Not our lane to modify — pin a release and verify integrity.",
+  "pin": {
+    "tag": "v0.4.45",
+    "commit": "dbe854faf5b8f53a484fd164ba6f84328b5dd24b",
+    "tree": "4161b5f614691e1248a303137ea833a4f9bf97df",
+    "released_on_main": true
+  },
+  "integrity": {
+    "algo": "sha512",
+    "git_archive_tar": "5f892c91e892206fd9b266202c3a4960528211fd593c79e64ea7ffaf8cc9ab5f29ec73bb5c06c09fc26acc866f13bf3ac12375ac8ac7d76f64e6e5d406ff7421",
+    "note": "sha512 of `git archive --format=tar <commit>`; recompute with tools/verify_vendor.py --checkout"
+  },
+  "license": "MIT",
+  "consumers": ["turtle-netwatch System Graph ingest", "surface feeds", "sourceos-shell"],
+  "vendored_at": "2026-08-03"
+}