#!/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())