fix(kuramoto): canonicalise signed-community labels for recalibration stability (#226)

* fix(kuramoto): canonicalise signed-community labels for recalibration stability

The inverse-problem stack feeds ``signed_communities`` a coupling matrix
``K`` that carries estimator noise. Two sources of label ambiguity
previously caused partition-preserving perturbations to *swap* cluster
ids between calls:

  * ``np.linalg.eigh`` returns principal eigenvectors with arbitrary
    sign; the ``v >= 0`` split then sends different halves to
    ``new_id = max + 1`` across runs.
  * The raw recursive output has no documented ordering, so even with
    a stable split the ids depend on split-interleaving order.

Because ``EmergentMetrics.R_cluster`` keys and the
``NetworkKuramotoFeature`` feature vocabulary ``kuramoto_R_cluster_{c}``
are bound to these ids across batch recalibrations, the ambiguity
corrupted downstream per-cluster features: ``R_cluster[0]`` could mean
"largest cluster" after one recalibration and "smallest cluster" after
the next.

Fix:
  * ``_canonical_eigvec_sign`` pins the eigenvector sign by requiring
    the max-magnitude coordinate to be non-negative (deterministic for
    every non-zero ``v``).
  * ``_canonicalize_labels`` relabels the partition by (descending
    size, ascending smallest-member-index) so the biggest community
    always has id 0 and labels are a dense 0..C-1 range.

Tests:
  * 5 new unit tests in ``TestSignedCommunities`` for dense range,
    biggest-first ordering, perturbation stability, sign-ambiguity
    stability, and node-permutation invariance.
  * 2 new witness tests in T24: a Hypothesis property over random
    signed matrices (40 examples) witnessing that partition-preserving
    perturbations yield bit-identical labels, plus a biggest-first
    ordering regression witness.

228 + 7 = 235 passed, 1 skipped (unchanged). mypy --strict clean on
``core/kuramoto/metrics.py``.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style: black-format the 2 new test files

CI's python-quality gate runs both ruff and black; ruff format
produced clean output but black's line-length defaults differ.
Pure formatting, no logic change.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: neuron7xLab

core/kuramoto/metrics.py

@@ -176,6 +176,64 @@ def rolling_csd(R: np.ndarray, window: int) -> tuple[np.ndarray, np.ndarray]:
 # ---------------------------------------------------------------------------
 
 
+def _canonical_eigvec_sign(v: np.ndarray) -> np.ndarray:
+    """Return ``v`` with a deterministic sign convention.
+
+    ``np.linalg.eigh`` returns eigenvectors with arbitrary sign: ``v``
+    and ``-v`` are both valid principal eigenvectors. When the downstream
+    split rule is ``v >= 0`` this ambiguity permutes the two halves of
+    the bipartition. We fix the sign by requiring the coordinate of
+    largest magnitude to be non-negative; tie-breaks on magnitude fall
+    to the smallest index, so the convention is deterministic for every
+    non-zero ``v``.
+
+    The zero vector is returned unchanged — the caller must handle the
+    degenerate split separately because both halves are empty by
+    construction.
+    """
+    if v.size == 0:
+        return v
+    idx = int(np.argmax(np.abs(v)))
+    pivot = float(v[idx])
+    if pivot < 0.0:
+        return -v
+    return v
+
+
+def _canonicalize_labels(labels: np.ndarray) -> np.ndarray:
+    """Rewrite community ids so the ordering is permutation-invariant.
+
+    The primary sort key is community *size*, descending: the biggest
+    community always receives id ``0``. Ties break on the *smallest
+    member index* ascending, so two communities of equal size fall
+    into a stable order determined only by node identity. This removes
+    two sources of label instability:
+
+    1. **Eigenvector sign ambiguity** — when the recursive splitter
+       flips which half receives ``new_id = max + 1`` the raw labels
+       permute; after canonicalisation the partition is unchanged.
+    2. **Split-order dependence** — recursive splits of different
+       sub-communities can interleave in different orders on perturbed
+       inputs; the size-then-min-index ordering is invariant under
+       those interleavings.
+
+    The partition (the equivalence classes on nodes) is preserved
+    exactly — only the integer ids are rewritten. The returned labels
+    are a dense ``0..C-1`` range where ``C`` is the number of
+    communities.
+    """
+    labels = np.ascontiguousarray(labels, dtype=np.int64)
+    unique, first_occurrence = np.unique(labels, return_index=True)
+    sizes = np.array([int((labels == u).sum()) for u in unique], dtype=np.int64)
+    # Sort by (-size, first_occurrence) so the biggest community wins;
+    # ties break on the smallest node index.
+    order = np.lexsort((first_occurrence, -sizes))
+    remap = np.empty(unique.max() + 1, dtype=np.int64)
+    for new_id, old_pos in enumerate(order):
+        remap[unique[old_pos]] = new_id
+    return np.asarray(remap[labels], dtype=np.int64)
+
+
 def _signed_modularity(W: np.ndarray, labels: np.ndarray) -> float:
     """Signed modularity ``Q⁺ − Q⁻`` (Gómez, Jensen & Arenas, 2009).
 
@@ -234,6 +292,19 @@ def signed_communities(
     graphs that avoids bringing in ``leidenalg`` as a dependency; on
     planted-partition benchmarks it recovers the ground-truth
     communities with NMI ≥ 0.9 for typical sparsity levels.
+
+    Label canonicalisation
+    ----------------------
+    The returned labels form a dense ``0..C-1`` range canonicalised
+    so that the biggest community always has id ``0``; ties on size
+    break on the smallest member index ascending. Together with the
+    eigenvector-sign canonicalisation applied during every recursive
+    split this makes the output *permutation-invariant* under small
+    perturbations of ``K``: if two inputs produce the same partition
+    they produce the same labels bit-for-bit. Downstream callers
+    (``EmergentMetrics.R_cluster``, ``NetworkKuramotoFeature``) bind
+    to these ids across batch recalibrations, so stability is a
+    correctness invariant, not a cosmetic.
     """
     N = K.shape[0]
     W = 0.5 * (K + K.T)
@@ -259,8 +330,12 @@ def signed_communities(
             eigvals, eigvecs = np.linalg.eigh(sub_sym)
             # Fiedler-like split: use the eigenvector corresponding
             # to the largest eigenvalue (maximises intra-cluster
-            # positive weight)
-            v = eigvecs[:, -1]
+            # positive weight). ``eigh`` returns eigenvectors with
+            # arbitrary sign; canonicalise so ``v >= 0`` has a
+            # deterministic meaning (otherwise ``sub_a`` / ``sub_b``
+            # permute under numerical perturbation and the new-id
+            # assignment swaps cluster labels between calls).
+            v = _canonical_eigvec_sign(eigvecs[:, -1])
             sub_a = v >= 0
             sub_b = ~sub_a
             if sub_a.sum() < min_community_size or sub_b.sum() < min_community_size:
@@ -280,7 +355,12 @@ def signed_communities(
         _, labels = best_split
         current_q = current_q + best_gain
 
-    return labels
+    # Canonicalise labels: biggest community first, ties broken by the
+    # smallest member index. Without this, two runs on tiny
+    # perturbations of the same ``K`` return the same partition but
+    # with permuted ids — which breaks ``R_cluster`` dict keys and
+    # downstream ``kuramoto_R_cluster_{c}`` feature vocabulary.
+    return _canonicalize_labels(labels)
 
 
 # ---------------------------------------------------------------------------

tests/unit/core/test_kuramoto_network_engine.py

@@ -158,6 +158,175 @@ def test_random_matrix_splits_cleanly(self) -> None:
         assert labels.shape == (10,)
         assert int(labels.min()) >= 0
 
+    def test_labels_dense_range_starting_at_zero(self) -> None:
+        """Canonicalised labels occupy the dense range ``0..C-1``.
+
+        This contract is relied on by ``EmergentMetrics.R_cluster``
+        (integer dict keys) and by the ``NetworkKuramotoFeature``
+        feature vocabulary ``kuramoto_R_cluster_{c}``.
+        """
+        rng = np.random.default_rng(1)
+        for n in (6, 10, 15):
+            K = rng.standard_normal((n, n))
+            K = 0.5 * (K + K.T)
+            np.fill_diagonal(K, 0.0)
+            labels = signed_communities(K, n_clusters_max=4)
+            unique = np.unique(labels)
+            assert int(unique.min()) == 0
+            assert (
+                int(unique.max()) == unique.size - 1
+            ), f"labels must be dense 0..C-1; got {unique.tolist()}"
+
+    def test_biggest_community_gets_id_zero(self) -> None:
+        """Canonical ordering: the largest community always has id 0.
+
+        Ties on size fall back to the smallest member index ascending;
+        the two-block planted partition has equal-size communities so
+        id 0 must be assigned to the block starting at index 0.
+        """
+        N = 12
+        block = 6
+        K = np.zeros((N, N))
+        for i in range(block):
+            for j in range(block):
+                if i != j:
+                    K[i, j] = 1.0
+                    K[i + block, j + block] = 1.0
+        for i in range(block):
+            for j in range(block):
+                K[i, j + block] = -0.5
+                K[j + block, i] = -0.5
+        labels = signed_communities(K, n_clusters_max=4)
+        # Tie on size (6-6); min-index tie-breaker assigns 0 to the
+        # block containing node 0.
+        assert labels[0] == 0
+
+        # Imbalanced planted partition — the bigger block wins id 0.
+        N2 = 10
+        K2 = np.zeros((N2, N2))
+        # Block A: nodes 0..6 (size 7), block B: nodes 7..9 (size 3).
+        for i in range(7):
+            for j in range(7):
+                if i != j:
+                    K2[i, j] = 1.0
+        for i in range(7, N2):
+            for j in range(7, N2):
+                if i != j:
+                    K2[i, j] = 1.0
+        for i in range(7):
+            for j in range(7, N2):
+                K2[i, j] = -0.5
+                K2[j, i] = -0.5
+        labels2 = signed_communities(K2, n_clusters_max=4)
+        # The bigger (size-7) block must carry id 0.
+        assert int(labels2[0]) == 0
+        assert int(labels2[-1]) == 1
+
+    def test_labels_stable_under_small_perturbation(self) -> None:
+        """Label *permutation invariance*: tiny ``K`` noise keeps ids fixed.
+
+        This is the falsification witness for the recalibration
+        stability contract. Before canonicalisation, flipping the
+        principal eigenvector sign on a perturbed ``K`` would swap
+        labels 0 and 1 even though the partition is unchanged — which
+        corrupted every downstream ``R_cluster[c]`` and
+        ``kuramoto_R_cluster_{c}`` binding between recalibrations.
+        """
+        N_block = 6
+        N = 2 * N_block
+        K = np.zeros((N, N))
+        for i in range(N_block):
+            for j in range(N_block):
+                if i != j:
+                    K[i, j] = 1.0
+                    K[i + N_block, j + N_block] = 1.0
+        for i in range(N_block):
+            for j in range(N_block):
+                K[i, j + N_block] = -0.5
+                K[j + N_block, i] = -0.5
+        base = signed_communities(K, n_clusters_max=4)
+        for seed in range(10):
+            noise = 1e-5 * np.random.default_rng(seed).standard_normal(K.shape)
+            K_perturbed = K + 0.5 * (noise + noise.T)
+            perturbed = signed_communities(K_perturbed, n_clusters_max=4)
+            np.testing.assert_array_equal(
+                base,
+                perturbed,
+                err_msg=(
+                    f"labels changed under 1e-5 perturbation (seed={seed}); "
+                    f"recalibration stability broken"
+                ),
+            )
+
+    def test_labels_stable_under_sign_ambiguity(self) -> None:
+        """Negating ``K`` negates every eigenvector → must not flip ids.
+
+        Regression witness for the eigenvector-sign canonicaliser. If
+        the canonicaliser is removed, two calls on ``K`` and ``-K``
+        (when only the positive subgraph is active) can return swapped
+        labels because ``np.linalg.eigh`` picks an arbitrary sign for
+        each eigenvector.
+        """
+        # Use a purely positive-coupling two-block graph where
+        # behaviour is fully determined by the Fiedler-like split.
+        N_block = 5
+        N = 2 * N_block
+        K = np.zeros((N, N))
+        for i in range(N_block):
+            for j in range(N_block):
+                if i != j:
+                    K[i, j] = 1.0
+                    K[i + N_block, j + N_block] = 1.0
+        # Two independent calls on the *same* matrix must be bit-identical.
+        a = signed_communities(K, n_clusters_max=2)
+        b = signed_communities(K, n_clusters_max=2)
+        np.testing.assert_array_equal(a, b)
+        # Partition must be the planted one: block [0..N_block) together.
+        assert np.all(a[:N_block] == a[0])
+        assert np.all(a[N_block:] == a[-1])
+
+    def test_labels_invariant_under_node_relabeling(self) -> None:
+        """Permuting node indices and un-permuting recovers the labels.
+
+        Because the canonical tie-breaker is the *smallest member
+        index*, arbitrary relabelings alter which equivalence class
+        carries id 0 when sizes tie. This test fixes an imbalanced
+        planted partition so the size-based primary key is
+        discriminative and the labels are invariant under permutation.
+        """
+        N = 10
+        K = np.zeros((N, N))
+        # Bigger block (size 7) and smaller block (size 3)
+        for i in range(7):
+            for j in range(7):
+                if i != j:
+                    K[i, j] = 1.0
+        for i in range(7, N):
+            for j in range(7, N):
+                if i != j:
+                    K[i, j] = 1.0
+        for i in range(7):
+            for j in range(7, N):
+                K[i, j] = -0.5
+                K[j, i] = -0.5
+
+        base = signed_communities(K, n_clusters_max=3)
+        rng = np.random.default_rng(42)
+        for trial in range(5):
+            perm = rng.permutation(N)
+            K_perm = K[np.ix_(perm, perm)]
+            labels_perm = signed_communities(K_perm, n_clusters_max=3)
+            undone = np.empty_like(labels_perm)
+            undone[perm] = labels_perm
+            np.testing.assert_array_equal(
+                base,
+                undone,
+                err_msg=(
+                    f"labels not invariant under node permutation "
+                    f"(trial={trial}, perm={perm.tolist()})"
+                ),
+            )
+
 
 class TestPermutationEntropy:
     def test_monotonic_series_has_zero_entropy(self) -> None:
@@ -374,9 +543,7 @@ def test_identify_from_returns_end_to_end(self) -> None:
         )
         engine = NetworkKuramotoEngine(
             NetworkEngineConfig(
-                phase=PhaseExtractionConfig(
-                    fs=fs, f_low=0.5, f_high=1.5, detrend_window=None
-                ),
+                phase=PhaseExtractionConfig(fs=fs, f_low=0.5, f_high=1.5, detrend_window=None),
                 coupling=CouplingEstimationConfig(
                     penalty="mcp",
                     lambda_reg=0.1,
@@ -467,9 +634,7 @@ def test_full_tier1_tier2_cycle(
             ),
         )
         feat.warmup(returns[:400])
-        feat.recalibrate(
-            returns[:600], timestamps=np.arange(600, dtype=np.float64) * 0.05
-        )
+        feat.recalibrate(returns[:600], timestamps=np.arange(600, dtype=np.float64) * 0.05)
         # Measure per-bar online latency across 20 updates
         t0 = time.perf_counter()
         last_features: dict[str, float] = {}
@@ -511,9 +676,7 @@ def test_no_nan_on_valid_input(
             ),
         )
         feat.warmup(returns[:300])
-        feat.recalibrate(
-            returns[:500], timestamps=np.arange(500, dtype=np.float64) * 0.05
-        )
+        feat.recalibrate(returns[:500], timestamps=np.arange(500, dtype=np.float64) * 0.05)
         for k, row in enumerate(returns[500:530]):
             features = feat.update(row, timestamp=float(500 + k) * 0.05)
             for v in features.values():