SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
#!/usr/bin/env python3
"""Validate the SolidCraft v0.2 concept package using Python 3.11 stdlib only.
Usage: python3 validate_catalog.py [CATALOG_DIRECTORY] [--json]
This is a read-only data lint and analytic planning check. Passing does not bind
presets, run a renderer, certify physical accuracy, or prove runtime support.
Current-command limits are taken from SolidCraft docs/render-settings.md and
the associated Rust settings types; future authoring presets use separate rules.
Both flat v0.2 envelopes and normalized {metadata: {...}, items: [...]} envelopes
are accepted so the same validator can run before and after package assembly.
"""
from __future__ import annotations
import argparse
import json
import math
import re
import sys
import unicodedata
from pathlib import Path
from typing import Any
SCHEMA_VERSION = "0.2.0"
COLLECTIONS = {
"materials.json": (600, "MAT-", 3, 1),
"lighting.json": (280, "LUZ-", 3, 1),
"environments.json": (280, "ENV-", 3, 1),
"capabilities.json": (120, "CAP-", 3, 1),
"ux.json": (56, "UX-", 3, 1),
"simulation-requirements.json": (36, "SIM-", 3, 1),
"roadmap.json": (19, "F", 2, 0),
"quality-presets.json": (10, "Q-", 3, 1),
"studio-presets.json": (24, "STU-", 3, 1),
"environment-presets.json": (24, "ENVSET-", 3, 1),
"scene-presets.json": (24, "SCENE-", 3, 1),
}
SUPPORT_FILES = (
"baseline-setup-commands.json", "selene-bindings.json",
"lunar-physics-fixtures.json", "provenance.json", "ui-integration.json",
)
REF_PATTERN = re.compile(
r"(?:MAT|LUZ|ENV|CAP|UX|SIM|Q|STU|ENVSET|SCENE)-\d{3}|[FS]\d{2}"
)
PHYSICAL_MODES = ("lunar_physical", "space_physical")
SCENE_MODES = ("terrestrial", "lunar_physical", "space_physical", "editorial")
def is_number(value: Any) -> bool:
return type(value) is int or (type(value) is float and math.isfinite(value))
def unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
result = {}
for key, value in pairs:
if key in result:
raise ValueError(f"Duplicate JSON object key: {key!r}")
result[key] = value
return result
def reject_constant(value: str) -> None:
raise ValueError(f"Non-finite JSON constant: {value}")
def metadata(document: dict[str, Any]) -> dict[str, Any]:
value = document.get("metadata", document)
return value if isinstance(value, dict) else {}
def declared_ids(value: Any) -> set[str]:
"""Return safe IDs for cross-checks; field validation reports bad shapes."""
return {x for x in value if isinstance(x, str)} if isinstance(value, list) else set()
def object_value(value: Any) -> dict[str, Any]:
return value if isinstance(value, dict) else {}
class Validator:
def __init__(self, directory: Path):
self.directory = directory
self.documents: dict[str, dict[str, Any]] = {}
self.indices: dict[str, dict[str, dict[str, Any]]] = {}
self.errors: list[dict[str, str]] = []
self.warnings: list[dict[str, str]] = []
self.counts: dict[str, int] = {}
def error(self, path: str, message: str) -> None:
self.errors.append({"path": path, "message": message})
def warning(self, path: str, message: str) -> None:
self.warnings.append({"path": path, "message": message})
def require(self, condition: bool, path: str, message: str) -> bool:
if not condition:
self.error(path, message)
return condition
def text(self, value: Any, path: str) -> bool:
return self.require(
isinstance(value, str) and bool(value.strip()) and value == value.strip(),
path, "Expected a nonempty, trimmed string.",
)
def string_list(self, value: Any, path: str, *, nonempty: bool = True,
unique: bool = False) -> bool:
if not self.require(isinstance(value, list), path, "Expected an array."):
return False
if nonempty:
self.require(bool(value), path, "Expected a nonempty array.")
valid = all([self.text(x, f"{path}[{i}]") for i, x in enumerate(value)])
if unique and valid:
self.require(len(value) == len(set(value)), path, "Repeated values are not allowed.")
return valid
def number(self, value: Any, path: str, *, minimum: float | None = None,
maximum: float | None = None, positive: bool = False,
integer: bool = False) -> bool:
if not self.require(is_number(value) and (not integer or type(value) is int),
path, "Expected a finite number" + (" of integer type." if integer else ".")):
return False
if minimum is not None:
self.require(value >= minimum, path, f"Must be at least {minimum}.")
if maximum is not None:
self.require(value <= maximum, path, f"Must be at most {maximum}.")
if positive:
self.require(value > 0, path, "Must be greater than zero.")
return True
def boolean(self, value: Any, path: str) -> bool:
return self.require(type(value) is bool, path, "Expected a boolean.")
def obj(self, value: Any, path: str, *, nonempty: bool = True) -> dict[str, Any]:
if not self.require(isinstance(value, dict), path, "Expected an object."):
return {}
if nonempty:
self.require(bool(value), path, "Expected a nonempty object.")
return value
def vector(self, value: Any, path: str, *, minimum: float | None = None,
maximum: float | None = None, unit: bool = False) -> bool:
if not self.require(isinstance(value, list) and len(value) == 3,
path, "Expected a three-component vector."):
return False
ok = all([self.number(x, f"{path}[{i}]", minimum=minimum, maximum=maximum)
for i, x in enumerate(value)])
if ok and unit:
self.require(all(abs(x) <= 1.000001 for x in value)
and math.isclose(sum(x*x for x in value), 1, abs_tol=1e-6),
path, "Expected a unit direction vector.")
return ok
def finite_tree(self, value: Any, path: str) -> None:
if isinstance(value, dict):
for key, child in value.items():
self.finite_tree(child, f"{path}.{key}")
elif isinstance(value, list):
for i, child in enumerate(value):
self.finite_tree(child, f"{path}[{i}]")
elif isinstance(value, float):
self.require(math.isfinite(value), path, "Non-finite numeric value.")
def load(self) -> None:
for filename in (*COLLECTIONS, *SUPPORT_FILES):
path = self.directory / filename
try:
value = json.loads(path.read_text(encoding="utf-8"),
object_pairs_hook=unique_object, parse_constant=reject_constant)
except (OSError, UnicodeError, ValueError) as exc:
self.error(filename, f"Cannot load strict UTF-8 JSON: {exc}")
continue
if self.require(isinstance(value, dict), filename, "Top level must be an object."):
self.documents[filename] = value
self.finite_tree(value, filename)
def collection_checks(self) -> None:
for filename, (count, prefix, width, start) in COLLECTIONS.items():
doc = self.documents.get(filename)
if doc is None:
continue
meta = metadata(doc)
self.require(meta.get("schema_version") == SCHEMA_VERSION,
filename + ".metadata.schema_version", f"Expected {SCHEMA_VERSION!r}.")
self.require(meta.get("language") == "en", filename + ".metadata.language", "Expected 'en'.")
self.text(meta.get("status"), filename + ".metadata.status")
items = doc.get("items")
if not self.require(isinstance(items, list), filename + ".items", "Expected an items array."):
continue
self.counts[filename] = len(items)
if count is None:
self.require(16 <= len(items) <= 20, filename, "Expected 16 to 20 scene presets.")
count = len(items)
else:
self.require(len(items) == count, filename, f"Expected exactly {count} items; found {len(items)}.")
expected = {f"{prefix}{i:0{width}d}" for i in range(start, start+count)}
if filename == "roadmap.json":
expected = {f"F{i:02d}" for i in range(13)} | {f"S{i:02d}" for i in range(1, 7)}
index: dict[str, dict[str, Any]] = {}
names: set[str] = set()
for position, item in enumerate(items):
path = f"{filename}.items[{position}]"
if not isinstance(item, dict):
self.error(path, "Each item must be an object.")
continue
identity = item.get("id")
if self.text(identity, path + ".id"):
self.require(identity not in index, path + ".id", "Duplicate item ID.")
index[identity] = item
path = f"{filename}:{identity}"
name = item.get("name")
if self.text(name, path + ".name"):
key = name.casefold()
self.require(key not in names, path + ".name", "Duplicate item name (case-insensitive).")
names.add(key)
self.text(item.get("status"), path + ".status")
if "priority" in item:
self.require(item["priority"] in ("P0", "P1", "P2"), path + ".priority", "Expected P0, P1 or P2.")
if "cost" in item:
self.require(item["cost"] in ("Low", "Medium", "High"), path + ".cost", "Expected Low, Medium or High.")
missing, extra = expected-index.keys(), index.keys()-expected
if missing:
self.error(filename, "Missing expected IDs: " + ", ".join(sorted(missing)))
if extra:
self.error(filename, "Unexpected IDs: " + ", ".join(sorted(extra)))
self.indices[filename] = index
def items(self, filename: str):
for identity, item in self.indices.get(filename, {}).items():
yield f"{filename}:{identity}", item
def reference(self, value: Any, filename: str, path: str) -> dict[str, Any] | None:
if not self.text(value, path):
return None
target = self.indices.get(filename, {}).get(value)
self.require(target is not None, path, f"Unknown reference {value!r} in {filename}.")
return target
def capability_list(self, value: Any, path: str) -> None:
if self.string_list(value, path, unique=True):
for i, identity in enumerate(value):
self.reference(identity, "capabilities.json", f"{path}[{i}]")
def reference_tree(self, value: Any, path: str, all_ids: set[str],
provenance_ids: set[str], calibration_ids: set[str], source_ids: set[str]) -> None:
if isinstance(value, dict):
for key, child in value.items():
childpath = f"{path}.{key}"
if key in {"required_capabilities", "capability_requirements"}:
self.capability_list(child, childpath)
elif key == "provenance_id":
self.require(isinstance(child, str) and child in provenance_ids, childpath,
f"Unknown provenance reference {child!r}.")
elif key == "reference_id" and isinstance(child, str) and child.startswith("CAL-"):
self.require(child in calibration_ids, childpath, f"Undefined calibration reference {child!r}.")
elif key in {"source_id", "gravity_source_id"}:
self.require(isinstance(child, str) and child in source_ids, childpath, f"Unknown source reference {child!r}.")
self.reference_tree(child, childpath, all_ids, provenance_ids, calibration_ids, source_ids)
elif isinstance(value, list):
for i, child in enumerate(value):
self.reference_tree(child, f"{path}[{i}]", all_ids, provenance_ids, calibration_ids, source_ids)
elif isinstance(value, str) and REF_PATTERN.fullmatch(value):
self.require(value in all_ids, path, f"Unknown catalog reference {value!r}.")
elif isinstance(value, str) and re.fullmatch(r"SRC-[A-Z0-9-]+", value):
self.require(value in source_ids, path, f"Unknown source reference {value!r}.")
def reference_checks(self) -> None:
all_ids = {identity for index in self.indices.values() for identity in index}
provenance_ids: set[str] = set()
calibration_ids: set[str] = set()
source_ids: set[str] = set()
provenance = self.documents.get("provenance.json", {})
for field, destination in (("items", provenance_ids), ("sources", source_ids)):
entries = provenance.get(field, [])
if isinstance(entries, list):
destination.update(x["id"] for x in entries if isinstance(x, dict) and isinstance(x.get("id"), str))
for filename in ("lighting.json", "studio-presets.json"):
norms = metadata(self.documents.get(filename, {})).get("normalization", {})
if isinstance(norms, dict):
calibration_ids.update(k for k in norms if k.startswith("CAL-"))
for filename, doc in self.documents.items():
self.reference_tree(doc, filename, all_ids, provenance_ids, calibration_ids, source_ids)
def required_fields(self) -> None:
common = ("family", "description", "authoring_method", "provenance_id")
catalog_text = {
"materials.json": common + ("optical_model", "scale_policy"),
"lighting.json": common + ("sources", "geometry", "contribution_policy"),
"environments.json": common + ("representation", "geometry", "ambient_lighting", "scale_policy"),
}
for filename, fields in catalog_text.items():
for path, item in self.items(filename):
for field in fields:
self.text(item.get(field), path + "." + field)
for field in ("domains", "use_cases", "controls", "capability_requirements", "validation"):
self.string_list(item.get(field), path + "." + field)
self.require(item.get("status") == "concept", path + ".status", "Catalog entries must remain 'concept'.")
self.require(item.get("priority") in ("P0", "P1", "P2"), path + ".priority", "Required priority is missing or invalid.")
self.require(item.get("cost") in ("Low", "Medium", "High"), path + ".cost", "Required cost is missing or invalid.")
for filename, fields in {
"capabilities.json": ("family", "benefit"),
"ux.json": ("area", "behavior"),
"simulation-requirements.json": ("family",),
"roadmap.json": ("scope",),
}.items():
for path, item in self.items(filename):
for field in fields:
self.text(item.get(field), path + "." + field)
self.string_list(item.get("acceptance"), path + ".acceptance")
for path, item in self.items("capabilities.json"):
self.string_list(item.get("controls"), path + ".controls")
for filename in ("quality-presets.json", "studio-presets.json", "environment-presets.json", "scene-presets.json"):
for path, item in self.items(filename):
self.require(item.get("status") == "specified_unbound", path + ".status",
"Numeric recipes must remain 'specified_unbound'.")
self.string_list(item.get("validation"), path + ".validation")
self.capability_list(item.get("required_capabilities"), path + ".required_capabilities")
def quality_checks(self) -> None:
for path, item in self.items("quality-presets.json"):
resolution = self.obj(item.get("resolution"), path + ".resolution")
for key in ("width", "height"):
self.number(resolution.get(key), path + ".resolution." + key, positive=True, integer=True)
self.require(item.get("integrator_intent") == "path_tracing", path + ".integrator_intent", "Expected declared path-tracing intent.")
sampling = self.obj(item.get("sampling"), path + ".sampling")
low, high = sampling.get("minimum_samples"), sampling.get("maximum_samples")
valid_low = self.number(low, path + ".sampling.minimum_samples", positive=True, integer=True)
valid_high = self.number(high, path + ".sampling.maximum_samples", positive=True, integer=True)
if valid_low and valid_high:
self.require(low <= high, path + ".sampling", "Minimum samples cannot exceed maximum samples.")
self.number(sampling.get("relative_error_target"), path + ".sampling.relative_error_target", positive=True, maximum=1)
for key in ("error_estimator", "maximum_samples_action"):
self.text(sampling.get(key), path + ".sampling." + key)
for key in ("scope", "stopping_rule_binding"):
self.text(sampling.get(key), path + ".sampling." + key)
transport = self.obj(item.get("transport"), path + ".transport")
for key in ("maximum_depth", "maximum_transmission_depth", "russian_roulette_after_depth"):
self.number(transport.get(key), path + ".transport." + key, minimum=0, integer=True)
depth = transport.get("maximum_depth")
if is_number(depth):
for key in ("maximum_transmission_depth", "russian_roulette_after_depth"):
if is_number(transport.get(key)):
self.require(transport[key] <= depth, path + ".transport." + key, "Cannot exceed maximum path depth.")
self.text(transport.get("roulette_policy"), path + ".transport.roulette_policy")
denoise = self.obj(item.get("denoising"), path + ".denoising")
for key in ("enabled", "preserve_raw", "temporal_validation_required"):
self.boolean(denoise.get(key), path + ".denoising." + key)
self.require(denoise.get("preserve_raw") is True, path + ".denoising.preserve_raw", "Raw output must be preserved.")
motion = self.obj(item.get("motion"), path + ".motion")
self.boolean(motion.get("enabled"), path + ".motion.enabled")
self.boolean(motion.get("requires_approved_bake"), path + ".motion.requires_approved_bake")
self.number(motion.get("shutter_fraction"), path + ".motion.shutter_fraction", minimum=0, maximum=1)
self.number(motion.get("temporal_samples"), path + ".motion.temporal_samples", minimum=0, integer=True)
if motion.get("enabled") is True:
self.require(is_number(motion.get("shutter_fraction")) and motion["shutter_fraction"] > 0,
path + ".motion.shutter_fraction", "Enabled motion needs a positive shutter fraction.")
self.require(is_number(motion.get("temporal_samples")) and motion["temporal_samples"] > 0,
path + ".motion.temporal_samples", "Enabled motion needs temporal samples.")
self.require(motion.get("requires_approved_bake") is True, path + ".motion.requires_approved_bake", "Motion must require an approved bake.")
for key in ("sample_budget_policy", "shutter_alignment", "frame_rate_binding"):
self.text(motion.get(key), path + ".motion." + key)
if denoise.get("enabled") is True:
self.require(denoise.get("temporal_validation_required") is True, path + ".denoising",
"Motion denoising needs temporal validation.")
else:
self.require(motion.get("shutter_fraction") == 0 and motion.get("temporal_samples") == 0,
path + ".motion", "Disabled motion must have zero shutter fraction and temporal samples.")
output = self.obj(item.get("output"), path + ".output")
self.require(output.get("master") in ("linear_buffer", "linear_exr"), path + ".output.master", "Expected scene-linear master output.")
self.require(output.get("presentation") == "png", path + ".output.presentation", "Expected PNG presentation output.")
self.require(output.get("color_transform") == "project_declared", path + ".output.color_transform", "Expected a project-declared color transform.")
self.require(output.get("exposure_policy") == "manual_locked", path + ".output.exposure_policy", "Expected manual locked exposure.")
needed = {"CAP-001", "CAP-003", "CAP-006", "CAP-057", "CAP-058", "CAP-059", "CAP-073"}
if output.get("master") == "linear_exr":
needed.add("CAP-074")
if denoise.get("enabled") is True:
needed.add("CAP-065")
if motion.get("enabled") is True:
needed.update({"CAP-053", "CAP-078", "CAP-119"})
self.missing_capabilities(item, needed, path)
self.number(item.get("seed"), path + ".seed", minimum=0, integer=True)
for key in ("goal", "budget_policy", "baseline_compatibility", "provenance_id"):
self.text(item.get(key), path + "." + key)
self.text(item.get("seed_policy"), path + ".seed_policy")
def missing_capabilities(self, item: dict[str, Any], needed: set[str], path: str) -> None:
provided = item.get("required_capabilities", [])
if isinstance(provided, list) and all(isinstance(x, str) for x in provided):
missing = needed - set(provided)
if missing:
self.error(path + ".required_capabilities", "Missing declared-feature dependencies: " + ", ".join(sorted(missing)))
def baseline_checks(self) -> None:
filename = "baseline-setup-commands.json"
doc = self.documents.get(filename)
if doc is None:
return
commands = doc.get("commands")
if not self.require(isinstance(commands, list), filename + ".commands", "Expected commands array."):
return
self.counts[filename] = len(commands)
self.require(len(commands) == 6, filename, "Expected exactly six baseline setup commands.")
names = set()
allowed = {"backend", "mode", "camera", "width", "height", "format", "exposure_ev",
"environment_rotation", "environment_intensity", "background"}
for i, raw in enumerate(commands):
path = f"{filename}.commands[{i}]"
command = self.obj(raw, path)
self.require(set(command) <= {"command", "params"}, path, "Unknown command-envelope field.")
self.require(command.get("command") == "render.settings.set", path + ".command", "Only render.settings.set belongs in this baseline file.")
params = self.obj(command.get("params"), path + ".params")
self.require(set(params) <= {"name", "set"}, path + ".params", "Unknown parameter field.")
name = params.get("name")
if self.text(name, path + ".params.name"):
self.require(len(name.encode("utf-8")) <= 128, path + ".params.name", "Name exceeds 128 UTF-8 bytes.")
self.require(not any(unicodedata.category(c) == "Cc" for c in name), path + ".params.name", "Name contains a control character.")
self.require(name not in names, path + ".params.name", "Duplicate setup name would overwrite another command.")
names.add(name)
values = self.obj(params.get("set"), path + ".params.set")
self.require(set(values) <= allowed, path + ".params.set", "Unknown render.settings.set field: " + ", ".join(sorted(set(values)-allowed)))
width, height = values.get("width", 1024), values.get("height", 768)
a = self.number(width, path + ".params.set.width", positive=True, maximum=4096, integer=True)
b = self.number(height, path + ".params.set.height", positive=True, maximum=4096, integer=True)
if a and b:
self.require(width * height <= 4_194_304, path + ".params.set", "Pixel product exceeds 4,194,304.")
backend = values.get("backend", "builtin")
self.require(isinstance(backend, str) and len(backend.encode("utf-8")) <= 64
and re.fullmatch(r"[a-z][a-z0-9._-]*", backend) is not None,
path + ".params.set.backend", "Invalid backend identifier.")
self.require(values.get("mode", "preview") in ("preview", "final", "quick"), path + ".params.set.mode", "Invalid settings mode.")
self.require(values.get("format", "png") in ("png", "exr"), path + ".params.set.format", "Invalid output format.")
self.number(values.get("exposure_ev", 0), path + ".params.set.exposure_ev", minimum=-32, maximum=32)
self.number(values.get("environment_rotation", 0), path + ".params.set.environment_rotation", minimum=-1_000_000, maximum=1_000_000)
self.number(values.get("environment_intensity", 1), path + ".params.set.environment_intensity", minimum=0, maximum=100)
color = values.get("background", [236, 240, 245])
if self.require(isinstance(color, list) and len(color) == 3, path + ".params.set.background", "Expected three sRGB bytes."):
for j, channel in enumerate(color):
self.number(channel, f"{path}.params.set.background[{j}]", minimum=0, maximum=255, integer=True)
if "camera" in values:
self.camera_checks(values["camera"], path + ".params.set.camera")
def camera_checks(self, raw: Any, path: str) -> None:
camera = self.obj(raw, path)
self.require(set(camera) <= {"target", "yaw", "pitch", "distance", "fov", "roll", "up"}, path, "Unknown camera field.")
self.vector(camera.get("target"), path + ".target", minimum=-1e9, maximum=1e9)
self.number(camera.get("distance"), path + ".distance", positive=True, maximum=1e9)
for key in ("yaw", "pitch", "roll"):
self.number(camera.get(key, 0 if key == "roll" else None), path + "." + key, minimum=-1e6, maximum=1e6)
if self.number(camera.get("fov"), path + ".fov", minimum=0):
self.require(camera["fov"] < math.pi, path + ".fov", "FOV must be below pi radians; zero selects orthographic.")
self.require(camera.get("up", "z") in ("z", "y"), path + ".up", "Camera up must be z or y.")
def studio_checks(self) -> None:
for path, item in self.items("studio-presets.json"):
self.reference(item.get("catalog_id"), "lighting.json", path + ".catalog_id")
self.text(item.get("description"), path + ".description")
self.require(item.get("mode") in ("studio", "lunar_physical", "lunar_editorial"), path + ".mode", "Unknown studio mode.")
policy = self.obj(item.get("subject_scale_policy"), path + ".subject_scale_policy")
for key in ("mode", "definition", "origin", "axes", "position_and_size_units", "angle_units", "fit_policy", "degenerate_subject_policy", "normalization_policy"):
self.text(policy.get(key), path + ".subject_scale_policy." + key)
self.require(policy.get("angle_units") == "radians", path + ".subject_scale_policy.angle_units", "Angles must use radians.")
for key in ("exposed_controls", "locks"):
self.string_list(item.get(key), path + "." + key)
local_ids: set[str] = set()
for collection in ("lights", "modifiers"):
entries = item.get(collection)
if not self.require(isinstance(entries, list), path + "." + collection, "Expected an array; an explicitly empty array is allowed."):
continue
for i, raw in enumerate(entries):
childpath = f"{path}.{collection}[{i}]"
light = self.obj(raw, childpath)
identity = light.get("id")
if self.text(identity, childpath + ".id"):
self.require(identity not in local_ids, childpath + ".id", "Duplicate local source/modifier ID.")
local_ids.add(identity)
if collection == "modifiers":
self.passive_modifier(light, childpath)
continue
source_type = light.get("type")
self.require(source_type in ("rectangular_area", "directional_sun"), childpath + ".type", "Unknown authored light type.")
color = self.obj(light.get("color"), childpath + ".color")
self.require(color.get("space") == "linear_srgb", childpath + ".color.space", "Expected a declared linear RGB color space.")
self.vector(color.get("value"), childpath + ".color.value", minimum=0)
intensity = self.obj(light.get("intensity"), childpath + ".intensity")
self.number(intensity.get("value"), childpath + ".intensity.value")
if source_type == "rectangular_area":
pos_ok = self.vector(light.get("position_b"), childpath + ".position_b")
target_ok = self.vector(light.get("target_b"), childpath + ".target_b")
if pos_ok and target_ok:
self.require(light["position_b"] != light["target_b"], childpath, "Emitter position and aim target must differ.")
self.size_checks(light.get("size_b"), childpath + ".size_b")
self.number(light.get("roll_rad"), childpath + ".roll_rad")
self.require(intensity.get("quantity") == "reference_contribution_ev", childpath + ".intensity.quantity", "Area recipes need calibrated reference EV semantics.")
self.text(intensity.get("reference_id"), childpath + ".intensity.reference_id")
self.require(light.get("energy_owner") == "analytic_light", childpath + ".energy_owner", "Area-light energy must have one analytic owner.")
elif source_type == "directional_sun":
self.vector(light.get("direction"), childpath + ".direction", unit=True)
self.number(light.get("angular_diameter_rad"), childpath + ".angular_diameter_rad", positive=True, maximum=math.pi)
self.require(intensity.get("quantity") == "relative_solar_irradiance", childpath + ".intensity.quantity", "Directional sun requires relative irradiance semantics.")
self.number(intensity.get("value"), childpath + ".intensity.value", minimum=0)
self.require(light.get("energy_owner") == "rig_sun", childpath + ".energy_owner", "Studio sun must declare rig ownership.")
self.text(light.get("visible_emitter_policy"), childpath + ".visible_emitter_policy")
if item.get("mode") == "lunar_physical":
self.require(source_type == "directional_sun", childpath, "Physical lunar rigs cannot contain editorial fill lights.")
def size_checks(self, raw: Any, path: str) -> None:
size = self.obj(raw, path)
for key in ("width", "height"):
self.number(size.get(key), path + "." + key, positive=True)
def passive_modifier(self, modifier: dict[str, Any], path: str) -> None:
self.text(modifier.get("type"), path + ".type")
self.text(modifier.get("role"), path + ".role")
self.vector(modifier.get("position_b"), path + ".position_b")
self.vector(modifier.get("normal"), path + ".normal", unit=True)
self.size_checks(modifier.get("size_b"), path + ".size_b")
self.number(modifier.get("roll_rad"), path + ".roll_rad")
self.require(modifier.get("emission") == 0, path + ".emission", "Passive cards/flags must not emit light.")
material = self.obj(modifier.get("material"), path + ".material")
self.text(material.get("model"), path + ".material.model")
self.vector(material.get("reflectance_linear_srgb"), path + ".material.reflectance_linear_srgb", minimum=0, maximum=1)
def environment_checks(self) -> None:
for path, item in self.items("environment-presets.json"):
self.reference(item.get("catalog_id"), "environments.json", path + ".catalog_id")
self.text(item.get("description"), path + ".description")
self.require(item.get("mode") in SCENE_MODES, path + ".mode", "Unknown environment mode.")
self.string_list(item.get("exposed_controls"), path + ".exposed_controls")
geometry = self.obj(item.get("geometry"), path + ".geometry")
self.text(geometry.get("generator"), path + ".geometry.generator")
self.require(geometry.get("units") == "mm", path + ".geometry.units", "Geometry must use explicit millimeters.")
parameters = self.obj(geometry.get("parameters_mm"), path + ".geometry.parameters_mm")
for key, value in parameters.items():
dimension = re.search(r"(?:^|_)(?:width|depth|height|length|radius|thickness|separation|distance|spacing|wavelength|extent(?:_[xyz])?)$", key) is not None
self.number(value, path + ".geometry.parameters_mm." + key,
positive=dimension, minimum=0 if key.endswith("amplitude") else None)
if is_number(parameters.get("rock_min_radius")) and is_number(parameters.get("rock_max_radius")):
self.require(parameters["rock_min_radius"] <= parameters["rock_max_radius"], path + ".geometry.parameters_mm", "Minimum rock radius cannot exceed maximum rock radius.")
self.number(geometry.get("procedural_seed"), path + ".geometry.procedural_seed", minimum=0, integer=True)
frame = self.obj(geometry.get("reference_frame"), path + ".geometry.reference_frame")
self.require(frame.get("up_axis") == "+Z", path + ".geometry.reference_frame.up_axis", "Environment frame must be Z-up.")
self.require(geometry.get("subject_scale_policy") == "preserve_physical_dimensions", path + ".geometry.subject_scale_policy", "Subject physical scale must be preserved.")
fit = self.obj(geometry.get("stage_fit"), path + ".geometry.stage_fit")
self.require(fit.get("mode") == "once_on_explicit_request", path + ".geometry.stage_fit.mode", "Stage fitting must be explicit and performed once.")
self.require(fit.get("scale_subject") is False and fit.get("resize_room_dimensions") is False,
path + ".geometry.stage_fit", "Stage fitting cannot rescale the subject or resize authored room dimensions.")
self.number(fit.get("minimum_clearance_mm"), path + ".geometry.stage_fit.minimum_clearance_mm", minimum=0)
self.number(fit.get("maximum_supported_subject_extent_mm"), path + ".geometry.stage_fit.maximum_supported_subject_extent_mm", positive=True)
self.text(geometry.get("topography_status"), path + ".geometry.topography_status")
ground = self.obj(item.get("ground"), path + ".ground")
self.boolean(ground.get("enabled"), path + ".ground.enabled")
self.text(ground.get("appearance_role"), path + ".ground.appearance_role")
gp = self.obj(ground.get("parameters"), path + ".ground.parameters")
self.number(gp.get("elevation_mm"), path + ".ground.parameters.elevation_mm")
self.number(gp.get("texture_scale_mm"), path + ".ground.parameters.texture_scale_mm", positive=True)
self.number(gp.get("roughness_multiplier"), path + ".ground.parameters.roughness_multiplier", minimum=0)
self.require(ground.get("shadow_mode") in ("physical_geometry", "shadow_catcher"), path + ".ground.shadow_mode", "Unknown ground shadow mode.")
ambient = self.obj(item.get("ambient"), path + ".ambient")
self.text(ambient.get("source_type"), path + ".ambient.source_type")
self.number(ambient.get("scale"), path + ".ambient.scale", minimum=0)
self.vector(ambient.get("color_linear_srgb"), path + ".ambient.color_linear_srgb", minimum=0)
self.require(ambient.get("sun_disk_in_environment") is False, path + ".ambient.sun_disk_in_environment", "Ambient map must not duplicate the separately owned sun.")
sun = self.obj(item.get("sun"), path + ".sun")
self.boolean(sun.get("enabled"), path + ".sun.enabled")
self.require(sun.get("owner") == "environment", path + ".sun.owner", "Environment recipes must declare solar ownership.")
self.number(sun.get("azimuth_rad"), path + ".sun.azimuth_rad")
self.number(sun.get("elevation_rad"), path + ".sun.elevation_rad", minimum=-math.pi/2, maximum=math.pi/2)
self.number(sun.get("angular_diameter_rad"), path + ".sun.angular_diameter_rad", positive=True, maximum=math.pi)
self.number(sun.get("relative_irradiance"), path + ".sun.relative_irradiance", minimum=0)
if sun.get("enabled") is False:
self.require(sun.get("relative_irradiance") == 0, path + ".sun.relative_irradiance", "Disabled sun must have zero relative irradiance.")
self.require(sun.get("occlusion") == "trace_scene_geometry", path + ".sun.occlusion", "Sun occlusion must be resolved geometrically.")
atmosphere = self.obj(item.get("atmosphere"), path + ".atmosphere")
for key in ("enabled", "participating_volume_enabled"):
self.boolean(atmosphere.get(key), path + ".atmosphere." + key)
self.number(atmosphere.get("density_scale"), path + ".atmosphere.density_scale", minimum=0)
background = self.obj(item.get("background"), path + ".background")
self.vector(background.get("color_linear_srgb"), path + ".background.color_linear_srgb", minimum=0)
self.number(background.get("alpha"), path + ".background.alpha", minimum=0, maximum=1)
earth = self.obj(background.get("earth"), path + ".background.earth")
stars = self.obj(background.get("stars"), path + ".background.stars")
self.boolean(earth.get("enabled"), path + ".background.earth.enabled")
self.boolean(stars.get("enabled"), path + ".background.stars.enabled")
self.number(stars.get("radiance_scale"), path + ".background.stars.radiance_scale", minimum=0)
if item.get("mode") in PHYSICAL_MODES:
self.require(ambient.get("source_type") == "none" and ambient.get("scale") == 0,
path + ".ambient", "Physical vacuum environments require zero atmospheric ambient radiance.")
self.require(atmosphere.get("enabled") is False and atmosphere.get("model") == "none"
and atmosphere.get("density_scale") == 0 and atmosphere.get("participating_volume_enabled") is False,
path + ".atmosphere", "Physical vacuum environments cannot have atmospheric scattering or volumes.")
self.require(earth.get("enabled") is False, path + ".background.earth.enabled", "Earth must stay off until location/trajectory, ephemeris and exposure are bound.")
self.require(stars.get("enabled") is False and stars.get("radiance_scale") == 0,
path + ".background.stars", "Unbound physical sunlit presets must not add a star overlay.")
self.require(ground.get("shadow_mode") == "physical_geometry", path + ".ground.shadow_mode", "Physical vacuum stages require physical ground when enabled.")
self.vacuum_extras(item, path)
def vacuum_extras(self, value: Any, path: str) -> None:
"""Reject active terrestrial media if added to a future vacuum recipe."""
if not isinstance(value, dict):
return
for key, child in value.items():
if key in {"wind", "rain", "fog", "atmospheric_smoke"}:
active = child.get("enabled", False) if isinstance(child, dict) else child
self.require(active in (False, 0, None), path + "." + key, "Terrestrial weather/media are incompatible with physical vacuum.")
if key == "dust" and isinstance(child, dict) and child.get("enabled"):
self.require(child.get("transport") == "ballistic_particles", path + ".dust.transport", "Vacuum dust requires ballistic particle transport.")
if isinstance(child, dict):
self.vacuum_extras(child, path + "." + key)
def scene_checks(self) -> None:
for path, scene in self.items("scene-presets.json"):
self.text(scene.get("description"), path + ".description")
self.require(scene.get("mode") in SCENE_MODES, path + ".mode", "Unknown scene mode.")
quality = self.reference(scene.get("quality_preset_id"), "quality-presets.json", path + ".quality_preset_id")
studio = self.reference(scene.get("studio_preset_id"), "studio-presets.json", path + ".studio_preset_id")
environment = self.reference(scene.get("environment_preset_id"), "environment-presets.json", path + ".environment_preset_id")
for field in ("controls", "locks"):
self.string_list(scene.get(field), path + "." + field, nonempty=False)
subject = self.obj(scene.get("subject_binding"), path + ".subject_binding")
for field in ("kind", "manifest", "selection_rule", "unresolved_action"):
self.text(subject.get(field), path + ".subject_binding." + field)
self.require(subject.get("preserve_physical_scale") is True, path + ".subject_binding.preserve_physical_scale", "Scene composition must preserve physical subject dimensions.")
self.require(subject.get("unresolved_action") == "block_without_scene_mutation", path + ".subject_binding.unresolved_action", "Unresolved composition must fail atomically.")
if isinstance(scene.get("name"), str) and scene["name"].startswith("SELENE "):
self.require(subject.get("kind") == "improved_selene_showcase_or_reviewed_derivative"
and subject.get("manifest") == "../../assets/render/selene/source-lock.json"
and subject.get("required_source_status") == "pinned_native",
path + ".subject_binding", "SELENE shots require the improved showcase source; v7 references are historical only.")
bindings = self.obj(scene.get("appearance_bindings"), path + ".appearance_bindings")
dependencies = set()
for preset in (quality, studio, environment):
if preset is not None:
dependencies.update(declared_ids(preset.get("required_capabilities")))
for preset, catalog in ((studio, "lighting.json"), (environment, "environments.json")):
if preset is not None and isinstance(preset.get("catalog_id"), str):
concept = self.indices.get(catalog, {}).get(preset["catalog_id"], {})
dependencies.update(declared_ids(concept.get("capability_requirements")))
for role, identity in bindings.items():
self.text(role, path + ".appearance_bindings.<role>")
material = self.reference(identity, "materials.json", path + ".appearance_bindings." + role)
if material is not None:
dependencies.update(declared_ids(material.get("capability_requirements")))
self.missing_capabilities(scene, dependencies, path)
appearance_overrides = scene.get("appearance_overrides", {})
if isinstance(appearance_overrides, dict):
for role, raw in appearance_overrides.items():
childpath = path + ".appearance_overrides." + role
self.require(role in bindings, childpath, "Appearance override refers to an unbound role.")
appearance = self.obj(raw, childpath)
if "base_color_linear_srgb" in appearance:
self.vector(appearance["base_color_linear_srgb"], childpath + ".base_color_linear_srgb", minimum=0, maximum=1)
else:
self.error(path + ".appearance_overrides", "Expected an object.")
camera = self.obj(scene.get("camera_intent"), path + ".camera_intent")
self.require(camera.get("projection") == "perspective", path + ".camera_intent.projection", "Expected explicit perspective intent for this package.")
if self.number(camera.get("vertical_fov_rad"), path + ".camera_intent.vertical_fov_rad", positive=True):
self.require(camera["vertical_fov_rad"] < math.pi, path + ".camera_intent.vertical_fov_rad", "Perspective FOV must be below pi.")
self.vector(camera.get("view_from_target_direction"), path + ".camera_intent.view_from_target_direction", unit=True)
self.number(camera.get("frame_fill_fraction"), path + ".camera_intent.frame_fill_fraction", positive=True, maximum=1)
self.require(camera.get("fit_policy") == "explicit_once_when_camera_not_locked", path + ".camera_intent.fit_policy", "Camera framing must be explicit and honor locks.")
for field in ("clip_planes", "exposure"):
self.text(camera.get(field), path + ".camera_intent." + field)
if "source_binding_policy" in scene:
self.text(scene["source_binding_policy"], path + ".source_binding_policy")
if quality is not None and object_value(quality.get("motion")).get("enabled") is True:
motion = self.obj(scene.get("motion_binding"), path + ".motion_binding")
self.require(motion.get("approved_bake_required") is True, path + ".motion_binding.approved_bake_required", "Animation composition needs an approved bake.")
self.number(motion.get("frame_rate_hz"), path + ".motion_binding.frame_rate_hz", positive=True)
for field in ("frame_range", "physics_retiming"):
self.text(motion.get(field), path + ".motion_binding." + field)
simulation = motion.get("required_simulation_requirements")
if self.string_list(simulation, path + ".motion_binding.required_simulation_requirements", unique=True):
for identity in simulation:
self.reference(identity, "simulation-requirements.json", path + ".motion_binding.required_simulation_requirements")
if "preview_quality_alternative" in motion:
self.reference(motion["preview_quality_alternative"], "quality-presets.json", path + ".motion_binding.preview_quality_alternative")
if studio is None or environment is None:
continue
ground = object_value(environment.get("ground"))
geometry = object_value(environment.get("geometry"))
if ground.get("enabled") is True:
role = ground.get("appearance_role")
self.require(isinstance(role, str) and role in bindings, path + ".appearance_bindings", f"Enabled environment ground role {role!r} must resolve to a material.")
if is_number(geometry.get("rock_count")) and geometry["rock_count"] > 0 and geometry.get("rock_appearance_role"):
role = geometry["rock_appearance_role"]
self.require(isinstance(role, str) and role in bindings, path + ".appearance_bindings", f"Environment rock role {role!r} must resolve to a material.")
overrides = scene.get("environment_overrides", {})
if not isinstance(overrides, dict):
self.error(path + ".environment_overrides", "Expected an object.")
overrides = {}
self.require(set(overrides) <= {"ambient_scale", "sun_enabled", "sun_relative_irradiance", "background_kind"}, path + ".environment_overrides", "Unknown environment override; add explicit validation before use.")
if "environment_override_reason" in scene:
self.text(scene["environment_override_reason"], path + ".environment_override_reason")
if "background_kind" in overrides:
self.require(overrides["background_kind"] in ("scene_geometry", "black", "transparent", "linked_environment"),
path + ".environment_overrides.background_kind", "Unknown background representation.")
ambient_scale = overrides.get("ambient_scale", object_value(environment.get("ambient")).get("scale"))
self.number(ambient_scale, path + ".effective_ambient_scale", minimum=0)
env_sun = object_value(environment.get("sun"))
sun_enabled = overrides.get("sun_enabled", env_sun.get("enabled"))
self.boolean(sun_enabled, path + ".effective_environment_sun_enabled")
irradiance = overrides.get("sun_relative_irradiance", env_sun.get("relative_irradiance"))
self.number(irradiance, path + ".effective_sun_relative_irradiance", minimum=0)
lights = studio.get("lights", [])
if not isinstance(lights, list):
continue
active_lights = [light for light in lights if isinstance(light, dict) and light.get("enabled", True) is not False]
rig_suns = [light for light in active_lights if light.get("type") == "directional_sun"
and is_number(object_value(light.get("intensity")).get("value")) and light["intensity"]["value"] > 0]
solar_count = int(sun_enabled is True and is_number(irradiance) and irradiance > 0) + len(rig_suns)
self.require(solar_count <= 1, path, "Composition has more than one active solar source.")
mode = scene.get("mode")
if mode in PHYSICAL_MODES:
self.require(environment.get("mode") == mode, path + ".mode", "Physical scene and environment modes must agree.")
self.require(studio.get("mode") == "lunar_physical", path + ".studio_preset_id", "Physical vacuum scenes require a physical solar/pass-through rig.")
self.require(ambient_scale == 0, path + ".environment_overrides", "Physical vacuum scenes cannot introduce ambient fill.")
self.require(all(light.get("type") == "directional_sun" for light in active_lights),
path + ".studio_preset_id", "Physical vacuum scenes cannot contain studio/editorial fill lights.")
self.require(not studio.get("modifiers"), path + ".studio_preset_id", "Unbound physical vacuum scenes cannot introduce editorial studio cards.")
if studio.get("id") in ("STU-020", "STU-021", "STU-023"):
self.require(solar_count == 1, path, "This physical rig requires exactly one resolved solar emitter.")
if studio.get("id") == "STU-022":
self.require(solar_count == 0, path, "Zero-source audit requires all solar emitters disabled.")
self.vacuum_extras(scene, path)
elif mode == "terrestrial":
self.require(environment.get("mode") == "terrestrial", path + ".environment_preset_id", "Terrestrial scene requires a terrestrial environment.")
self.require(studio.get("mode") == "studio", path + ".studio_preset_id", "Terrestrial scene requires an appropriate studio rig.")
if studio.get("mode") == "studio":
self.require(ambient_scale == 0, path + ".environment_overrides", "Calibrated studio composition must explicitly remove unaccounted environment illumination.")
self.require(solar_count == 0, path, "Calibrated studio composition cannot silently add a solar source.")
if studio.get("mode") == "lunar_editorial":
self.require(mode == "editorial", path + ".mode", "Promotional lunar fill must be labeled editorial.")
self.require(solar_count == 1, path, "Editorial solar-relative fill needs one resolved environment sun.")
def roadmap_checks(self) -> None:
graph = self.indices.get("roadmap.json", {})
for identity, item in graph.items():
path = "roadmap.json:" + identity + ".depends_on"
deps = item.get("depends_on")
if self.string_list(deps, path, nonempty=False, unique=True):
for dep in deps:
self.reference(dep, "roadmap.json", path)
self.require(dep != identity, path, "A phase cannot depend on itself.")
visiting, visited = set(), set()
def visit(identity: str) -> None:
if identity in visiting:
self.error("roadmap.json:" + identity, "Dependency cycle detected.")
return
if identity in visited:
return
visiting.add(identity)
deps = graph.get(identity, {}).get("depends_on", [])
if isinstance(deps, list):
for dep in deps:
if isinstance(dep, str) and dep in graph:
visit(dep)
visiting.remove(identity)
visited.add(identity)
for identity in graph:
visit(identity)
def support_checks(self) -> None:
"""Structural and original analytic checks; no simulation is performed."""
for filename in ("selene-bindings.json", "lunar-physics-fixtures.json", "provenance.json", "ui-integration.json"):
doc = self.documents.get(filename)
if doc is None:
continue
meta = metadata(doc)
self.require(meta.get("schema_version") == SCHEMA_VERSION, filename + ".metadata.schema_version", "Expected v0.2 schema version.")
self.require(meta.get("language") == "en", filename + ".metadata.language", "Expected English metadata.")
self.text(meta.get("status"), filename + ".metadata.status")
self.require(any(k != "metadata" for k in doc), filename, "Support document must contain substantive data.")
self.provenance_checks()
self.selene_checks()
self.physics_checks()
def support_index(self, entries: Any, path: str) -> dict[str, dict[str, Any]]:
"""Index a support collection without prescribing external ID sequences."""
if not self.require(isinstance(entries, list) and bool(entries), path, "Expected a nonempty array of identified records."):
return {}
result, names = {}, set()
for i, raw in enumerate(entries):
itempath = f"{path}[{i}]"
item = self.obj(raw, itempath)
identity, name = item.get("id"), item.get("name")
if self.text(identity, itempath + ".id"):
self.require(identity not in result, itempath + ".id", "Duplicate support-record ID.")
result[identity] = item
if self.text(name, itempath + ".name"):
self.require(name.casefold() not in names, itempath + ".name", "Duplicate support-record name.")
names.add(name.casefold())
return result
def provenance_checks(self) -> None:
filename = "provenance.json"
doc = self.documents.get(filename)
if doc is None:
return
records = self.support_index(doc.get("items"), filename + ".items")
sources = self.support_index(doc.get("sources"), filename + ".sources")
self.require(not set(records).intersection(sources), filename, "Authorship and reference IDs must be distinct.")
self.require("ORIGINAL-2026-10-CATALOG" in records, filename + ".items", "Original catalog provenance record is required.")
for identity, item in records.items():
path = filename + ":" + identity
for key in ("license", "author", "authorship"):
self.text(item.get(key), path + "." + key)
for key in ("external_assets_bundled", "commercial_product_extraction", "gpl_implementation_reference"):
self.require(item.get(key) is False, path + "." + key, "Clean-room package must not claim bundled external assets or extracted implementations.")
if self.string_list(item.get("sources"), path + ".sources", unique=True):
for source in item["sources"]:
self.require(source in sources, path + ".sources", f"Unknown source {source!r}.")
for identity, source in sources.items():
path = filename + ":" + identity
for key in ("url", "use", "accessed", "redistribution"):
self.text(source.get(key), path + "." + key)
self.require(isinstance(source.get("url"), str) and source["url"].startswith("https://"),
path + ".url", "Reference URL must use HTTPS.")
self.require(isinstance(source.get("accessed"), str) and re.fullmatch(r"\d{4}-\d{2}-\d{2}", source["accessed"]) is not None,
path + ".accessed", "Expected a YYYY-MM-DD access date.")
def selene_checks(self) -> None:
filename = "selene-bindings.json"
doc = self.documents.get(filename)
if doc is None:
return
self.require(metadata(doc).get("status") == "historical_reference_only"
and metadata(doc).get("active_demo_source") is False
and metadata(doc).get("superseded_by") == "../../assets/render/selene/source-lock.json",
filename + ".metadata", "The original v7 inventory must remain explicitly ineligible as the active demo source.")
source = self.obj(doc.get("source"), filename + ".source")
for key in ("repository", "path", "format", "source_id"):
self.text(source.get(key), filename + ".source." + key)
self.require(isinstance(source.get("commit"), str) and re.fullmatch(r"[0-9a-f]{40}", source["commit"]) is not None,
filename + ".source.commit", "Source must be pinned to a 40-character commit SHA.")
self.require(isinstance(source.get("sha256"), str) and re.fullmatch(r"[0-9a-f]{64}", source["sha256"]) is not None,
filename + ".source.sha256", "Model identity requires a SHA-256 digest.")
self.number(source.get("size_bytes"), filename + ".source.size_bytes", positive=True, integer=True)
self.require(source.get("units") == "mm" and source.get("up_axis") == "+Z", filename + ".source", "Model must declare millimeters and Z-up.")
counts = self.obj(doc.get("observed_counts"), filename + ".observed_counts")
for key, value in counts.items():
self.number(value, filename + ".observed_counts." + key, minimum=0, integer=True)
components = doc.get("components")
joints = doc.get("joints")
if not self.require(isinstance(components, list) and isinstance(joints, list), filename, "Components and joints arrays are required."):
return
component_ids, occurrence_ids, component_names = set(), set(), set()
for i, raw in enumerate(components):
path = f"{filename}.components[{i}]"
component = self.obj(raw, path)
identity, name = component.get("component_id"), component.get("name")
if self.number(identity, path + ".component_id", positive=True, integer=True):
self.require(identity not in component_ids, path + ".component_id", "Duplicate component ID.")
component_ids.add(identity)
if self.text(name, path + ".name"):
self.require(name not in component_names, path + ".name", "Duplicate component name.")
component_names.add(name)
occurrences = component.get("occurrence_ids")
if self.require(isinstance(occurrences, list) and bool(occurrences), path + ".occurrence_ids", "Component needs an occurrence reference."):
for occurrence in occurrences:
if self.number(occurrence, path + ".occurrence_ids", positive=True, integer=True):
self.require(occurrence not in occurrence_ids, path + ".occurrence_ids", "Occurrence is assigned more than once.")
occurrence_ids.add(occurrence)
for i, component in enumerate(components):
if isinstance(component, dict):
parent = component.get("parent_component_id")
self.require(type(parent) is int and parent in component_ids | {0}, f"{filename}.components[{i}].parent_component_id", "Unknown parent component.")
self.require(len(component_ids) == counts.get("component_definitions_excluding_root"), filename + ".observed_counts", "Component count does not match inspected records.")
self.require(len(occurrence_ids) == counts.get("occurrences"), filename + ".observed_counts", "Occurrence count does not match inspected records.")
joint_ids, joint_names = set(), set()
joint_index = {}
for i, raw in enumerate(joints):
path = f"{filename}.joints[{i}]"
joint = self.obj(raw, path)
identity, name = joint.get("id"), joint.get("name")
if self.number(identity, path + ".id", positive=True, integer=True):
self.require(identity not in joint_ids, path + ".id", "Duplicate joint ID.")
joint_ids.add(identity)
joint_index[identity] = joint
if self.text(name, path + ".name"):
self.require(name not in joint_names, path + ".name", "Duplicate joint name.")
joint_names.add(name)
self.require(joint.get("kind") == "revolute", path + ".kind", "Expected inspected revolute joint.")
for key in ("a_occurrence_id", "b_occurrence_id"):
value = joint.get(key)
self.require(type(value) is int and value in occurrence_ids, path + "." + key, "Joint refers to an unknown occurrence.")
limits = joint.get("limits_rad")
if limits is None:
self.require(joint.get("limit_status") == "not_declared", path + ".limit_status", "Unspecified joint limits must be explicitly identified.")
elif self.require(isinstance(limits, list) and len(limits) == 2 and all(is_number(x) for x in limits), path + ".limits_rad", "Expected two finite radian limits or null."):
self.require(limits[0] <= limits[1], path + ".limits_rad", "Joint lower limit exceeds upper limit.")
self.require(joint.get("limit_status") == "inspected_source_limits", path + ".limit_status", "Declared limits must retain their inspection status.")
self.require(len(joint_ids) == counts.get("revolute_joints"), filename + ".observed_counts", "Joint count does not match inspected records.")
chain, arm_joints = doc.get("arm_chain_occurrence_ids"), doc.get("arm_joint_ids")
if self.require(isinstance(chain, list) and isinstance(arm_joints, list) and len(chain) == len(arm_joints) and bool(chain), filename + ".arm_chain_occurrence_ids", "Arm chain and joint list must have matching nonzero lengths."):
for i, (occurrence, joint_id) in enumerate(zip(chain, arm_joints)):
self.require(type(occurrence) is int and occurrence in occurrence_ids, filename + ".arm_chain_occurrence_ids", "Unknown arm occurrence.")
valid_id = type(joint_id) is int and joint_id in joint_index
self.require(valid_id, filename + ".arm_joint_ids", "Unknown arm joint.")
if valid_id:
joint = joint_index[joint_id]
self.require(joint.get("b_occurrence_id") == occurrence, filename + ".arm_joint_ids", "Arm joint does not terminate at the corresponding occurrence.")
if i:
self.require(joint.get("a_occurrence_id") == chain[i-1], filename + ".arm_joint_ids", "Arm chain connectivity is inconsistent.")
vial = self.obj(doc.get("candidate_vial"), filename + ".candidate_vial")
parent_component, parent_occurrence = vial.get("parent_component_id"), vial.get("parent_occurrence_id")
self.require(type(parent_component) is int and parent_component in component_ids, filename + ".candidate_vial.parent_component_id", "Unknown vial parent component.")
self.require(type(parent_occurrence) is int and parent_occurrence in occurrence_ids, filename + ".candidate_vial.parent_occurrence_id", "Unknown vial parent occurrence.")
self.require(any(isinstance(component, dict)
and component.get("component_id") == parent_component
and isinstance(component.get("occurrence_ids"), list)
and parent_occurrence in component["occurrence_ids"] for component in components),
filename + ".candidate_vial.parent_occurrence_id", "Vial parent occurrence does not belong to the selected parent component.")
self.boolean(vial.get("independent_occurrence_exists"), filename + ".candidate_vial.independent_occurrence_exists")
self.string_list(vial.get("required_derivative_changes"), filename + ".candidate_vial.required_derivative_changes")
refs = vial.get("body_references")
if self.require(isinstance(refs, list) and bool(refs), filename + ".candidate_vial.body_references", "Vial body references are required."):
body_names, features, transfers = set(), set(), set()
for i, raw in enumerate(refs):
path = f"{filename}.candidate_vial.body_references[{i}]"
body = self.obj(raw, path)
name = body.get("exact_body_name")
if self.text(name, path + ".exact_body_name"):
self.require(name not in body_names, path + ".exact_body_name", "Duplicate vial body name.")
body_names.add(name)
feature = body.get("source_feature_id")
if self.number(feature, path + ".source_feature_id", positive=True, integer=True):
self.require(feature not in features, path + ".source_feature_id", "Duplicate source-feature reference.")
features.add(feature)
ids = body.get("transfer_feature_ids")
if self.require(isinstance(ids, list) and bool(ids), path + ".transfer_feature_ids", "Transfer-feature IDs are required."):
for value in ids:
if self.number(value, path + ".transfer_feature_ids", positive=True, integer=True):
self.require(value not in transfers, path + ".transfer_feature_ids", "Duplicate transfer-feature reference.")
transfers.add(value)
for key in ("moves_with_vial", "contents"):
self.boolean(body.get(key), path + "." + key)
policy = self.obj(doc.get("binding_policy"), filename + ".binding_policy")
for key in ("match", "ambiguous_names", "source_geometry", "appearance_scope", "runtime_support"):
self.text(policy.get(key), filename + ".binding_policy." + key)
self.require(policy.get("native_model_bundled") is False, filename + ".binding_policy.native_model_bundled", "Reference-only package must not claim a bundled native model.")
self.string_list(doc.get("attribution_requirements"), filename + ".attribution_requirements")
hints = doc.get("appearance_role_hints")
if self.require(isinstance(hints, list) and bool(hints), filename + ".appearance_role_hints", "Reviewed appearance role hints are required."):
roles = set()
for i, raw in enumerate(hints):
path = f"{filename}.appearance_role_hints[{i}]"
hint = self.obj(raw, path)
role = hint.get("role")
if self.text(role, path + ".role"):
self.require(role not in roles, path + ".role", "Duplicate appearance role.")
roles.add(role)
self.reference(hint.get("material_concept_id"), "materials.json", path + ".material_concept_id")
self.text(hint.get("scope_note"), path + ".scope_note")
ids = hint.get("occurrence_ids")
if self.require(isinstance(ids, list), path + ".occurrence_ids", "Expected occurrence-hint array."):
for occurrence in ids:
self.require(type(occurrence) is int and occurrence in occurrence_ids,
path + ".occurrence_ids", "Appearance hint refers to an unknown source occurrence.")
expected_status = "requires_reviewed_body_or_face_selection" if ids else "requires_explicit_derivative_geometry_if_used"
self.require(hint.get("assignment_status") == expected_status, path + ".assignment_status", "Role hints must retain explicit target-review or derivative-geometry status.")
def close_expected(self, observed: Any, expected: Any, tolerance: float, path: str) -> None:
if isinstance(expected, list):
if self.require(isinstance(observed, list) and len(observed) == len(expected), path, "Expected matching numeric vector length."):
for i, (a, b) in enumerate(zip(observed, expected)):
self.close_expected(a, b, tolerance, f"{path}[{i}]")
elif self.number(observed, path):
self.require(abs(observed - expected) <= tolerance, path,
f"Analytic mismatch: expected {expected!r}, observed {observed!r}, absolute tolerance {tolerance!r}.")
def physics_checks(self) -> None:
"""Recompute closed-form fixtures only; this does not integrate dynamics."""
filename = "lunar-physics-fixtures.json"
doc = self.documents.get(filename)
if doc is None:
return
records = self.support_index(doc.get("items"), filename + ".items")
self.counts[filename] = len(records)
self.require(set(records) == {f"PHY-{i:03d}" for i in range(1, 7)}, filename + ".items", "Expected exactly PHY-001 through PHY-006.")
for identity, item in records.items():
path = filename + ":" + identity
self.text(item.get("interpretation"), path + ".interpretation")
kind = item.get("kind")
self.text(kind, path + ".kind")
tolerance = item.get("absolute_tolerance", 1e-12)
if not self.number(tolerance, path + ".absolute_tolerance", positive=True, maximum=1e-6):
continue
if kind == "ballistic_equal_height":
keys = ("gravity_m_s2", "initial_position_m", "initial_velocity_m_s")
if not all([self.vector(item.get(k), path + "." + k) for k in keys]):
continue
g, p, v = (item[k] for k in keys)
if not self.require(g[0] == 0 and g[1] == 0 and g[2] < 0 and v[2] > 0, path, "Equal-height analytic fixture requires downward Z gravity and upward release."):
continue
apex_time, flight_time = -v[2]/g[2], -2*v[2]/g[2]
position = lambda t: [p[i]+v[i]*t+0.5*g[i]*t*t for i in range(3)]
expected = {
"apex_time_s": apex_time, "flight_time_s": flight_time,
"rise_m": -v[2]*v[2]/(2*g[2]),
"range_m": math.hypot(v[0], v[1])*flight_time,
"apex_position_m": position(apex_time),
"landing_position_m": position(flight_time),
"landing_velocity_m_s": [v[i]+g[i]*flight_time for i in range(3)],
}
saved = self.obj(item.get("expected"), path + ".expected")
for key, value in expected.items():
self.close_expected(saved.get(key), value, tolerance, path + ".expected." + key)
self.string_list(item.get("assumptions"), path + ".assumptions")
elif kind == "unit_conversion":
inputs = self.obj(item.get("inputs"), path + ".inputs")
saved = self.obj(item.get("expected"), path + ".expected")
conversions = (
("position_mm", "position_m", 1e-3),
("velocity_mm_s", "velocity_m_s", 1e-3),
("gravity_mm_s2", "gravity_m_s2", 1e-3),
("inertia_kg_mm2", "inertia_kg_m2", 1e-6),
("torque_n_mm", "torque_n_m", 1e-3),
)
for source, destination, factor in conversions:
if self.vector(inputs.get(source), path + ".inputs." + source):
self.close_expected(saved.get(destination), [x*factor for x in inputs[source]], tolerance, path + ".expected." + destination)
elif kind == "release_velocity":
keys = ("grip_velocity_m_s", "grip_angular_velocity_rad_s", "grip_to_center_of_mass_m")
if not all([self.vector(item.get(k), path + "." + k) for k in keys]):
continue
velocity, omega, r = (item[k] for k in keys)
cross = [omega[1]*r[2]-omega[2]*r[1], omega[2]*r[0]-omega[0]*r[2], omega[0]*r[1]-omega[1]*r[0]]
self.close_expected(item.get("expected_center_of_mass_velocity_m_s"), [velocity[i]+cross[i] for i in range(3)], tolerance, path + ".expected_center_of_mass_velocity_m_s")
elif kind == "principal_inertia_admissibility":
self.require(item.get("units") == "kg*m^2", path + ".units", "Inertia fixture must use kg*m^2.")
cases = item.get("cases")
if not self.require(isinstance(cases, list) and bool(cases), path + ".cases", "Inertia fixture requires positive and negative cases."):
continue
self.require(any(isinstance(c, dict) and c.get("expected_valid") is True for c in cases)
and any(isinstance(c, dict) and c.get("expected_valid") is False for c in cases),
path + ".cases", "Inertia fixture must include both admissible and inadmissible cases.")
for i, raw in enumerate(cases):
casepath = f"{path}.cases[{i}]"
case = self.obj(raw, casepath)
if self.vector(case.get("moments"), casepath + ".moments"):
a, b, c = case["moments"]
valid = min(a, b, c) > 0 and a+b >= c and a+c >= b and b+c >= a
self.boolean(case.get("expected_valid"), casepath + ".expected_valid")
self.require(case.get("expected_valid") is valid, casepath + ".expected_valid", "Admissibility disagrees with positive moments and triangle inequalities.")
elif kind == "sample_mass":
keys = ("container_mass_kg", "collected_sample_mass_kg", "spilled_sample_mass_kg")
if not all([self.number(item.get(k), path + "." + k, minimum=0) for k in keys]):
continue
container, sample, spilled = (item[k] for k in keys)
self.require(container > 0, path + ".container_mass_kg", "Container mass must be positive.")
self.require(spilled <= sample, path + ".spilled_sample_mass_kg", "Spilled mass cannot exceed collected mass.")
self.close_expected(item.get("expected_retained_sample_mass_kg"), sample-spilled, tolerance, path + ".expected_retained_sample_mass_kg")
self.close_expected(item.get("expected_total_sealed_mass_kg"), container+sample-spilled, tolerance, path + ".expected_total_sealed_mass_kg")
else:
self.error(path + ".kind", "Unknown analytic fixture kind.")
def ui_checks(self) -> None:
filename = "ui-integration.json"
doc = self.documents.get(filename)
if doc is None:
return
meta = metadata(doc)
self.require(meta.get("status") == "specified_unbound" and meta.get("runtime_ready") is False,
filename + ".metadata", "The UI contract describes unbound intent, not implemented UI.")
snapshots = self.obj(doc.get("source_snapshots"), filename + ".source_snapshots")
for kind in ("integration_base", "design_reference"):
record = self.obj(snapshots.get(kind), filename + ".source_snapshots." + kind)
self.require(isinstance(record.get("commit"), str) and re.fullmatch(r"[0-9a-f]{40}", record["commit"]) is not None,
filename + ".source_snapshots." + kind, "Source snapshots require exact Git commit identities.")
records = doc.get("source_records")
if self.require(isinstance(records, list) and bool(records), filename + ".source_records", "Source records are required."):
seen = set()
self.counts["ui-integration.json source records"] = len(records)
for index, raw in enumerate(records):
path = f"{filename}.source_records[{index}]"
record = self.obj(raw, path)
identity = record.get("id")
if self.text(identity, path + ".id"):
self.require(identity not in seen, path + ".id", "Duplicate source record.")
seen.add(identity)
source_path = record.get("path")
self.require(isinstance(source_path, str) and bool(source_path) and not Path(source_path).is_absolute()
and ".." not in Path(source_path).parts, path + ".path", "Source paths must be repository relative.")
for field in ("baseline_git_blob", "reference_git_blob"):
self.require(isinstance(record.get(field), str) and re.fullmatch(r"[0-9a-f]{40}", record[field]) is not None,
path + "." + field, "Expected an exact Git blob identity.")
self.require(record.get("identical_between_revisions") is (record.get("baseline_git_blob") == record.get("reference_git_blob")),
path, "Source comparison must match recorded blob identities.")
workspace = self.obj(doc.get("workspace"), filename + ".workspace")
self.require(workspace.get("visible_tab_ids_at_baseline") == ["RENDER"] and workspace.get("group_is_tab") is False,
filename + ".workspace", "The baseline has one RENDER tab; SCENE and IMAGE are groups.")
navigation = object_value(workspace.get("navigation"))
self.require(navigation.get("handler") == "navigation::handle" and navigation.get("pick_at_baseline") is False,
filename + ".workspace.navigation", "Do not invent current Render picking or a separate camera controller.")
disclosure = self.obj(doc.get("disclosure"), filename + ".disclosure")
self.require(disclosure.get("default") == "Quick" and disclosure.get("levels") == ["Quick", "Detailed", "Expert"]
and disclosure.get("global_mode_switch") is False, filename + ".disclosure", "Use one inspector with progressive disclosure.")
self.number(disclosure.get("quick_adjustment_budget"), filename + ".disclosure.quick_adjustment_budget", minimum=1, maximum=6, integer=True)
library = self.obj(doc.get("library"), filename + ".library")
self.require(library.get("category_labels") == ["Scenes", "Materials", "Lighting", "Environments"]
and library.get("category_is_workspace") is False, filename + ".library", "Library types are local category navigation.")
recommendations = doc.get("quality_recommendations")
if self.require(isinstance(recommendations, list), filename + ".quality_recommendations", "Expected recommendations."):
for index, raw in enumerate(recommendations):
path = f"{filename}.quality_recommendations[{index}]"
record = self.obj(raw, path)
values = record.get("preset_ids")
if self.string_list(values, path + ".preset_ids", unique=True):
self.require(len(values) == 3, path, "Recommend three exact profiles, with the complete picker still available.")
for value in values:
self.reference(value, "quality-presets.json", path + ".preset_ids")
reused, proposed = doc.get("command_reuse"), doc.get("proposed_commands")
if self.require(isinstance(reused, list) and isinstance(proposed, list), filename, "Command reuse and proposal arrays are required."):
ids = set()
for raw in reused:
record = self.obj(raw, filename + ".command_reuse")
identity = record.get("id")
if self.text(identity, filename + ".command_reuse.id"):
self.require(identity not in ids, filename + ".command_reuse", "Duplicate existing command.")
ids.add(identity)
self.require(record.get("status") == "registered_at_baseline", filename + ".command_reuse", "Declare existing-command evidence scope.")
for raw in proposed:
record = self.obj(raw, filename + ".proposed_commands")
identity = record.get("candidate_id")
if self.text(identity, filename + ".proposed_commands.candidate_id"):
self.require(identity not in ids, filename + ".proposed_commands", "Proposed commands cannot duplicate existing routes.")
ids.add(identity)
self.require(record.get("status") == "unregistered_proposal", filename + ".proposed_commands", "Do not claim new runtime registration.")
self.require(metadata(self.documents.get("ux.json", {})).get("integration_contract") == "ui-integration.json",
"ux.json.metadata.integration_contract", "UX requirements must identify their UI integration contract.")
def run(self) -> dict[str, Any]:
self.load()
self.collection_checks()
self.required_fields()
self.reference_checks()
self.quality_checks()
self.baseline_checks()
self.studio_checks()
self.environment_checks()
self.scene_checks()
self.roadmap_checks()
self.support_checks()
self.ui_checks()
return {
"valid": not self.errors,
"schema_version": SCHEMA_VERSION,
"directory": str(self.directory),
"counts": self.counts,
"errors": self.errors,
"warnings": self.warnings,
"scope": "Read-only concept data and analytic planning validation; no renderer or simulation execution.",
}
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("directory", nargs="?", type=Path, default=Path(__file__).resolve().parent,
help="Package directory (default: directory containing this script).")
parser.add_argument("--json", action="store_true", help="Write a machine-readable JSON result to stdout.")
args = parser.parse_args()
validator = Validator(args.directory.resolve())
report = validator.run()
if args.json:
print(json.dumps(report, indent=2, ensure_ascii=False, allow_nan=False))
else:
print("PASS" if report["valid"] else "FAIL", "— SolidCraft v0.2 catalog validation")
for filename, count in report["counts"].items():
print(f" {filename}: {count}")
for level in ("errors", "warnings"):
for issue in report[level]:
print(f" {level[:-1].upper()} {issue['path']}: {issue['message']}")
print(f"{len(report['errors'])} error(s), {len(report['warnings'])} warning(s).")
print(report["scope"])
return 0 if report["valid"] else 1
if __name__ == "__main__":
sys.exit(main())