python-cad-tools 0.1.0rc1__py3-none-any.whl

python_cad_tools/manifests.py

@@ -0,0 +1,338 @@
+"""Schema-versioned manifest construction and validation."""
+
+from __future__ import annotations
+
+import json
+import platform
+import re
+from dataclasses import asdict
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .determinism import normalized_epoch_iso, semantic_hash, write_json
+from .exceptions import ArtifactIntegrityError
+from .geometry import bounds
+
+SCHEMAS: dict[str, tuple[int, frozenset[str]]] = {
+    "urn:python-cad-tools:schema:design-manifest:1": (
+        1,
+        frozenset({"model_id", "model_name", "artifact_stem", "coordinate_system", "metadata", "elements", "semantic_hash"}),
+    ),
+    "urn:python-cad-tools:schema:build-manifest:1": (
+        1,
+        frozenset(
+            {
+                "producer",
+                "project",
+                "source_inputs",
+                "source_set_hash",
+                "config_schema_version",
+                "selected_formats",
+                "annotation_import",
+                "annotation_provider_id",
+                "emitted_schemas",
+                "artifacts",
+                "design_semantic_hash",
+                "artifact_set_hash",
+                "stable_artifact_set_hash",
+                "validation",
+            }
+        ),
+    ),
+    "urn:python-cad-tools:schema:run-metadata:1": (
+        1,
+        frozenset({"started_at", "normalized_epoch", "host", "platform", "python", "process_id"}),
+    ),
+    "urn:python-cad-tools:schema:glb-manifest:1": (
+        1,
+        frozenset({"coordinate_transform", "elements", "triangle_counts", "bounds_cad_mm", "bounds_y_up_mm", "file_size"}),
+    ),
+    "urn:python-cad-tools:schema:step-validation:1": (
+        1,
+        frozenset({"valid", "schema", "requested_schema", "schema_note", "solid_count", "bounds_mm"}),
+    ),
+    "urn:python-cad-tools:schema:ifc-validation:1": (
+        1,
+        frozenset({"schema", "valid", "fatal_count", "issue_count", "issues", "bounds_mm", "element_global_ids"}),
+    ),
+    "urn:python-cad-tools:schema:quantities:1": (1, frozenset({"records"})),
+    "urn:python-cad-tools:schema:drawing-annotations:1": (
+        1,
+        frozenset({"provider_id", "annotations", "sheets"}),
+    ),
+}
+_SNAKE_CASE = re.compile(r"[a-z][a-z0-9]*(?:_[a-z0-9]+)*\Z")
+_DRAWING_ID = re.compile(r"[A-Za-z0-9._-]+\Z", re.ASCII)
+
+
+def design_manifest(model: Any) -> dict[str, Any]:
+    elements = []
+    for element in model.walk():
+        elements.append(
+            {
+                "id": element.id,
+                "name": element.name,
+                "category": element.category,
+                "geometry_kind": element.geometry_kind,
+                "physical": element.physical,
+                "bounds_mm": [round(value, 6) for value in bounds(element.geometry)],
+                "placement": {
+                    "translation_mm": element.placement.translation_mm,
+                    "rotation_deg_xyz": element.placement.rotation_deg_xyz,
+                },
+                "dimensions": {
+                    "length_mm": element.dimensions.length_mm,
+                    "width_mm": element.dimensions.width_mm,
+                    "height_mm": element.dimensions.height_mm,
+                    "radius_mm": element.dimensions.radius_mm,
+                    "extras": element.dimensions.extras,
+                },
+                "material_id": element.material.id if element.material else None,
+                "color_rgb": element.color_rgb,
+                "ifc_class": element.ifc_mapping.ifc_class,
+                "ifc_exclusion": element.ifc_mapping.exclude_reason,
+                "storey": element.storey,
+                "tags": sorted(element.tags),
+                "parent_id": element.parent_id,
+                "source_module": element.source_module,
+                "export_formats": sorted(element.export_formats),
+            }
+        )
+    value: dict[str, Any] = {
+        "schema_id": "urn:python-cad-tools:schema:design-manifest:1",
+        "schema_version": 1,
+        "model_id": model.id,
+        "model_name": model.name,
+        "artifact_stem": model.artifact_stem,
+        "coordinate_system": model.coordinate_system,
+        "metadata": model.metadata,
+        "elements": elements,
+    }
+    value["semantic_hash"] = semantic_hash(value)
+    return value
+
+
+def write_preinventory_manifests(
+    model: Any,
+    staging: Path,
+    selected_formats: tuple[str, ...],
+) -> tuple[Path, Path, dict[str, Any]]:
+    target = staging / "manifests"
+    design = design_manifest(model)
+    design_path = write_json(target / "design-manifest.json", design)
+    run_path = write_json(
+        target / "run-metadata.json",
+        {
+            "schema_id": "urn:python-cad-tools:schema:run-metadata:1",
+            "schema_version": 1,
+            "started_at": datetime.now(UTC).isoformat(),
+            "normalized_epoch": normalized_epoch_iso(),
+            "host": platform.node(),
+            "platform": platform.platform(),
+            "python": platform.python_version(),
+            "process_id": __import__("os").getpid(),
+            "selected_formats": list(selected_formats),
+        },
+    )
+    return design_path, run_path, design
+
+
+def build_manifest_document(
+    *,
+    project_name: str,
+    source_revision: str | None,
+    source_dirty: bool,
+    source_inputs: list[dict[str, Any]],
+    source_set_hash: str,
+    config_schema_version: int,
+    selected_formats: tuple[str, ...],
+    annotation_import: str | None,
+    annotation_provider_id: str | None,
+    artifacts: tuple[Any, ...],
+    design_semantic_hash: str,
+    artifact_set_hash: str,
+    stable_artifact_set_hash: str,
+    issues: tuple[Any, ...],
+) -> dict[str, Any]:
+    emitted_schemas = {
+        record.path: {"schema_id": record.schema_id, "schema_version": record.schema_version}
+        for record in artifacts
+        if record.schema_id is not None
+    }
+    return {
+        "schema_id": "urn:python-cad-tools:schema:build-manifest:1",
+        "schema_version": 1,
+        "producer": {"distribution": "python-cad-tools", "version": __version__},
+        "project": {"repository": project_name, "revision": source_revision, "dirty": source_dirty},
+        "source_inputs": source_inputs,
+        "source_set_hash": source_set_hash,
+        "config_schema_version": config_schema_version,
+        "selected_formats": list(selected_formats),
+        "annotation_import": annotation_import,
+        "annotation_provider_id": annotation_provider_id,
+        "emitted_schemas": emitted_schemas,
+        "artifacts": [asdict(record) for record in artifacts],
+        "design_semantic_hash": design_semantic_hash,
+        "artifact_set_hash": artifact_set_hash,
+        "stable_artifact_set_hash": stable_artifact_set_hash,
+        "validation": {
+            "status": "passed",
+            "warnings": [asdict(issue) for issue in issues if issue.severity == "warning"],
+        },
+    }
+
+
+def load_json_document(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"), object_pairs_hook=_unique_object)
+    except (OSError, UnicodeError, json.JSONDecodeError, ArtifactIntegrityError) as error:
+        if isinstance(error, ArtifactIntegrityError):
+            raise
+        raise ArtifactIntegrityError(f"Unable to parse JSON document {path}: {error}") from error
+    if not isinstance(value, dict):
+        raise ArtifactIntegrityError(f"Package JSON document must contain an object: {path}")
+    return value
+
+
+def validate_json_document(path: Path) -> dict[str, Any]:
+    value = load_json_document(path)
+    schema_id = value.get("schema_id")
+    schema_version = value.get("schema_version")
+    if not isinstance(schema_id, str) or schema_id not in SCHEMAS:
+        raise ArtifactIntegrityError(f"Unsupported or missing schema_id in {path}")
+    expected_version, required = SCHEMAS[schema_id]
+    if type(schema_version) is not int or schema_version != expected_version:
+        raise ArtifactIntegrityError(f"Unsupported schema_version in {path}: {schema_version!r}")
+    missing = sorted(required - set(value))
+    if missing:
+        raise ArtifactIntegrityError(f"Schema document {path} is missing: {', '.join(missing)}")
+    _validate_package_keys(value, path)
+    if schema_id == "urn:python-cad-tools:schema:drawing-annotations:1":
+        _validate_drawing_annotation_document(value, path)
+    return value
+
+
+def stable_build_manifest_projection(document: dict[str, Any]) -> dict[str, Any]:
+    projected = dict(document)
+    projected.pop("artifact_set_hash", None)
+    projected["artifacts"] = [record for record in document["artifacts"] if not record["volatile"]]
+    return projected
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    value: dict[str, Any] = {}
+    for key, item in pairs:
+        if key in value:
+            raise ArtifactIntegrityError(f"Duplicate JSON object key: {key}")
+        value[key] = item
+    return value
+
+
+def _validate_package_keys(value: Any, path: Path, *, exempt: bool = False) -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not exempt and not _SNAKE_CASE.fullmatch(key):
+                raise ArtifactIntegrityError(f"Non-snake_case package field {key!r} in {path}")
+            _validate_package_keys(
+                item,
+                path,
+                exempt=exempt
+                or key in {"metadata", "extras", "emitted_schemas", "triangle_counts", "element_global_ids"},
+            )
+    elif isinstance(value, list):
+        for item in value:
+            _validate_package_keys(item, path, exempt=exempt)
+
+
+def _validate_drawing_annotation_document(value: dict[str, Any], path: Path) -> None:
+    provider_id = value.get("provider_id")
+    annotations = value.get("annotations")
+    sheets = value.get("sheets")
+    if provider_id is not None and (not isinstance(provider_id, str) or _DRAWING_ID.fullmatch(provider_id) is None):
+        raise ArtifactIntegrityError(f"Invalid drawing annotation provider_id in {path}")
+    if not isinstance(annotations, list) or not isinstance(sheets, list):
+        raise ArtifactIntegrityError(f"Invalid drawing annotation arrays in {path}")
+    annotation_fields = {
+        "id",
+        "parent_id",
+        "sheet_id",
+        "primitive_type",
+        "role",
+        "content",
+        "child_ids",
+        "rendered_entity",
+        "renderer_presence",
+    }
+    ids: list[str] = []
+    for record in annotations:
+        if not isinstance(record, dict) or set(record) != annotation_fields:
+            raise ArtifactIntegrityError(f"Invalid drawing annotation record in {path}")
+        annotation_id = record.get("id")
+        presence = record.get("renderer_presence")
+        if (
+            not isinstance(annotation_id, str)
+            or _DRAWING_ID.fullmatch(annotation_id) is None
+            or not isinstance(record.get("sheet_id"), str)
+            or not isinstance(record.get("primitive_type"), str)
+            or not isinstance(record.get("role"), str)
+            or not isinstance(record.get("content"), dict)
+            or not isinstance(record.get("child_ids"), list)
+            or not all(isinstance(child, str) for child in record["child_ids"])
+            or type(record.get("rendered_entity")) is not bool
+            or presence != {"svg": True, "dxf": True, "pdf": True}
+        ):
+            raise ArtifactIntegrityError(f"Invalid drawing annotation semantics in {path}")
+        parent_id = record.get("parent_id")
+        if parent_id is not None and (
+            not isinstance(parent_id, str) or _DRAWING_ID.fullmatch(parent_id) is None
+        ):
+            raise ArtifactIntegrityError(f"Invalid drawing annotation parent in {path}")
+        ids.append(annotation_id)
+    if ids != sorted(ids) or len(ids) != len(set(ids)):
+        raise ArtifactIntegrityError(f"Drawing annotation IDs must be unique and sorted in {path}")
+    if provider_id is None and annotations:
+        raise ArtifactIntegrityError(f"Drawing annotations require a provider_id in {path}")
+    known = set(ids)
+    for record in annotations:
+        if record["parent_id"] is not None and record["parent_id"] not in known:
+            raise ArtifactIntegrityError(f"Unknown drawing annotation parent in {path}")
+        if any(child not in known for child in record["child_ids"]):
+            raise ArtifactIntegrityError(f"Unknown drawing annotation child in {path}")
+    sheet_fields = {
+        "sheet_id",
+        "view_id",
+        "page_number",
+        "viewport_bounds_mm",
+        "annotation_ids",
+        "pdf_text",
+    }
+    sheet_ids: list[str] = []
+    for page, sheet in enumerate(sheets, start=1):
+        if not isinstance(sheet, dict) or set(sheet) != sheet_fields:
+            raise ArtifactIntegrityError(f"Invalid drawing sheet record in {path}")
+        annotation_ids = sheet.get("annotation_ids")
+        viewport = sheet.get("viewport_bounds_mm")
+        pdf_text = sheet.get("pdf_text")
+        if (
+            not isinstance(sheet.get("sheet_id"), str)
+            or sheet.get("view_id") not in {"plan", "front", "side", "section"}
+            or sheet.get("page_number") != page
+            or not isinstance(viewport, list)
+            or len(viewport) != 4
+            or not all(isinstance(item, (int, float)) for item in viewport)
+            or viewport[0] >= viewport[2]
+            or viewport[1] >= viewport[3]
+            or not isinstance(annotation_ids, list)
+            or annotation_ids != sorted(annotation_ids)
+            or not all(isinstance(item, str) and item in known for item in annotation_ids)
+            or not isinstance(pdf_text, list)
+            or not all(isinstance(item, str) for item in pdf_text)
+        ):
+            raise ArtifactIntegrityError(f"Invalid drawing sheet mapping in {path}")
+        sheet_ids.append(sheet["sheet_id"])
+    if len(sheet_ids) != len(set(sheet_ids)):
+        raise ArtifactIntegrityError(f"Duplicate drawing sheet record in {path}")
+    if any(record["sheet_id"] not in sheet_ids for record in annotations):
+        raise ArtifactIntegrityError(f"Drawing annotation references an unknown sheet in {path}")

python_cad_tools/project_config.py

@@ -0,0 +1,174 @@
+"""Strict parser for the versioned ``[tool.python-cad]`` project contract."""
+
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, cast
+
+from ._project_state import authoritative_path
+from .exceptions import ProjectConfigError, UnsafePathError
+
+type FormatName = Literal["step", "ifc", "glb", "drawings", "quantities"]
+FORMAT_ORDER: tuple[FormatName, ...] = ("step", "ifc", "glb", "drawings", "quantities")
+_ALLOWED_KEYS = {
+    "schema-version",
+    "config",
+    "model",
+    "drawing-annotations",
+    "source-inputs",
+    "output-directory",
+    "default-formats",
+}
+_MODULE = re.compile(r"[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*\Z", re.ASCII)
+_CALLABLE = re.compile(r"([A-Za-z_]\w*(?:\.[A-Za-z_]\w)*):([A-Za-z_]\w*)\Z", re.ASCII)
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectConfig:
+    schema_version: Literal[1]
+    config_target: str
+    model_target: str
+    drawing_annotations_target: str | None
+    source_inputs: tuple[str, ...]
+    output_directory: str
+    default_formats: tuple[FormatName, ...]
+
+    @property
+    def declared_sources(self) -> frozenset[str]:
+        return frozenset(self.source_inputs)
+
+
+def resolve_project_root(project_root: Path | None = None) -> Path:
+    raw = project_root
+    if raw is None:
+        configured = os.environ.get("PYTHON_CAD_PROJECT_ROOT")
+        raw = Path(configured) if configured else Path.cwd()
+    root = raw.expanduser().resolve()
+    if not root.is_dir():
+        raise ProjectConfigError(f"Project root is not a directory: {root}")
+    return root
+
+
+def load_project_config(project_root: Path) -> ProjectConfig:
+    root = resolve_project_root(project_root)
+    pyproject = root / "pyproject.toml"
+    if pyproject.is_symlink() or not pyproject.is_file():
+        raise ProjectConfigError(f"Project configuration is missing or not a regular file: {pyproject}")
+    try:
+        document = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError) as error:
+        raise ProjectConfigError(f"Unable to parse {pyproject}: {error}") from error
+    table = _python_cad_table(document)
+    unknown = sorted(set(table) - _ALLOWED_KEYS)
+    if unknown:
+        raise ProjectConfigError(f"Unknown [tool.python-cad] key(s): {', '.join(unknown)}")
+
+    schema_version = table.get("schema-version")
+    if type(schema_version) is not int or schema_version != 1:
+        raise ProjectConfigError(f"Unsupported [tool.python-cad] schema-version: {schema_version!r}; expected 1")
+    config_target = _module_target(table.get("config", "config"), "config")
+    model_target = _callable_target(table.get("model", "model:build_model"), "model")
+    drawing_value = table.get("drawing-annotations")
+    drawing_target = None if drawing_value is None else _callable_target(drawing_value, "drawing-annotations")
+    sources = _source_inputs(table.get("source-inputs"), root)
+    output = _output_directory(table.get("output-directory", "generated"), root)
+    formats = _formats(table.get("default-formats", list(FORMAT_ORDER)))
+    return ProjectConfig(
+        schema_version=1,
+        config_target=config_target,
+        model_target=model_target,
+        drawing_annotations_target=drawing_target,
+        source_inputs=sources,
+        output_directory=output,
+        default_formats=formats,
+    )
+
+
+def split_callable_target(target: str) -> tuple[str, str]:
+    match = _CALLABLE.fullmatch(target)
+    if match is None:
+        raise ProjectConfigError(f"Invalid callable target: {target!r}")
+    return match.group(1), match.group(2)
+
+
+def output_path(project_root: Path, config: ProjectConfig) -> Path:
+    return project_root.joinpath(*Path(config.output_directory).parts)
+
+
+def _python_cad_table(document: dict[str, Any]) -> dict[str, Any]:
+    tool = document.get("tool")
+    if not isinstance(tool, dict) or "python-cad" not in tool:
+        raise ProjectConfigError("Missing required [tool.python-cad] table")
+    table = tool["python-cad"]
+    if not isinstance(table, dict):
+        raise ProjectConfigError("[tool.python-cad] must be a TOML table")
+    return cast(dict[str, Any], table)
+
+
+def _module_target(value: Any, key: str) -> str:
+    if not isinstance(value, str) or _MODULE.fullmatch(value) is None:
+        raise ProjectConfigError(f"[tool.python-cad].{key} must be a dotted Python module name")
+    return value
+
+
+def _callable_target(value: Any, key: str) -> str:
+    if not isinstance(value, str) or _CALLABLE.fullmatch(value) is None:
+        raise ProjectConfigError(f"[tool.python-cad].{key} must have the form dotted.module:callable")
+    return value
+
+
+def _source_inputs(value: Any, root: Path) -> tuple[str, ...]:
+    if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value):
+        raise ProjectConfigError("[tool.python-cad].source-inputs must be a nonempty array of strings")
+    normalized: list[str] = []
+    for item in cast(list[str], value):
+        _, relative = authoritative_path(root, item)
+        normalized.append(relative)
+    if len(normalized) != len(set(normalized)):
+        raise ProjectConfigError("[tool.python-cad].source-inputs contains a duplicate path")
+    if "pyproject.toml" not in normalized:
+        raise ProjectConfigError("[tool.python-cad].source-inputs must include pyproject.toml")
+    return tuple(normalized)
+
+
+def _output_directory(value: Any, root: Path) -> str:
+    if (
+        not isinstance(value, str)
+        or not value
+        or "\\" in value
+        or "\x00" in value
+        or ":" in value
+        or any(part in {"", ".", ".."} for part in value.split("/"))
+    ):
+        raise UnsafePathError("[tool.python-cad].output-directory must be a safe project-relative path")
+    path = Path(*value.split("/"))
+    if path.is_absolute():
+        raise UnsafePathError(f"Unsafe output-directory: {value!r}")
+    current = root
+    for part in path.parts:
+        current /= part
+        if current.is_symlink():
+            raise UnsafePathError(f"output-directory traverses a symlink: {value!r}")
+    if not current.resolve(strict=False).is_relative_to(root):
+        raise UnsafePathError(f"output-directory escapes the project root: {value!r}")
+    return path.as_posix()
+
+
+def _formats(value: Any) -> tuple[FormatName, ...]:
+    if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value):
+        raise ProjectConfigError("[tool.python-cad].default-formats must be a nonempty array of strings")
+    raw = cast(list[str], value)
+    if len(raw) != len(set(raw)):
+        raise ProjectConfigError("[tool.python-cad].default-formats contains a duplicate format")
+    unknown = sorted(set(raw) - set(FORMAT_ORDER))
+    if unknown:
+        raise ProjectConfigError(f"Unsupported format(s): {', '.join(unknown)}")
+    selected = set(raw)
+    return tuple(item for item in FORMAT_ORDER if item in selected)
+
+
+__all__: list[str] = []

python_cad_tools/py.typed

@@ -0,0 +1 @@
+

python_cad_tools/runtime_sync.py

@@ -0,0 +1,126 @@
+"""Synchronize a transitional project environment with its legacy runtime lock."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from collections.abc import Callable
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+PIN_PATTERN = re.compile(r"^([A-Za-z0-9_.-]+)==([^\s;]+)$")
+LEGACY_OCP_DISTRIBUTIONS = ("cadquery-ocp", "cadquery-vtk")
+
+
+def locked_versions(lock_path: Path) -> dict[str, str]:
+    pins: dict[str, str] = {}
+    for raw_line in lock_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        match = PIN_PATTERN.fullmatch(line)
+        if not match:
+            raise RuntimeError(f"Runtime lock entry is not an exact package pin: {line}")
+        pins[match.group(1)] = match.group(2)
+    if not pins:
+        raise RuntimeError(f"Runtime lock contains no package pins: {lock_path}")
+    return pins
+
+
+def version_mismatches(
+    pins: dict[str, str],
+    *,
+    get_version: Callable[[str], str] | None = None,
+) -> list[str]:
+    resolve_version = get_version or version
+    mismatches: list[str] = []
+    for name, expected in pins.items():
+        try:
+            installed = resolve_version(name)
+        except PackageNotFoundError:
+            mismatches.append(f"{name}: missing (requires {expected})")
+        else:
+            if installed != expected:
+                mismatches.append(f"{name}: {installed} (requires {expected})")
+    return mismatches
+
+
+def installed_legacy_ocp(
+    *,
+    get_version: Callable[[str], str] | None = None,
+) -> list[str]:
+    resolve_version = get_version or version
+    installed: list[str] = []
+    for name in LEGACY_OCP_DISTRIBUTIONS:
+        try:
+            resolve_version(name)
+        except PackageNotFoundError:
+            continue
+        installed.append(name)
+    return installed
+
+
+def in_virtual_environment() -> bool:
+    return sys.prefix != sys.base_prefix
+
+
+def synchronize(lock_path: Path) -> bool:
+    """Install the lock when pinned versions or package consistency have drifted."""
+    if not lock_path.is_file():
+        raise RuntimeError(f"Managed runtime lock is missing: {lock_path}")
+    pins = locked_versions(lock_path)
+    mismatches = version_mismatches(pins)
+    check = subprocess.run(
+        [sys.executable, "-m", "pip", "check"],
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if not mismatches and check.returncode == 0:
+        return False
+    if not in_virtual_environment():
+        details = "; ".join(mismatches) or (check.stdout + check.stderr).strip()
+        raise RuntimeError(
+            "Runtime dependencies need synchronization, but the selected Python is not "
+            f"inside a virtual environment ({details}). Create .venv and install {lock_path}."
+        )
+
+    print("Synchronizing the project virtual environment with the managed runtime lock...")
+    legacy = installed_legacy_ocp() if "cadquery-ocp-novtk" in pins else []
+    if legacy:
+        subprocess.run(
+            [sys.executable, "-m", "pip", "uninstall", "-y", *legacy],
+            check=True,
+        )
+    subprocess.run(
+        [sys.executable, "-m", "pip", "install", "--upgrade", "-r", str(lock_path)],
+        check=True,
+    )
+    subprocess.run([sys.executable, "-m", "pip", "check"], check=True)
+    remaining = version_mismatches(pins)
+    if remaining:
+        raise RuntimeError("Runtime synchronization did not satisfy the lock: " + "; ".join(remaining))
+    return True
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("lock_path", type=Path, help="Managed requirements lock to enforce")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    changed = synchronize(args.lock_path.expanduser().resolve())
+    print("Runtime dependencies synchronized." if changed else "Runtime dependencies already match the managed lock.")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as error:
+        print(f"Runtime dependency synchronization failed: {error}", file=sys.stderr)
+        raise SystemExit(1) from error

python_cad_tools/schemas/build-manifest-1.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"urn:python-cad-tools:schema:build-manifest:1","type":"object","required":["schema_id","schema_version","producer","project","source_inputs","source_set_hash","selected_formats","artifacts","design_semantic_hash","artifact_set_hash","stable_artifact_set_hash"],"properties":{"schema_id":{"const":"urn:python-cad-tools:schema:build-manifest:1"},"schema_version":{"const":1}}}

python_cad_tools/schemas/design-manifest-1.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"urn:python-cad-tools:schema:design-manifest:1","type":"object","required":["schema_id","schema_version","model_id","model_name","artifact_stem","elements","semantic_hash"],"properties":{"schema_id":{"const":"urn:python-cad-tools:schema:design-manifest:1"},"schema_version":{"const":1}}}