se-interpretive-kernel 0.1.0__py3-none-any.whl

se_interpretive_kernel/__init__.py

@@ -0,0 +1,7 @@
+"""SE Interpretive Kernel (SE-220).
+
+A companion to the paper, providing executable finite constructions and checks
+for the interpretation-induced kernel, the generated occurrence regime, their
+adjunction, interpretive thresholds, pairwise demand, and incompatibility
+witnesses.
+"""

se_interpretive_kernel/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

se_interpretive_kernel/artifact.py

@@ -0,0 +1,76 @@
+"""artifact.py - Finite comparison artifact for the Interpretive Kernel.
+
+An :class:`Artifact` holds the data the theory starts from:
+
+- a finite carrier of frames (the paper's E),
+- a finite carrier of outputs (the paper's A),
+- a finite set of probes (the paper's P), and
+- a total interpretation table I : P x E -> A.
+
+It holds no equivalence relations. Frame regimes and output regimes are
+:class:`~se_interpretive_kernel.partition.Partition` values supplied
+separately, over ``frames`` and ``outputs`` in the order stored here.
+
+Nothing here decides which probes, frames, or outputs a domain ought to
+declare, and nothing here shows that an interpretation is correct.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+
+from se_interpretive_kernel.partition import Item
+
+
+@dataclass(frozen=True)
+class Artifact:
+    """Contain the finite data of one comparison.
+
+    ``table`` maps ``(probe, frame)`` to an output. It must be defined for
+    every probe and frame, and every value must be an output. Totality is
+    required by the theory: a missing or inapplicable result must be
+    represented by a declared output value.
+
+    ``label`` is a human-readable name for diagnostics.
+    """
+
+    frames: tuple[Item, ...]
+    outputs: tuple[Item, ...]
+    probes: tuple[Item, ...]
+    table: Mapping[tuple[Item, Item], Item]
+    label: str = ""
+
+    def __post_init__(self) -> None:
+        """Reject malformed data: duplicates, missing entries, unknown outputs."""
+        if len(set(self.frames)) != len(self.frames):
+            msg = "frames must be distinct"
+            raise ValueError(msg)
+        if len(set(self.outputs)) != len(self.outputs):
+            msg = "outputs must be distinct"
+            raise ValueError(msg)
+        if len(set(self.probes)) != len(self.probes):
+            msg = "probes must be distinct"
+            raise ValueError(msg)
+        output_set = set(self.outputs)
+        for probe in self.probes:
+            for frame in self.frames:
+                key = (probe, frame)
+                if key not in self.table:
+                    msg = f"interpretation is not total: missing {key!r}"
+                    raise ValueError(msg)
+                if self.table[key] not in output_set:
+                    msg = f"interpretation value {self.table[key]!r} is not an output"
+                    raise ValueError(msg)
+
+    def interpret(self, probe: Item, frame: Item) -> Item:
+        """Return I(probe, frame)."""
+        return self.table[(probe, frame)]
+
+    def require_selected(self, selected: Sequence[Item]) -> None:
+        """Reject a selection that names a probe the artifact does not have."""
+        probe_set = set(self.probes)
+        for probe in selected:
+            if probe not in probe_set:
+                msg = f"selected probe {probe!r} is not a probe of this artifact"
+                raise ValueError(msg)

se_interpretive_kernel/cases.py

@@ -0,0 +1,120 @@
+"""cases.py - Finite cases mirroring the Lean examples.
+
+Each function returns an :class:`Artifact`, using the same carriers and
+interpretation as the corresponding Lean example in
+``SETest/InterpretiveKernel``. The assertions about these cases live in
+``check.py``.
+
+Lean names are given in each docstring. Carriers of size 2 or 3 use integers;
+Booleans are written 0 and 1.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .artifact import Artifact
+from .partition import Item, Partition
+
+
+def _table(frames, probes, rule):
+    """Return the table {(p, f): rule(p, f)}."""
+    return {(p, f): rule(p, f) for p in probes for f in frames}
+
+
+def example_a() -> Artifact:
+    """Return Example A: four frames, parity regime, XOR interpretation."""
+    frames, probes, outputs = (0, 1, 2, 3), (0, 1), (0, 1)
+    return Artifact(
+        frames, outputs, probes, _table(frames, probes, lambda p, f: p ^ (f % 2)), "A"
+    )
+
+
+def example_b() -> Artifact:
+    """Return Example B: identity interpretation with a single probe."""
+    frames, probes, outputs = (0, 1), ("p",), (0, 1)
+    return Artifact(
+        frames, outputs, probes, _table(frames, probes, lambda _p, f: f), "B"
+    )
+
+
+def example_c() -> Artifact:
+    """Return Example C: the interpretation only records whether the frame is 0."""
+    frames, probes, outputs = (0, 1, 2), (0, 1), (0, 1)
+    return Artifact(
+        frames, outputs, probes, _table(frames, probes, lambda _p, f: int(f == 0)), "C"
+    )
+
+
+def example_d() -> Artifact:
+    """Return Example D: I(p, f) = p and f, so probe 0 erases the frame."""
+    frames, probes, outputs = (0, 1), (0, 1), (0, 1)
+    return Artifact(
+        frames, outputs, probes, _table(frames, probes, lambda p, f: p & f), "D"
+    )
+
+
+def example_e() -> Artifact:
+    """Return Example E: two probes whose images chain 0~1 and 1~2."""
+    frames, probes, outputs = (0, 1), (0, 1), (0, 1, 2)
+
+    def rule(p: int, f: int) -> int:
+        return (2 if f else 1) if p else (1 if f else 0)
+
+    return Artifact(frames, outputs, probes, _table(frames, probes, rule), "E")
+
+
+def example_f() -> Artifact:
+    """Return Example F: one frame, constant output, so the counit is strict."""
+    frames, probes, outputs = (0,), ("p",), (0, 1)
+    return Artifact(
+        frames, outputs, probes, _table(frames, probes, lambda _p, _f: 0), "F"
+    )
+
+
+def example_g() -> Artifact:
+    """Return Example G: K need not preserve joins."""
+    frames, probes, outputs = (0, 1), ("p",), (0, 1, 2)
+    return Artifact(
+        frames,
+        outputs,
+        probes,
+        _table(frames, probes, lambda _p, f: 0 if f == 0 else 2),
+        "G",
+    )
+
+
+def example_h() -> Artifact:
+    """Return Example H: L need not preserve meets."""
+    frames, probes, outputs = (0, 1, 2), ("p",), (0, 1)
+    return Artifact(
+        frames, outputs, probes, _table(frames, probes, lambda _p, f: int(f != 0)), "H"
+    )
+
+
+def example_i() -> Artifact:
+    """Return Example I: identity interpretation, incomparable thresholds."""
+    frames, probes, outputs = (0, 1, 2), ("p",), (0, 1, 2)
+    return Artifact(
+        frames, outputs, probes, _table(frames, probes, lambda _p, f: f), "I"
+    )
+
+
+def merge(carrier: Sequence[Item], a: Item, b: Item) -> Partition:
+    """Return the partition of ``carrier`` that merges only ``a`` and ``b``."""
+    return Partition.from_pairs(carrier, [(a, b)])
+
+
+def all_cases() -> list[Artifact]:
+    """Return every example artifact."""
+    return [
+        example_a(),
+        example_b(),
+        example_c(),
+        example_d(),
+        example_e(),
+        example_f(),
+        example_g(),
+        example_h(),
+        example_i(),
+    ]

se_interpretive_kernel/check.py

@@ -0,0 +1,293 @@
+"""check.py - Exhaustive and randomized checks of the Interpretive Kernel laws.
+
+Replaces the SE-210 check. Verifies, on finite artifacts, the statements that
+the Lean development proves in general:
+
+- the Galois adjunction  L_Q(phi) <= rho  iff  phi <= K_Q(rho),
+- unit, counit, and the identities L K L = L and K L K = K,
+- monotonicity in the regimes and in the probe family,
+- K preserves meets and L preserves joins,
+- probe-union duality and the empty family,
+- generating-set reduction,
+- agreement of the partition-based code with the literal pair-set oracle,
+- witnesses, thresholds, and pairwise demand,
+- the specific phenomena of Examples A to I.
+
+For each artifact, every selected family Q, every phi on the frames, and every
+rho on the outputs is enumerated. This is evidence for small carriers, not a
+proof. The proofs are in the Lean library.
+
+Usage::
+
+    python -m se_interpretive_kernel.check [--random N] [--seed S]
+
+Exits nonzero if any check fails.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+from itertools import combinations
+import sys
+
+from .artifact import Artifact
+from .cases import (
+    all_cases,
+    example_a,
+    example_b,
+    example_c,
+    example_d,
+    example_e,
+    example_f,
+    example_g,
+    example_h,
+    example_i,
+    merge,
+)
+from .demand import demand, kernel_from_demand, ultrametric_violations
+from .generated import generated, generated_all_pairs, threshold
+from .kernel import coherent, kernel
+from .literal import generated_pairs, generator_pairs, kernel_pairs, pairs_of
+from .partition import Item, Partition, all_partitions
+from .sampling import random_artifacts
+from .witness import find_witness, witness_is_valid
+
+
+def probe_families(artifact: Artifact) -> list[tuple[Item, ...]]:
+    """Return every subset of the probes, smallest first, in probe order."""
+    subsets: list[tuple[Item, ...]] = []
+    for size in range(len(artifact.probes) + 1):
+        subsets.extend(combinations(artifact.probes, size))
+    return subsets
+
+
+def check_artifact(artifact: Artifact) -> list[str]:
+    """Return a description of every law violated on this artifact."""
+    failures: list[str] = []
+    name = artifact.label or "artifact"
+
+    def fail(law: str, detail: str = "") -> None:
+        failures.append(f"{name}: {law} {detail}".rstrip())
+
+    frame_regimes = list(all_partitions(artifact.frames))
+    output_regimes = list(all_partitions(artifact.outputs))
+    frame_top = Partition.indiscrete(artifact.frames)
+    output_bottom = Partition.discrete(artifact.outputs)
+    output_top = Partition.indiscrete(artifact.outputs)
+    frame_bottom = Partition.discrete(artifact.frames)
+    families = probe_families(artifact)
+
+    for q in families:
+        # Totals and bottoms.
+        if kernel(artifact, q, output_top) != frame_top:
+            fail("K(total) = total", f"Q={q}")
+        if generated(artifact, q, frame_bottom) != output_bottom:
+            fail("L(discrete) = discrete", f"Q={q}")
+
+        for phi in frame_regimes:
+            lift = generated(artifact, q, phi)
+            if lift != generated_all_pairs(artifact, q, phi):
+                fail("generating-set reduction", f"Q={q} phi={phi.labels}")
+            if pairs_of(lift) != generated_pairs(artifact, q, pairs_of(phi)):
+                fail("L matches literal oracle", f"Q={q} phi={phi.labels}")
+            if not phi.refines(kernel(artifact, q, lift)):
+                fail("unit", f"Q={q} phi={phi.labels}")
+            if generated(artifact, q, kernel(artifact, q, lift)) != lift:
+                fail("L K L = L", f"Q={q} phi={phi.labels}")
+            if threshold(artifact, q, phi) != lift:
+                fail("threshold = L", f"Q={q} phi={phi.labels}")
+
+        for rho in output_regimes:
+            ker = kernel(artifact, q, rho)
+            if pairs_of(ker) != kernel_pairs(artifact, q, pairs_of(rho)):
+                fail("K matches literal oracle", f"Q={q} rho={rho.labels}")
+            if not generated(artifact, q, ker).refines(rho):
+                fail("counit", f"Q={q} rho={rho.labels}")
+            if kernel(artifact, q, generated(artifact, q, ker)) != ker:
+                fail("K L K = K", f"Q={q} rho={rho.labels}")
+            if kernel_from_demand(artifact, q, rho) != ker:
+                fail("kernel via demand", f"Q={q} rho={rho.labels}")
+
+            for x in artifact.frames:
+                for y in artifact.frames:
+                    if ker.same(x, y) != demand(artifact, q, x, y).refines(rho):
+                        fail("K iff demand refines rho", f"Q={q} rho={rho.labels}")
+
+            for phi in frame_regimes:
+                adjoint_left = generated(artifact, q, phi).refines(rho)
+                adjoint_right = phi.refines(ker)
+                if adjoint_left != adjoint_right:
+                    fail("adjunction", f"Q={q} phi={phi.labels} rho={rho.labels}")
+                witness = find_witness(artifact, q, phi, rho)
+                if adjoint_right != (witness is None):
+                    fail(
+                        "witness iff incoherent",
+                        f"Q={q} phi={phi.labels} rho={rho.labels}",
+                    )
+                if witness is not None and not witness_is_valid(
+                    artifact, q, phi, rho, witness
+                ):
+                    fail("witness is valid", f"Q={q} phi={phi.labels} rho={rho.labels}")
+                if coherent(artifact, q, phi, rho) != adjoint_right:
+                    fail("coherent agrees with refinement")
+
+        # Monotonicity and preservation.
+        for r1 in output_regimes:
+            for r2 in output_regimes:
+                k1, k2 = kernel(artifact, q, r1), kernel(artifact, q, r2)
+                if r1.refines(r2) and not k1.refines(k2):
+                    fail("K monotone")
+                if kernel(artifact, q, r1.meet(r2)) != k1.meet(k2):
+                    fail("K preserves meets", f"Q={q}")
+        for p1 in frame_regimes:
+            for p2 in frame_regimes:
+                l1, l2 = generated(artifact, q, p1), generated(artifact, q, p2)
+                if p1.refines(p2) and not l1.refines(l2):
+                    fail("L monotone")
+                if generated(artifact, q, p1.join(p2)) != l1.join(l2):
+                    fail("L preserves joins", f"Q={q}")
+
+    # Probe-family laws.
+    for q1 in families:
+        for q2 in families:
+            union = tuple(p for p in artifact.probes if p in q1 or p in q2)
+            if set(q1) <= set(q2):
+                for rho in output_regimes:
+                    if not kernel(artifact, q2, rho).refines(kernel(artifact, q1, rho)):
+                        fail("more probes refine K", f"{q1} <= {q2}")
+                for phi in frame_regimes:
+                    if not generated(artifact, q1, phi).refines(
+                        generated(artifact, q2, phi)
+                    ):
+                        fail("more probes enlarge L", f"{q1} <= {q2}")
+            for rho in output_regimes:
+                if kernel(artifact, union, rho) != kernel(artifact, q1, rho).meet(
+                    kernel(artifact, q2, rho)
+                ):
+                    fail("K probe-union duality", f"{q1} {q2}")
+            for phi in frame_regimes:
+                if generated(artifact, union, phi) != generated(artifact, q1, phi).join(
+                    generated(artifact, q2, phi)
+                ):
+                    fail("L probe-union duality", f"{q1} {q2}")
+
+    for q in families:
+        for violation in ultrametric_violations(artifact, q):
+            fail("ultrametric", f"Q={q} {violation}")
+    return failures
+
+
+def check_cases() -> list[str]:
+    """Return failures of the specific phenomena of Examples A to I."""
+    failures: list[str] = []
+
+    def expect(condition: bool, message: str) -> None:
+        if not condition:
+            failures.append(f"case: {message}")
+
+    # A: parity regime is coherent with equality on the outputs.
+    a = example_a()
+    parity = Partition.from_labels(a.frames, {0: 0, 1: 1, 2: 0, 3: 1})
+    eq_out = Partition.discrete(a.outputs)
+    expect(coherent(a, a.probes, parity, eq_out), "A coherent")
+    expect(generated(a, a.probes, parity).refines(eq_out), "A lift finer than equality")
+
+    # B: the total frame regime is incoherent with equality; the witness is valid.
+    b = example_b()
+    b_total, b_eq = Partition.indiscrete(b.frames), Partition.discrete(b.outputs)
+    expect(not coherent(b, b.probes, b_total, b_eq), "B incoherent")
+    w = find_witness(b, b.probes, b_total, b_eq)
+    expect(
+        w is not None and witness_is_valid(b, b.probes, b_total, b_eq, w), "B witness"
+    )
+    expect(generated(b, b.probes, b_total).same(0, 1), "B lift relates 0 and 1")
+
+    # C: the kernel separates 0 from 1 and relates 1 and 2; the unit is strict.
+    c = example_c()
+    c_eq = Partition.discrete(c.outputs)
+    ker_c = kernel(c, c.probes, c_eq)
+    expect(ker_c.same(1, 2) and not ker_c.same(0, 1), "C kernel collapses 1 and 2")
+    c_frames_eq = Partition.discrete(c.frames)
+    expect(
+        c_frames_eq != kernel(c, c.probes, generated(c, c.probes, c_frames_eq)),
+        "C unit strict",
+    )
+
+    # D: more probes refine the kernel and enlarge the lift, both strictly.
+    d = example_d()
+    d_eq, d_total = Partition.discrete(d.outputs), Partition.indiscrete(d.frames)
+    expect(kernel(d, (0,), d_eq).same(0, 1), "D Q0 does not separate")
+    expect(not kernel(d, (0, 1), d_eq).same(0, 1), "D Q1 separates")
+    expect(coherent(d, (0,), d_total, d_eq), "D coherent at Q0")
+    expect(not coherent(d, (0, 1), d_total, d_eq), "D incoherent at Q1")
+    expect(not generated(d, (0,), d_total).same(0, 1), "D L_Q0 stays discrete")
+    expect(generated(d, (0, 1), d_total).same(0, 1), "D L_Q1 relates 0 and 1")
+
+    # E: the generating pairs are not transitive; the closure relates 0 and 2.
+    e = example_e()
+    e_total = Partition.indiscrete(e.frames)
+    expect(generated(e, e.probes, e_total).same(0, 2), "E closure relates 0 and 2")
+    expect(
+        (0, 2) not in generator_pairs(e, e.probes, pairs_of(e_total)),
+        "E generators skip (0, 2)",
+    )
+
+    # F: the counit is strict.
+    f = example_f()
+    f_total = Partition.indiscrete(f.outputs)
+    f_lk = generated(f, f.probes, kernel(f, f.probes, f_total))
+    expect(f_lk != f_total and f_lk.refines(f_total), "F counit strict")
+
+    # G: K does not preserve joins.
+    g = example_g()
+    rho, sigma = merge(g.outputs, 0, 1), merge(g.outputs, 1, 2)
+    kg = lambda r: kernel(g, g.probes, r)
+    expect(
+        kg(rho.join(sigma)) != kg(rho).join(kg(sigma)), "G K does not preserve joins"
+    )
+
+    # H: L does not preserve meets.
+    h = example_h()
+    phi1, phi2 = merge(h.frames, 0, 1), merge(h.frames, 0, 2)
+    lh = lambda p: generated(h, h.probes, p)
+    expect(
+        lh(phi1.meet(phi2)) != lh(phi1).meet(lh(phi2)), "H L does not preserve meets"
+    )
+
+    # I: thresholds are incomparable.
+    i = example_i()
+    t01 = threshold(i, i.probes, merge(i.frames, 0, 1))
+    t12 = threshold(i, i.probes, merge(i.frames, 1, 2))
+    expect(not t01.refines(t12) and not t12.refines(t01), "I thresholds incomparable")
+
+    # J: without equivalence the adjunction fails (empty family, empty relation).
+    # Partition values are always equivalences, so this is stated, not run.
+    return failures
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run all checks and return a process exit status."""
+    parser = argparse.ArgumentParser(description="Check Interpretive Kernel laws.")
+    parser.add_argument("--random", type=int, default=50, help="random artifacts")
+    parser.add_argument("--seed", type=int, default=0, help="random seed")
+    args = parser.parse_args(argv)
+
+    failures: list[str] = []
+    for artifact in all_cases():
+        failures.extend(check_artifact(artifact))
+    failures.extend(check_cases())
+    checked = len(all_cases())
+    for artifact in random_artifacts(args.random, args.seed):
+        failures.extend(check_artifact(artifact))
+        checked += 1
+
+    for line in failures[:50]:
+        print(line)
+    status = "FAILED" if failures else "OK"
+    print(f"{status}: {checked} artifacts, {len(failures)} failures")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

se_interpretive_kernel/cli.py

@@ -0,0 +1,5 @@
+"""Command-line interface."""
+
+from se_interpretive_kernel.check import main
+
+__all__ = ["main"]

se_interpretive_kernel/demand.py

@@ -0,0 +1,66 @@
+"""demand.py - Pairwise interpretive demand.
+
+Definition (Lean: ``demand``). The demand of a pair of frames (x, y) is the
+least occurrence regime under which every selected probe treats x and y alike:
+
+    delta(x, y) = equivalence closure of {(I(p,x), I(p,y)) | p selected}.
+
+Theorem (Lean: ``kernelRel_iff_demand_finer``). For every occurrence regime
+rho, F K_Q(rho) F' exactly when delta(F, F') refines rho.
+
+delta is a generalized pseudo-ultrametric: it is the bottom partition on the
+diagonal, symmetric, and satisfies the strong triangle inequality
+delta(x,z) <= delta(x,y) join delta(y,z). Distinct frames may have zero
+demand, so delta does not recover identity of frames.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .artifact import Artifact
+from .partition import Item, Pair, Partition
+
+
+def demand(artifact: Artifact, selected: Sequence[Item], x: Item, y: Item) -> Partition:
+    """Return the pairwise interpretive demand delta(x, y)."""
+    artifact.require_selected(selected)
+    pairs: list[Pair] = []
+    for probe in selected:
+        pairs.append((artifact.interpret(probe, x), artifact.interpret(probe, y)))
+    return Partition.from_pairs(artifact.outputs, pairs)
+
+
+def kernel_from_demand(
+    artifact: Artifact, selected: Sequence[Item], rho: Partition
+) -> Partition:
+    """Return K_Q(rho) computed as {(x, y) | delta(x, y) refines rho}."""
+    pairs: list[Pair] = []
+    for x in artifact.frames:
+        for y in artifact.frames:
+            if demand(artifact, selected, x, y).refines(rho):
+                pairs.append((x, y))
+    return Partition.from_pairs(artifact.frames, pairs)
+
+
+def ultrametric_violations(artifact: Artifact, selected: Sequence[Item]) -> list[str]:
+    """Return a description of every violated ultrametric law."""
+    bottom = Partition.discrete(artifact.outputs)
+    found: list[str] = []
+    for x in artifact.frames:
+        if demand(artifact, selected, x, x) != bottom:
+            found.append(f"zero: demand({x!r}, {x!r}) is not discrete")
+    for x in artifact.frames:
+        for y in artifact.frames:
+            if demand(artifact, selected, x, y) != demand(artifact, selected, y, x):
+                found.append(f"symmetry: demand({x!r}, {y!r}) differs from reverse")
+    for x in artifact.frames:
+        for y in artifact.frames:
+            for z in artifact.frames:
+                direct = demand(artifact, selected, x, z)
+                detour = demand(artifact, selected, x, y).join(
+                    demand(artifact, selected, y, z)
+                )
+                if not direct.refines(detour):
+                    found.append(f"triangle: ({x!r}, {y!r}, {z!r})")
+    return found

se_interpretive_kernel/differences.py

@@ -0,0 +1,69 @@
+"""differences.py - Report where two frame regimes disagree.
+
+Given two declared groupings of the same frames, this module lists the groups
+one regime makes that the other regime splits.
+
+It reports differences. It does not say which regime is correct, which is
+closer to some truth, or which should be preferred. Deciding that needs
+evidence outside this package.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .partition import Item, Partition
+
+
+@dataclass(frozen=True)
+class Difference:
+    """Contain one group made by one regime and split by the other.
+
+    ``grouped_by`` is ``"first"`` or ``"second"``: the regime that puts
+    ``frames`` in one block. ``split_into`` is how the other regime separates
+    those frames, as parts that each stay together under both regimes.
+    """
+
+    grouped_by: str
+    frames: tuple[Item, ...]
+    split_into: tuple[tuple[Item, ...], ...]
+
+
+def _splits(block: tuple[Item, ...], common: Partition) -> tuple[tuple[Item, ...], ...]:
+    """Return the parts of ``block`` under a partition, in first-seen order."""
+    parts: dict[int, list[Item]] = {}
+    for frame in block:
+        parts.setdefault(common.label_of(frame), []).append(frame)
+    return tuple(tuple(part) for part in parts.values())
+
+
+def regime_differences(first: Partition, second: Partition) -> list[Difference]:
+    """Return every group that one regime makes and the other splits.
+
+    An empty list means the two regimes are the same partition.
+    """
+    if first.carrier != second.carrier:
+        msg = "both regimes must be partitions of the same frames, in order"
+        raise ValueError(msg)
+    common = first.meet(second)
+    found: list[Difference] = []
+    for block in first.blocks():
+        parts = _splits(block, common)
+        if len(parts) > 1:
+            found.append(Difference("first", block, parts))
+    for block in second.blocks():
+        parts = _splits(block, common)
+        if len(parts) > 1:
+            found.append(Difference("second", block, parts))
+    return found
+
+
+def format_differences(differences: list[Difference]) -> str:
+    """Return the differences as plain text, one line each."""
+    lines: list[str] = []
+    for item in differences:
+        parts = " | ".join(", ".join(repr(f) for f in part) for part in item.split_into)
+        lines.append(
+            f"{item.grouped_by} groups {len(item.frames)} frames; other splits: {parts}"
+        )
+    return "\n".join(lines)