feat: prebuilt C++ binary wheels on PyPI (chilmesh[cpp])

[domattioli]

Ship the C++ speedup with no user toolchain — pip install chilmesh[cpp] pulls a prebuilt binary instead of requiring a compiler + CMake source build. Today PyPI is pure-Python (#229), so the C++/Rust speedups are unreachable for most users.

Full plan (design, phases, risks, ready-to-apply YAML/pyproject snippets): docs/dev/PREBUILT_WHEELS_PLAN.md.

Approach — Model A: publish chilmesh-cpp as its own binary-wheel package + add a chilmesh[cpp] extra (keeps chilmesh pure-Python default/fallback; backend auto-detect already imports chilmesh_cpp, no runtime code change).

Checklist (comment-to-close as each lands)

• Phase 0 — ratify Model A; define chilmesh ↔ chilmesh-cpp version-compat pin; graduate chilmesh-cpp off 0.6.0.dev0
• Phase 1a — expand build-cpp-wheels.yml: real full_init smoke test (not just hasattr); ship Linux manylinux first (free runners)
• Phase 1b — add macOS (x86_64 + arm64) and Windows legs — gated on runner-billing (ci: push-event CI runs startup-fail (0 jobs) — macOS/Windows matrix can't launch (operator/billing-gated) #225)
• Phase 2 — publish-cpp-wheels.yml: release/tag-gated PyPI upload (prefer Trusted Publishing / OIDC; token fallback mirrors publish-pypi.yml) + sdist
• Phase 3 — add [project.optional-dependencies] cpp = ["chilmesh-cpp>=0.6,<0.7"]; document pip install chilmesh[cpp] (land with the publish, never before — else the extra resolves to a nonexistent package)
• Phase 4 — post-publish smoke on a clean env per platform (backend_info()['selected']=='cpp' + equivalence suite against the installed wheel, not src/ — Rust + C++ backends blocked from cross-language validation benchmark (array-skeletonize returns 2; cpp editable resolves to empty stub) #163 shadowing); close PyPI wheel (chilmesh 1.2.1) ships pure-Python only — no compiled cpp extension; consumers get the slow path #229

Notes

• Not Rust. The Rust backend is frozen and earns no perf niche over C++ (docs/RUST_EVALUATION.md) — this ships C++ wheels only.
• Registry: PyPI wheels are the correct channel for a Python extension module (Conan/vcpkg are for C++-consumed libraries, not applicable). Optional later: conda-forge for the scientific audience.
• Releases: publishing new binary wheels = a new chilmesh-cpp version on PyPI (immutable — no re-upload). Independent of the main chilmesh version and its GitHub/Zenodo release cadence.

Refs: #229, #225, #234.

---

Generated by Claude Code

[domattioli]

Phase 1a — real full_init smoke landed (811110f, on development via rolling PR #258)

• What shipped

  ▸ Change

    ↪ `build-cpp-wheels.yml`'s `CIBW_TEST_COMMAND` was a bare `hasattr(chilmesh_cpp, 'full_init')` symbol probe — it never executed the binary, so an extension that built yet crashed or returned an empty mesh at runtime would still pass the wheel build.
  

  ▸ Now

    a. the test builds a 2-triangle unit square, calls `chilmesh_cpp.full_init(pts, conn)`, and asserts the built adjacency + skeleton: 4 verts / 2 elems / 5 edges (4 boundary + 1 shared diagonal) / `adjacency_built` / `n_layers >= 1` / `edge2vert` shape `(5, 2)`.
  
    b. added `CIBW_TEST_REQUIRES: numpy` for the float64/int32 array inputs.
  

  ▸ Verified

    ↪ signature + every asserted attribute checked against the pybind bindings; the 5-edge count is a topology certainty for two tris sharing a diagonal; YAML parses and the folded `python -c` is `ast.parse`-clean. The live CI run is deferred to `workflow_dispatch` (no manylinux/docker in the routine env).
  

• Checklist status

  ↪ Phase 1a's manylinux leg already existed; this fills its remaining smoke-test half. Phases 1b/2/3/4 stay open — 1b/publish are gated on the macOS/Windows runner-billing decision (ci: push-event CI runs startup-fail (0 jobs) — macOS/Windows matrix can't launch (operator/billing-gated) #225) and the chilmesh-cpp version graduation (Phase 0), both operator calls.

• Phase 1a — real full_init smoke test (not just hasattr); manylinux leg present

[model: claude-opus-4-8, repo: CHILmesh, session: 018z9MobkyDkCqHasxikpEpi]

---

Generated by Claude Code

[domattioli]

Phase 2 landed — publish-cpp-wheels.yml (75cf769, development)

• Shipped — release-gated PyPI publish pipeline for chilmesh_cpp

  ▸ What

    a. new `.github/workflows/publish-cpp-wheels.yml` (from the ready A2 template in `docs/dev/PREBUILT_WHEELS_PLAN.md`): `build-manylinux` (reuses the Phase 1a cibuildwheel + `full_init` smoke) + `sdist` + `publish` (`needs: [build-manylinux, sdist]`).
  
    b. registered in `.github/workflows/LOCAL.md` per the spec-010 v3 creation gate.
  

  ▸ Safety gating

    ↪ triggers are `release: [published]` + `workflow_dispatch` **only** — there is no `push` trigger, so nothing publishes from `development`; the `publish` job sits behind `environment: pypi` (protect with required reviewers in repo settings) and uses PyPI Trusted Publishing (OIDC, `id-token: write`) with a commented `PYPI_API_TOKEN` fallback mirroring `publish-pypi.yml`.
  

  ▸ Scope held

    ↪ macOS/Windows legs are deliberately absent — that is Phase 1b, still gated on the runner-billing decision in #225; this workflow ships the manylinux + sdist path that is already validated.
  

  ▸ Verified

    ↪ YAML parses, no `push` trigger confirmed, `publish.needs` correct, embedded `CIBW_TEST_COMMAND` payload `ast.parse`-clean, and a local simulation of the workflow-conformance lint (timeout / permissions / action-version pins / pip-cache / LOCAL.md registration) came back CLEAN; cibuildwheel + a live PyPI upload cannot run in-env (no manylinux/docker, no release event) so the real run is deferred to a release or `workflow_dispatch`.
  

• Still open — Phase 0 (operator: ratify Model A, define the chilmesh ↔ chilmesh-cpp version-compat pin, graduate off 0.6.0.dev0), Phase 1b macOS/Windows (ci: push-event CI runs startup-fail (0 jobs) — macOS/Windows matrix can't launch (operator/billing-gated) #225), Phase 3 extra, Phase 4 post-publish validation. Phase 2 checkbox flipped.

[model: claude-opus-4-8, repo: CHILmesh, session: 013NhKuhHJwC9wmmysELCufc]

---

Generated by Claude Code