Structural PKG.* checks @919af26

tools/spec_sync/state.json

@@ -6,6 +6,10 @@
   "synced_at": "2026-06-02T00:00:00Z",
   "synced_by": "initial-setup",
   "rules_pinned_against": [
-    "AA.002 supported-file-types (validate.py:_AA_002_ALLOWED)"
+    "AA.002 supported-file-types (validate.py:_AA_002_ALLOWED) — foundation",
+    "PKG.1 interface file (validate.py:_check_pkg_layout) — local SDK packaging spec",
+    "PKG.6 package manifest (validate.py:_check_pkg_layout) — local SDK packaging spec",
+    "PKG.NO-ROOT-USD no root USDs (validate.py:_check_pkg_layout) — local SDK packaging spec",
+    "PKG.NO-ARCHIVES no zip files (validate.py:_check_pkg_layout) — local SDK packaging spec"
   ]
 }

tools/validation/plugins/simready-report/skills/simready-report/validate.py

@@ -692,21 +692,33 @@ _ATOMIC_ASSET_PATHS = (f"{_FOUNDATION_SPECS_BASE}/core/atomic_asset/"
 
 
 def run_preliminary_checks(root: Path) -> list[dict]:
-    """Preliminary check phase: filesystem-only foundation requirements,
-    evaluated before USD traversal.
-
-    These checks are intentionally cheap and deterministic — no LLM
-    calls in the validation hot path. Each rule is a small function
-    with a strong link to its foundation spec section. Drift detection
-    (does our hardcoded list still match the spec?) runs OUT of band
-    via tools/spec_sync/ (a weekly job that uses the agent to compare
-    the foundation spec text to these hardcoded rules and opens a PR
-    on drift).
-
-    Currently implemented:
-      - AA.002 supported-file-types
+    """Preliminary check phase: filesystem-only checks, evaluated
+    before USD traversal.
+
+    Cheap, deterministic, runs every validation. The point is to
+    surface ALL filesystem-visible spec violations in a single
+    roundtrip — partners fix everything at once instead of getting
+    piece-meal feedback over multiple iterations.
+
+    Each check has a strong link to its source-of-truth spec section.
+    Two sources are in play:
+      - Foundation specs (NVIDIA/simready-foundation): AA.002.
+        Drift-watched via tools/spec_sync/.
+      - SDK packaging spec (docs/sdk/packaging-spec.md): PKG.*.
+        Lives in this repo, no drift watch needed.
+
+    Implemented:
+      - AA.002  supported-file-types (foundation)
+      - PKG.1   interface file convention (SDK §"Discovery Rules" #1+#4)
+      - PKG.6   package manifest required (SDK §"Discovery Rules" #6)
+      - PKG.NO-ROOT-USD   no USDs at dataset root (SDK §"Folder Structure")
+      - PKG.NO-ARCHIVES   no zip files (SDK §"Folder Structure" — packages
+                                        ship unpacked)
     """
-    return _check_aa_002_supported_file_types(root)
+    issues: list[dict] = []
+    issues.extend(_check_aa_002_supported_file_types(root))
+    issues.extend(_check_pkg_layout(root))
+    return issues
 
 
 # AA.002 supported-file-types — hardcoded from the foundation spec at
@@ -777,6 +789,128 @@ def _check_aa_002_supported_file_types(root: Path) -> list[dict]:
     return issues
 
 
+# SDK packaging spec — the SimReady asset packaging convention this
+# repo's docs/sdk/packaging-spec.md mandates. Independent from the
+# foundation specs (which cover USD-content, not packaging structure).
+_SDK_PACKAGING_SPEC_URL = ("https://github.com/NVIDIA-dev/simready-oem-library-pm/"
+                          "blob/main/docs/sdk/packaging-spec.md")
+_SDK_PACKAGING_SPEC_FOLDER = f"{_SDK_PACKAGING_SPEC_URL}#folder-structure"
+_SDK_PACKAGING_SPEC_DISCOVERY = f"{_SDK_PACKAGING_SPEC_URL}#discovery-rules"
+_SDK_PACKAGING_SPEC_MANIFEST = f"{_SDK_PACKAGING_SPEC_URL}#package-manifest-wrapp"
+
+
+def _check_pkg_layout(root: Path) -> list[dict]:
+    """Checks against the SDK packaging spec's structural requirements.
+
+    Spec: docs/sdk/packaging-spec.md (in this repo). Codes follow the
+    spec's own numbered Discovery Rules where applicable.
+
+    Rules enforced:
+      PKG.1            Each top-level dir must contain
+                       <dirname>/<dirname>.usd (Discovery Rules #1+#4).
+      PKG.6            Each top-level dir must contain .<dirname>.wrapp
+                       (Discovery Rules #6 — "required, flag as error").
+      PKG.NO-ROOT-USD  No USD files at the dataset root — each asset
+                       must live in its own directory per Folder
+                       Structure.
+      PKG.NO-ARCHIVES  No .zip files anywhere — SimReady packages ship
+                       unpacked per Folder Structure.
+    """
+    issues: list[dict] = []
+    try:
+        entries = sorted(root.iterdir())
+    except OSError as e:
+        return [{
+            "code": "PKG.READ-FAILED",
+            "severity": "failure",
+            "path": str(root),
+            "spec_url": _SDK_PACKAGING_SPEC_URL,
+            "msg": f"Could not read dataset root: {e}",
+        }]
+
+    has_any_bundle_dir = False
+    for entry in entries:
+        rel = entry.name
+        if entry.is_file():
+            suffix = entry.suffix.lower()
+            if suffix == ".zip":
+                issues.append({
+                    "code": "PKG.NO-ARCHIVES",
+                    "severity": "failure",
+                    "path": rel,
+                    "spec_url": _SDK_PACKAGING_SPEC_FOLDER,
+                    "msg": (f"'{rel}' is a zip archive. SimReady packages "
+                            f"must be delivered as unpacked directories — "
+                            f"extract all archives and re-publish."),
+                })
+            elif suffix in {".usd", ".usda", ".usdc", ".usdz"}:
+                issues.append({
+                    "code": "PKG.NO-ROOT-USD",
+                    "severity": "failure",
+                    "path": rel,
+                    "spec_url": _SDK_PACKAGING_SPEC_FOLDER,
+                    "msg": (f"'{rel}' is a USD file at the dataset root. "
+                            f"Each asset must live in its own directory: "
+                            f"<asset_name>/<asset_name>.usd."),
+                })
+            continue
+        if not entry.is_dir():
+            continue
+        if entry.name.startswith(".") or entry.name in _SKIP_DIR_NAMES:
+            continue
+        has_any_bundle_dir = True
+
+        # PKG.1 — interface file convention
+        interface_candidates = [
+            entry / f"{entry.name}.usd",
+            entry / f"{entry.name}.usda",
+            entry / f"{entry.name}.usdc",
+        ]
+        if not any(p.is_file() for p in interface_candidates):
+            try:
+                found = [str(p.relative_to(entry))
+                         for p in sorted(entry.rglob("*"))
+                         if p.is_file() and p.suffix.lower() in USD_EXTS][:5]
+            except OSError:
+                found = []
+            hint = (f" Found USDs here: {', '.join(found)}"
+                    if found else " No USD files found in this directory.")
+            issues.append({
+                "code": "PKG.1",
+                "severity": "failure",
+                "path": rel + "/",
+                "spec_url": _SDK_PACKAGING_SPEC_DISCOVERY,
+                "msg": (f"Directory '{rel}/' must contain an interface "
+                        f"file named '{rel}.usd' (or .usda/.usdc) per "
+                        f"the SimReady packaging spec.{hint}"),
+            })
+
+        # PKG.6 — package manifest
+        manifest = entry / f".{entry.name}.wrapp"
+        if not manifest.is_file():
+            issues.append({
+                "code": "PKG.6",
+                "severity": "failure",
+                "path": rel + "/",
+                "spec_url": _SDK_PACKAGING_SPEC_MANIFEST,
+                "msg": (f"Directory '{rel}/' is missing the required "
+                        f"package manifest '.{rel}.wrapp'."),
+            })
+
+    if not has_any_bundle_dir and not issues:
+        issues.append({
+            "code": "PKG.EMPTY",
+            "severity": "failure",
+            "path": ".",
+            "spec_url": _SDK_PACKAGING_SPEC_FOLDER,
+            "msg": (f"Dataset root contains no asset directories. Per "
+                    f"the SimReady packaging spec, each asset lives in "
+                    f"its own top-level directory."),
+        })
+
+    return issues
+
+
 def discover_assets(
     root: Path, exclude: Path | None = None,
 ) -> tuple[list[Path], list[dict]]: