Spec drift detection @0041177

tools/hf_space/runner.py

@@ -1056,6 +1056,71 @@ def _foundation_sha() -> str:
     return os.environ.get("SIMREADY_FOUNDATIONS_COMMIT", "unpinned")
 
 
+# Path to the spec-sync state file. The state file declares which
+# foundation commit our hardcoded validator rules were last aligned
+# against. The Space's checkout includes the file at this relative
+# path (tools/spec_sync/state.json in the repo).
+_SPEC_SYNC_STATE_FILE = Path(__file__).resolve().parents[2] / "tools" / "spec_sync" / "state.json"
+
+
+def _check_foundation_spec_drift() -> dict:
+    """Check whether NVIDIA/simready-foundation has new commits to its
+    spec dir since we last synced our hardcoded rules.
+
+    Cheap event-driven drift detection (one GitHub API call per run,
+    soft-fails on errors). The validator surfaces drift in results.json
+    so the dashboard can warn operators that hardcoded rules may be
+    stale relative to the source of truth. Auto-update is the
+    follow-up step (spec-sync workflow opens a PR to refresh rules).
+
+    Returns a dict the dashboard renders; never raises.
+    """
+    out: dict = {"checked": False}
+    try:
+        if not _SPEC_SYNC_STATE_FILE.is_file():
+            out["reason"] = "state file missing"
+            return out
+        state = json.loads(_SPEC_SYNC_STATE_FILE.read_text(encoding="utf-8"))
+        last_sync_sha = state.get("foundation_commit_sha") or ""
+        last_sync_at = state.get("synced_at") or ""
+        watched_path = state.get("watched_path") or "nv_core/sr_specs/docs"
+        repo = state.get("foundation_repo") or "NVIDIA/simready-foundation"
+    except Exception as e:
+        out["reason"] = f"could not read state: {type(e).__name__}: {e}"
+        return out
+    try:
+        import urllib.request
+        url = (f"https://api.github.com/repos/{repo}/commits"
+               f"?path={watched_path}&per_page=1")
+        req = urllib.request.Request(url)
+        req.add_header("Accept", "application/vnd.github.v3+json")
+        token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_VALIDATOR_TOKEN")
+        if token:
+            req.add_header("Authorization", f"Bearer {token}")
+        with urllib.request.urlopen(req, timeout=8) as resp:
+            data = json.loads(resp.read())
+    except Exception as e:
+        out["reason"] = f"github api: {type(e).__name__}: {e}"
+        return out
+    if not isinstance(data, list) or not data:
+        out["reason"] = "no commit data"
+        return out
+    current = data[0] or {}
+    current_sha = current.get("sha") or ""
+    current_at = (current.get("commit") or {}).get("committer", {}).get("date") or ""
+    drifted = bool(current_sha) and current_sha != last_sync_sha
+    return {
+        "checked": True,
+        "drifted": drifted,
+        "current_sha": current_sha,
+        "current_at": current_at,
+        "last_sync_sha": last_sync_sha,
+        "last_sync_at": last_sync_at,
+        "repo": repo,
+        "watched_path": watched_path,
+    }
+
+
 def _validator_version() -> str:
     """Version of the simready-validate package that ships in this Space."""
     try:
@@ -1316,6 +1381,23 @@ def run(
                 summary="validator produced no result (unified streaming path returned None)",
                 results_json={}, report_path=out_dir, pr_url=None,
             )
+        # Event-driven foundation spec drift check. One GitHub API
+        # call per run; soft-fails so network hiccups don't block
+        # validation. The dashboard renders a notice if drifted=true.
+        drift = _check_foundation_spec_drift()
+        if drift.get("checked"):
+            if drift.get("drifted"):
+                out(f"  ⚠ spec drift: foundation HEAD={drift.get('current_sha', '')[:8]} "
+                    f"@ {drift.get('current_at', '')}, last synced "
+                    f"{drift.get('last_sync_sha', '')[:8]} @ {drift.get('last_sync_at', '')} "
+                    f"— hardcoded rules may be stale; run spec-sync to refresh")
+            else:
+                out(f"  spec sync: in sync with foundation HEAD "
+                    f"{drift.get('current_sha', '')[:8]}")
+        else:
+            out(f"  spec sync: skipped ({drift.get('reason', 'unknown')})")
+        streamed["spec_drift"] = drift
+
         results_path.write_text(json.dumps(streamed), encoding="utf-8")
         results_json = streamed
         status, summary = _summarize(results_json)

tools/spec_sync/state.json

@@ -0,0 +1,11 @@
+{
+  "_doc": "Drift state for NVIDIA/simready-foundation specs. The validator hits the GitHub API on every run; if the latest commit touching nv_core/sr_specs/docs differs from foundation_commit_sha below, the validator surfaces a 'spec drift' warning and (future) triggers the spec-sync workflow to auto-update hardcoded rules.",
+  "foundation_repo": "NVIDIA/simready-foundation",
+  "watched_path": "nv_core/sr_specs/docs",
+  "foundation_commit_sha": "805d2c50179a9878c89b0f41baaa0ecafe47c3d7",
+  "synced_at": "2026-06-02T00:00:00Z",
+  "synced_by": "initial-setup",
+  "rules_pinned_against": [
+    "AA.002 supported-file-types (validate.py:_AA_002_ALLOWED)"
+  ]
+}