solvecraft/assets/render/selene/tools/validate_prepared.py

#!/usr/bin/env python3
"""Read-only checks for prepared SELENE resources; no runtime readiness claim.

Usage: python3 assets/render/selene/tools/validate_prepared.py [--json]
Python 3.11 standard-library development tooling, not an application dependency.
"""

from __future__ import annotations

import argparse
import hashlib
import json
import math
import re
import sys
from pathlib import Path

from prepare import PACKAGE, number, read_json


CATALOG = PACKAGE.parents[2] / "docs/render-materials"
COLLECTIONS = {
    "materials/appearance-pack.json": (48, "SELENE-AP-"),
    "scenes/roles.json": (33, None),
    "scenes/stages.json": (10, "SELENE-STAGE-"),
    "scenes/shots.json": (12, "SELENE-SHOT-"),
    "motion/mechanism-acceptance.json": (12, "MCA-"),
}


class Validation:
    def __init__(self, directory: Path, catalog: Path):
        self.directory, self.catalog = directory, catalog
        self.errors: list[str] = []
        self.counts: dict[str, int] = {}
        self.documents: dict[str, dict] = {}
        self.indices: dict[str, dict] = {}

    def check(self, condition: bool, message: str) -> None:
        if not condition:
            self.errors.append(message)

    def pbr(self, params: dict, label: str) -> None:
        self.check(set(params) == {"appearance", "color", "opacity", "pbr"}, label + ": unexpected appearance parameters")
        self.check(isinstance(params.get("appearance"), str) and bool(params["appearance"].strip())
                   and len(params["appearance"].encode("utf-8")) <= 128, label + ": invalid label")
        color = params.get("color")
        self.check(isinstance(color, str) and re.fullmatch(r"#[0-9a-fA-F]{6}", color) is not None, label + ": expected sRGB8 hex color")
        self.check(number(params.get("opacity")) and params["opacity"] == 1, label + ": PBR must be numerically opaque")
        pbr = params.get("pbr", {})
        self.check(isinstance(pbr, dict) and set(pbr) == {"metallic", "roughness", "dielectric_ior"}, label + ": wrong PBR fields")
        for field, lower, upper in (("metallic", 0, 1), ("roughness", .045, 1), ("dielectric_ior", 1, 3)):
            value = pbr.get(field)
            self.check(number(value) and lower <= value <= upper, label + ": invalid " + field)

    def ui_checks(self, catalog: dict) -> None:
        flow = self.documents["ui/demo-flow.json"]
        ui_path = self.directory / "ui"
        contract_path = (ui_path / flow["metadata"]["integration_contract"]).resolve()
        self.check(contract_path == (self.catalog / "ui-integration.json").resolve(), "UI flow must reference the shared integration contract")
        contract = read_json(self.catalog / "ui-integration.json")
        self.check(flow["metadata"]["status"] == "specified_unbound" and contract["metadata"]["runtime_ready"] is False,
                   "UI specification cannot imply implemented runtime behavior")
        controls = flow["controls"]
        self.check(flow["defaults"]["default_view"] == controls["disclosure"]["default"] == contract["disclosure"]["default"] == "Quick",
                   "UI disclosure defaults disagree")
        self.check(controls["disclosure"]["global_mode_switch"] is False and controls["disclosure"]["extra_ribbon_tabs"] is False,
                   "Disclosure must not create global modes or ribbon tabs")
        self.check(controls["maximum_primary_adjustments"] == contract["disclosure"]["quick_adjustment_budget"] == 6,
                   "Primary adjustment budgets disagree")
        for context, values in controls["quick_by_context"].items():
            self.check(isinstance(values, list) and 0 < len(values) <= 6 and len(set(values)) == len(values),
                       "Invalid primary control list for " + context)
        self.check(controls["quick"] == controls["quick_by_context"]["lunar_scene"], "Default lunar controls disagree")
        self.check(flow["library"]["local_categories"] == contract["library"]["category_labels"], "UI library categories disagree")
        quality = flow["quality_selection"]
        self.check((ui_path / quality["source"]).resolve() == (self.catalog / "quality-presets.json").resolve(),
                   "UI quality picker must reference the shared quality catalog")
        profiles = quality["profiles"]
        self.check(len(profiles) == len(catalog["quality-presets.json"])
                   and {p["quality_preset_id"] for p in profiles} == set(catalog["quality-presets.json"]), "UI quality profile inventory disagrees")
        for profile in profiles:
            source = catalog["quality-presets.json"].get(profile["quality_preset_id"], {})
            self.check(profile["name"] == source.get("name") and profile["status"] == source.get("status") == "specified_unbound",
                       "UI quality labels or availability disagree with the source catalog")
        shots = self.indices["scenes/shots.json"]
        recommendations = quality["recommendations"]
        self.counts["ui/demo-flow.json shot quality recommendations"] = len(recommendations)
        self.check(len(recommendations) == len(shots) and {r["shot_id"] for r in recommendations} == set(shots),
                   "Every prepared shot needs one quality recommendation group")
        for item in recommendations:
            ids = item["quality_preset_ids"]
            self.check(len(ids) == 3 and len(set(ids)) == 3 and set(ids) <= set(catalog["quality-presets.json"]),
                       item["shot_id"] + ": recommend three known quality profiles")
            self.check(item["default_quality_preset_id"] in ids
                       and item["default_quality_preset_id"] == shots.get(item["shot_id"], {}).get("quality_preset_id"),
                       item["shot_id"] + ": UI default must preserve the prepared shot quality")
        registered = {r["id"] for r in contract["command_reuse"]}
        self.check({r["command"] for r in flow["command_bindings"]["registered_authorities"]} <= registered,
                   "UI flow invents an existing command authority")
        proposals = {r["candidate_id"] for r in contract["proposed_commands"]}
        self.check(all(r["registered"] is False and r["command"] in proposals for r in flow["command_bindings"]["future_proposals"]),
                   "UI future proposals disagree with the shared contract")
        swatches = flow["swatch_opening"]
        self.check((ui_path / swatches["script"]).resolve() == (self.directory / "materials/appearance-swatches.json").resolve()
                   and swatches["script_first_command"] == "file.new" and swatches["preserve_existing_documents"] is True
                   and swatches["runtime_executed"] is False and swatches["visual_reviewed"] is False,
                   "Swatch opening must preserve document isolation and actual evidence status")
        self.check(all(s["runtime_ui_available"] is False and s["render_available_after_preflight"] is False
                       for s in flow["availability_states"]), "Illustrative UI states cannot claim current runtime enablement")

    def run(self) -> dict:
        catalog_ids = set()
        catalog = {}
        for filename in ("materials.json", "capabilities.json", "environment-presets.json", "studio-presets.json",
                         "quality-presets.json", "scene-presets.json", "lunar-physics-fixtures.json"):
            document = read_json(self.catalog / filename)
            catalog[filename] = {item["id"]: item for item in document["items"]}
            catalog_ids.update(catalog[filename])
        for path in sorted(self.directory.rglob("*.json")):
            relative = path.relative_to(self.directory).as_posix()
            if relative == "motion/interference-pairs.json":
                # This native-validation input is an explicit array, unlike catalog documents.
                with path.open("rb") as stream:
                    data = stream.read(65537)
                if len(data) > 65536:
                    raise ValueError(relative + ": selection exceeds 64 KiB")
                pairs = json.loads(data)
                valid = (isinstance(pairs, list) and 0 < len(pairs) <= 20
                         and all(isinstance(pair, list) and len(pair) == 2
                                 and all(isinstance(name, str) and 0 < len(name) <= 256 for name in pair)
                                 and pair[0] != pair[1] for pair in pairs))
                self.check(valid, relative + ": expected 1–20 pairs of distinct exact body names")
                if valid:
                    self.counts[relative + " pairs"] = len(pairs)
                    self.check(len({tuple(sorted(pair)) for pair in pairs}) == len(pairs),
                               relative + ": duplicate pair")
                continue
            document = read_json(path)
            self.documents[relative] = document
            if "metadata" in document:
                self.check(document["metadata"].get("language") == "en", relative + ": metadata must declare English")
            pending = [document]
            while pending:
                node = pending.pop()
                if isinstance(node, dict):
                    pending.extend(node.values())
                elif isinstance(node, list):
                    pending.extend(node)
                elif isinstance(node, str) and re.fullmatch(r"(?:MAT|CAP|Q|STU|ENVSET|SCENE|PHY)-\d{3}", node):
                    self.check(node in catalog_ids, relative + ": unknown catalog reference " + node)
        for filename, (count, prefix) in COLLECTIONS.items():
            items = self.documents[filename]["items"]
            identities = [item["id"] for item in items]
            self.counts[filename] = len(items)
            self.check(len(items) == count and len(set(identities)) == count, filename + ": wrong count or duplicate IDs")
            if prefix:
                self.check(identities == [f"{prefix}{i:03}" for i in range(1, count + 1)], filename + ": unexpected ID series")
            self.indices[filename] = {item["id"]: item for item in items}
        lock = self.documents["source-lock.json"]
        source = lock["active_source"]
        self.check(source["variant"] == "SELENE-showcase", "Active source must select the improved showcase")
        self.check(source["status"] in {"awaiting_native_source", "pinned_native"}, "Unknown source-admission status")
        if source["status"] == "awaiting_native_source":
            self.check(all(source.get(key) is None for key in ("repository", "commit", "path", "download_url", "sha256", "size_bytes", "format")),
                       "Unavailable native source cannot have invented identity fields")
            self.check(lock["admission_review"]["variant_identity_confirmed"] is False
                       and lock["admission_review"]["license_and_attribution_reviewed"] is False, "Unavailable native source cannot be approved")
        self.check(source["units"] == "mm" and source["up_axis"] == "+Z", "Source units must remain mm and Z-up")
        self.check(all(old["status"] == "historical_reference_only" and old["eligible_as_active_source"] is False
                       and old["sha256"] != source["sha256"] for old in lock["legacy_sources"]), "Legacy source must be excluded")
        for scene in catalog["scene-presets.json"].values():
            if scene["name"].startswith("SELENE "):
                subject = scene["subject_binding"]
                self.check(subject["manifest"] == "../../assets/render/selene/source-lock.json"
                           and subject.get("required_source_status") == "pinned_native", scene["id"] + ": stale SELENE source binding")
        recipes = self.indices["materials/appearance-pack.json"]
        for identity, item in recipes.items():
            self.pbr(item["baseline_projection"]["runtime_parameters"], identity)
            self.check(item["component_binding"] == "unbound", identity + ": recipes must not invent native targets")
            self.check(item["advanced_target"]["status"] == "authored_specification_not_runtime_bound", identity + ": advanced target availability mismatch")
        swatches = self.documents["materials/appearance-swatches.json"]["commands"]
        self.counts["materials/appearance-swatches.json commands"] = len(swatches)
        self.check(len(swatches) == 99 and swatches[0]["command"] == "file.new", "Swatches need a new design and 99 expected commands")
        bodies, seen_recipes = set(), set()
        for command in swatches:
            name, params = command["command"], command["params"]
            self.check(name in {"file.new", "solid.box", "appearance.assign"}, "Swatch script includes unexpected behavior")
            if name == "solid.box":
                body = params["body_name"]
                self.check(body not in bodies, "Duplicate swatch body name")
                bodies.add(body)
                self.check(all(number(params[k]) and params[k] > 0 for k in ("length", "width", "height")), "Invalid swatch box dimensions")
                self.check(len(params["corner"]) == 3 and all(number(x) for x in params["corner"]), "Invalid swatch corner")
            elif name == "appearance.assign":
                targets = params["bodies"]
                self.check(len(targets) == 1 and targets[0] in bodies, "Swatch assignment must target a created body")
                runtime = {k: v for k, v in params.items() if k != "bodies"}
                self.pbr(runtime, targets[0])
                identity = targets[0].split(" ", 1)[0]
                if identity in recipes:
                    self.check(identity not in seen_recipes, "Recipe assigned more than once")
                    seen_recipes.add(identity)
                    self.check(runtime == recipes[identity]["baseline_projection"]["runtime_parameters"], identity + ": swatch diverges from recipe")
        self.check(len(bodies) == 49 and seen_recipes == set(recipes), "Missing swatch bodies or appearance assignments")
        roles = self.indices["scenes/roles.json"]
        stages = self.indices["scenes/stages.json"]
        for filename in ("scenes/roles.json", "scenes/stages.json", "scenes/shots.json"):
            for record in self.documents[filename]["metadata"]["catalog_inputs"]:
                path = (self.catalog / record["path"]).resolve()
                self.check(path.is_relative_to(self.catalog.resolve()), "Catalog hash path leaves the catalog")
                self.check(hashlib.sha256(path.read_bytes()).hexdigest() == record["sha256"], filename + ": stale catalog hash for " + record["path"])
        for identity, role in roles.items():
            if role["kind"] in {"appearance_layer", "light_source", "optical_appearance", "emissive_appearance"}:
                self.check(role.get("opaque_proxy_allowed") is False, identity + ": advanced role must not enter the opaque native adapter")
        for identity, stage in stages.items():
            self.check(stage["geometry"]["subject_scale"] == 1, identity + ": do not rescale the native rover")
            self.check(stage["geometry"]["fit_subject_role_id"] in roles, identity + ": unknown fit role")
            for output in stage["geometry"]["role_outputs"]:
                for field in ("geometry_role_id", "appearance_role_id"):
                    if field in output:
                        self.check(output[field] in roles, identity + ": unknown generated role")
            if stage["mode"] == "lunar_physical":
                self.check(stage["ambient"]["enabled"] is False and stage["ambient"]["radiance_scale"] == 0, identity + ": physical lunar ambient fill")
                self.check(stage["atmosphere"]["enabled"] is False and stage["atmosphere"]["density_scale"] == 0, identity + ": physical lunar atmosphere")
                self.check(stage["editorial_fill"]["enabled"] is False, identity + ": hidden editorial fill")
                self.check(stage["background"]["earth"]["enabled"] is False and stage["background"]["stars"]["enabled"] is False, identity + ": unresolved celestial backdrop")
            sun = stage["solar_source"]
            if sun["enabled"]:
                self.check(sun["owner"] == "environment" and sun["environment_map_contains_sun"] is False, identity + ": duplicate or ambiguous Sun owner")
                self.check(sun["distance_model"] == "directional_at_infinity_for_local_stage"
                           and 0 < sun["angular_diameter_rad"] < .1, identity + ": invalid local finite-disk Sun")
        for identity, shot in self.indices["scenes/shots.json"].items():
            stage = stages[shot["stage_id"]]
            self.check(shot["mode"] == stage["mode"], identity + ": shot/stage mode mismatch")
            self.check(shot["camera"]["target_role_id"] in roles, identity + ": unknown framing role")
            needed = set(stage["required_capabilities"])
            for field, filename in (("quality_preset_id", "quality-presets.json"), ("studio_preset_id", "studio-presets.json")):
                needed.update(catalog[filename][shot[field]]["required_capabilities"])
            for role in shot["appearance_role_ids"] + shot["subject"]["required_geometry_role_ids"]:
                self.check(role in roles, identity + ": unknown role " + role)
                needed.update(roles[role]["required_capabilities"])
            self.check(needed <= set(shot["required_capabilities"]), identity + ": missing inherited capabilities " + str(sorted(needed - set(shot["required_capabilities"]))))
            camera = shot["camera"]
            self.check(0 < camera["vertical_fov_rad"] < math.pi and 0 < camera["frame_fill_fraction"] < 1, identity + ": invalid camera framing")
            self.check(shot["subject"]["preserve_native_dimensions"] is True, identity + ": preserve model scale")
        references = {entry["id"] for entry in lock["references"]}
        for item in self.indices["motion/mechanism-acceptance.json"].values():
            self.check(set(item["documentation_evidence"]["reference_ids"]) <= references, item["id"] + ": unknown documentation reference")
            if source["status"] == "awaiting_native_source":
                self.check(item["native_evidence"]["bindings"] is None and item["runtime_evidence"]["report"] is None, item["id"] + ": fabricated native/runtime evidence")
        preflight = self.documents["motion/preflight-commands.json"]["commands"]
        self.check(preflight == [{"command": name, "params": {}} for name in
                                 ("joint.list", "motion.list", "appearance.list", "material.list", "render.scene")], "Preflight must remain a read-only command inventory")
        sequence = self.documents["motion/sample-sequence.json"]
        states = {state["id"] for state in sequence["states"]}
        self.counts["motion/sample-sequence.json states"] = len(states)
        for transition in sequence["transitions"]:
            self.check(transition["from"] in states and transition["to"] in states, "Unknown sequence state")
        self.check(sequence["local_physics"]["gravity_m_s2"] == [0, 0, -1.62]
                   and sequence["local_physics"]["atmospheric_drag"] is False, "Lunar local physics assumption changed without review")
        self.check({"release", "free_flight", "capture", "miss", "store"} <= states, "Sequence lacks physical success/failure events")
        self.ui_checks(catalog)
        return {
            "valid": not self.errors, "counts": self.counts, "errors": self.errors,
            "native_source_status": source["status"], "runtime_ready": False,
            "outstanding": (["Obtain, inspect and admit the improved native file."]
                            if source["status"] == "awaiting_native_source" else []) +
                           ["Review exact native targets and execute the overlay on a saved derivative.",
                            "Bind optical, terrain, lighting and final-output resources to the actual renderer.",
                            "Run required repository gates, runtime previews and mechanism/dynamics validation."],
            "scope": "Prepared data, source-state honesty, references, hashes, opaque command projections and composition checks; no native solver or renderer execution.",
        }


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--directory", type=Path, default=PACKAGE)
    parser.add_argument("--catalog", type=Path, default=CATALOG)
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args()
    try:
        report = Validation(args.directory.resolve(), args.catalog.resolve()).run()
    except (OSError, ValueError, TypeError, KeyError, AttributeError, OverflowError, RecursionError) as exc:
        report = {"valid": False, "runtime_ready": False, "errors": [str(exc)]}
    if args.json:
        print(json.dumps(report, indent=2, ensure_ascii=False, allow_nan=False))
    else:
        print("PASS" if report["valid"] else "FAIL", "— prepared SELENE resource checks")
        for filename, count in report.get("counts", {}).items():
            print(f"  {filename}: {count}")
        for error in report["errors"]:
            print("  ERROR:", error)
        print("Runtime readiness is not established by this validator.")
    return 0 if report["valid"] else 1


if __name__ == "__main__":
    sys.exit(main())