fixpoints 0.4.0.post85.dev0__tar.gz

fixpoints-0.4.0.post85.dev0/.gitignore

@@ -0,0 +1,241 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+**/docs/_build/
+**/docs/api/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+.jupyter_ystore.db
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+.direnv/
+.devenv/
+result
+
+# LaTeX
+*.pdf
+*.aux
+*.fls
+*.fdb_latexmk
+*.synctex.gz
+*.bbl
+*.blg
+*.out
+*.dvi
+*.xcp
+
+# Local data
+data/
+trajectory/
+experiment_results.db
+
+.playwright-mcp/
+*.local.*
+.envrc.private
+.pre-commit-config.yaml
+
+# nixago: ignore-linked-files
+/.vscode/extensions.json
+
+/inheritance-calculus/arxiv-submission.tar.gz
+node_modules/
+inheritance-calculus/comment.cut

fixpoints-0.4.0.post85.dev0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: fixpoints
+Version: 0.4.0.post85.dev0
+Summary: Least-fixpoint cached-property infrastructure for mutual recursion
+Project-URL: Repository, https://github.com/Atry/MIXINv2
+Author-email: "Yang, Bo" <yang-bo@yang-bo.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# fixpoints
+
+Least-fixpoint cached-property infrastructure for mutual recursion.
+
+`fixpoints` provides `fixpoint_cached_property` and `fixpoint_dependent`, drop-in
+replacements for `functools.cached_property` that resolve mutually recursive
+computations by least-fixpoint iteration. When reentry (a cycle) is detected, the
+outermost caller drives a digest loop that re-evaluates participants until their
+values stabilize, starting from a configurable bottom value.
+
+This package depends only on the Python standard library.

fixpoints-0.4.0.post85.dev0/README.md

@@ -0,0 +1,11 @@
+# fixpoints
+
+Least-fixpoint cached-property infrastructure for mutual recursion.
+
+`fixpoints` provides `fixpoint_cached_property` and `fixpoint_dependent`, drop-in
+replacements for `functools.cached_property` that resolve mutually recursive
+computations by least-fixpoint iteration. When reentry (a cycle) is detected, the
+outermost caller drives a digest loop that re-evaluates participants until their
+values stabilize, starting from a configurable bottom value.
+
+This package depends only on the Python standard library.

fixpoints-0.4.0.post85.dev0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0", "editables"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = false
+fallback-version = "0.0.0.dev0"
+metadata = false
+
+[project]
+name = "fixpoints"
+dynamic = ["version"]
+description = "Least-fixpoint cached-property infrastructure for mutual recursion"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+authors = [{ name = "Yang, Bo", email = "yang-bo@yang-bo.com" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fixpoints"]
+only-include = ["src/fixpoints"]
+sources = ["src"]
+
+[project.urls]
+Repository = "https://github.com/Atry/MIXINv2"

fixpoints-0.4.0.post85.dev0/src/fixpoints/__init__.py

@@ -0,0 +1,8 @@
+"""Least-fixpoint cached-property infrastructure for mutual recursion.
+
+Import the public symbols directly from :mod:`fixpoints._core`::
+
+    from fixpoints._core import fixpoint_cached_property
+    from fixpoints._core import fixpoint_dependent
+    from fixpoints._core import FixpointRecursionError
+"""

fixpoints-0.4.0.post85.dev0/src/fixpoints/_core.py

@@ -0,0 +1,370 @@
+"""Least-fixpoint cached-property infrastructure for mutual recursion.
+
+``fixpoint_cached_property`` and ``fixpoint_dependent`` are drop-in
+replacements for ``functools.cached_property`` that resolve mutually
+recursive computations by least-fixpoint iteration.  When reentry (a cycle)
+is detected, the outermost caller drives a digest loop that re-evaluates
+participants until their values stabilize, starting from a configurable
+bottom value.
+"""
+
+from __future__ import annotations
+
+import itertools
+import math
+from collections import defaultdict
+from contextvars import ContextVar
+from enum import Enum
+from functools import cached_property
+from typing import Callable, ClassVar
+
+
+class _FixpointContext:
+    """Tracks the state of a fixpoint iteration (digest cycle).
+
+    Stored in a ContextVar so that nested/concurrent fixpoint computations
+    are isolated per-thread/per-coroutine.
+    """
+
+    __slots__ = ("computing", "reentrant", "participant_ids", "participant_refs",
+                 "_clearable_attr_names", "approximations")
+
+    def __init__(self, clearable_attr_names: frozenset[str]) -> None:
+        self.computing: set[tuple[int, str]] = set()
+        self.reentrant: bool = False
+        self.participant_ids: set[int] = set()
+        self.participant_refs: list[object] = []
+        self._clearable_attr_names = clearable_attr_names
+        self.approximations: dict[tuple[int, str], object] = {}
+
+    def add_participant(self, instance: object) -> None:
+        instance_id = id(instance)
+        if instance_id not in self.participant_ids:
+            self.participant_ids.add(instance_id)
+            self.participant_refs.append(instance)
+
+    def clear_participant_caches(self) -> None:
+        """Clear all fixpoint-related cached values on all participants.
+
+        Before clearing, save each value into ``approximations`` so that
+        intermediate fixpoint_cached_property computations can use their
+        previous iteration's result as an approximation instead of bottom
+        when they encounter reentry.
+        """
+        for instance in self.participant_refs:
+            instance_dict = instance.__dict__
+            instance_id = id(instance)
+            for attr_name in self._clearable_attr_names:
+                value = instance_dict.pop(attr_name, None)
+                if value is not None:
+                    self.approximations[(instance_id, attr_name)] = value
+
+
+_fixpoint_context_var: ContextVar[_FixpointContext | None] = ContextVar(
+    "_fixpoint_context_var", default=None
+)
+
+
+class FixpointRecursionError(RecursionError):
+    """Raised when fixpoint iteration is exhausted or reentry is detected with no iterations remaining.
+
+    Carries the best approximation computed so far in ``incomplete_result``.
+    As a ``RecursionError`` subclass, existing code that catches ``RecursionError``
+    will also catch ``FixpointRecursionError``.
+    """
+
+    incomplete_result: object
+
+    def __init__(self, message: str, *, incomplete_result: object) -> None:
+        super().__init__(message)
+        self.incomplete_result = incomplete_result
+
+
+_FIXPOINT_SENTINEL = object()
+
+# Registry of attribute names that need clearing during fixpoint digest cycles.
+# Populated by fixpoint_cached_property and fixpoint_dependent decorators.
+_fixpoint_clearable_attrs: set[str] = set()
+
+
+def _accumulate_defaultdict_set(
+    accumulator: defaultdict[object, set[object]],
+    new_result: defaultdict[object, set[object]],
+) -> bool:
+    """Merge new_result into accumulator (pointwise set union).
+
+    Returns True if accumulator grew (new entries were added).
+    """
+    changed = False
+    for key, values in new_result.items():
+        existing = accumulator[key]
+        old_size = len(existing)
+        existing.update(values)
+        if len(existing) > old_size:
+            changed = True
+    return changed
+
+
+class FixpointIterationSentinel(Enum):
+    UNLIMITED = math.inf
+
+
+class fixpoint_cached_property:
+    """A cached_property that supports mutual-recursion via least fixpoint iteration.
+
+    API-compatible with functools.cached_property. When reentry is detected
+    (mutual recursion), returns the previous iteration's approximation
+    (or ``bottom()`` on the first iteration). The outermost caller drives
+    a digest loop until values stabilize (no reentry occurs in a round).
+
+    Usage::
+
+        @fixpoint_cached_property(bottom=lambda: defaultdict(set))
+        def qualified_this(self):
+            ...
+
+    The class-level ``max_fixpoint_iterations`` ContextVar controls the
+    maximum number of digest rounds.  ``0`` disables fixpoint iteration
+    and raises ``FixpointRecursionError`` on reentry.  Default
+    ``FixpointIterationSentinel.UNLIMITED`` iterates until convergence or
+    until Python's stack is exhausted::
+
+        fixpoint_cached_property.max_fixpoint_iterations.set(0)   # single-pass
+        fixpoint_cached_property.max_fixpoint_iterations.set(100) # bounded multi-pass
+        fixpoint_cached_property.max_fixpoint_iterations.set(FixpointIterationSentinel.UNLIMITED) # unbounded (default)
+    """
+
+    max_fixpoint_iterations: ClassVar[ContextVar[int | FixpointIterationSentinel]] = ContextVar(
+        "fixpoint_cached_property.max_fixpoint_iterations", default=FixpointIterationSentinel.UNLIMITED
+    )
+
+    def __init__(
+        self,
+        func: Callable = None,
+        *,
+        bottom: Callable[[], object],
+        accumulate: Callable[[object, object], bool] | None = None,
+    ) -> None:
+        # Support both @fixpoint_cached_property(bottom=...) and direct call
+        self._bottom = bottom
+        self._accumulate = accumulate
+        if func is not None:
+            self.func: Callable = func
+            self.attrname: str = func.__name__
+            self.__doc__ = func.__doc__
+            _fixpoint_clearable_attrs.add(self.attrname)
+
+    def __call__(self, func: Callable) -> "fixpoint_cached_property":
+        """Support @fixpoint_cached_property(bottom=...) decorator syntax."""
+        self.func = func
+        self.attrname = func.__name__
+        self.__doc__ = func.__doc__
+        _fixpoint_clearable_attrs.add(self.attrname)
+        return self
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        if not hasattr(self, "attrname"):
+            self.attrname = name
+        _fixpoint_clearable_attrs.add(self.attrname)
+
+    @classmethod
+    def _get_max_iterations(cls) -> int | float:
+        raw = cls.max_fixpoint_iterations.get()
+        if isinstance(raw, FixpointIterationSentinel):
+            return raw.value
+        return raw
+
+    def __get__(self, instance: object, owner: type = None) -> object:
+        if instance is None:
+            return self
+
+        # Fast path: already cached
+        cache = instance.__dict__
+        value = cache.get(self.attrname, _FIXPOINT_SENTINEL)
+        if value is not _FIXPOINT_SENTINEL:
+            max_iterations = self._get_max_iterations()
+            if max_iterations == 0:
+                return value
+            # Detect reentry: if this key is currently being computed
+            # (on the call stack), accessing its cached approximation
+            # means the fixpoint has not converged yet.
+            context = _fixpoint_context_var.get()
+            if context is not None:
+                key = (id(instance), self.attrname)
+                if key in context.computing:
+                    context.reentrant = True
+                    context.add_participant(instance)
+            return value
+
+        max_iterations = self._get_max_iterations()
+        context = _fixpoint_context_var.get()
+        instance_id = id(instance)
+        key = (instance_id, self.attrname)
+
+        if context is None:
+            # I am the driver — start a digest loop (or single-pass for max_iterations=0)
+            context = _FixpointContext(
+                clearable_attr_names=frozenset(_fixpoint_clearable_attrs)
+            )
+            token = _fixpoint_context_var.set(context)
+            try:
+                if max_iterations == 0:
+                    # Zero-iteration mode: compute once with reentry detection.
+                    # Reentry raises FixpointRecursionError instead of infinite recursion.
+                    context.computing.add(key)
+                    result = self.func(instance)
+                    cache[self.attrname] = result
+                    return result
+
+                approximation = self._bottom()
+                accumulator = self._bottom() if self._accumulate is not None else None
+                previous_result = _FIXPOINT_SENTINEL
+                for iteration in itertools.count():
+                    context.computing.add(key)
+                    context.add_participant(instance)
+                    result = self.func(instance)
+
+                    if not context.reentrant:
+                        # No reentry this round — fixpoint reached
+                        cache[self.attrname] = result
+                        return result
+
+                    if self._accumulate is not None:
+                        # Monotonic accumulation: merge each iteration's
+                        # result into an accumulator that only grows.
+                        # This prevents oscillation when intermediate
+                        # computations encounter cycles in varying order.
+                        changed = self._accumulate(accumulator, result)
+                        if not changed and iteration > 0:
+                            cache[self.attrname] = accumulator
+                            return accumulator
+                        # Use the accumulator as next round's approximation
+                        approximation = accumulator
+                    else:
+                        # Exact equality convergence (original behavior)
+                        if result == previous_result:
+                            cache[self.attrname] = result
+                            return result
+                        previous_result = result
+                        approximation = result
+
+                    # Cache current approximation, clear all intermediate
+                    # caches, and re-run
+                    cache[self.attrname] = approximation
+                    context.clear_participant_caches()
+                    # Restore driver's own approximation
+                    cache[self.attrname] = approximation
+                    context.computing.clear()
+                    context.reentrant = False
+
+                    if iteration + 1 >= max_iterations:
+                        raise FixpointRecursionError(
+                            f"fixpoint_cached_property '{self.attrname}' did not converge "
+                            f"after {max_iterations} iterations",
+                            incomplete_result=approximation,
+                        )
+            finally:
+                _fixpoint_context_var.reset(token)
+        elif key in context.computing:
+            # Reentry detected — return previous approximation or bottom.
+            context.reentrant = True
+            context.add_participant(instance)
+            if max_iterations == 0:
+                raise FixpointRecursionError(
+                    f"fixpoint_cached_property '{self.attrname}': "
+                    f"reentry detected with max_fixpoint_iterations=0",
+                    incomplete_result=self._bottom(),
+                )
+            # Check the instance cache first, then fall back to saved
+            # approximations from the previous iteration.
+            approximation = cache.get(self.attrname, _FIXPOINT_SENTINEL)
+            if approximation is not _FIXPOINT_SENTINEL:
+                return approximation
+            saved = context.approximations.get(key, _FIXPOINT_SENTINEL)
+            if saved is not _FIXPOINT_SENTINEL:
+                return saved
+            return self._bottom()
+        else:
+            # Inside a fixpoint context but this is a fresh (instance, attr)
+            # pair — compute normally.  Keep the key in ``computing`` only
+            # while ``self.func`` runs so that cycles through this key are
+            # detected by the ``elif`` branch above.  Once computation
+            # finishes, remove the key so the fast-path cache check does
+            # not misidentify a later read of this cached value as reentry.
+            context.computing.add(key)
+            context.add_participant(instance)
+            result = self.func(instance)
+            context.computing.discard(key)
+            cache[self.attrname] = result
+            return result
+
+    def __set__(self, instance: object, value: object) -> None:
+        """Data descriptor setter to ensure __get__ is always called."""
+        instance.__dict__[self.attrname] = value
+
+
+class _fixpoint_dependent_property:
+    """A cached_property that registers its instance as a fixpoint participant.
+
+    Behaves like ``functools.cached_property`` but, when computed inside an
+    active fixpoint context, registers the instance so that
+    ``clear_participant_caches`` will clear the cached value between
+    iterations.  Without this, stale values computed from an incomplete
+    fixpoint approximation survive across iterations.
+    """
+
+    def __init__(self, func: Callable) -> None:
+        self.func = func
+        self.attrname = func.__name__
+        self.__doc__ = func.__doc__
+        _fixpoint_clearable_attrs.add(self.attrname)
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        if not hasattr(self, "attrname"):
+            self.attrname = name
+        _fixpoint_clearable_attrs.add(self.attrname)
+
+    def __get__(self, instance: object, owner: type = None) -> object:
+        if instance is None:
+            return self
+
+        cache = instance.__dict__
+        value = cache.get(self.attrname)
+        if value is not None:
+            return value
+
+        if fixpoint_cached_property._get_max_iterations() > 0:
+            # Register as participant so clear_participant_caches can
+            # invalidate this cached value between fixpoint iterations.
+            context = _fixpoint_context_var.get()
+            if context is not None:
+                context.add_participant(instance)
+
+        value = self.func(instance)
+        cache[self.attrname] = value
+        return value
+
+
+def fixpoint_dependent(func: Callable) -> _fixpoint_dependent_property:
+    """Mark a cached_property as dependent on fixpoint_cached_property values.
+
+    During fixpoint digest cycles, these caches are cleared between iterations
+    so they are recomputed with updated approximations.
+
+    Usage::
+
+        @fixpoint_dependent
+        @cached_property
+        def symbol_kind(self):
+            ...
+
+    Or equivalently::
+
+        @fixpoint_dependent
+        def symbol_kind(self):
+            ...
+    """
+    if isinstance(func, cached_property):
+        return _fixpoint_dependent_property(func.func)
+    else:
+        return _fixpoint_dependent_property(func)

fixpoints-0.4.0.post85.dev0/tests/test_fixpoint.py

@@ -0,0 +1,271 @@
+"""Tests for fixpoint_cached_property fixpoint-iteration and FixpointRecursionError behavior."""
+
+from collections import defaultdict
+
+import pytest
+
+from fixpoints._core import (
+    FixpointIterationSentinel,
+    FixpointRecursionError,
+    _accumulate_defaultdict_set,
+    fixpoint_cached_property,
+)
+
+
+class TestDivergentConvergenceBehavior:
+    """Tests showing different convergence behavior with different max_fixpoint_iterations.
+
+    The inheritance-calculus paper (Section 7) defines a translation T from
+    the lazy λ-calculus to mixin trees.  The mixin-tree equations for the
+    ``this`` function (qualified-this resolution) form a monotone system
+    whose least fixpoint is computed iteratively when max_fixpoint_iterations > 0.
+
+    With max_fixpoint_iterations=0, cyclic dependencies in the ``this``
+    function raise ``FixpointRecursionError`` because reentry is detected with no iterations
+    remaining to converge.
+
+    The cycle pattern arises from self-referential λ-terms such as the
+    self-application combinator Ω = (λx. x x)(λx. x x).  The T
+    translation maps Ω to a mixin tree where the ``tailCall`` scope
+    inherits from ``↑1.argument`` (the enclosing lambda's argument slot).
+    After composition, this creates a cycle in the ``this`` function:
+    computing ``this(p, p_def)`` for one scope requires ``this`` for
+    another scope, which in turn requires the first.
+
+    The tests below use ``fixpoint_cached_property`` directly — the same
+    mechanism that implements ``qualified_this`` in the MixinSymbol —
+    to demonstrate the divergence/convergence difference.
+    """
+
+    def _make_transitive_closure_nodes(
+        self,
+        initial_a: dict[str, set[int]],
+        initial_b: dict[str, set[int]],
+    ) -> tuple[object, object]:
+        """Create two nodes with mutually recursive transitive closure.
+
+        Each node's ``reachable`` property is the union of its own values
+        and everything reachable from the other node.  This is analogous
+        to the ``this(p, p_def)`` function: ``this(p) = own(p) ∪
+        ⋃{this(q) | q ∈ supers(p)}``, which forms a monotone system
+        over set-valued lattices.
+
+        The mutual dependence mirrors the cycle that arises in
+        ``qualified_this`` when a scope's overrides depend on the
+        qualified-this of another scope, which in turn depends on the
+        first scope's overrides.
+        """
+
+        class TransitiveClosureNode:
+            def __init__(self, initial_values: dict[str, set[int]]) -> None:
+                self.__dict__["_initial_values"] = initial_values
+                self.__dict__["_other"] = None
+
+            def set_other(self, other: "TransitiveClosureNode") -> None:
+                self.__dict__["_other"] = other
+
+            @fixpoint_cached_property(
+                bottom=lambda: defaultdict(set),
+                accumulate=_accumulate_defaultdict_set,
+            )
+            def reachable(self) -> defaultdict[str, set[int]]:
+                result: defaultdict[str, set[int]] = defaultdict(set)
+                for key, values in self._initial_values.items():
+                    result[key].update(values)
+                if self._other is not None:
+                    for key, values in self._other.reachable.items():
+                        result[key].update(values)
+                return result
+
+        node_a = TransitiveClosureNode(initial_a)
+        node_b = TransitiveClosureNode(initial_b)
+        node_a.set_other(node_b)
+        node_b.set_other(node_a)
+        return node_a, node_b
+
+    def test_fixpoint_converges_on_mutual_recursion(self) -> None:
+        """max_fixpoint_iterations=100 resolves mutual recursion via iterative approximation.
+
+        Analogous to Datalog transitive closure or the ``this`` fixpoint:
+        the computation starts with ⊥ (empty set), and each iteration
+        discovers more reachable elements until convergence.
+        """
+        token = fixpoint_cached_property.max_fixpoint_iterations.set(100)
+        try:
+            node_a, node_b = self._make_transitive_closure_nodes(
+                initial_a={"x": {1, 2}},
+                initial_b={"y": {3, 4}},
+            )
+            reachable_a = dict(node_a.reachable)
+            reachable_b = dict(node_b.reachable)
+        finally:
+            fixpoint_cached_property.max_fixpoint_iterations.reset(token)
+
+        # Both nodes discover each other's values through fixpoint iteration
+        assert reachable_a["x"] == {1, 2}
+        assert reachable_a["y"] == {3, 4}
+        assert reachable_b["x"] == {1, 2}
+        assert reachable_b["y"] == {3, 4}
+
+    def test_zero_iterations_raises_bottom_on_mutual_recursion(self) -> None:
+        """max_fixpoint_iterations=0 raises FixpointRecursionError on mutual recursion.
+
+        With no fixpoint iterations allowed, the mutual dependency between
+        A and B triggers reentry detection.  Unlike the old
+        INDEXED_HYLOMORPHISM (which had no reentry detection and caused
+        Python's natural stack overflow), max_fixpoint_iterations=0 detects
+        the reentry immediately and raises FixpointRecursionError with the incomplete result.
+        """
+        token = fixpoint_cached_property.max_fixpoint_iterations.set(0)
+        try:
+            node_a, _node_b = self._make_transitive_closure_nodes(
+                initial_a={"x": {1, 2}},
+                initial_b={"y": {3, 4}},
+            )
+            with pytest.raises(FixpointRecursionError) as exception_info:
+                node_a.reachable
+            assert isinstance(exception_info.value.incomplete_result, defaultdict)
+        finally:
+            fixpoint_cached_property.max_fixpoint_iterations.reset(token)
+
+    def test_fixpoint_converges_three_node_cycle(self) -> None:
+        """max_fixpoint_iterations=100 handles N-way cycles (A→B→C→A), not just 2-cycles.
+
+        This mirrors the 3-cycle in RelationalCycle.mixin.yaml (a→b→c→a),
+        where the transitive closure requires multiple fixpoint iterations
+        to discover all reachable pairs.
+        """
+
+        class TriCycleNode:
+            def __init__(self, initial_values: dict[str, set[int]]) -> None:
+                self.__dict__["_initial_values"] = initial_values
+                self.__dict__["_next"] = None
+
+            def set_next(self, other: "TriCycleNode") -> None:
+                self.__dict__["_next"] = other
+
+            @fixpoint_cached_property(
+                bottom=lambda: defaultdict(set),
+                accumulate=_accumulate_defaultdict_set,
+            )
+            def reachable(self) -> defaultdict[str, set[int]]:
+                result: defaultdict[str, set[int]] = defaultdict(set)
+                for key, values in self._initial_values.items():
+                    result[key].update(values)
+                if self._next is not None:
+                    for key, values in self._next.reachable.items():
+                        result[key].update(values)
+                return result
+
+        token = fixpoint_cached_property.max_fixpoint_iterations.set(100)
+        try:
+            node_a = TriCycleNode({"a": {1}})
+            node_b = TriCycleNode({"b": {2}})
+            node_c = TriCycleNode({"c": {3}})
+            node_a.set_next(node_b)
+            node_b.set_next(node_c)
+            node_c.set_next(node_a)
+
+            reachable_a = dict(node_a.reachable)
+        finally:
+            fixpoint_cached_property.max_fixpoint_iterations.reset(token)
+
+        # All three values discovered through the cycle
+        assert reachable_a["a"] == {1}
+        assert reachable_a["b"] == {2}
+        assert reachable_a["c"] == {3}
+
+
+class TestUnlimitedIterationsOmega:
+    """Tests that UNLIMITED iterations causes RecursionError (not FixpointRecursionError) for divergent computations."""
+
+    def test_omega_raises_recursion_error_not_bottom(self) -> None:
+        """With UNLIMITED, a divergent fixpoint hits Python's native RecursionError.
+
+        This simulates the Omega combinator: a computation that never converges.
+        With a finite limit, the fixpoint loop would raise FixpointRecursionError after exhausting
+        iterations. With UNLIMITED, the itertools.count() loop runs indefinitely,
+        and eventually Python's recursion limit is hit within a single iteration's
+        computation, raising a native RecursionError (not FixpointRecursionError).
+        """
+        iteration_count = 0
+
+        class OmegaNode:
+            def __init__(self) -> None:
+                self.__dict__["_other"] = None
+
+            def set_other(self, other: "OmegaNode") -> None:
+                self.__dict__["_other"] = other
+
+            @fixpoint_cached_property(bottom=lambda: 0)
+            def divergent(self) -> int:
+                nonlocal iteration_count
+                iteration_count += 1
+                if iteration_count > 200:
+                    raise RecursionError("simulated stack overflow after 200 iterations")
+                # Return alternating values so it never converges
+                return self._other.divergent + 1
+
+        node_a = OmegaNode()
+        node_b = OmegaNode()
+        node_a.set_other(node_b)
+        node_b.set_other(node_a)
+
+        with pytest.raises(RecursionError) as exception_info:
+            node_a.divergent
+        # The error should be a native RecursionError, NOT a FixpointRecursionError
+        assert not isinstance(exception_info.value, FixpointRecursionError)
+        # Verify we actually ran past the old default of 100
+        assert iteration_count > 100
+
+
+class TestFixpointRecursionErrorException:
+    """Tests for the FixpointRecursionError exception class."""
+
+    def test_bottom_is_recursion_error_subclass(self) -> None:
+        assert issubclass(FixpointRecursionError, RecursionError)
+
+    def test_negative_max_fixpoint_iterations_raises_bottom(self) -> None:
+        """Negative max_fixpoint_iterations is meaningless; ContextVar accepts any int."""
+        # ContextVar accepts any int value, but negative values are nonsensical.
+        # The fixpoint loop uses range(max_iterations), so negative values
+        # produce zero iterations and raise FixpointRecursionError on reentry (same as 0).
+        pass
+
+    def test_bottom_carries_incomplete_result(self) -> None:
+        """max_fixpoint_iterations=1 on a system needing 2+ iterations raises FixpointRecursionError with partial result."""
+        token = fixpoint_cached_property.max_fixpoint_iterations.set(1)
+        try:
+
+            class MutualNode:
+                def __init__(self, initial_values: dict[str, set[int]]) -> None:
+                    self.__dict__["_initial_values"] = initial_values
+                    self.__dict__["_other"] = None
+
+                def set_other(self, other: "MutualNode") -> None:
+                    self.__dict__["_other"] = other
+
+                @fixpoint_cached_property(
+                    bottom=lambda: defaultdict(set),
+                    accumulate=_accumulate_defaultdict_set,
+                )
+                def reachable(self) -> defaultdict[str, set[int]]:
+                    result: defaultdict[str, set[int]] = defaultdict(set)
+                    for key, values in self._initial_values.items():
+                        result[key].update(values)
+                    if self._other is not None:
+                        for key, values in self._other.reachable.items():
+                            result[key].update(values)
+                    return result
+
+            node_a = MutualNode({"x": {1}})
+            node_b = MutualNode({"y": {2}})
+            node_a.set_other(node_b)
+            node_b.set_other(node_a)
+
+            with pytest.raises(FixpointRecursionError) as exception_info:
+                node_a.reachable
+            # The incomplete result should be a defaultdict(set) with partial data
+            assert isinstance(exception_info.value.incomplete_result, defaultdict)
+        finally:
+            fixpoint_cached_property.max_fixpoint_iterations.reset(token)