@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/plugins/beamng-vehicle/bin/beamng_jbeam.py

@@ -0,0 +1,858 @@
+"""Deterministic parser for BeamNG's JSON-like JBeam text format.
+
+BeamNG's shipped definitions permit comments, trailing/repeated commas, and
+omitted separators between adjacent values. One 0.39.4 base-game file also
+contains the invalid JSON integer ``00``. The compatibility pass below handles
+only those observed lexical forms; it never balances delimiters, ignores
+trailing content, or rewrites arbitrary malformed number tokens.
+"""
+from __future__ import annotations
+
+import hashlib
+import codecs
+import io
+import json
+import os
+import re
+import sqlite3
+import stat
+import tempfile
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+from typing import Any, Iterable
+
+
+SELECTED_PART_INDEX_SCHEMA = "helix.beamng-selected-part-index/1"
+MAX_JBEAM_FILE_BYTES = 64 * 1024 * 1024
+MAX_JBEAM_TOTAL_BYTES = 2 * 1024 * 1024 * 1024
+MAX_JBEAM_SOURCES = 50_000
+MAX_JBEAM_PARTS = 250_000
+MAX_CLOSURE_PARTS = 100_000
+MAX_JBEAM_ENTRIES = 500_000
+MAX_JBEAM_DIRECTORIES = 50_000
+MAX_JBEAM_DEPTH = 64
+MAX_SCAN_DIRECTORY_ENTRIES = 100_000
+MAX_RETAINED_PARSE_FAILURES = 20
+MAX_JBEAM_NORMALIZED_CHARS = MAX_JBEAM_FILE_BYTES * 2
+MAX_SELECTED_PART_INDEX_BYTES = 128 * 1024 * 1024
+MAX_PC_FILE_BYTES = 8 * 1024 * 1024
+MAX_PC_TOTAL_BYTES = 128 * 1024 * 1024
+MAX_PC_SOURCES = 4_096
+MAX_INFO_FILE_BYTES = 8 * 1024 * 1024
+MAX_INFO_TOTAL_BYTES = 128 * 1024 * 1024
+MAX_INFO_SOURCES = 4_096
+MAX_JSON_NODES = 2_000_000
+MAX_JSON_DEPTH = 256
+CATALOG_SQLITE_CACHE_KIB = 4 * 1024
+BRAKE_AXLE_PATTERN = re.compile(r"(?:^|_)brakes?_?([FR])(?:_|$)", re.I)
+
+
+def pressure_wheel_options(body: dict[str, Any]) -> dict[str, Any]:
+    """Merge only section-level option dictionaries, never anonymous wheel rows."""
+    section = body.get("pressureWheels")
+    if not isinstance(section, list):
+        return {}
+    options: dict[str, Any] = {}
+    for row in section[1:]:
+        if isinstance(row, dict):
+            options.update(row)
+    return options
+
+
+def selected_part_axle(pattern: re.Pattern[str], slot_name: str, part_name: str,
+                       body: dict[str, Any]) -> str | None:
+    matches: set[str] = set()
+    for label in (slot_name, body.get("slotType"), part_name):
+        if not isinstance(label, str):
+            continue
+        match = pattern.search(label)
+        if match:
+            matches.add("front" if match.group(1).lower() == "f" else "rear")
+    return next(iter(matches)) if len(matches) == 1 else None
+
+
+def _source_limits(extension: str) -> tuple[int, int, int]:
+    return {
+        ".jbeam": (MAX_JBEAM_FILE_BYTES, MAX_JBEAM_TOTAL_BYTES, MAX_JBEAM_SOURCES),
+        ".pc": (MAX_PC_FILE_BYTES, MAX_PC_TOTAL_BYTES, MAX_PC_SOURCES),
+        ".json": (MAX_INFO_FILE_BYTES, MAX_INFO_TOTAL_BYTES, MAX_INFO_SOURCES),
+    }.get(extension, (MAX_INFO_FILE_BYTES, MAX_INFO_TOTAL_BYTES, MAX_INFO_SOURCES))
+
+
+class JBeamParseError(ValueError):
+    """A byte-bounded, fingerprinted JBeam source could not be decoded."""
+
+
+def preselect_configuration(vehicle_root: str | Path, variants: Iterable[str],
+                            hint: str | None = None) -> Path | None:
+    """Select an explicit/canonical config without consulting Blender geometry."""
+    root = Path(vehicle_root).resolve()
+    configs = bounded_asset_paths([root], {".pc": (MAX_PC_SOURCES, MAX_PC_TOTAL_BYTES,
+                                                        MAX_PC_FILE_BYTES)}, recursive=False)
+    if hint:
+        normalized = re.sub(r"[^a-z0-9]", "", hint.lower())
+        matches = [path for path in configs
+                   if normalized in re.sub(r"[^a-z0-9]", "", path.stem.lower())]
+        if matches:
+            return min(matches, key=lambda path: (
+                bool(re.search(r"antichrome|weissach", path.stem, re.I)),
+                path.stat().st_size,
+                path.name,
+            ))
+    by_stem = {path.stem.lower(): path for path in configs}
+    for variant in variants:
+        selected = by_stem.get(str(variant).lower())
+        if selected is not None:
+            return selected
+    return configs[0] if len(configs) == 1 else None
+
+
+def normalize_jbeam(text: str) -> tuple[str, dict[str, int]]:
+    """Normalize shipped BeamNG lexical quirks in one bounded state-machine pass."""
+    output = io.StringIO()
+    pending_after_comma = io.StringIO()
+    output_chars = 0
+    pending_chars = 0
+    leading_zero_count = 0
+    quoted = False
+    last = ""
+    gap = False
+    comma_pending = False
+    index = 0
+    blocked_before = set("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_.+-")
+    blocked_after = set("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_.")
+
+    def write(value: str, *, pending: bool = False) -> None:
+        nonlocal output_chars, pending_chars
+        if output_chars + pending_chars + len(value) > MAX_JBEAM_NORMALIZED_CHARS:
+            raise ValueError(f"normalized JBeam exceeds {MAX_JBEAM_NORMALIZED_CHARS} characters")
+        if pending:
+            pending_after_comma.write(value)
+            pending_chars += len(value)
+        else:
+            output.write(value)
+            output_chars += len(value)
+
+    def resolve_comma(next_char: str) -> None:
+        nonlocal comma_pending, pending_chars
+        if not comma_pending:
+            return
+        if next_char not in "}]":
+            write(",")
+        tail = pending_after_comma.getvalue()
+        pending_after_comma.seek(0)
+        pending_after_comma.truncate(0)
+        pending_chars = 0
+        write(tail)
+        comma_pending = False
+
+    while index < len(text):
+        char = text[index]
+        if quoted:
+            write(char)
+            if char == "\\" and index + 1 < len(text):
+                write(text[index + 1])
+                index += 2
+                continue
+            if char == '"':
+                quoted = False
+                last, gap = '"', False
+            index += 1
+            continue
+        if text.startswith("//", index):
+            newline = text.find("\n", index + 2)
+            if newline < 0:
+                index = len(text)
+                break
+            write("\n", pending=comma_pending)
+            gap = True
+            index = newline + 1
+            continue
+        if text.startswith("/*", index):
+            end = text.find("*/", index + 2)
+            if end < 0:
+                raise ValueError("unterminated JBeam block comment")
+            newlines = text.count("\n", index, end + 2)
+            if newlines:
+                write("\n" * newlines, pending=comma_pending)
+                gap = True
+            index = end + 2
+            continue
+        if char in " \t\r\n":
+            write(char, pending=comma_pending)
+            gap = True
+            index += 1
+            continue
+        if char == "," and comma_pending:
+            # `[1,\n, ]` / `,,`: BeamNG's reader treats a run of commas as one separator.
+            index += 1
+            continue
+        resolve_comma(char)
+        if char in '"[{' and last and (last in '"]}.' or last.isalnum()):
+            write(",")
+        elif (char.isdigit() or char == "-") and last in '"]}':
+            write(",")
+        elif (char.isdigit() or char == "-") and gap and (last.isalnum() or last == "."):
+            write(",")
+        if char == "," and last in (",", "[", "{", ""):
+            index += 1
+            continue
+        if char == ",":
+            comma_pending = True
+            last, gap, index = ",", False, index + 1
+            continue
+        if char == '"':
+            quoted = True
+            write(char)
+            last, gap = char, False
+            index += 1
+            continue
+        before = text[index - 1] if index > 0 else ""
+        after = text[index + 2] if index + 2 < len(text) else ""
+        if text.startswith("00", index) and before not in blocked_before and after not in blocked_after:
+            write("0")
+            leading_zero_count += 1
+            last, gap = "0", False
+            index += 2
+            continue
+        write(char)
+        last, gap, index = char, False, index + 1
+    if quoted:
+        raise ValueError("unterminated JBeam string")
+    resolve_comma("")
+    return output.getvalue(), {"leadingZeroValues": leading_zero_count}
+
+
+def parse_jbeam_text(text: str) -> tuple[dict[str, Any], dict[str, int]]:
+    normalized, diagnostics = normalize_jbeam(text)
+    try:
+        value = json.loads(normalized)
+    except json.JSONDecodeError as error:
+        # BeamNG's reader stops at the end of the root object and ignores what follows, so a
+        # file that closes one brace too many (a stray `},}` at the end, seen in shipped mods
+        # such as the mmbng 993's Porsh_engine.jbeam) still loads in the game. Accept exactly
+        # that: a complete root followed by nothing but closers, commas and whitespace.
+        if error.msg != "Extra data":
+            raise
+        body = normalized.lstrip()
+        value, end = json.JSONDecoder().raw_decode(body)
+        tail = body[end:]
+        if not isinstance(value, dict) or tail.strip(" \t\r\n,}]") != "":
+            raise
+        diagnostics = {**diagnostics, "strayClosers": sum(1 for c in tail if c in "}]")}
+    if not isinstance(value, dict):
+        raise ValueError("JBeam root must be an object")
+    nodes = 0
+    stack: list[tuple[Any, int]] = [(value, 0)]
+    while stack:
+        node, depth = stack.pop()
+        nodes += 1
+        if nodes > MAX_JSON_NODES:
+            raise ValueError(f"decoded JBeam exceeds {MAX_JSON_NODES} values")
+        if depth > MAX_JSON_DEPTH:
+            raise ValueError(f"decoded JBeam exceeds nested depth {MAX_JSON_DEPTH}")
+        if isinstance(node, dict):
+            stack.extend((child, depth + 1) for child in node.values())
+        elif isinstance(node, list):
+            stack.extend((child, depth + 1) for child in node)
+    return value, diagnostics
+
+
+def parse_jbeam(path: str | Path) -> dict[str, Any]:
+    value, _ = parse_jbeam_text(Path(path).read_text(errors="ignore"))
+    return value
+
+
+def parse_jbeam_with_diagnostics(path: str | Path) -> tuple[dict[str, Any], dict[str, int]]:
+    return parse_jbeam_text(Path(path).read_text(errors="ignore"))
+
+
+def decode_jbeam_table(section: object) -> list[dict[str, Any]]:
+    """Decode a JBeam table while preserving BeamNG's state-row semantics.
+
+    Standalone objects update the persistent state inherited by subsequent
+    rows. Objects embedded in an individual row apply only to that row. Header
+    names use BeamNG's optional trailing-colon notation.
+    """
+    if not isinstance(section, list) or not section or not isinstance(section[0], list):
+        return []
+    header = [value.rstrip(":") for value in section[0] if isinstance(value, str)]
+    if len(header) != len(section[0]) or len(set(header)) != len(header):
+        raise ValueError("JBeam table header must contain unique string fields")
+    state: dict[str, Any] = {}
+    rows: list[dict[str, Any]] = []
+    for raw in section[1:]:
+        if isinstance(raw, dict):
+            state.update(raw)
+            continue
+        if not isinstance(raw, list):
+            continue
+        row = dict(state)
+        values = [value for value in raw if not isinstance(value, dict)]
+        row.update({field: values[index] for index, field in enumerate(header)
+                    if index < len(values)})
+        for value in raw:
+            if isinstance(value, dict):
+                row.update(value)
+        rows.append(row)
+    return rows
+
+
+def _portable_source_path(path: Path, source_root: Path) -> str:
+    try:
+        return path.relative_to(source_root).as_posix()
+    except ValueError as error:
+        raise ValueError(f"JBeam source escapes source root: {path}") from error
+
+
+def stream_file_receipt(path: str | Path, source_root: str | Path,
+                        chunk_bytes: int = 1024 * 1024) -> dict[str, Any]:
+    """Return a portable path and a streaming byte fingerprint."""
+    requested = Path(path)
+    if requested.is_symlink():
+        raise ValueError(f"JBeam source must not be a symlink: {requested}")
+    target = requested.resolve()
+    root = Path(source_root).resolve()
+    portable = _portable_source_path(target, root)
+    info = target.stat()
+    if not stat.S_ISREG(info.st_mode) or info.st_size > MAX_JBEAM_FILE_BYTES:
+        raise ValueError(f"JBeam source is not a regular file or exceeds {MAX_JBEAM_FILE_BYTES} bytes: {portable}")
+    digest = hashlib.sha256()
+    size = 0
+    with target.open("rb") as handle:
+        while chunk := handle.read(chunk_bytes):
+            digest.update(chunk)
+            size += len(chunk)
+    return {"path": portable, "sha256": digest.hexdigest(), "sizeBytes": size}
+
+
+def stable_json_sha256(value: object) -> str:
+    encoded = json.dumps(value, sort_keys=True, separators=(",", ":"),
+                         ensure_ascii=False).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+class JBeamDocumentCache:
+    """Single-parse cache for the JBeam/config documents in one source tree."""
+
+    def __init__(self, source_root: str | Path,
+                 dependency_roots: Iterable[str | Path] = ()):
+        self.source_root = Path(source_root).resolve()
+        self.roots = [("source", self.source_root), *[
+            (f"dependency:{index}", Path(root).resolve())
+            for index, root in enumerate(dependency_roots)
+        ]]
+        self._documents: dict[Path, dict[str, Any]] = {}
+        self._failures: dict[Path, Exception] = {}
+        self._receipts: dict[Path, dict[str, Any]] = {}
+        self.parse_counts: dict[Path, int] = {}
+        self.total_bytes = 0
+        self.extension_counts: dict[str, int] = {}
+        self.extension_bytes: dict[str, int] = {}
+        self._released: set[Path] = set()
+
+    def _origin(self, target: Path) -> tuple[str, str]:
+        for origin, root in self.roots:
+            try:
+                return origin, target.relative_to(root).as_posix()
+            except ValueError:
+                continue
+        raise ValueError(f"JBeam source escapes admitted roots: {target}")
+
+    def load(self, path: str | Path) -> dict[str, Any]:
+        requested = Path(path)
+        if requested.is_symlink():
+            raise ValueError(f"JBeam source must not be a symlink: {requested}")
+        target = requested.resolve()
+        if target in self.parse_counts and target not in self._documents:
+            raise self._failures.get(target, JBeamParseError("previous bounded decode attempt failed"))
+        if target not in self._documents:
+            extension = target.suffix.lower()
+            file_limit, total_limit, source_limit = _source_limits(extension)
+            if self.extension_counts.get(extension, 0) >= source_limit:
+                raise ValueError(f"{extension or 'document'} source count exceeds {source_limit}")
+            self.parse_counts[target] = self.parse_counts.get(target, 0) + 1
+            self.extension_counts[extension] = self.extension_counts.get(extension, 0) + 1
+            origin, portable = self._origin(target)
+            info = target.stat()
+            if not stat.S_ISREG(info.st_mode) or info.st_size > file_limit:
+                raise ValueError(f"{extension or 'document'} source is not a regular file or exceeds {file_limit} bytes")
+            if self.extension_bytes.get(extension, 0) + info.st_size > total_limit:
+                raise ValueError(f"{extension or 'document'} source bytes exceed {total_limit}")
+            initial_identity = (info.st_dev, info.st_ino, info.st_size,
+                                info.st_mtime_ns, info.st_ctime_ns)
+            digest = hashlib.sha256()
+            decoded_chunks: list[str] = []
+            decoder = codecs.getincrementaldecoder("utf-8")(errors="ignore")
+            size = 0
+            flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+            descriptor = os.open(target, flags)
+            try:
+                opened = os.fstat(descriptor)
+                if (opened.st_dev, opened.st_ino, opened.st_size,
+                    opened.st_mtime_ns, opened.st_ctime_ns) != initial_identity:
+                    raise ValueError(f"JBeam source changed before reading: {portable}")
+                while True:
+                    remaining_file = file_limit - size
+                    remaining_total = total_limit - self.extension_bytes.get(extension, 0)
+                    read_size = min(1024 * 1024, max(1, min(remaining_file, remaining_total) + 1))
+                    chunk = os.read(descriptor, read_size)
+                    if not chunk:
+                        break
+                    size += len(chunk)
+                    self.total_bytes += len(chunk)
+                    self.extension_bytes[extension] = self.extension_bytes.get(extension, 0) + len(chunk)
+                    if size > file_limit:
+                        raise ValueError(f"{extension or 'document'} source exceeds {file_limit} bytes while reading: {portable}")
+                    if self.extension_bytes[extension] > total_limit:
+                        self.extension_bytes[extension] = total_limit
+                        raise ValueError(f"{extension or 'document'} source bytes exceed {total_limit}")
+                    digest.update(chunk)
+                    decoded = decoder.decode(chunk)
+                    if decoded:
+                        decoded_chunks.append(decoded)
+                decoded = decoder.decode(b"", final=True)
+                if decoded:
+                    decoded_chunks.append(decoded)
+                final = os.fstat(descriptor)
+                final_identity = (final.st_dev, final.st_ino, final.st_size,
+                                  final.st_mtime_ns, final.st_ctime_ns)
+                if final_identity != initial_identity or size != final.st_size:
+                    raise ValueError(f"JBeam source changed while reading: {portable}")
+            finally:
+                os.close(descriptor)
+            self._receipts[target] = {
+                "root": origin,
+                "path": portable,
+                "sha256": digest.hexdigest(),
+                "sizeBytes": size,
+            }
+            try:
+                document, _ = parse_jbeam_text("".join(decoded_chunks))
+            except Exception as error:
+                failure = JBeamParseError(str(error))
+                if len(self._failures) < MAX_RETAINED_PARSE_FAILURES:
+                    self._failures[target] = failure
+                raise failure from error
+            self._documents[target] = document
+        return self._documents[target]
+
+    def release(self, path: str | Path) -> None:
+        """Drop a parsed corpus document after its bodies have been spilled."""
+        target = Path(path).resolve()
+        self._documents.pop(target, None)
+        self._released.add(target)
+
+    def receipt(self, path: str | Path) -> dict[str, Any]:
+        target = Path(path).resolve()
+        if target not in self._receipts:
+            origin, portable = self._origin(target)
+            root = next(root for name, root in self.roots if name == origin)
+            self._receipts[target] = {"root": origin, **stream_file_receipt(target, root),
+                                      "path": portable}
+        return dict(self._receipts[target])
+
+
+def _part_definition(name: str, body: dict[str, Any], path: Path,
+                     cache: JBeamDocumentCache) -> dict[str, Any]:
+    flex = [row.get("mesh") for row in decode_jbeam_table(body.get("flexbodies"))
+            if isinstance(row.get("mesh"), str)]
+    props = [row.get("mesh") for row in decode_jbeam_table(body.get("props"))
+             if isinstance(row.get("mesh"), str)]
+    slots: list[dict[str, Any]] = []
+    for key in ("slots", "slots2"):
+        for row in decode_jbeam_table(body.get(key)):
+            slots.append({"type": row.get("type") or row.get("name"),
+                          "default": row.get("default"),
+                          "variables": row.get("variables") if isinstance(row.get("variables"), dict) else {}})
+    return {"name": name, "slotType": body.get("slotType"),
+            "meshes": flex + props, "slots": slots,
+            "source": cache.receipt(path)["path"],
+            "sourceRoot": cache.receipt(path)["root"],
+            "_sourcePath": path.resolve()}
+
+
+class JBeamPartCatalog(Mapping[str, dict[str, Any]]):
+    """Disk-backed part metadata/body store with a deliberately tiny page cache."""
+
+    def __init__(self) -> None:
+        self._temporary = tempfile.TemporaryDirectory(prefix="helix-jbeam-catalog-")
+        self.path = Path(self._temporary.name) / "catalog.sqlite3"
+        self._db = sqlite3.connect(self.path)
+        self._db.execute("PRAGMA journal_mode=OFF")
+        self._db.execute("PRAGMA synchronous=OFF")
+        self._db.execute("PRAGMA temp_store=FILE")
+        self._db.execute(f"PRAGMA cache_size=-{CATALOG_SQLITE_CACHE_KIB}")
+        self._db.execute("PRAGMA mmap_size=0")
+        self._db.execute("""CREATE TABLE parts (
+            name TEXT PRIMARY KEY, slot_type TEXT, meshes TEXT NOT NULL, slots TEXT NOT NULL,
+            source TEXT NOT NULL, source_root TEXT NOT NULL, source_path TEXT NOT NULL,
+            body TEXT NOT NULL, source_rank INTEGER NOT NULL
+        ) WITHOUT ROWID""")
+        self._count = 0
+        self._closed = False
+
+    def add(self, definition: dict[str, Any], body: dict[str, Any], source_rank: int) -> None:
+        values = (
+            definition["name"],
+            json.dumps(definition.get("slotType"), separators=(",", ":"), ensure_ascii=False),
+            json.dumps(definition["meshes"], separators=(",", ":"), ensure_ascii=False),
+            json.dumps(definition["slots"], separators=(",", ":"), ensure_ascii=False),
+            definition["source"], definition["sourceRoot"], str(definition["_sourcePath"]),
+            json.dumps(body, separators=(",", ":"), ensure_ascii=False),
+            source_rank,
+        )
+        previous_row = self._db.execute(
+            "SELECT source_rank, source_root, source FROM parts WHERE name = ?",
+            (definition["name"],)).fetchone()
+        if previous_row is not None:
+            previous_rank, previous_root, previous_source = previous_row
+            if source_rank > previous_rank:
+                return
+            if source_rank == previous_rank:
+                error = ValueError(
+                    f"ambiguous JBeam part definition {definition['name']!r}: "
+                    f"{previous_root}:{previous_source} and "
+                    f"{definition['sourceRoot']}:{definition['source']}")
+                raise error
+            self._db.execute(
+                "DELETE FROM parts WHERE name = ?", (definition["name"],))
+            self._db.execute("INSERT INTO parts VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)", values)
+            return
+        try:
+            self._db.execute("INSERT INTO parts VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)", values)
+        except sqlite3.IntegrityError as error:
+            raise ValueError(
+                f"ambiguous JBeam part definition {definition['name']!r}: "
+                f"existing definition and "
+                f"{definition['sourceRoot']}:{definition['source']}") from error
+        self._count += 1
+        if self._count > MAX_JBEAM_PARTS:
+            raise ValueError(f"JBeam part catalog exceeds {MAX_JBEAM_PARTS} definitions")
+
+    def finish_source(self) -> None:
+        self._db.commit()
+
+    @staticmethod
+    def _definition(row: tuple[Any, ...]) -> dict[str, Any]:
+        name, slot_type, meshes, slots, source, source_root, source_path = row
+        return {"name": name, "slotType": json.loads(slot_type), "meshes": json.loads(meshes),
+                "slots": json.loads(slots), "source": source, "sourceRoot": source_root,
+                "_sourcePath": Path(source_path)}
+
+    def __getitem__(self, name: str) -> dict[str, Any]:
+        row = self._db.execute(
+            "SELECT name, slot_type, meshes, slots, source, source_root, source_path "
+            "FROM parts WHERE name = ?", (name,)).fetchone()
+        if row is None:
+            raise KeyError(name)
+        return self._definition(row)
+
+    def __iter__(self) -> Iterator[str]:
+        for row in self._db.execute("SELECT name FROM parts ORDER BY name"):
+            yield str(row[0])
+
+    def __len__(self) -> int:
+        return self._count
+
+    def values(self) -> Iterator[dict[str, Any]]:
+        rows = self._db.execute(
+            "SELECT name, slot_type, meshes, slots, source, source_root, source_path "
+            "FROM parts ORDER BY name")
+        for row in rows:
+            yield self._definition(row)
+
+    def body(self, name: str) -> dict[str, Any]:
+        row = self._db.execute("SELECT body FROM parts WHERE name = ?", (name,)).fetchone()
+        if row is None:
+            raise KeyError(name)
+        body = json.loads(row[0])
+        if not isinstance(body, dict):
+            raise ValueError(f"spilled JBeam part {name!r} is not an object")
+        return body
+
+    @property
+    def spill_bytes(self) -> int:
+        self._db.commit()
+        return self.path.stat().st_size
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._db.close()
+        self._temporary.cleanup()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+
+def bounded_asset_paths(roots: Iterable[str | Path],
+                        limits: dict[str, tuple[int, int, int]], *,
+                        recursive: bool = True,
+                        exact_names: dict[str, str] | None = None) -> list[Path]:
+    """Scan files with bounded traversal and independent count/byte budgets.
+
+    ``limits`` maps a lowercase extension (or an exact-name class supplied by
+    ``exact_names``) to ``(files, aggregate bytes, bytes per file)``.
+    """
+    paths: set[Path] = set()
+    entries = 0
+    directories = 0
+    counts = {key: 0 for key in limits}
+    bytes_by_kind = {key: 0 for key in limits}
+    stack: list[tuple[Path, int]] = []
+    exact_names = {name.lower(): kind for name, kind in (exact_names or {}).items()}
+    for raw_root in roots:
+        root = Path(raw_root).resolve()
+        if root.is_file():
+            stack.append((root.parent, -1))
+        elif root.is_dir():
+            stack.append((root, 0))
+    while stack:
+        directory, depth = stack.pop()
+        if depth > MAX_JBEAM_DEPTH:
+            raise ValueError(f"JBeam discovery exceeds depth {MAX_JBEAM_DEPTH}")
+        directories += 1
+        if directories > MAX_JBEAM_DIRECTORIES:
+            raise ValueError(f"JBeam discovery exceeds {MAX_JBEAM_DIRECTORIES} directories")
+        children: list[tuple[str, Path, bool]] = []
+        with os.scandir(directory) as iterator:
+            for entry in iterator:
+                entries += 1
+                if entries > MAX_JBEAM_ENTRIES:
+                    raise ValueError(f"JBeam discovery exceeds {MAX_JBEAM_ENTRIES} entries")
+                if len(children) >= MAX_SCAN_DIRECTORY_ENTRIES:
+                    raise ValueError(
+                        f"asset discovery exceeds {MAX_SCAN_DIRECTORY_ENTRIES} entries in one directory")
+                if entry.is_symlink():
+                    raise ValueError(f"asset discovery refuses symlink: {entry.path}")
+                path = Path(entry.path).resolve()
+                children.append((entry.name, path, entry.is_dir(follow_symlinks=False)))
+        for name, path, is_directory in sorted(children, reverse=True):
+            if is_directory and recursive:
+                stack.append((path, depth + 1))
+            elif not is_directory:
+                lowered = name.lower()
+                kind = exact_names.get(lowered, path.suffix.lower())
+                if kind not in limits:
+                    continue
+                max_files, max_bytes, max_file_bytes = limits[kind]
+                info = path.stat()
+                if not stat.S_ISREG(info.st_mode) or info.st_size > max_file_bytes:
+                    raise ValueError(
+                        f"{kind} asset is not regular or exceeds {max_file_bytes} bytes: {path}")
+                counts[kind] += 1
+                bytes_by_kind[kind] += info.st_size
+                if counts[kind] > max_files:
+                    raise ValueError(f"{kind} asset count exceeds {max_files}")
+                if bytes_by_kind[kind] > max_bytes:
+                    raise ValueError(f"{kind} asset bytes exceed {max_bytes}")
+                paths.add(path)
+    return sorted(paths)
+
+
+def _bounded_jbeam_paths(roots: Iterable[str | Path]) -> list[Path]:
+    return bounded_asset_paths(
+        roots, {".jbeam": (MAX_JBEAM_SOURCES, MAX_JBEAM_TOTAL_BYTES,
+                            MAX_JBEAM_FILE_BYTES)})
+
+
+def build_part_catalog(roots: Iterable[str | Path], cache: JBeamDocumentCache,
+                       root_ranks: Iterable[int] | None = None) -> tuple[JBeamPartCatalog, list[str]]:
+    """Parse every admitted JBeam once and reject ambiguous part ownership."""
+    catalog = JBeamPartCatalog()
+    failures: list[str] = []
+    admitted_roots = [Path(root).resolve() for root in roots]
+    ranks = list(root_ranks) if root_ranks is not None else [0] * len(admitted_roots)
+    if len(ranks) != len(admitted_roots):
+        raise ValueError("JBeam root rank count does not match admitted roots")
+    paths = _bounded_jbeam_paths(admitted_roots)
+    for path in paths:
+        source_rank = min(rank for root, rank in zip(admitted_roots, ranks)
+                          if path == root or root in path.parents)
+        try:
+            document = cache.load(path)
+        except JBeamParseError as error:  # retain a bounded best-effort parse report
+            if len(failures) < MAX_RETAINED_PARSE_FAILURES:
+                receipt = cache.receipt(path)
+                failures.append(f"{receipt['root']}:{receipt['path']}: {type(error).__name__}: {error}")
+            continue
+        try:
+            for name, body in document.items():
+                if isinstance(body, dict):
+                    catalog.add(_part_definition(name, body, path, cache), body, source_rank)
+            catalog.finish_source()
+        finally:
+            cache.release(path)
+    return catalog, failures
+
+
+def resolve_part_closure(catalog: Mapping[str, dict[str, Any]], overrides: dict[str, Any],
+                         main_part_name: str | None = None) -> dict[str, Any]:
+    """Resolve a deterministic main/default/override part closure."""
+    roots = [part for part in catalog.values() if part.get("slotType") == "main"]
+    if main_part_name not in catalog:
+        main_part_name = max(roots, key=lambda part: (
+            len(part["slots"]), len(part["meshes"]), part["name"]
+        ))["name"] if roots else main_part_name
+
+    selected: list[dict[str, Any]] = []
+    closure: list[dict[str, Any]] = []
+    missing: list[dict[str, Any]] = []
+    visited: set[str] = set()
+    admitted_slots: set[str] = set()
+
+    def visit_many(entries: list[tuple[object, str | None, str, str]]) -> None:
+        stack = list(reversed(entries))
+        while stack:
+            part_name, host_part, slot_type, selection = stack.pop()
+            if not isinstance(part_name, str) or not part_name or part_name == "none":
+                continue
+            definition = catalog.get(part_name)
+            if definition is None:
+                missing.append({"hostPart": host_part, "slotType": slot_type,
+                                "partName": part_name, "selection": selection})
+                continue
+            if part_name in visited:
+                continue
+            visited.add(part_name)
+            if len(visited) > MAX_CLOSURE_PARTS:
+                raise ValueError(f"selected JBeam closure exceeds {MAX_CLOSURE_PARTS} parts")
+            selected.append(definition)
+            children: list[tuple[object, str | None, str, str]] = []
+            for slot in definition["slots"]:
+                child_slot = slot.get("type")
+                if not isinstance(child_slot, str) or not child_slot:
+                    continue
+                admitted_slots.add(child_slot)
+                child = overrides.get(child_slot, slot.get("default"))
+                source = "override" if child_slot in overrides else "default"
+                closure.append({"hostPart": part_name, "slotType": child_slot,
+                                "defaultPart": slot.get("default"), "selectedPart": child,
+                                "variables": slot.get("variables", {}),
+                                "selection": source,
+                                "resolution": "disabled" if child in (None, "", "none") else
+                                              "resolved" if child in catalog else "missing-source"})
+                children.append((child, part_name, child_slot, source))
+            stack.extend(reversed(children))
+
+    visit_many([(main_part_name, None, "$main", "root")])
+    # BeamNG configurations can contain valid optional slots that are not
+    # reachable from a compact local main-part corpus. Preserve the converter's
+    # historical behavior by admitting those explicit bodies as graph roots.
+    for slot_type in sorted(overrides):
+        if slot_type not in admitted_slots:
+            visit_many([(overrides[slot_type], None, slot_type, "orphan-override")])
+    return {"mainPartName": main_part_name, "parts": selected,
+            "slotClosure": closure, "missing": missing}
+
+
+def build_selected_part_index(candidate_id: str, configuration_path: str | Path,
+                              closure: dict[str, Any], cache: JBeamDocumentCache,
+                              catalog: JBeamPartCatalog | None = None) -> dict[str, Any]:
+    """Create the digestable, source-bound body payload consumed by lowering."""
+    configuration = cache.receipt(configuration_path)
+    configuration_body = cache.load(configuration_path)
+    parts = closure["parts"]
+    source_paths = sorted({part["_sourcePath"] for part in parts})
+    sources = [cache.receipt(path) for path in source_paths]
+    configuration_info_path = Path(configuration_path).with_name(f"info_{Path(configuration_path).stem}.json")
+    configuration_info = None
+    if configuration_info_path.is_file():
+        cache.load(configuration_info_path)
+        configuration_info = cache.receipt(configuration_info_path)
+    return {
+        "schemaVersion": SELECTED_PART_INDEX_SCHEMA,
+        "candidateId": candidate_id,
+        "configuration": configuration,
+        "configurationInfo": configuration_info,
+        "configurationSha256": configuration["sha256"],
+        "configurationModel": configuration_body.get("model"),
+        "configurationMainPartName": configuration_body.get("mainPartName"),
+        "configurationParts": configuration_body.get("parts", {}),
+        "mainPartName": closure.get("mainPartName"),
+        "selectedBodies": [part["name"] for part in parts],
+        "slotClosure": closure.get("slotClosure", []),
+        "missing": closure.get("missing", []),
+        "sources": sources,
+        "parts": [{"name": part["name"], "slotType": part.get("slotType"),
+                   "source": part["source"], "sourceRoot": part["sourceRoot"],
+                   "body": catalog.body(part["name"]) if catalog is not None else part["body"]}
+                  for part in parts],
+    }
+
+
+_SEMANTIC_PATTERNS = {
+    "slots": re.compile(r'"slots2?"|slottype', re.I),
+    "drivetrain": re.compile(r'powertrain|combustionengine|electricmotor|gearbox|transmission|differential|clutch', re.I),
+    "lights": re.compile(r'electrics|headlight|taillight|brakelight|lightbar|signal_(?:left|right)|foglight', re.I),
+    "panels": re.compile(r'door|hood|bonnet|trunk|boot|tailgate|hinge|latch', re.I),
+    "detachable": re.compile(r'breakgroup|breaktriggerbeam|deformgroup', re.I),
+    "audio": re.compile(r'soundconfig|samplename|enginesound|exhaustsound', re.I),
+}
+
+
+def selected_part_summary(index: dict[str, Any], receipt: dict[str, Any]) -> dict[str, Any]:
+    """Return only the compact manifest evidence needed outside the lowerer."""
+    evidence = {name: [] for name in _SEMANTIC_PATTERNS}
+    for part in index.get("parts", []):
+        label = f"{part.get('sourceRoot')}:{part.get('source')}"
+        text = json.dumps(part.get("body", {}), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+        for name, pattern in _SEMANTIC_PATTERNS.items():
+            if pattern.search(text):
+                evidence[name].append(label)
+    return {
+        "schemaVersion": index.get("schemaVersion"),
+        "receipt": {**receipt, "sourceCount": len(index.get("sources", [])),
+                    "partCount": len(index.get("parts", []))},
+        "configuration": index.get("configuration"),
+        "configurationInfo": index.get("configurationInfo"),
+        "selectedBodies": index.get("selectedBodies", []),
+        "explicitOverrides": len([value for value in index.get("configurationParts", {}).values() if value]),
+        "slotClosure": index.get("slotClosure", []),
+        "missing": index.get("missing", []),
+        "sources": index.get("sources", []),
+        "semanticEvidence": {name: sorted(set(rows)) for name, rows in evidence.items()},
+    }
+
+
+def write_bound_selected_part_index(index: dict[str, Any], output: str | Path,
+                                    bridge_plan_key: str, source_sha256: str,
+                                    common_closure_sha256: str | None) -> dict[str, Any]:
+    """Write the one final canonical, Bridge-identity-bound selected index."""
+    index["identity"] = {
+        "bridgePlanKey": bridge_plan_key,
+        "sourceSha256": source_sha256,
+        "commonDependencyClosureSha256": common_closure_sha256,
+    }
+    target = Path(output)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    digest = hashlib.sha256()
+    size = 0
+    encoder = json.JSONEncoder(sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", newline="",
+                                         dir=target.parent, prefix=f".{target.name}.",
+                                         suffix=".tmp", delete=False) as handle:
+            temporary_path = Path(handle.name)
+            for chunk in encoder.iterencode(index):
+                encoded = chunk.encode("utf-8")
+                if size + len(encoded) > MAX_SELECTED_PART_INDEX_BYTES:
+                    raise ValueError(
+                        f"selected-part index exceeds {MAX_SELECTED_PART_INDEX_BYTES} bytes")
+                handle.write(chunk)
+                digest.update(encoded)
+                size += len(encoded)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary_path, target)
+        temporary_path = None
+    finally:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+    return {"sha256": digest.hexdigest(), "sizeBytes": size}