groupoid 0.1.0.dev2__tar.gz → 0.1.0.dev4__tar.gz

groupoid-0.1.0.dev4/.github/dependabot.yml

@@ -0,0 +1,78 @@
+# Dependabot configuration.
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+#
+# Opens reviewable update PRs (never auto-merged) so security and version bumps
+# are surfaced proactively, rather than relying on a manual read of the CI
+# dependency-audit output. Complements the CI dependency-vulnerability scan.
+version: 2
+updates:
+  # Python dependencies declared in pyproject.toml.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      # Pin the run to a predictable local hour. With no time/timezone,
+      # Dependabot fires at its default slot in UTC, which lands in the middle
+      # of the night for the maintainer. Adjust `timezone` to your actual IANA
+      # zone if America/New_York is not yours.
+      time: "09:00"
+      timezone: "America/New_York"
+    open-pull-requests-limit: 5
+    # Manage DIRECT dependencies only — the ones declared in pyproject.toml.
+    # GROUPOID ships no committed/compiled lockfile, so this is currently a
+    # no-op (Dependabot already only edits the pyproject declarations). It is
+    # kept for consistency and as a guard: should a compiled lock ever be added,
+    # its transitive pins must advance by recompiling the lock, not by standalone
+    # Dependabot line-edits. Transitive CVEs are NOT lost: Dependabot *security*
+    # updates patch vulnerable dependencies regardless of this allow filter.
+    allow:
+      - dependency-type: "direct"
+    groups:
+      # Batch updates by area into a single PR per group to limit noise instead
+      # of one PR per package.
+      runtime:
+        patterns:
+          - "torch"
+          - "geomstats"
+          - "pymanopt"
+          - "ripser"
+          - "persim"
+          - "POT"
+          - "networkx"
+          - "einops"
+          - "numpy"
+          - "scipy"
+          - "pydantic"
+          - "loguru"
+      dev:
+        patterns:
+          - "pytest*"
+          - "ruff"
+          - "black"
+          - "mypy"
+          - "hypothesis"
+          - "bandit"
+          - "pip-audit"
+          - "pre-commit"
+      docs:
+        patterns: ["mkdocs*", "mkdocstrings*"]
+      # Fallback batcher. With `allow: direct` and the groups above, this should
+      # stay empty; if a future declared dep is not matched above, this keeps it
+      # to a single PR instead of one-per-package.
+      other:
+        patterns: ["*"]
+
+  # GitHub Actions used in the workflows (keeps action versions current).
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/New_York"
+    open-pull-requests-limit: 5
+    groups:
+      # Batch all action bumps into a single weekly PR instead of one each.
+      actions:
+        patterns: ["*"]

groupoid-0.1.0.dev4/.github/scripts/install_torch_cpu.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Installs CPU-only torch from the PyTorch index with retries.
+#
+# That index (download.pytorch.org/whl/cpu, Cloudflare R2-backed as
+# download-r2.pytorch.org) intermittently drops the TLS handshake
+# (SSLV3_ALERT_HANDSHAKE_FAILURE) from GitHub-hosted runners. pip's own
+# built-in retries reuse the same connection pool within one process and
+# do not help here; a fresh `pip install` invocation gets a fresh TLS
+# connection and has in practice succeeded where the retries within a
+# single invocation did not. Five attempts with linear backoff (10s, 20s,
+# 30s, 40s) before giving up.
+set -euo pipefail
+
+max_attempts=5
+attempt=1
+until pip install torch --index-url https://download.pytorch.org/whl/cpu; do
+  if [ "${attempt}" -ge "${max_attempts}" ]; then
+    echo "::error::torch install failed after ${max_attempts} attempts" >&2
+    exit 1
+  fi
+  sleep_seconds=$((attempt * 10))
+  echo "torch install attempt ${attempt}/${max_attempts} failed; retrying in ${sleep_seconds}s" >&2
+  sleep "${sleep_seconds}"
+  attempt=$((attempt + 1))
+done

groupoid-0.1.0.dev4/.github/workflows/auto-tag-release.yml

@@ -0,0 +1,72 @@
+name: Auto Tag Release
+
+# Creates the tag for a release-cut merge to main; it does nothing else.
+# release.yml (build, attestations, PyPI publish, signing, GitHub Release)
+# is triggered solely by that tag push, exactly as it would be from a
+# manual `git tag vX.Y.Z && git push origin vX.Y.Z`. Keeping tag creation
+# and publishing in two separate, single-purpose workflows means the
+# actual publish path has exactly one trigger (a tag push) to reason
+# about, instead of depending on GitHub's anti-recursion behavior for
+# GITHUB_TOKEN-authored pushes not re-triggering the same push event.
+#
+# If a version needs a tag this workflow's format check rejects (see
+# below), tag it manually -- this automation only ever creates a tag
+# when one is missing, so a pre-existing manual tag always takes
+# precedence and this workflow becomes a no-op for that version.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - pyproject.toml
+
+permissions:
+  contents: read
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # push the tag; nothing else in this workflow needs it
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          fetch-depth: 0   # need full tag history to check for an existing tag
+
+      - name: Create the release tag if this version doesn't have one yet
+        run: |
+          set -euo pipefail
+
+          version=$(grep -m1 '^version = "' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          if [ -z "${version}" ]; then
+            echo "::error::could not extract a version from pyproject.toml"
+            exit 1
+          fi
+
+          # PEP 440-ish release/pre-release only: X.Y.Z, optionally with
+          # .devN / aN / bN / rcN. No local version segment (+...), no
+          # anything else. A version that doesn't match this is presumably
+          # intentional and unusual enough to want a human tagging it by
+          # hand rather than this automation guessing.
+          if ! echo "${version}" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(\.dev[0-9]+|a[0-9]+|b[0-9]+|rc[0-9]+)?$'; then
+            echo "::error::version '${version}' is not a recognized release format (expected X.Y.Z, optionally with .devN/aN/bN/rcN, no local metadata); refusing to tag automatically. Tag it manually if this is intentional."
+            exit 1
+          fi
+
+          tag="v${version}"
+
+          if git rev-parse "refs/tags/${tag}" >/dev/null 2>&1; then
+            echo "Tag ${tag} already exists; nothing to do."
+            exit 0
+          fi
+
+          if ! grep -qF "[${version}]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no [${version}] heading; refusing to tag an undocumented release. Add the changelog section as part of the version-bump PR."
+            exit 1
+          fi
+
+          echo "Version ${version} has no matching tag; creating ${tag}."
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "${tag}" -m "Release ${tag}"
+          git push origin "refs/tags/${tag}"

{groupoid-0.1.0.dev2 → groupoid-0.1.0.dev4}/.github/workflows/ci.yml

@@ -13,8 +13,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
       - name: Install dependencies
@@ -25,7 +25,7 @@ jobs:
           # Linting only against `ruff black mypy` left numpy/pydantic uninstalled,
           # so --strict raised disallow_subclassing_any on the BaseModel subclass.
           # Consistent with the test / security / docs jobs. CPU torch keeps it lean.
-          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          .github/scripts/install_torch_cpu.sh
           pip install -e ".[dev]"
       - name: Run ruff
         run: ruff check .
@@ -40,14 +40,14 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          .github/scripts/install_torch_cpu.sh
           pip install -e ".[dev]"
       - name: Run tests with coverage gate
         run: >-
@@ -58,8 +58,8 @@ jobs:
   security:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
       - name: Install dependencies
@@ -69,7 +69,7 @@ jobs:
           # packages GROUPOID actually depends on. The previous `safety` step
           # installed only the tools and never the project, so it audited the
           # wrong environment. CPU torch keeps the install lean.
-          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          .github/scripts/install_torch_cpu.sh
           pip install -e .
           pip install bandit pip-audit
           # Pin setuptools LAST. torch requires setuptools<82 and pulls in a
@@ -95,8 +95,8 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
       - name: Install pre-commit
@@ -107,14 +107,14 @@ jobs:
   benchmark:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          .github/scripts/install_torch_cpu.sh
           pip install -e ".[dev]"
       # Benchmarks run for information only. There is no regression gate:
       # timing baselines recorded on one machine are not comparable to a
@@ -128,7 +128,7 @@ jobs:
           pytest benchmarks/ -v --benchmark-json=benchmark_results.json || true
       - name: Upload benchmark results
         if: always()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: benchmark-results
           path: benchmark_results.json
@@ -137,14 +137,14 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          .github/scripts/install_torch_cpu.sh
           pip install -e ".[docs]"
       - name: Build docs
         run: mkdocs build --strict

{groupoid-0.1.0.dev2 → groupoid-0.1.0.dev4}/.github/workflows/docs-deploy.yml

@@ -7,8 +7,6 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
   group: pages
@@ -18,27 +16,30 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          .github/scripts/install_torch_cpu.sh
           pip install -e ".[docs]"
       - name: Build docs
         run: mkdocs build --strict
-      - uses: actions/upload-pages-artifact@v5
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
         with:
           path: site/
 
   deploy:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

{groupoid-0.1.0.dev2 → groupoid-0.1.0.dev4}/.github/workflows/release.yml

@@ -22,7 +22,7 @@ jobs:
       id-token: write       # provenance OIDC
       attestations: write   # actions/attest-build-provenance + attest-sbom
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           ref: ${{ github.event.inputs.ref || github.ref }}
           fetch-depth: 0
@@ -43,7 +43,7 @@ jobs:
         with:
           subject-path: "dist/*"
       - name: SBOM attestation (CycloneDX)
-        uses: actions/attest-sbom@5026d3663739160db546203eeaffa6aa1c51a4d6  # v1
+        uses: actions/attest-sbom@c604332985a26aa8cf1bdc465b92731239ec6b9e  # v4.1.0
         with:
           subject-path: "dist/*"
           sbom-path: "sbom.cdx.json"
@@ -65,7 +65,7 @@ jobs:
       name: pypi
       url: https://pypi.org/project/groupoid/
     steps:
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
         with:
           name: release-artifacts
           path: .
@@ -86,19 +86,19 @@ jobs:
       contents: write       # create GitHub Release
       id-token: write       # Sigstore signing OIDC
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
         with:
           name: release-artifacts
           path: .
       - name: Sign artifacts with Sigstore
-        uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46  # v3.0.0
+        uses: sigstore/gh-action-sigstore-python@5b79a39c381910c090341a2c9b0bf022c8b387e1  # v3.4.0
         with:
           inputs: |
             dist/*.tar.gz
             dist/*.whl
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda  # v3.0.0
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b  # v3.0.1
         with:
           generate_release_notes: true
           files: |

groupoid-0.1.0.dev4/.zenodo.json

@@ -0,0 +1,39 @@
+{
+  "upload_type": "software",
+  "title": "GROUPOID: Groupoid-based aggregation for federated learning on Riemannian manifolds",
+  "version": "0.1.0.dev4",
+  "description": "<p>Pre-alpha research prototype exploring groupoid-based aggregation for federated learning on Riemannian manifolds. Implements transport groupoid morphisms, first cohomology (H^1) for consistency detection, the cellular sheaf Laplacian for spectral analysis, parallel transport (Schild's and pole ladders), Riemannian optimizers, and Karcher mean aggregation via geomstats.</p><p><strong>Erratum / supersession notice:</strong> this version (v0.1.0.dev4) carries the mathematical corrections introduced in v0.1.0.dev1 over the earlier v0.1.0.dev0 snapshot (version DOI 10.5281/zenodo.20563975): the sheaf (connection) Laplacian is a verified positive-semidefinite operator with a transport-consistent kernel; persistence diagrams retain the homology-dimension label so H0 and H1 are no longer conflated; and H^1 cohomology raises on incomplete cocycles instead of forming partial holonomy. It also carries the v0.1.0.dev2 correction of a first-step magnitude inflation in the RiemannianAdam optimizer's bias initialization, and the v0.1.0.dev3 Morphism str()/format() display fix and documentation-accuracy corrections (v0.1.0.dev3 was cut in source control but never separately tagged or deposited, so this is the first deposit carrying its changes). New in v0.1.0.dev4: the Riemannian SGD and Adam optimizers now parallel-transport their accumulated moments between iterates instead of projecting them (projection could annihilate a geodesic-aligned moment); the parallel-transport and persistent-homology modules are wired into the aggregation pipeline; and a preregistered synthetic benchmark (see the repository's experiments/ directory) tests the central transport-aggregation hypothesis, finding it supported on synthetic frame-misaligned data and still unvalidated on real federated learning tasks. The v0.1.0.dev0 version DOI must not be cited for results. Cite the concept DOI (10.5281/zenodo.20563974), which always resolves to the latest corrected version, or this version or later.</p>",
+  "creators": [
+    {
+      "name": "Maniches, Santiago",
+      "affiliation": "TOPOLOGICA LLC",
+      "orcid": "0009-0005-6480-1987"
+    }
+  ],
+  "license": "Apache-2.0",
+  "keywords": [
+    "federated learning",
+    "Riemannian geometry",
+    "groupoid",
+    "sheaf theory",
+    "cohomology",
+    "topological data analysis"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "10.5281/zenodo.20563974",
+      "relation": "isVersionOf",
+      "scheme": "doi"
+    },
+    {
+      "identifier": "10.5281/zenodo.20787126",
+      "relation": "isNewVersionOf",
+      "scheme": "doi"
+    },
+    {
+      "identifier": "https://github.com/smaniches/GROUPOID",
+      "relation": "isSupplementTo",
+      "scheme": "url"
+    }
+  ]
+}

{groupoid-0.1.0.dev2 → groupoid-0.1.0.dev4}/CHANGELOG.md

@@ -10,6 +10,74 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 Nothing yet.
 
+## [0.1.0.dev4] - 2026-07-06
+
+`v0.1.0.dev3` was cut in source control (below) but never tagged or
+released: no `v0.1.0.dev3` tag was ever pushed, so PyPI, the GitHub
+Release, and the Zenodo deposit all skip directly from `0.1.0.dev2` to
+this version, which carries both the `0.1.0.dev3` changes and the ones
+below. See the "Releasing" section of `CONTRIBUTING.md` for the
+automation added in this version that prevents this gap from recurring.
+
+### Fixed
+- **Optimizer moment accumulators are now parallel-transported between
+  iterates**: Adam's first moment was previously carried across steps by
+  tangent projection (which can annihilate a geodesic-aligned moment) and
+  the SGD momentum velocity was not moved at all (leaving it non-tangent
+  at the new iterate). Both now use the metric's parallel transport (the
+  Becigneul-Ganea construction), with projection kept as the fallback for
+  metrics without parallel transport. Regression tests discriminate
+  transport from projection by exact norm preservation (#49).
+
+### Added
+- `TransportGroupoidAggregator.register_transport_from_points`: computes
+  and registers the transport matrix from two client base points via the
+  pole or Schild ladder, wiring `groupoid.transport` into the pipeline
+  (#49).
+- Opt-in `track_divergence` flag on the aggregator: each round computes
+  the persistent-homology summary of the transported parameters with the
+  H0-vs-H0 bottleneck distance to the previous round, exposed as
+  `FederatedRound.divergence` (default off; existing behavior unchanged),
+  wiring `groupoid.persistence` into the pipeline (#49).
+- Descent validation for the Riemannian optimizers: SGD, momentum SGD,
+  and Adam descend to a known target on S^2; the optimizer status labels
+  in STATUS.md and the docs are upgraded accordingly (general
+  convergence-rate analysis still does not exist and is not claimed)
+  (#49).
+- A preregistered synthetic benchmark (`experiments/`): preregistration
+  pushed before execution, 600 seeded runs, 2x2 transport/mean ablation
+  against an oracle estimand, corrupted-cocycle conditions, and a
+  committed preregistered analysis (`experiments/RESULTS.md`). Supports
+  the transport benefit under frame misalignment (largely by
+  construction) and the pooled H^1-error correlation under corruption,
+  with the within-level caveat, a failed null check reported as failed,
+  and one documented seeding deviation (#49).
+- Release automation: pushing a version bump to `main` now tags and
+  releases automatically, removing the manual tag-push step.
+
+## [0.1.0.dev3] - 2026-07-06
+
+Cut in source control but never tagged or released; see `0.1.0.dev4` above.
+
+### Fixed
+- **`Morphism` `str()`/`format()` output**: pydantic's `BaseModel` defines
+  `__str__` separately from `__repr__`, so `print()`, f-strings, and loguru's
+  `{}` formatting dumped the full transport matrix instead of the compact
+  `Morphism(A -> B)` form the `__repr__` override implements. `__str__` now
+  aliases `__repr__`, with a regression test (#47).
+
+### Changed
+- Docs-site installation pages corrected to state the package is published on
+  PyPI as a development pre-release, aligning `docs/index.md` and
+  `docs/quickstart.md` with the README and `STATUS.md` corrections from #37
+  and #39 (#47).
+- `curvature_adaptive_lr` docstring corrected to describe the implemented
+  behavior: the rate is damped in positive curvature and returned unchanged
+  otherwise; no enlargement is applied in negative curvature (#47).
+- `LIMITATIONS.md` now records that `torch`, `pymanopt`, `POT`, and `einops`
+  are declared runtime dependencies with no current code path (the suite
+  passes with all four uninstalled) (#47).
+
 ## [0.1.0.dev2] - 2026-06-21
 
 ### Fixed
@@ -86,7 +154,9 @@ Date shown is the tag commit (`v0.1.0.dev0` -> 2a02954). `CITATION.cff` records
 `date-released: 2026-05-25`, when the core implementation landed; the tag was
 later placed on the metadata commit.
 
-[Unreleased]: https://github.com/smaniches/GROUPOID/compare/v0.1.0.dev2...HEAD
+[Unreleased]: https://github.com/smaniches/GROUPOID/compare/v0.1.0.dev4...HEAD
+[0.1.0.dev4]: https://github.com/smaniches/GROUPOID/compare/v0.1.0.dev2...v0.1.0.dev4
+[0.1.0.dev3]: https://github.com/smaniches/GROUPOID/compare/v0.1.0.dev2...af42cb4
 [0.1.0.dev2]: https://github.com/smaniches/GROUPOID/compare/v0.1.0.dev1...v0.1.0.dev2
 [0.1.0.dev1]: https://github.com/smaniches/GROUPOID/compare/v0.1.0.dev0...v0.1.0.dev1
 [0.1.0.dev0]: https://github.com/smaniches/GROUPOID/releases/tag/v0.1.0.dev0

{groupoid-0.1.0.dev2 → groupoid-0.1.0.dev4}/CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
 type: software
 title: "GROUPOID: Groupoid-based aggregation for federated learning on Riemannian manifolds"
-version: 0.1.0.dev2
-date-released: 2026-06-21
+version: 0.1.0.dev4
+date-released: 2026-07-06
 license: Apache-2.0
 repository-code: "https://github.com/smaniches/GROUPOID"
 doi: 10.5281/zenodo.20563974

{groupoid-0.1.0.dev2 → groupoid-0.1.0.dev4}/CONTRIBUTING.md

@@ -75,6 +75,45 @@ please open an issue using the "Mathematical Correction" template.
 6. Ensure CI passes (lint, test, security, docs build).
 7. Address all review comments before merging.
 
+## Releasing
+
+1. Open a release-cut PR that bumps the version across every metadata
+   file that carries it: `pyproject.toml`, `groupoid/__init__.py`,
+   `codemeta.json`, `CITATION.cff` (version and `date-released`),
+   `STATUS.md` (both mentions), and `.zenodo.json` (version, the erratum
+   description, and `isNewVersionOf` advanced to the prior version's
+   Zenodo DOI). Roll `CHANGELOG.md`'s `Unreleased` section into a new
+   version heading with compare links. See PRs #40 or #48 for the
+   template.
+2. Merge the PR to `main`.
+
+That's it — merging is the release trigger, split across two workflows
+with one job each so the actual publish path has exactly one trigger to
+reason about:
+
+- `.github/workflows/auto-tag-release.yml` runs on every push to `main`
+  that touches `pyproject.toml`. It reads the version out of
+  `pyproject.toml`, and if no `v<version>` tag exists yet, it creates and
+  pushes one (as `github-actions[bot]`) after checking the version has a
+  recognized format and that `CHANGELOG.md` documents it. A push with no
+  version change, or whose tag already exists, is a no-op.
+- That tag push triggers `.github/workflows/release.yml` exactly as a
+  manual `git tag vX.Y.Z && git push origin vX.Y.Z` would: build,
+  provenance and SBOM attestation, publish to PyPI via Trusted
+  Publishing, Sigstore signing, and a GitHub Release (which in turn
+  triggers the Zenodo deposit for the new version DOI). `release.yml`
+  itself is unchanged from before this automation existed — it only
+  ever runs from a tag push or a manual `workflow_dispatch`.
+
+The actual PyPI publish step still runs under the `pypi` GitHub
+Environment; if that environment has required reviewers configured, the
+publish waits for that approval exactly as before. Automating the tag
+does not remove that gate.
+
+If you need to re-publish an existing tag to PyPI only (no new GitHub
+Release, no new Zenodo deposit), use the `workflow_dispatch` trigger on
+`release.yml` with the `ref` input set to the existing tag.
+
 ## Issue Templates
 
 When reporting bugs or requesting features, please use the appropriate

{groupoid-0.1.0.dev2 → groupoid-0.1.0.dev4}/LIMITATIONS.md

@@ -59,6 +59,13 @@ system. The following limitations apply.
 - Requires `scipy < 1.14` for the same reason.
 - The `ripser` and `persim` packages may have build issues on
   some platforms (C++ compilation required).
+- `torch`, `pymanopt`, `POT`, and `einops` are declared as required
+  runtime dependencies but are not imported by any current code path
+  (the full test suite passes with all four uninstalled). Installing
+  `groupoid` therefore pulls in packages -- most notably `torch` -- that
+  the current code does not use. The `torch` advisory tracked in
+  SECURITY.md applies to the installed dependency, not to any code path
+  GROUPOID exercises.
 
 ## Test coverage
 
@@ -68,11 +75,13 @@ system. The following limitations apply.
   defensive guards and a `TYPE_CHECKING` import are excluded via
   `# pragma: no cover` with justifications.
 - Coverage is not validation. The transport and persistence modules are
-  now validated against ground truth (analytic parallel transport;
-  known-topology point clouds) but remain unintegrated into the pipeline.
-  The optimizer module has smoke-test coverage only: its steps stay on
-  the manifold and the curvature-adaptive learning rate behaves sensibly,
-  but its core descent/convergence behavior is not validated.
+  validated against ground truth (analytic parallel transport;
+  known-topology point clouds) and are wired into the aggregation
+  pipeline (`register_transport_from_points`; the opt-in
+  `track_divergence` flag). The optimizer module is validated for
+  descent to a known target on S^2 and for parallel-transported moment
+  accumulators, but it has no general convergence-rate analysis and is
+  not integrated into the pipeline.
 - No end-to-end test with real neural network training exists.
 - Property-based tests use 500 examples per property, which provides
   reasonable but not exhaustive coverage of edge cases.