Merge ac-partition-scheme: AC reads its own mechanism-partition scheme

Fixes a Wave-1 correctness bug from the 2026-07-13 whole-library review:
actual-causation partition enumeration silently read the IIT
mechanism_partition_scheme field, deflating AC alpha of first-order occurrences
under an IIT 3.0 pin via paper-forbidden partitions. AC now routes through its
own field (default JOINT_PARTITION_ALL, the 2019-paper family). Reconciles the
tests that codified the leak, regenerates the AC perf pin, and logs a benign
tie-resolver quirk surfaced by the fix as a ROADMAP follow-up.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UB4jbV4bQ8Y7Eywt1TNgJe

Author: wmayner

ROADMAP.md

@@ -333,6 +333,8 @@ New ideas surfaced by the 2026-06-13 audit (the roadmap "started as an engineeri
 
 *Correctness & rigor:* **(N1)** a comprehensive **paper-reproduction acceptance suite** as a CI gate — every worked example (IIT 4.0 Figs 1/2/4/6/7, Marshall 2024, AC 2019 Fig 11, Gómez p53) with pinned values, *including a network that exercises the 2026 ii-cap with non-zero φ*. **(N2)** a standing **`parallel ≡ sequential` Hypothesis invariant** in CI (the loky bug shows results can silently diverge/crash). **(N3)** recurring **mutation testing** as a scheduled gate so the golden+property net is proven to bite.
 
+**Follow-up — tie-resolver returns None on cut-equivalent partitions** *(surfaced 2026-07-15 by the AC mechanism-partition-scheme fix; open)*. `resolve_ac_partition_tie` (and the shared `cascade` Determinism level, keyed on `partition.lex_key()`) cannot break a tie between two partitions that sever the same connections but split the intact side differently — `JOINT_PARTITION_ALL` emits such cut-equivalent full-cut partitions, they share a `lex_key`, and `argmin` over equal keys leaves the tie unresolved, so `_find_mip` returns `None`. Benign for actual causation today (the full cut is maximal-α and never the minimal-α MIP, so the redundant pair never ties at the minimum; every end-to-end AC test passes), but the resolver should still resolve deterministically. Fix options: a final index-order fallback in `cascade` when `lex_key`s collide, or deduplicating cut-equivalent partitions in `all_joint_partitions`. Both touch shared machinery used by IIT, so each needs its own regression coverage. The AC fix left the contrived unit test (`test_ac_system_ties.py::TestFindMipPartitionTies`) targeting distinct-cut partitions to avoid the collision.
+
 *Performance / algorithmic:* **(N4)** a **disk-backed result cache** keyed on the P9.5 math-fingerprint, so notebook re-runs and paper reproductions skip recomputation. **(N5)** elevate the "**Rust/PyO3 kernel**" aside to a concrete, P17-gated item for the partition-enumeration + repertoire inner loops — the one lever that touches the O(2ⁿ) floor caching can't. **(N6 — landed 2026-07-11)** a **lazy / top-K relations mode** (relations are the n≥6 bottleneck that OxiDD + analytical folds only partly address). The 2026-07-07 relations exploration (`docs/superpowers/specs/2026-07-07-relations-without-materialization-design.md`) settled the design — the relation set is a deterministic view of a linear-size summary; exact/top-K/sampling query tiers verified at Fig-6D scale — and its query surface is landed on ``pyphi/relations.py`` (closed-form moments/degrees/histogram/binding/faces, lazy top-K ``strongest()``, seeded sampling, bounded ``materialize()``), discharging this item together with N24.
 
 *API ergonomics / usability:* **(N7 — landed)** one high-level **`pyphi.analyze(substrate, state, formalism=…)`** entry point. **(N8)** a full **provenance stamp** on every result (pyphi version, git sha, seed, wall-time) extending the P10 config snapshot. **(N9 — landed)** the unified labeled-export (`to_pandas`/xarray) story — already a P14d follow-on, elevated because it interlocks with the freeze. **(N11 — landed)** **Bayesian-network / dynamic-BN interop** — render a substrate as a **2-timeslice DBN** (nodes_t → nodes_{t+1}) where the TPM becomes CPDs, enabling pgmpy / d-separation / Markov-blanket workflows. The static-BN view is **unfaithful** — substrates are cyclic by construction (feedback/self-loops); the 2-TBN unrolling is the correct acyclic target. Builds on B20's topology bridge.

changelog.d/ac-partition-scheme.fix.md

@@ -0,0 +1,6 @@
+Actual-causation partition enumeration now reads its own
+`actual_causation.mechanism_partition_scheme` config field instead of silently
+inheriting the IIT `mechanism_partition_scheme`. Under an IIT 3.0 pin the AC
+alpha of first-order occurrences was deflated by the paper-forbidden bipartition
+family; AC now defaults to the 2019-paper `JOINT_PARTITION_ALL` family
+regardless of the IIT setting.

docs/superpowers/plans/2026-07-15-ac-mechanism-partition-scheme-threading.md

@@ -0,0 +1,150 @@
+# Actual Causation reads its own mechanism-partition scheme
+
+**Status:** design. Fixes a confirmed correctness bug from the 2026-07-13
+whole-library review (Wave 1).
+
+## 0. Summary
+
+Actual-causation partition enumeration silently reads the *IIT* config field
+`config.formalism.iit.mechanism_partition_scheme`, so AC α values change with an
+unrelated IIT setting, while the dedicated
+`ActualCausationConfig.mechanism_partition_scheme` field (default
+`JOINT_PARTITION_ALL`) is never read. Under any IIT 3.0 pin (which sets the IIT
+field to `JOINT_BIPARTITION`), AC enumerates partitions the 2019 paper forbids
+for first-order occurrences, deflating α to 0 where the paper defines α = ρ.
+
+The fix routes AC through its own field, mirroring how AC already threads its
+other three schemes (`alpha_measure`, `partitioned_repertoire_scheme`,
+`background_scheme`, `alpha_aggregation`). The field remains freely
+configurable — users may investigate partition variants deliberately — but the
+choice is now an explicit AC setting rather than a value silently inherited
+from an unrelated formalism.
+
+## 1. The bug
+
+`pyphi/formalism/actual_causation/compute.py` — `_find_mip` and `_get_partitions`
+call `pyphi.partition.mechanism_partitions(mechanism, purview, node_labels)`,
+which dispatches on `config.formalism.iit.mechanism_partition_scheme`
+(`partition.py:473`) and takes no scheme argument. So:
+
+- AC partition enumeration is governed by the **IIT** field.
+- `config.formalism.actual_causation.mechanism_partition_scheme` (defined at
+  `formalism.py:148`, default `JOINT_PARTITION_ALL`) has **no reader** — it is
+  dead.
+- The `iit3` preset sets `iit.mechanism_partition_scheme="JOINT_BIPARTITION"`,
+  so every AC computation pinned with `IIT_3_CONFIG` silently uses the IIT
+  bipartition family.
+
+**Why this is wrong (paper-grounded).** Albantakis et al. (2019), *What Caused
+What?*, Eq. 7 defines a partition ψ of an occurrence into `m` parts as a split
+of the mechanism with the constrained purview distributed across the parts
+(any part's purview may be empty). Fig 3B (p. 9) and p. 13 add the m=1 rule:
+for a first-order occurrence the *only* permitted partition is the full cut
+(occurrence completely severed from its purview), giving α = ρ. The paper's
+family is therefore *all* partitions of the occurrence with the m=1 non-full-cut
+cases excluded — which is precisely what `JOINT_PARTITION_ALL`
+(`all_joint_partitions`) implements, via its `partition.py:663` guard that skips
+partitions leaving the whole mechanism in one part with a non-empty purview.
+`JOINT_BIPARTITION` (m=2) and `WEDGE_TRIPARTITION` (m=3) are IIT-3.0 constructs
+that restrict to a fixed part count; the 2019 paper names neither. Under
+`JOINT_BIPARTITION`, first-order occurrences over a multi-unit purview get
+purview-splitting m=1 partitions with the occurrence intact — the "Not
+permitted" case — and minimizing over them drives α to 0.
+
+**Verified.** On the 4-node OR/AND `actual_causation_substrate`, cause link
+`_find_mip(t, CAUSE, (0,), (0,1))`: α = 0.415037 under `JOINT_PARTITION_ALL`
+(= ρ, paper-correct) vs α = 0.0 under `JOINT_BIPARTITION`.
+
+## 2. The fix
+
+### 2.1 Thread AC's own field
+
+`_resolve_ac_measures` (`formalism.py`) already resolves the AC alpha measure and
+the other three AC schemes into callables read from
+`config.formalism.actual_causation`. Extend it to also resolve
+`mechanism_partition_scheme`:
+
+```python
+mp_name = (
+    mechanism_partition_scheme_name
+    if mechanism_partition_scheme_name is not None
+    else ac.mechanism_partition_scheme
+)
+...
+"mechanism_partitions": partition_types[mp_name],
+```
+
+`partition_types[mp_name]` is the generator callable with signature
+`(mechanism, purview, node_labels) -> Iterable[partition]` — the same signature
+the global `mechanism_partitions()` invokes. An unregistered name raises
+`KeyError` from the registry (the only validation needed; no allowlist).
+
+Thread the resolved callable through the AC compute entry points
+(`_account`, `_directed_account`, `_sia`, `_find_mip`, `_find_causal_link`) as a
+`mechanism_partitions` keyword argument, exactly as `partitioned_repertoire_scheme`
+is threaded today. `_find_mip` and `_get_partitions` call the passed callable
+instead of the global `mechanism_partitions()`.
+
+### 2.2 IIT paths untouched
+
+`pyphi.partition.mechanism_partitions()` keeps reading the IIT field and keeps
+its current signature; IIT distinction/MICE computation is unchanged. Only AC
+stops routing through it.
+
+### 2.3 Configurable, informed — no restriction
+
+The AC field accepts any registered mechanism-partition scheme; selecting a
+non-default scheme is a deliberate variant investigation. The
+`ActualCausationConfig.mechanism_partition_scheme` field docstring documents the
+semantics so the choice is informed: `JOINT_PARTITION_ALL` is the 2019-paper
+family (Eq. 7 + Fig 3B); other schemes deviate — notably `JOINT_BIPARTITION`
+admits m=1 partitions the paper forbids for first-order occurrences, so it
+produces α below the published values. No config constraint or allowlist is
+added.
+
+## 3. Tests and goldens
+
+Fixing the leak changes AC results that were computed under the leaked scheme,
+and flips test expectations that codified the bug. All AC tests live under
+`test/test_actual.py` (the `TestActualCausationIIT30` class pins `IIT_3_CONFIG`);
+AC goldens live in `test/golden/zoo.py` / `test/golden/compute.py`.
+
+### 3.1 New guarantees (regression tests)
+
+- **The IIT field no longer affects AC; the AC field does.** Set
+  `iit.mechanism_partition_scheme` and
+  `actual_causation.mechanism_partition_scheme` to different values and assert AC
+  α tracks the AC field, not the IIT field.
+- **First-order occurrence is paper-correct by default.** The §1 repro: under the
+  AC default `JOINT_PARTITION_ALL`, `_find_mip(t, CAUSE, (0,), (0,1)).alpha` =
+  ρ = 0.415037, not 0.
+
+### 3.2 Expectation changes (bug was codified)
+
+- `test_sia_cause_direction` asserts `alpha == 0.0` under the inherited
+  `JOINT_BIPARTITION`. After the fix, AC uses its own default
+  `JOINT_PARTITION_ALL`, so the cause α is the paper value. Re-assert the
+  recomputed value. A separate test may set the *AC* field to `JOINT_BIPARTITION`
+  explicitly to retain coverage of that regime as a deliberate variant.
+- `test_prevention` overrides the *IIT* field to `WEDGE_TRIPARTITION`. Repoint the
+  override to the *AC* field; `WEDGE_TRIPARTITION` remains a legitimate
+  intentional variant. Re-verify the asserted values under the corrected routing.
+- The remaining `TestActualCausationIIT30` tests and AC goldens recompute under
+  `JOINT_PARTITION_ALL`. Regenerate affected goldens deliberately, each documented
+  as previously computed under the leaked IIT scheme.
+
+### 3.3 Verification
+
+`uv run pytest test/test_actual.py` and the golden regression suite green;
+`uv run pytest` (no path argument) green for the doctest sweep, since the AC
+config field docstring changes.
+
+## 4. Scope boundaries
+
+- **AC only.** IIT and IIT 3.0 mechanism partitioning are untouched.
+- **No new partition schemes.** The fix routes existing schemes correctly; it does
+  not add or modify any `partition_types` entry.
+- **No config-constraint machinery.** The field stays a free choice; the registry
+  lookup is the only validation.
+- **Not in scope:** the other Wave 1 remainders (macro TPM bugs, factored-backend
+  select crash) are separate fixes.

docs/superpowers/specs/2026-07-15-ac-mechanism-partition-scheme-threading-design.md

@@ -56,6 +56,11 @@ option-by-option reference, loaded only when working with this directory.
 
 - **`mechanism_partition_scheme`**: Default `"JOINT_PARTITION_ALL"`
 - **`system_partition_scheme`**: Default `"DIRECTED_SET_PARTITION"`
+- **`config.formalism.actual_causation.mechanism_partition_scheme`**: AC
+  partition family (default `"JOINT_PARTITION_ALL"`, the Albantakis et al. 2019
+  Eq. 7 / Fig. 3B family). Read independently of the IIT field above;
+  `"JOINT_BIPARTITION"` is a deliberate variant that deviates from the published
+  α on first-order occurrences.
 
 ## Debugging & Output (`config.infrastructure`)
 

pyphi/conf/CLAUDE.md

@@ -162,6 +162,12 @@ class ActualCausationConfig:
 
     version: str = "AC_2019"
     alpha_measure: str = "PMI"
+    # The partition family for actual-causation MIP search. JOINT_PARTITION_ALL
+    # is the Albantakis et al. (2019) family (Eq. 7 + Fig. 3B: all partitions of
+    # the occurrence, excluding the m=1 non-full-cut cases forbidden for
+    # first-order occurrences). Other registered schemes are deliberate
+    # variants — notably JOINT_BIPARTITION admits those m=1 partitions and so
+    # yields alpha below the published values on first-order occurrences.
     mechanism_partition_scheme: str = "JOINT_PARTITION_ALL"
     partitioned_repertoire_scheme: str = "PRODUCT"
     background_scheme: str = "UNIFORM"

pyphi/conf/formalism.py

@@ -38,7 +38,7 @@
 from pyphi.models import _null_ac_ria
 from pyphi.models import _null_ac_sia
 from pyphi.parallel import map_reduce
-from pyphi.partition import mechanism_partitions
+from pyphi.partition import partition_types
 from pyphi.registry import Registry
 
 if TYPE_CHECKING:
@@ -198,6 +198,21 @@ def account_distance(A1, A2):
     return sum([action.alpha for action in A1]) - sum([action.alpha for action in A2])
 
 
+def _ac_mechanism_partitions(mechanism, purview, node_labels=None):
+    """Yield mechanism partitions under the actual-causation partition scheme.
+
+    Resolves ``config.formalism.actual_causation.mechanism_partition_scheme``
+    through the partition-scheme registry at call time, so actual-causation
+    partitioning is governed by the AC formalism and never by the IIT
+    ``mechanism_partition_scheme`` field. The default ``JOINT_PARTITION_ALL`` is
+    the partition family of Albantakis et al. (2019), Eq. 7 and Fig. 3B: all
+    partitions of the occurrence, excluding the m=1 non-full-cut cases the paper
+    forbids for first-order occurrences.
+    """
+    scheme = config.formalism.actual_causation.mechanism_partition_scheme
+    return partition_types[scheme](mechanism, purview, node_labels)
+
+
 def _find_mip(
     transition: Transition,
     direction,
@@ -254,7 +269,9 @@ def _find_mip(
 
     probability = transition.probability(direction, mechanism, purview)
     candidates: list[AcRepertoireIrreducibilityAnalysis] = []
-    for partition in mechanism_partitions(mechanism, purview, transition.node_labels):
+    for partition in _ac_mechanism_partitions(
+        mechanism, purview, transition.node_labels
+    ):
         partitioned_probability = transition.partitioned_probability(
             direction,
             partition,
@@ -557,7 +574,7 @@ def _get_partitions(transition, direction):
     else:
         mechanism = transition.mechanism_indices(direction)
         purview = transition.purview_indices(direction)
-        for inner_partition in mechanism_partitions(
+        for inner_partition in _ac_mechanism_partitions(
             mechanism, purview, transition.node_labels
         ):
             yield DirectedJointPartition(

pyphi/formalism/actual_causation/compute.py

@@ -2,8 +2,8 @@
   "actual_causation::account": {
     "conf/:override": 2,
     "relations.py:relations": 0,
-    "repertoire_algebra.py:cause_repertoire": 41,
-    "repertoire_algebra.py:effect_repertoire": 43,
+    "repertoire_algebra.py:cause_repertoire": 54,
+    "repertoire_algebra.py:effect_repertoire": 63,
     "system.py:find_mip": 0
   },
   "basic_iit3_emd::sia": {

test/data/perf/call_counts.json

@@ -146,7 +146,9 @@ def _find_mip_with_alphas(make_alphas):
         purview = (0, 1)
         n = len(
             list(
-                compute.mechanism_partitions(mechanism, purview, transition.node_labels)
+                compute._ac_mechanism_partitions(
+                    mechanism, purview, transition.node_labels
+                )
             )
         )
         alphas = make_alphas(n)
@@ -170,8 +172,13 @@ def test_unique_minimum_yields_no_partition_ties(self):
         assert ria.partition_ties is None
 
     def test_tied_minimum_yields_exact_alpha_cluster(self):
+        # The tied minimum is placed on the last two partitions, which are
+        # distinct cuts. The JOINT_PARTITION_ALL family leads with cut-equivalent
+        # full-cut partitions (mechanism intact vs. internally split, same cut
+        # matrix, same lex_key); a minimum landing on that redundant pair has no
+        # unique lex-canonical winner (see the resolver follow-up in ROADMAP).
         ria, alphas = _find_mip_with_alphas(
-            lambda n: [0.2, 0.2] + [0.9 + 0.1 * i for i in range(n - 2)]
+            lambda n: [0.9 + 0.1 * i for i in range(n - 2)] + [0.2, 0.2]
         )
         assert len(alphas) > 2  # cluster must be a strict subset of candidates
         assert ria.partition_ties is not None

test/formalism/test_ac_system_ties.py

@@ -90,9 +90,9 @@
 from pyphi.conf.formalism import IITConfig
 from pyphi.direction import Direction
 from pyphi.formalism import iit3
-from pyphi.formalism.actual_causation.compute import mechanism_partitions
 from pyphi.formalism.actual_causation.compute import probability_distance
 from pyphi.measures.distribution import generalized_intrinsic_difference
+from pyphi.partition import mechanism_partitions
 from test.hypothesis_utils import binary_state
 from test.hypothesis_utils import small_substrate