gitcad 0.7.7__tar.gz

gitcad-0.7.7/.gitignore

@@ -0,0 +1,38 @@
+# Generated geometry is a build artifact, NOT source (ADR-0004). Never commit it.
+*.brep
+*.step
+*.stp
+*.stl
+*.gltf
+*.glb
+*.iges
+*.igs
+# Drawings are generated from the model too.
+/build-artifacts/
+*.dxf
+# PDFs generated from drawings (keep hand-authored docs elsewhere if needed).
+/out/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

gitcad-0.7.7/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: gitcad
+Version: 0.7.7
+Summary: Agent-first, headless, git-native CAD (metapackage: core + mech + ecad + MCP + viewer + release)
+Project-URL: Homepage, https://gitcad.xyz
+Project-URL: Repository, https://github.com/gitcad-xyz/gitcad
+Project-URL: Issues, https://github.com/gitcad-xyz/gitcad/issues
+Author-email: Dan Willis <danielcwillis@gmail.com>
+License-Expression: Apache-2.0
+Keywords: agent,brep,cad,eda,git,headless,mcp,occt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.10
+Requires-Dist: gitcad-core==0.7.7
+Requires-Dist: gitcad-ecad==0.7.7
+Requires-Dist: gitcad-mech==0.7.7
+Requires-Dist: mcp>=1.0
+Provides-Extra: occt
+Requires-Dist: gitcad-mech[occt]==0.7.7; extra == 'occt'
+Description-Content-Type: text/markdown
+
+# gitcad
+
+**Agent-first, headless, git-native CAD — mechanical and electrical, one substrate.**
+
+gitcad is a boundary-representation CAD system designed to be driven by agents and
+version-controlled like source. Models are byte-canonical text (geometry is a
+build artifact, never committed); identity is construction-lineage based, never
+ordinal; every build produces a reviewable, diffable report.
+
+This metapackage installs the whole system:
+
+| package | domain |
+|---|---|
+| [`gitcad-core`](https://pypi.org/project/gitcad-core/) | canonical text, stable identity, the Part standard, report pipeline |
+| [`gitcad-mech`](https://pypi.org/project/gitcad-mech/) | document model, **exact B-rep kernel**, sketches, drawings, importers |
+| [`gitcad-ecad`](https://pypi.org/project/gitcad-ecad/) | schematic + ERC, board + DRC, fab outputs, KiCad import |
+
+## Install
+
+```bash
+pip install gitcad           # full system: both domains, exact+native kernel, MCP server
+pip install gitcad[occt]     # + OCCT kernel oracle/fallback (cadquery-ocp)
+```
+
+`pip install gitcad` is complete and agent-ready out of the box — mechanical and
+electrical, the exact kernel with its native accelerator, and the `gitcad-mcp`
+Model Context Protocol server. Only OCCT (a heavy optional oracle) is an extra.
+
+The mechanical kernel is **exact**: topological decisions are made in rational
+arithmetic (ℚ), never by a floating-point tolerance — see
+[`forgekernel`](https://pypi.org/project/forgekernel/) and the
+[benchmarks vs OCCT](https://github.com/gitcad-xyz/gitcad/blob/main/bench/RUST-vs-OCCT.md).
+The compiled Rust build of the hot paths installs **by default** on mainstream
+platforms (identical results, only faster); on an architecture with no wheel it is
+skipped and the kernel runs pure-Python — same answers, nothing breaks.
+
+## Console tools
+
+`gitcad-init`, `gitcad-render`, `gitcad-view`, `gitcad-review`, `gitcad-merge`,
+`gitcad-verify`, `gitcad-convert`, `gitcad-explore`, `gitcad-mcp`, `gitcad-lot`.
+
+Apache-2.0 · https://gitcad.xyz · https://github.com/gitcad-xyz/gitcad

gitcad-0.7.7/README.md

@@ -0,0 +1,42 @@
+# gitcad
+
+**Agent-first, headless, git-native CAD — mechanical and electrical, one substrate.**
+
+gitcad is a boundary-representation CAD system designed to be driven by agents and
+version-controlled like source. Models are byte-canonical text (geometry is a
+build artifact, never committed); identity is construction-lineage based, never
+ordinal; every build produces a reviewable, diffable report.
+
+This metapackage installs the whole system:
+
+| package | domain |
+|---|---|
+| [`gitcad-core`](https://pypi.org/project/gitcad-core/) | canonical text, stable identity, the Part standard, report pipeline |
+| [`gitcad-mech`](https://pypi.org/project/gitcad-mech/) | document model, **exact B-rep kernel**, sketches, drawings, importers |
+| [`gitcad-ecad`](https://pypi.org/project/gitcad-ecad/) | schematic + ERC, board + DRC, fab outputs, KiCad import |
+
+## Install
+
+```bash
+pip install gitcad           # full system: both domains, exact+native kernel, MCP server
+pip install gitcad[occt]     # + OCCT kernel oracle/fallback (cadquery-ocp)
+```
+
+`pip install gitcad` is complete and agent-ready out of the box — mechanical and
+electrical, the exact kernel with its native accelerator, and the `gitcad-mcp`
+Model Context Protocol server. Only OCCT (a heavy optional oracle) is an extra.
+
+The mechanical kernel is **exact**: topological decisions are made in rational
+arithmetic (ℚ), never by a floating-point tolerance — see
+[`forgekernel`](https://pypi.org/project/forgekernel/) and the
+[benchmarks vs OCCT](https://github.com/gitcad-xyz/gitcad/blob/main/bench/RUST-vs-OCCT.md).
+The compiled Rust build of the hot paths installs **by default** on mainstream
+platforms (identical results, only faster); on an architecture with no wheel it is
+skipped and the kernel runs pure-Python — same answers, nothing breaks.
+
+## Console tools
+
+`gitcad-init`, `gitcad-render`, `gitcad-view`, `gitcad-review`, `gitcad-merge`,
+`gitcad-verify`, `gitcad-convert`, `gitcad-explore`, `gitcad-mcp`, `gitcad-lot`.
+
+Apache-2.0 · https://gitcad.xyz · https://github.com/gitcad-xyz/gitcad

gitcad-0.7.7/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gitcad"
+version = "0.7.7"
+description = "Agent-first, headless, git-native CAD (metapackage: core + mech + ecad + MCP + viewer + release)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{name = "Dan Willis", email = "danielcwillis@gmail.com"}]
+keywords = ["cad", "brep", "occt", "mcp", "agent", "headless", "git", "eda"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Manufacturing",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Multimedia :: Graphics :: 3D Modeling",
+    "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+]
+# Agent-first: the MCP server ships by default (gitcad-mcp entry point). The
+# compiled kernel (forgekernel_rs) is likewise a default dep of gitcad-mech on
+# mainstream architectures — no extra needed for either.
+dependencies = [
+    "gitcad-core==0.7.7",
+    "gitcad-mech==0.7.7",
+    "gitcad-ecad==0.7.7",
+    "mcp>=1.0",
+]
+
+[project.optional-dependencies]
+# OCCT oracle/fallback kernel.
+occt = ["gitcad-mech[occt]==0.7.7"]
+
+[project.urls]
+Homepage = "https://gitcad.xyz"
+Repository = "https://github.com/gitcad-xyz/gitcad"
+Issues = "https://github.com/gitcad-xyz/gitcad/issues"
+
+[project.scripts]
+gitcad-mcp = "gitcad.mcp.server:main"
+gitcad-view = "gitcad.viewer.server:main"
+gitcad-review = "gitcad.review:main"
+gitcad-merge = "gitcad.merge3:main"
+gitcad-verify = "gitcad.requirements:main"
+gitcad-lot = "gitcad.lots:main"
+gitcad-init = "gitcad.init:main"
+gitcad-render = "gitcad.render:main"
+gitcad-convert = "gitcad.convert:main"
+gitcad-explore = "gitcad.explore:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gitcad"]

gitcad-0.7.7/src/gitcad/bench/corpus.py

@@ -0,0 +1,260 @@
+"""The kernel benchmark corpus — deterministic documents per operator
+class (ADR-0018 W0).
+
+Each entry builds a Document tagged with the operator classes it
+exercises. This corpus is simultaneously: the differential-test input
+(ref vs occt), the benchmark workload (timed per backend), and the
+future acceptance suite for kernel cutover. Torture entries encode the
+configurations that break kernels — tangencies, coincidences, slivers
+— where beating OCCT must become measurable.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from gitcad.document import Document, Feature
+
+
+def plate_with_holes() -> Document:
+    d = Document()
+    base = d.add(Feature(op="box", params={"dx": 60, "dy": 40, "dz": 4}))
+    prev = base
+    for i in range(4):
+        prev = d.add(Feature(op="hole", params={
+            "x": 10 + 13 * i, "y": 20, "top_z": 4, "depth": 4,
+            "diameter": 5}, inputs=[prev]))
+    return d
+
+
+def quadric_boss() -> Document:
+    d = Document()
+    base = d.add(Feature(op="cylinder", params={"radius": 20, "height": 8}))
+    boss = d.add(Feature(op="cone", params={"r1": 10, "r2": 6, "height": 12}))
+    bm = d.add(Feature(op="move", params={"translate": [0, 0, 8]}, inputs=[boss]))
+    u = d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[base, bm]))
+    s = d.add(Feature(op="sphere", params={"radius": 5}))
+    sm = d.add(Feature(op="move", params={"translate": [0, 0, 22]}, inputs=[s]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[u, sm]))
+    return d
+
+
+def revolve_profile() -> Document:
+    d = Document()
+    profile = {"start": [5, 0], "segments": [
+        {"kind": "line", "to": [15, 0]}, {"kind": "line", "to": [15, 4]},
+        {"kind": "line", "to": [8, 8]}, {"kind": "line", "to": [8, 20]},
+        {"kind": "line", "to": [5, 20]}, {"kind": "line", "to": [5, 0]}]}
+    d.add(Feature(op="revolve", params={"profile": profile, "angle_deg": 360.0}))
+    return d
+
+
+def extrude_L() -> Document:
+    d = Document()
+    profile = {"start": [0, 0], "segments": [
+        {"kind": "line", "to": [30, 0]}, {"kind": "line", "to": [30, 8]},
+        {"kind": "line", "to": [8, 8]}, {"kind": "line", "to": [8, 25]},
+        {"kind": "line", "to": [0, 25]}, {"kind": "line", "to": [0, 0]}]}
+    d.add(Feature(op="extrude", params={"profile": profile, "height": 12}))
+    return d
+
+
+def filleted_block() -> Document:
+    d = Document()
+    b = d.add(Feature(op="box", params={"dx": 30, "dy": 20, "dz": 10}))
+    d.add(Feature(op="fillet", params={"radius": 2.5}, inputs=[b]))
+    return d
+
+
+def chamfered_block() -> Document:
+    d = Document()
+    b = d.add(Feature(op="box", params={"dx": 30, "dy": 20, "dz": 10}))
+    d.add(Feature(op="chamfer", params={"distance": 2.0}, inputs=[b]))
+    return d
+
+
+def shelled_box() -> Document:
+    d = Document()
+    b = d.add(Feature(op="box", params={"dx": 40, "dy": 30, "dz": 20}))
+    d.add(Feature(op="shell", params={"faces": [], "thickness": 2.0},
+                  inputs=[b]))
+    return d
+
+
+def shelled_prism() -> Document:
+    # K4.1: closed hollow of a non-box prism — a right trapezoid with a
+    # 3-4-5 hypotenuse (Pythagorean edges → the exact inward inset).
+    # ref = exactly 541/6; OCCT's thick-solid offset agrees in float.
+    d = Document()
+    p = d.add(Feature(op="extrude", params={"profile": {
+        "start": [0, 0], "segments": [
+            {"kind": "line", "to": [8, 0]}, {"kind": "line", "to": [8, 3]},
+            {"kind": "line", "to": [4, 6]}, {"kind": "line", "to": [0, 6]},
+            {"kind": "line", "to": [0, 0]}]}, "height": 5}))
+    d.add(Feature(op="shell", params={"faces": [], "thickness": 0.5},
+                  inputs=[p]))
+    return d
+
+
+def drafted_block() -> Document:
+    d = Document()
+    b = d.add(Feature(op="box", params={"dx": 30, "dy": 30, "dz": 15}))
+    d.add(Feature(op="draft", params={"faces": [], "angle_deg": 3.0},
+                  inputs=[b]))
+    return d
+
+
+def spring() -> Document:
+    d = Document()
+    d.add(Feature(op="spring", params={"radius": 8, "pitch": 4, "turns": 6,
+                                       "wire_diameter": 1.5}))
+    return d
+
+
+def swept_channel() -> Document:
+    d = Document()
+    profile = {"start": [-2, -2], "segments": [
+        {"kind": "line", "to": [2, -2]}, {"kind": "line", "to": [2, 2]},
+        {"kind": "line", "to": [-2, 2]}, {"kind": "line", "to": [-2, -2]}]}
+    d.add(Feature(op="sweep", params={"profile": profile,
+                                      "path": [[0, 0, 0], [0, 0, 20],
+                                               [15, 0, 35], [40, 0, 35]]}))
+    return d
+
+
+def loft_transition() -> Document:
+    d = Document()
+    sq = {"start": [-10, -10], "segments": [
+        {"kind": "line", "to": [10, -10]}, {"kind": "line", "to": [10, 10]},
+        {"kind": "line", "to": [-10, 10]}, {"kind": "line", "to": [-10, -10]}]}
+    sm = {"start": [-4, -4], "segments": [
+        {"kind": "line", "to": [4, -4]}, {"kind": "line", "to": [4, 4]},
+        {"kind": "line", "to": [-4, 4]}, {"kind": "line", "to": [-4, -4]}]}
+    d.add(Feature(op="loft", params={"sections": [
+        {"profile": sq, "z": 0.0}, {"profile": sm, "z": 25.0}]}))
+    return d
+
+
+def sheetmetal_folded() -> Document:
+    from gitcad.sheetmetal import Flange, SheetMetal
+
+    sm = SheetMetal(name="bench-bracket", width=40, height=50, thickness=2,
+                    k_factor=0.44, bend_radius=2,
+                    flanges=[Flange(edge="n", length=20),
+                             Flange(edge="e", length=12, direction="down")])
+    return sm.to_document()
+
+
+# -- torture: the configurations that break kernels ---------------------------
+
+def torture_tangent_cylinders() -> Document:
+    d = Document()
+    a = d.add(Feature(op="cylinder", params={"radius": 10, "height": 10}))
+    b = d.add(Feature(op="cylinder", params={"radius": 10, "height": 10}))
+    bm = d.add(Feature(op="move", params={"translate": [20, 0, 0]}, inputs=[b]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[a, bm]))
+    return d
+
+
+def torture_coincident_faces() -> Document:
+    d = Document()
+    a = d.add(Feature(op="box", params={"dx": 20, "dy": 20, "dz": 10}))
+    b = d.add(Feature(op="box", params={"dx": 20, "dy": 20, "dz": 10}))
+    bm = d.add(Feature(op="move", params={"translate": [20, 0, 0]}, inputs=[b]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[a, bm]))
+    return d
+
+
+def torture_sliver_cut() -> Document:
+    d = Document()
+    a = d.add(Feature(op="box", params={"dx": 30, "dy": 30, "dz": 10}))
+    b = d.add(Feature(op="box", params={"dx": 30, "dy": 30, "dz": 10}))
+    bm = d.add(Feature(op="move", params={"translate": [29.999, 0, 0]},
+                       inputs=[b]))
+    d.add(Feature(op="boolean", params={"kind": "cut"}, inputs=[a, bm]))
+    return d
+
+
+def torture_tangent_sphere_plane() -> Document:
+    d = Document()
+    a = d.add(Feature(op="box", params={"dx": 30, "dy": 30, "dz": 10}))
+    s = d.add(Feature(op="sphere", params={"radius": 5}))
+    sm = d.add(Feature(op="move", params={"translate": [15, 15, 15]},
+                       inputs=[s]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[a, sm]))
+    return d
+
+
+def quadric_sphere_overlap() -> Document:
+    """Two GENUINELY OVERLAPPING spheres unioned — a non-coaxial quadric
+    boolean OCCT builds and ref does EXACTLY in ℚ[π] (cap/lens): r=5
+    spheres 6 apart -> union = 896/3 π. The K2.2 exact case (parallel-
+    cylinder overlap stays transcendental / refused)."""
+    d = Document()
+    a = d.add(Feature(op="sphere", params={"radius": 5}))
+    b = d.add(Feature(op="sphere", params={"radius": 5}))
+    bm = d.add(Feature(op="move", params={"translate": [6, 0, 0]}, inputs=[b]))
+    d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[a, bm]))
+    return d
+
+
+def sweep_rightangle() -> Document:
+    """A square profile swept along a 90-degree-cornered axis-aligned path
+    — all segment lengths RATIONAL, so ref builds it in plain Q (no surd
+    field needed). Exact volume = area * (10+10+10) = 16*30 = 480."""
+    d = Document()
+    profile = {"start": [-2, -2], "segments": [
+        {"kind": "line", "to": [2, -2]}, {"kind": "line", "to": [2, 2]},
+        {"kind": "line", "to": [-2, 2]}, {"kind": "line", "to": [-2, -2]}]}
+    d.add(Feature(op="sweep", params={"profile": profile,
+                                      "path": [[0, 0, 0], [0, 0, 10],
+                                               [10, 0, 10], [10, 0, 20]]}))
+    return d
+
+
+def torture_menger_1() -> Document:
+    """The K1 acid test: Menger sponge level 1 — a 27mm cube minus three
+    orthogonal 9mm square rods through the center. Five chained booleans
+    with coincident internal faces everywhere; exact volume is KNOWN:
+    20/27 of the cube = 14580 mm^3. A kernel that smears tolerances gets
+    this wrong; an exact kernel gets it to the last bit."""
+    d = Document()
+    cube = d.add(Feature(op="box", params={"dx": 27, "dy": 27, "dz": 27}))
+    rz = d.add(Feature(op="box", params={"dx": 9, "dy": 9, "dz": 27}))
+    rzm = d.add(Feature(op="move", params={"translate": [9, 9, 0]}, inputs=[rz]))
+    rx = d.add(Feature(op="box", params={"dx": 27, "dy": 9, "dz": 9}))
+    rxm = d.add(Feature(op="move", params={"translate": [0, 9, 9]}, inputs=[rx]))
+    ry = d.add(Feature(op="box", params={"dx": 9, "dy": 27, "dz": 9}))
+    rym = d.add(Feature(op="move", params={"translate": [9, 0, 9]}, inputs=[ry]))
+    u1 = d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[rzm, rxm]))
+    u2 = d.add(Feature(op="boolean", params={"kind": "union"}, inputs=[u1, rym]))
+    d.add(Feature(op="boolean", params={"kind": "cut"}, inputs=[cube, u2]))
+    return d
+
+
+CORPUS: list[tuple[str, tuple[str, ...], Callable[[], Document]]] = [
+    ("plate_with_holes", ("planar", "boolean", "hole"), plate_with_holes),
+    ("quadric_boss", ("quadric", "boolean"), quadric_boss),
+    ("revolve_profile", ("quadric", "revolve"), revolve_profile),
+    ("extrude_L", ("planar", "extrude"), extrude_L),
+    ("filleted_block", ("blend",), filleted_block),
+    ("chamfered_block", ("planar", "blend"), chamfered_block),
+    ("shelled_box", ("offset",), shelled_box),
+    ("shelled_prism", ("offset",), shelled_prism),
+    ("drafted_block", ("draft",), drafted_block),
+    ("spring", ("sweep", "freeform"), spring),
+    ("swept_channel", ("sweep",), swept_channel),
+    ("loft_transition", ("loft", "freeform"), loft_transition),
+    ("sheetmetal_folded", ("planar", "boolean"), sheetmetal_folded),
+    ("torture_tangent_cylinders", ("torture", "quadric", "boolean"),
+     torture_tangent_cylinders),
+    ("torture_coincident_faces", ("torture", "planar", "boolean"),
+     torture_coincident_faces),
+    ("torture_sliver_cut", ("torture", "planar", "boolean"),
+     torture_sliver_cut),
+    ("torture_tangent_sphere_plane", ("torture", "quadric", "boolean"),
+     torture_tangent_sphere_plane),
+    ("torture_menger_1", ("torture", "planar", "boolean"), torture_menger_1),
+    ("sweep_rightangle", ("sweep",), sweep_rightangle),
+    ("quadric_sphere_overlap", ("quadric", "boolean"), quadric_sphere_overlap),
+]

gitcad-0.7.7/src/gitcad/bench/scorecard.py

@@ -0,0 +1,176 @@
+"""Kernel scorecard — the benchmark that makes improvement provable
+(ADR-0018 W0; owner requirement: "show we are actually improving").
+
+Runs the corpus on a named backend and emits a snapshot: per-model
+build result, wall time, volume/bbox/topology metrics, validation.
+With two backends, emits deltas. Snapshots are dated JSON committed
+under bench/; TREND.md regenerates from them so every improvement
+claim has a number in git history behind it.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from gitcad.bench.corpus import CORPUS
+
+_REL_TOL = 1e-9
+
+
+def _get_kernel(name: str):
+    if name == "occt":
+        from gitcad.kernel.occt import OcctKernel
+        return OcctKernel()
+    if name == "null":
+        from gitcad.kernel.null import NullKernel
+        return NullKernel()
+    if name == "ref":
+        from gitcad.kernel.ref import RefKernel
+        return RefKernel()
+    if name == "forge":
+        from gitcad.kernel.rustref import RustKernel
+        return RustKernel()
+    if name == "auto":
+        from gitcad.kernel.auto import AutoKernel
+        return AutoKernel()
+    raise ValueError(f"unknown backend {name!r} (occt|null|ref|forge|auto)")
+
+
+def run_backend(backend: str) -> dict[str, Any]:
+    """Build every corpus model on one backend; never raises — failures
+    are data (that is the point of a robustness benchmark)."""
+    kernel = _get_kernel(backend)
+    models: dict[str, Any] = {}
+    for name, classes, build in CORPUS:
+        entry: dict[str, Any] = {"classes": list(classes)}
+        t0 = time.perf_counter()
+        try:
+            doc = build()
+            result = doc.build(kernel)
+            shape = result.final(doc)
+            entry["ok"] = True
+            entry["seconds"] = round(time.perf_counter() - t0, 4)
+            try:
+                mp = kernel.mass_props(shape)
+                entry["volume"] = mp.get("volume")
+            except Exception as exc:                     # metric, not fatal
+                entry["volume_error"] = f"{type(exc).__name__}: {exc}"
+            try:
+                (x0, y0, z0), (x1, y1, z1) = kernel.bbox(shape)
+                entry["bbox"] = [round(v, 6) for v in
+                                 (x0, y0, z0, x1, y1, z1)]
+            except Exception:
+                pass
+            try:
+                entry["faces"] = len(kernel.entities(shape, "face"))
+                entry["edges"] = len(kernel.entities(shape, "edge"))
+            except Exception:
+                pass
+            try:
+                v = kernel.validate(shape)
+                entry["valid"] = bool(v.ok)
+            except Exception:
+                pass
+        except Exception as exc:
+            entry["ok"] = False
+            entry["seconds"] = round(time.perf_counter() - t0, 4)
+            entry["error"] = f"{type(exc).__name__}: {exc}"
+        models[name] = entry
+
+    by_class: dict[str, dict[str, int]] = {}
+    for name, entry in models.items():
+        for cls in entry["classes"]:
+            c = by_class.setdefault(cls, {"total": 0, "ok": 0, "valid": 0})
+            c["total"] += 1
+            c["ok"] += 1 if entry.get("ok") else 0
+            c["valid"] += 1 if entry.get("valid") else 0
+    return {"backend": backend, "models": models, "by_class": by_class,
+            "capability_pct": round(
+                100 * sum(1 for m in models.values() if m.get("ok"))
+                / len(models), 1)}
+
+
+def compare(a: dict[str, Any], b: dict[str, Any]) -> dict[str, Any]:
+    """Deltas of run b against oracle run a (volume rel-delta, topology
+    count diffs, disagreement list)."""
+    out: dict[str, Any] = {"oracle": a["backend"], "subject": b["backend"],
+                           "models": {}, "disagreements": []}
+    for name, ea in a["models"].items():
+        eb = b["models"].get(name, {})
+        row: dict[str, Any] = {"oracle_ok": ea.get("ok"),
+                               "subject_ok": eb.get("ok")}
+        va, vb = ea.get("volume"), eb.get("volume")
+        if isinstance(va, (int, float)) and isinstance(vb, (int, float)) and va:
+            row["volume_rel_delta"] = abs(vb - va) / abs(va)
+            if row["volume_rel_delta"] > 1e-6:
+                out["disagreements"].append(
+                    f"{name}: volume {va:.6g} vs {vb:.6g}")
+        if ea.get("ok") != eb.get("ok"):
+            out["disagreements"].append(
+                f"{name}: ok {ea.get('ok')} vs {eb.get('ok')}")
+        for k in ("faces", "edges"):
+            if k in ea and k in eb and ea[k] != eb[k]:
+                row[f"{k}_diff"] = (ea[k], eb[k])
+        out["models"][name] = row
+    return out
+
+
+def snapshot(backends: list[str], outdir: str = "bench", *,
+             stamp: str) -> dict[str, Any]:
+    """Run + persist one dated benchmark snapshot; regenerate TREND.md."""
+    runs = {b: run_backend(b) for b in backends}
+    payload: dict[str, Any] = {"stamp": stamp, "runs": runs}
+    if len(backends) == 2:
+        payload["compare"] = compare(runs[backends[0]], runs[backends[1]])
+    out = Path(outdir)
+    out.mkdir(parents=True, exist_ok=True)
+    path = out / f"{stamp}-{'-vs-'.join(backends)}.json"
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n",
+                    newline="\n")
+    _render_trend(out)
+    return payload
+
+
+def _render_trend(outdir: Path) -> None:
+    rows: list[str] = ["# Kernel benchmark trend", "",
+                       "Regenerated from bench/*.json — every improvement "
+                       "claim has a snapshot behind it.", "",
+                       "| snapshot | backend | capability % | torture ok | "
+                       "models ok | total s |",
+                       "|---|---|---|---|---|---|"]
+    for p in sorted(outdir.glob("*.json")):
+        data = json.loads(p.read_text())
+        for backend, run in sorted(data.get("runs", {}).items()):
+            models = run["models"]
+            torture = [m for m in models.values() if "torture" in m["classes"]]
+            rows.append(
+                f"| {data['stamp']} | {backend} | {run['capability_pct']} | "
+                f"{sum(1 for m in torture if m.get('ok'))}/{len(torture)} | "
+                f"{sum(1 for m in models.values() if m.get('ok'))}/{len(models)} | "
+                f"{round(sum(m.get('seconds', 0) for m in models.values()), 2)} |")
+    (outdir / "TREND.md").write_text("\n".join(rows) + "\n", newline="\n")
+
+
+def main() -> None:  # pragma: no cover - CLI entry
+    import argparse
+    from datetime import date
+
+    ap = argparse.ArgumentParser(description="kernel benchmark scorecard")
+    ap.add_argument("backends", nargs="+", help="occt | null | ref")
+    ap.add_argument("--outdir", default="bench")
+    ap.add_argument("--stamp", default=str(date.today()))
+    args = ap.parse_args()
+    payload = snapshot(args.backends, args.outdir, stamp=args.stamp)
+    for b, run in payload["runs"].items():
+        print(f"{b}: capability {run['capability_pct']}% "
+              f"({sum(1 for m in run['models'].values() if m.get('ok'))}"
+              f"/{len(run['models'])} models)")
+    for d in payload.get("compare", {}).get("disagreements", []):
+        print("DISAGREE:", d)
+
+
+if __name__ == "__main__":
+    main()