fix(solver): use all 3 cross-product components to avoid XY-plane singularity

The parallel-normal constraints (ParallelConstraint, PlanarConstraint,
ConcentricConstraint, RevoluteConstraint, CylindricalConstraint,
SliderConstraint, ScrewConstraint) and point-on-line constraints
previously used only the x and y components of the cross product,
dropping the z component.

This created a singularity when both normal vectors lay in the XY
plane: a yaw rotation produced a cross product entirely along Z,
which was discarded, making the constraint blind to the rotation.

Fix: return all 3 cross-product components. The Jacobian has a
rank deficiency at the solution (3 residuals, rank 2), but the
Newton solver handles this correctly via its pseudoinverse.

Similarly, point_line_perp_components now returns all 3 components
of the displacement cross product to avoid singularity when the
line direction aligns with a coordinate axis.

.gitignore

@@ -1,44 +1,83 @@
-# Prerequisites
+# C++ compiled objects
 *.d
-
-# Compiled Object files
 *.slo
 *.lo
 *.o
 *.obj
-
-# Precompiled Headers
 *.gch
 *.pch
 
-# Compiled Dynamic libraries
+# C++ libraries
 *.so
 *.dylib
 *.dll
-
-# Fortran module files
-*.mod
-*.smod
-
-# Compiled Static libraries
 *.lai
 *.la
 *.a
 *.lib
 
-# Executables
+# C++ executables
 *.exe
 *.out
 *.app
 
-.vs
+# C++ build
+build/
+cmake-build-debug/
+.vs/
 x64/
+temp/
+
+# OndselSolver test artifacts
 *.bak
 assembly.asmt
-
-build
-cmake-build-debug
-.idea
-temp/
 /testapp/draggingBackhoe.log
 /testapp/runPreDragBackhoe.asmt
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# mypy / ruff / pytest
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Data (large files tracked separately)
+data/synthetic/*.pt
+data/fusion360/*.json
+data/fusion360/*.step
+data/processed/*.pt
+!data/**/.gitkeep
+
+# Model checkpoints
+*.ckpt
+*.pth
+*.onnx
+*.torchscript
+
+# Experiment tracking
+wandb/
+runs/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env

GNN/.gitea/workflows/ci.yaml

@@ -0,0 +1,209 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      run_datagen:
+        description: "Run dataset generation"
+        required: false
+        type: boolean
+        default: false
+      num_assemblies:
+        description: "Number of assemblies to generate"
+        required: false
+        type: string
+        default: "100000"
+      num_workers:
+        description: "Parallel workers for datagen"
+        required: false
+        type: string
+        default: "4"
+
+env:
+  PIP_CACHE_DIR: /tmp/pip-cache-solver
+  TORCH_INDEX: https://download.pytorch.org/whl/cpu
+  VIRTUAL_ENV: /tmp/solver-venv
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Lint — fast, no torch required
+  # ---------------------------------------------------------------------------
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      PATH: /tmp/solver-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    steps:
+      - name: Trust internal CA
+        run: |
+          curl -sk https://ipa.kindred.internal/ipa/config/ca.crt \
+            -o /usr/local/share/ca-certificates/kindred-internal.crt
+          update-ca-certificates
+
+      - name: Checkout
+        uses: https://github.com/actions/checkout@v4
+
+      - name: Set up venv
+        run: python3 -m venv $VIRTUAL_ENV
+
+      - name: Install lint tools
+        run: pip install --cache-dir $PIP_CACHE_DIR ruff
+
+      - name: Ruff check
+        run: ruff check solver/ freecad/ tests/ scripts/
+
+      - name: Ruff format check
+        run: ruff format --check solver/ freecad/ tests/ scripts/
+
+  # ---------------------------------------------------------------------------
+  # Type check
+  # ---------------------------------------------------------------------------
+  type-check:
+    runs-on: ubuntu-latest
+    env:
+      PATH: /tmp/solver-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    steps:
+      - name: Trust internal CA
+        run: |
+          curl -sk https://ipa.kindred.internal/ipa/config/ca.crt \
+            -o /usr/local/share/ca-certificates/kindred-internal.crt
+          update-ca-certificates
+
+      - name: Checkout
+        uses: https://github.com/actions/checkout@v4
+
+      - name: Set up venv
+        run: python3 -m venv $VIRTUAL_ENV
+
+      - name: Install dependencies
+        run: |
+          pip install --cache-dir $PIP_CACHE_DIR \
+            mypy numpy scipy \
+            torch --index-url $TORCH_INDEX
+          pip install --cache-dir $PIP_CACHE_DIR torch-geometric
+          pip install --cache-dir $PIP_CACHE_DIR -e ".[dev]"
+
+      - name: Mypy
+        run: mypy solver/ freecad/
+
+  # ---------------------------------------------------------------------------
+  # Tests
+  # ---------------------------------------------------------------------------
+  test:
+    runs-on: ubuntu-latest
+    env:
+      PATH: /tmp/solver-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    steps:
+      - name: Trust internal CA
+        run: |
+          curl -sk https://ipa.kindred.internal/ipa/config/ca.crt \
+            -o /usr/local/share/ca-certificates/kindred-internal.crt
+          update-ca-certificates
+
+      - name: Checkout
+        uses: https://github.com/actions/checkout@v4
+
+      - name: Set up venv
+        run: python3 -m venv $VIRTUAL_ENV
+
+      - name: Install dependencies
+        run: |
+          pip install --cache-dir $PIP_CACHE_DIR \
+            torch --index-url $TORCH_INDEX
+          pip install --cache-dir $PIP_CACHE_DIR torch-geometric
+          pip install --cache-dir $PIP_CACHE_DIR -e ".[train,dev]"
+
+      - name: Run tests
+        run: pytest tests/ freecad/tests/ -v --tb=short
+
+  # ---------------------------------------------------------------------------
+  # Dataset generation — manual trigger or on main push
+  # ---------------------------------------------------------------------------
+  datagen:
+    runs-on: ubuntu-latest
+    if: >-
+      (github.event_name == 'workflow_dispatch' && inputs.run_datagen == true) ||
+      (github.event_name == 'push' && github.ref == 'refs/heads/main')
+    needs: [test]
+    env:
+      PATH: /tmp/solver-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    steps:
+      - name: Trust internal CA
+        run: |
+          curl -sk https://ipa.kindred.internal/ipa/config/ca.crt \
+            -o /usr/local/share/ca-certificates/kindred-internal.crt
+          update-ca-certificates
+
+      - name: Checkout
+        uses: https://github.com/actions/checkout@v4
+
+      - name: Set up venv
+        run: python3 -m venv $VIRTUAL_ENV
+
+      - name: Install dependencies
+        run: |
+          pip install --cache-dir $PIP_CACHE_DIR \
+            torch --index-url $TORCH_INDEX
+          pip install --cache-dir $PIP_CACHE_DIR torch-geometric
+          pip install --cache-dir $PIP_CACHE_DIR -e ".[train]"
+
+      - name: Restore datagen checkpoint
+        id: datagen-cache
+        uses: https://github.com/actions/cache/restore@v4
+        with:
+          path: data/synthetic
+          key: datagen-${{ github.sha }}
+          restore-keys: |
+            datagen-
+
+      - name: Generate dataset
+        run: |
+          NUM=${INPUTS_NUM_ASSEMBLIES:-100000}
+          WORKERS=${INPUTS_NUM_WORKERS:-4}
+          echo "Generating ${NUM} assemblies with ${WORKERS} workers"
+          python3 scripts/generate_synthetic.py \
+            --num-assemblies "${NUM}" \
+            --num-workers "${WORKERS}" \
+            --output-dir data/synthetic
+        env:
+          INPUTS_NUM_ASSEMBLIES: ${{ inputs.num_assemblies }}
+          INPUTS_NUM_WORKERS: ${{ inputs.num_workers }}
+
+      - name: Save datagen checkpoint
+        if: always()
+        uses: https://github.com/actions/cache/save@v4
+        with:
+          path: data/synthetic
+          key: datagen-${{ github.sha }}
+
+      - name: Upload dataset
+        uses: https://github.com/actions/upload-artifact@v3
+        with:
+          name: synthetic-dataset
+          path: |
+            data/synthetic/index.json
+            data/synthetic/stats.json
+            data/synthetic/shards/
+          retention-days: 90
+
+      - name: Print summary
+        if: always()
+        run: |
+          echo "=== Dataset Generation Results ==="
+          if [ -f data/synthetic/stats.json ]; then
+            python3 -c "
+          import json
+          with open('data/synthetic/stats.json') as f:
+              s = json.load(f)
+          print(f'Total examples: {s[\"total_examples\"]}')
+          print(f'Classification: {json.dumps(s[\"classification_distribution\"], indent=2)}')
+          print(f'Rigid: {s[\"rigidity\"][\"rigid_fraction\"]*100:.1f}%')
+          print(f'Degeneracy: {s[\"geometric_degeneracy\"][\"fraction_with_degeneracy\"]*100:.1f}%')
+          "
+          else
+            echo "stats.json not found — generation may have failed"
+            ls -la data/synthetic/ 2>/dev/null || echo "output dir missing"
+          fi

GNN/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - torch>=2.2
+          - numpy>=1.26
+        args: [--ignore-missing-imports]
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v3.1.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: [feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert]

GNN/Dockerfile

@@ -0,0 +1,61 @@
+FROM nvidia/cuda:12.4.1-devel-ubuntu22.04 AS base
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONUNBUFFERED=1
+
+# System deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3.11 python3.11-venv python3.11-dev python3-pip \
+    git wget curl \
+    # FreeCAD headless deps
+    freecad \
+    libgl1-mesa-glx libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN update-alternatives --install /usr/bin/python python /usr/bin/python3.11 1
+
+# Create venv
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Install PyTorch with CUDA
+RUN pip install --no-cache-dir \
+    torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
+
+# Install PyG
+RUN pip install --no-cache-dir \
+    torch-geometric \
+    pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv \
+    -f https://data.pyg.org/whl/torch-2.4.0+cu124.html
+
+WORKDIR /workspace
+
+# Install project
+COPY pyproject.toml .
+RUN pip install --no-cache-dir -e ".[train,dev]" || true
+
+COPY . .
+RUN pip install --no-cache-dir -e ".[train,dev]"
+
+# -------------------------------------------------------------------
+FROM base AS cpu
+
+# CPU-only variant (for CI and non-GPU environments)
+FROM python:3.11-slim AS cpu-only
+
+ENV PYTHONUNBUFFERED=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git freecad libgl1-mesa-glx libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+
+COPY pyproject.toml .
+RUN pip install --no-cache-dir torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
+RUN pip install --no-cache-dir torch-geometric
+
+COPY . .
+RUN pip install --no-cache-dir -e ".[train,dev]"
+
+CMD ["pytest", "tests/", "-v"]

GNN/Makefile

@@ -0,0 +1,48 @@
+.PHONY: train test lint data-gen export format type-check install dev clean help
+
+PYTHON ?= python
+PYTEST ?= pytest
+RUFF ?= ruff
+MYPY ?= mypy
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install core dependencies
+	pip install -e .
+
+dev: ## Install all dependencies including dev tools
+	pip install -e ".[train,dev]"
+	pre-commit install
+	pre-commit install --hook-type commit-msg
+
+train: ## Run training (pass CONFIG=path/to/config.yaml)
+	$(PYTHON) -m solver.training.train $(if $(CONFIG),--config-path $(CONFIG))
+
+test: ## Run test suite
+	$(PYTEST) tests/ freecad/tests/ -v --tb=short
+
+lint: ## Run ruff linter
+	$(RUFF) check solver/ freecad/ tests/ scripts/
+
+format: ## Format code with ruff
+	$(RUFF) format solver/ freecad/ tests/ scripts/
+	$(RUFF) check --fix solver/ freecad/ tests/ scripts/
+
+type-check: ## Run mypy type checker
+	$(MYPY) solver/ freecad/
+
+data-gen: ## Generate synthetic dataset (pass CONFIG=path/to/config.yaml)
+	$(PYTHON) scripts/generate_synthetic.py $(if $(CONFIG),--config-path $(CONFIG))
+
+export: ## Export trained model for deployment
+	$(PYTHON) export/package_model.py $(if $(MODEL),--model $(MODEL))
+
+clean: ## Remove build artifacts and caches
+	rm -rf build/ dist/ *.egg-info/
+	rm -rf .mypy_cache/ .pytest_cache/ .ruff_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+
+check: lint type-check test ## Run all checks (lint, type-check, test)