cadgen 0.4.1__tar.gz

cadgen-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thompson Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cadgen-0.4.1/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: cadgen
+Version: 0.4.1
+Summary: STEP-first CAD artifact generation runtime: build123d STEP/GLB/topology generation, validation, and inspection for CAD agent skills.
+Author: earthtojake
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/earthtojake/text-to-cad
+Project-URL: Repository, https://github.com/earthtojake/text-to-cad
+Project-URL: Issues, https://github.com/earthtojake/text-to-cad/issues
+Keywords: cad,step,glb,build123d,parametric,agent-skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: build123d
+Requires-Dist: cadquery-ocp
+Requires-Dist: ezdxf
+Requires-Dist: shapely
+Dynamic: license-file
+
+# cadgen
+
+STEP-first CAD artifact generation runtime for CAD agent skills, built on
+[build123d](https://github.com/gumyr/build123d) and OCCT.
+
+The package boundary is intentionally narrow: it owns artifact generation,
+validation, selector/topology extraction, mesh settings, source hashing, and the
+`cadgen-step-artifact` CLI. It also includes small generated-script helpers such
+as `cadgen.assembly.AssemblyHelper`, which wraps native build123d labels, joints,
+and compounds without owning skill-specific UX. Prompts, viewer UI, and snapshot
+job orchestration stay in their owning skills.
+
+`cadgen` is developed in
+[earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) and was
+previously named `cadpy` inside that repository.
+
+## Public API
+
+The supported import surface is the root `cadgen` exports plus the top-level
+`cadgen.*` modules:
+
+- Generator-script helpers: root exports (`AssemblyHelper`, `MateRelation`,
+  `MateTarget`, `label_text`, `label_shape`, `target`,
+  `ensure_step_glb_artifact`, `validate_step_glb_artifact`), `cadgen.assembly`,
+  and `cadgen.step_scene` (`import_step`, `load_step_scene`, `located_shape`,
+  `occurrence_selector_id`, `scene_occurrence_shape`).
+- Generator-script helpers (2D): `cadgen.sources` (`load_source_module`) and
+  `cadgen.flatten` (planar-face projection/unfold, contour emission, kerf
+  offsetting) for `.dxf.py` drawing generators.
+- Skill CLI surface: `cadgen.generation` (`generate_step_targets`,
+  `generate_dxf_targets`, `targets_include_output_pairs`), `cadgen.catalog`,
+  `cadgen.metadata`, `cadgen.analysis`, `cadgen.lookup`, `cadgen.cad_ref_syntax`,
+  `cadgen.selector_types`, `cadgen.reporting`, `cadgen.cli_logging`,
+  `cadgen.render`, `cadgen.step_artifacts`, `cadgen.step_targets`,
+  `cadgen.step_export`, `cadgen.drawing_checks` (DXF drawing validation), and
+  `cadgen.drawing_render` (DXF render payload + SVG snapshots).
+- Process entry points: `cadgen-step-artifact`, `python -m cadgen.step_artifact`,
+  `python -m cadgen.step_export_target`, and `python -m cadgen.dxf_artifact`.
+
+Everything under `cadgen._internal` is private implementation (the STEP scene,
+generation, GLB/topology, and export engines live there) with no import
+stability between releases; `cadgen.generation` and `cadgen.step_scene` are
+thin facades over those engines that re-export only the supported names.
+
+## Install
+
+Released versions are published to PyPI by the repository's `Release` workflow;
+the package version always matches the CAD plugin release version:
+
+```bash
+python -m pip install cadgen
+```
+
+Production skill bundles pin the exact release version in their
+`requirements.txt` (for example `cadgen==0.4.0`) and keep a vendored copy of
+this package as an offline fallback:
+
+```bash
+python -m pip install ./scripts/packages/cadgen
+```
+
+## Local Development
+
+Install it editable into the repo CAD runtime when working on the source
+package directly:
+
+```bash
+./.venv/bin/python -m pip install -e packages/cadgen
+```
+
+After that, changes under `packages/cadgen/src/cadgen` are immediately visible to
+local source checkouts that import the package directly.
+
+On `develop`, the CAD skill and root Viewer point at this package through the
+development symlinks `skills/cad/scripts/packages/cadgen` and
+`viewer/packages/cadgen`. Keep those links intact with
+`scripts/dev/setup-symlinks.sh --check`.
+
+## Production Bundling
+
+Build a wheel and install it into each skill's bundled Python environment during
+packaging:
+
+```bash
+./.venv/bin/python -m build packages/cadgen
+python -m pip install packages/cadgen/dist/cadgen-*.whl
+```
+
+The CAD and cad-viewer skills should depend on the package artifact they bundle,
+not on `skills/cad` or the repository root. Production packaging vendors
+installable packages under `skills/cad/scripts/packages/cadgen` and
+`skills/cad-viewer/scripts/viewer/packages/cadgen`; production packaging can also
+set `VIEWER_CAD_PYTHON` to a skill-local Python runtime with this package
+installed. Production skill bundles install `cadgen==<release version>` from
+PyPI first and fall back to the vendored copy when offline.

cadgen-0.4.1/README.md

@@ -0,0 +1,95 @@
+# cadgen
+
+STEP-first CAD artifact generation runtime for CAD agent skills, built on
+[build123d](https://github.com/gumyr/build123d) and OCCT.
+
+The package boundary is intentionally narrow: it owns artifact generation,
+validation, selector/topology extraction, mesh settings, source hashing, and the
+`cadgen-step-artifact` CLI. It also includes small generated-script helpers such
+as `cadgen.assembly.AssemblyHelper`, which wraps native build123d labels, joints,
+and compounds without owning skill-specific UX. Prompts, viewer UI, and snapshot
+job orchestration stay in their owning skills.
+
+`cadgen` is developed in
+[earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) and was
+previously named `cadpy` inside that repository.
+
+## Public API
+
+The supported import surface is the root `cadgen` exports plus the top-level
+`cadgen.*` modules:
+
+- Generator-script helpers: root exports (`AssemblyHelper`, `MateRelation`,
+  `MateTarget`, `label_text`, `label_shape`, `target`,
+  `ensure_step_glb_artifact`, `validate_step_glb_artifact`), `cadgen.assembly`,
+  and `cadgen.step_scene` (`import_step`, `load_step_scene`, `located_shape`,
+  `occurrence_selector_id`, `scene_occurrence_shape`).
+- Generator-script helpers (2D): `cadgen.sources` (`load_source_module`) and
+  `cadgen.flatten` (planar-face projection/unfold, contour emission, kerf
+  offsetting) for `.dxf.py` drawing generators.
+- Skill CLI surface: `cadgen.generation` (`generate_step_targets`,
+  `generate_dxf_targets`, `targets_include_output_pairs`), `cadgen.catalog`,
+  `cadgen.metadata`, `cadgen.analysis`, `cadgen.lookup`, `cadgen.cad_ref_syntax`,
+  `cadgen.selector_types`, `cadgen.reporting`, `cadgen.cli_logging`,
+  `cadgen.render`, `cadgen.step_artifacts`, `cadgen.step_targets`,
+  `cadgen.step_export`, `cadgen.drawing_checks` (DXF drawing validation), and
+  `cadgen.drawing_render` (DXF render payload + SVG snapshots).
+- Process entry points: `cadgen-step-artifact`, `python -m cadgen.step_artifact`,
+  `python -m cadgen.step_export_target`, and `python -m cadgen.dxf_artifact`.
+
+Everything under `cadgen._internal` is private implementation (the STEP scene,
+generation, GLB/topology, and export engines live there) with no import
+stability between releases; `cadgen.generation` and `cadgen.step_scene` are
+thin facades over those engines that re-export only the supported names.
+
+## Install
+
+Released versions are published to PyPI by the repository's `Release` workflow;
+the package version always matches the CAD plugin release version:
+
+```bash
+python -m pip install cadgen
+```
+
+Production skill bundles pin the exact release version in their
+`requirements.txt` (for example `cadgen==0.4.0`) and keep a vendored copy of
+this package as an offline fallback:
+
+```bash
+python -m pip install ./scripts/packages/cadgen
+```
+
+## Local Development
+
+Install it editable into the repo CAD runtime when working on the source
+package directly:
+
+```bash
+./.venv/bin/python -m pip install -e packages/cadgen
+```
+
+After that, changes under `packages/cadgen/src/cadgen` are immediately visible to
+local source checkouts that import the package directly.
+
+On `develop`, the CAD skill and root Viewer point at this package through the
+development symlinks `skills/cad/scripts/packages/cadgen` and
+`viewer/packages/cadgen`. Keep those links intact with
+`scripts/dev/setup-symlinks.sh --check`.
+
+## Production Bundling
+
+Build a wheel and install it into each skill's bundled Python environment during
+packaging:
+
+```bash
+./.venv/bin/python -m build packages/cadgen
+python -m pip install packages/cadgen/dist/cadgen-*.whl
+```
+
+The CAD and cad-viewer skills should depend on the package artifact they bundle,
+not on `skills/cad` or the repository root. Production packaging vendors
+installable packages under `skills/cad/scripts/packages/cadgen` and
+`skills/cad-viewer/scripts/viewer/packages/cadgen`; production packaging can also
+set `VIEWER_CAD_PYTHON` to a skill-local Python runtime with this package
+installed. Production skill bundles install `cadgen==<release version>` from
+PyPI first and fall back to the vendored copy when offline.

cadgen-0.4.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cadgen"
+version = "0.4.1"
+description = "STEP-first CAD artifact generation runtime: build123d STEP/GLB/topology generation, validation, and inspection for CAD agent skills."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "earthtojake" }]
+keywords = ["cad", "step", "glb", "build123d", "parametric", "agent-skills"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Manufacturing",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Multimedia :: Graphics :: 3D Modeling",
+  "Topic :: Scientific/Engineering",
+]
+dependencies = [
+  "build123d",
+  "cadquery-ocp",
+  "ezdxf",
+  "shapely",
+]
+
+[project.urls]
+Homepage = "https://github.com/earthtojake/text-to-cad"
+Repository = "https://github.com/earthtojake/text-to-cad"
+Issues = "https://github.com/earthtojake/text-to-cad/issues"
+
+[project.scripts]
+cadgen-step-artifact = "cadgen.step_artifact:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["cadgen*"]
+
+[tool.setuptools.package-data]
+cadgen = ["py.typed"]
+# The Node builder bridge (cadgen/_internal/node_runtime.py) spawns node with
+# `--import node_resolve_register.mjs`; both .mjs files must ship with the package.
+"cadgen._internal" = ["*.mjs"]

cadgen-0.4.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cadgen-0.4.1/src/cadgen/__init__.py

@@ -0,0 +1,44 @@
+"""Shared CAD artifact generation runtime."""
+
+__all__ = [
+    "AssemblyHelper",
+    "srgb",
+    "MateRelation",
+    "MateTarget",
+    "compound_from_instances",
+    "ensure_step_glb_artifact",
+    "label_text",
+    "label_shape",
+    "target",
+    "validate_step_glb_artifact",
+]
+
+
+def __getattr__(name: str):
+    if name in {"ensure_step_glb_artifact", "validate_step_glb_artifact"}:
+        from cadgen.api import ensure_step_glb_artifact, validate_step_glb_artifact
+
+        return {
+            "ensure_step_glb_artifact": ensure_step_glb_artifact,
+            "validate_step_glb_artifact": validate_step_glb_artifact,
+        }[name]
+    if name in {"AssemblyHelper", "MateRelation", "MateTarget", "label_shape", "label_text", "target"}:
+        from cadgen.assembly import AssemblyHelper, MateRelation, MateTarget, label_shape, label_text, target
+
+        return {
+            "AssemblyHelper": AssemblyHelper,
+            "MateRelation": MateRelation,
+            "MateTarget": MateTarget,
+            "label_text": label_text,
+            "label_shape": label_shape,
+            "target": target,
+        }[name]
+    if name in {"srgb", "srgb_to_linear", "linear_to_srgb"}:
+        from cadgen import color
+
+        return getattr(color, name)
+    if name == "compound_from_instances":
+        from cadgen.instances import compound_from_instances
+
+        return compound_from_instances
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

cadgen-0.4.1/src/cadgen/_internal/__init__.py

@@ -0,0 +1,6 @@
+"""Internal cadgen implementation modules.
+
+Everything under ``cadgen._internal`` is private: no import stability is
+promised between releases. The supported API is the top-level ``cadgen``
+modules and the root ``cadgen`` exports.
+"""

cadgen-0.4.1/src/cadgen/_internal/assembly_spec.py

@@ -0,0 +1,54 @@
+"""Catalog path utilities and identity-transform constants.
+
+Historically this module also parsed Python ``gen_step()`` assembly recipes
+(``instances`` / ``children`` envelopes) into a typed ``AssemblySpec`` tree.
+That contract is gone — ``gen_step()`` is shape-only — and the parser was
+deleted with it. Only the catalog-path helpers and the identity-transform
+constants survive, kept here so the established import paths in
+``step_artifacts``, ``step_targets``, and ``generation`` continue to resolve.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cadgen.catalog import find_source_by_cad_ref
+
+
+STEP_SUFFIXES = (".step", ".stp")
+
+IDENTITY_TRANSFORM: tuple[float, ...] = (
+    1.0, 0.0, 0.0, 0.0,
+    0.0, 1.0, 0.0, 0.0,
+    0.0, 0.0, 1.0, 0.0,
+    0.0, 0.0, 0.0, 1.0,
+)
+
+
+def find_step_path(cad_ref: str) -> Path | None:
+    source = find_source_by_cad_ref(cad_ref)
+    if source is not None and source.kind in {"part", "assembly"}:
+        return source.step_path.resolve() if source.step_path is not None else None
+    return None
+
+
+def resolve_cad_source_path(cad_ref: str) -> tuple[str, Path] | None:
+    source = find_source_by_cad_ref(cad_ref)
+    if source is not None:
+        if source.kind == "assembly":
+            return "assembly", source.source_path
+        if source.kind == "part":
+            step_path = source.step_path
+            return ("part", step_path) if step_path is not None else None
+    return None
+
+
+def multiply_transforms(left: tuple[float, ...], right: tuple[float, ...]) -> tuple[float, ...]:
+    product: list[float] = []
+    for row in range(4):
+        for column in range(4):
+            total = 0.0
+            for offset in range(4):
+                total += left[(row * 4) + offset] * right[(offset * 4) + column]
+            product.append(total)
+    return tuple(product)

cadgen-0.4.1/src/cadgen/_internal/cli_errors.py

@@ -0,0 +1,107 @@
+"""Compact failure reporting for the CAD CLIs.
+
+A generator that raises used to reach the interpreter uncaught, so an ordinary authoring
+mistake printed a 62-line, 4.2 KB traceback whose one useful line -- the exception -- was
+last, under ~50 frames of ``runpy``, the launcher, and cadgen internals. A `gen_step()`
+missing its return printed 43 lines to say ``must return one value``.
+
+What a caller actually needs is the failure and WHERE IN THEIR MODEL it happened. Those
+frames are already identifiable: :func:`is_first_party_source_file` is the same predicate
+the source-closure capture uses to tell model code from the stdlib, site-packages, and the
+running runtime. So the report keeps the model's own frames and drops everything else.
+
+``--verbose`` still prints the full traceback -- when the fault IS in cadgen, the internal
+frames are the point.
+"""
+
+from __future__ import annotations
+
+import sys
+import traceback
+from pathlib import Path
+from typing import TextIO
+
+# Deep recursion in a generator (a parametric model calling itself) can produce hundreds of
+# identical model frames. The innermost few are where the failure is.
+_MAX_FRAMES = 6
+
+
+def _display(filename: str) -> str:
+    """Cwd-relative where that is meaningful, otherwise the tail.
+
+    A runtime frame's absolute path runs through the symlinked skill bundle and is longer
+    than the line it is annotating; the last few components identify the module just as
+    well without burying the message above it.
+    """
+    try:
+        resolved = Path(filename).resolve()
+    except (OSError, ValueError):
+        return filename
+    try:
+        return resolved.relative_to(Path.cwd().resolve()).as_posix()
+    except ValueError:
+        parts = resolved.parts
+        return ("…/" + "/".join(parts[-3:])) if len(parts) > 3 else resolved.as_posix()
+
+
+def _model_frames(exc: BaseException) -> list[traceback.FrameSummary]:
+    """The frames in the caller's own CAD sources, outermost first.
+
+    Everything else -- the launcher, cadgen, build123d/OCP, the stdlib -- is runtime: it is
+    the same in every failure and says nothing about which model broke.
+    """
+    from cadgen._internal.source_hash import is_first_party_source_file
+
+    frames: list[traceback.FrameSummary] = []
+    for frame in traceback.extract_tb(exc.__traceback__):
+        try:
+            path = Path(frame.filename).resolve()
+        except (OSError, ValueError):
+            continue
+        if is_first_party_source_file(path):
+            frames.append(frame)
+    return frames
+
+
+def report_cli_error(
+    exc: BaseException,
+    *,
+    tool: str,
+    verbose: bool = False,
+    stream: TextIO | None = None,
+) -> int:
+    """Print ``exc`` as a CLI failure and return the exit code (always 1).
+
+    Under ``verbose`` this is the raw traceback, unchanged -- a cadgen bug needs its own
+    frames. Otherwise it is the exception plus the model frames that led to it.
+    """
+    out = stream if stream is not None else sys.stderr
+    if verbose:
+        traceback.print_exception(type(exc), exc, exc.__traceback__, file=out)
+        return 1
+
+    def line(text: str) -> None:
+        print(f"[{tool}] {text}", file=out)
+
+    detail = str(exc).strip()
+    line(f"FAILED: {type(exc).__name__}: {detail}" if detail else f"FAILED: {type(exc).__name__}")
+
+    frames = _model_frames(exc)
+    if frames:
+        if len(frames) > _MAX_FRAMES:
+            line(f"  ... {len(frames) - _MAX_FRAMES} earlier frame(s) omitted")
+        for frame in frames[-_MAX_FRAMES:]:
+            line(f"  {_display(frame.filename)}:{frame.lineno} in {frame.name}")
+            if frame.line:
+                line(f"      {frame.line.strip()}")
+    else:
+        # Nothing of the caller's ran -- a validation or resolution error raised before the
+        # generator was reached. Name the frame that raised so it is still diagnosable; the
+        # message itself usually already names the offending file.
+        raised = traceback.extract_tb(exc.__traceback__)
+        if raised:
+            innermost = raised[-1]
+            line(f"  raised in {_display(innermost.filename)}:{innermost.lineno}")
+
+    line("re-run with --verbose for the full traceback")
+    return 1

cadgen-0.4.1/src/cadgen/_internal/cli_locking.py

@@ -0,0 +1,99 @@
+"""The CLI half of artifact coordination: how a command-line producer waits, reports the
+wait, and answers when it decides not to wait at all.
+
+One implementation for every artifact CLI (``step_artifact``, ``dxf_artifact``,
+``implicit_artifact``, and the ``gen``/``export`` paths in ``_internal.generation``),
+because the three things below have to agree across all of them:
+
+* the flag name and its default, since the CAD Viewer passes ``--lock-timeout`` to whichever
+  module a given entry maps to and a module that did not accept it would fail argument
+  parsing rather than build;
+* the wait notice, which is the only thing distinguishing a contended acquire from a hang --
+  cadgen's acquire is blocking by default, so without it a queued build emits nothing on
+  either stream for as long as the peer holds the lock;
+* the shape of the "a peer has it" payload, which the viewer branches on.
+
+Not in :mod:`cadgen.coordination`: that package is the cross-process protocol shared with
+the viewer's long-lived server, and it has no business knowing about argparse or loggers.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Callable
+
+from cadgen.cli_logging import CliLogger, format_elapsed
+
+# Waiting is the CLI default on purpose: an agent that asked for a build wants the build,
+# and giving up would leave it with no artifact and nothing to do about it. The viewer is
+# the caller that must not block, and it passes an explicit timeout.
+WAIT_FOREVER = 0.0
+
+_LOCK_TIMEOUT_HELP = (
+    "Give up after SECONDS if another run holds this model's generation lock, reporting "
+    '{"ok":true,"contended":true} instead of building. 0 (the default) waits for the peer; '
+    "either way the wait itself is reported on stderr."
+)
+
+
+def add_lock_timeout_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--lock-timeout",
+        type=float,
+        default=WAIT_FOREVER,
+        metavar="SECONDS",
+        help=_LOCK_TIMEOUT_HELP,
+    )
+
+
+def deadline_ms(lock_timeout_s: float | None) -> float | None:
+    """``deadline_ms`` for :func:`cadgen.coordination.artifact_build`. None means block."""
+    timeout = float(lock_timeout_s or 0.0)
+    return timeout * 1000.0 if timeout > 0 else None
+
+
+def lock_wait_notice(logger: CliLogger | None, ref: str) -> Callable[[float], None] | None:
+    """A callback that says WHY the process is sitting still, while it still is.
+
+    Repeats on the interval :mod:`cadgen.coordination.lock` applies, so a long wait keeps
+    proving it is alive instead of looking wedged."""
+    if logger is None:
+        return None
+
+    def notice(elapsed_s: float) -> None:
+        logger.info(
+            f"waiting for another run to finish building {ref} "
+            f"({format_elapsed(elapsed_s)} so far)"
+        )
+
+    return notice
+
+
+def contended_payload(
+    *,
+    source_ref: str,
+    cad_ref: str = "",
+    package_dir: Path | str | None = None,
+    **extra: object,
+) -> dict[str, object]:
+    """The answer when a peer holds the lock and this run declined to wait for it.
+
+    ``ok`` is true because nothing went wrong -- the model is being built, just not here --
+    and ``contended`` is what a caller branches on. Deliberately claims no artifact: the
+    peer decides what the package ends up containing.
+    """
+    payload: dict[str, object] = {
+        "ok": True,
+        "contended": True,
+        "skipped": True,
+        "sourceRef": source_ref,
+    }
+    if cad_ref:
+        payload["cadPath"] = cad_ref
+    if package_dir is not None:
+        from cadgen.render import relative_to_cwd
+
+        payload["packagePath"] = relative_to_cwd(Path(package_dir))
+    payload.update({key: value for key, value in extra.items() if value is not None})
+    return payload