morphata 2.0.4__tar.gz → 2.0.6__tar.gz

{morphata-2.0.4 → morphata-2.0.6}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2.0.6 — 2026-06-02
+
+### Fixed
+
+- A major regression where the streaming `to_hoa` stuff changed the label enumeration
+  semantics to be _minterms_ instead of _cubes_.
+  This is now fixed.
+
+### Added
+
+- Added a free-floating function that helps enumerate the successor BDDs from a symbolic
+  automaton state, given a specific alphabet and set of symbols.
+
+## 2.0.5 — 2026-06-01
+
+### Added
+
+`SymbolicAutomaton` and `Automaton` now support a streaming writer
+for HOA export via `morphata.hoa.symbolic_automaton_to_hoa`
+and `morphata.hoa.automaton_to_hoa`, and is also present in `SymbolicAutomaton.to_hoa`.
+
+This is mostly a performance thing:
+providing a buffered writer to the exporter allows one to stream the HOA format into a
+file, without having to manifest the entire string representation of the automaton,
+which can be cumbersome.
+
 ## 2.0.4 — 2026-05-28
 
 ### Added

{morphata-2.0.4 → morphata-2.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphata
-Version: 2.0.4
+Version: 2.0.6
 Summary: Representation theory for automata, made practical.
 Project-URL: Documentation, https://docs.anandb.dev/morphata
 Project-URL: Repository, https://git.anandb.dev/morphata.git
@@ -20,7 +20,7 @@ Requires-Dist: logic-asts>=1.6.2
 Requires-Dist: networkx
 Requires-Dist: numpy
 Requires-Dist: types-networkx
-Requires-Dist: typing-extensions
+Requires-Dist: typing-extensions>=4.14
 Provides-Extra: dot
 Requires-Dist: pydot>=4.0.1; extra == 'dot'
 Provides-Extra: jax

{morphata-2.0.4 → morphata-2.0.6}/ci/make-release

@@ -88,7 +88,7 @@ echo "==> Promoting CHANGELOG Unreleased -> ${NEW_VERSION} (${RELEASE_DATE})"
 sed -i "s/^## Unreleased$/## ${NEW_VERSION} \xe2\x80\x94 ${RELEASE_DATE}/" CHANGELOG.md
 
 # Commit
-COMMIT_MSG="chore(release): ${NEW_VERSION}"
+COMMIT_MSG="chore(release): $(uv version)"
 echo "==> Committing: $COMMIT_MSG"
 
 if is_jj; then
@@ -120,8 +120,8 @@ echo "==> Tagging $TAG"
 if is_jj; then
   jj git import 2>/dev/null || true
 fi
-printf '%s\n\n%s\n' "$TAG_TITLE" "$TAG_BODY" \
-  | git tag -a "$TAG" --cleanup=verbatim -F -
+printf '%s\n\n%s\n' "$TAG_TITLE" "$TAG_BODY" |
+  git tag -a "$TAG" --cleanup=verbatim -F -
 if is_jj; then
   jj git import 2>/dev/null || true
 fi

{morphata-2.0.4 → morphata-2.0.6}/pixi.lock

@@ -5474,7 +5474,7 @@ packages:
   - networkx
   - numpy
   - types-networkx
-  - typing-extensions
+  - typing-extensions>=4.14
   - jax>=0.8 ; extra == 'jax'
   - torch>=2.0 ; extra == 'torch'
   - pydot>=4.0.1 ; extra == 'dot'

{morphata-2.0.4 → morphata-2.0.6}/pixi.toml

@@ -17,7 +17,7 @@ lark = ">=1.3.1"
 networkx = "*"
 numpy = "*"
 types-networkx = "*"
-typing-extensions = "*"
+typing-extensions = ">=4.14"
 
 [pypi-dependencies]
 morphata = { path = ".", editable = true }

{morphata-2.0.4 → morphata-2.0.6}/pyproject.toml

@@ -2,7 +2,7 @@
 name = "morphata"
 authors = [{ name = "Anand Balakrishnan", email = "anandbala1597@gmail.com" }]
 description = "Representation theory for automata, made practical."
-version = "2.0.4"
+version = "2.0.6"
 requires-python = ">=3.12"
 classifiers = [
   "Intended Audience :: Science/Research",
@@ -21,7 +21,7 @@ dependencies = [
   "networkx",
   "numpy",
   "types-networkx",
-  "typing-extensions",
+  "typing-extensions>=4.14",
 ]
 
 [project.optional-dependencies]

{morphata-2.0.4 → morphata-2.0.6}/src/morphata/hoa/__init__.py

@@ -37,7 +37,8 @@ Example extended HOA with finite acceptance::
 
 import morphata.hoa.parser as parser
 from morphata.hoa.exporter import automaton_to_hoa as automaton_to_hoa
+from morphata.hoa.exporter import symbolic_automaton_to_hoa as symbolic_automaton_to_hoa
 from morphata.hoa.parser import ParsedAutomaton as ParsedAutomaton
 from morphata.hoa.parser import parse as parse
 
-__all__ = ["parse", "parser", "ParsedAutomaton", "automaton_to_hoa"]
+__all__ = ["parse", "parser", "ParsedAutomaton", "automaton_to_hoa", "symbolic_automaton_to_hoa"]

{morphata-2.0.4 → morphata-2.0.6}/src/morphata/hoa/exporter.py

@@ -12,23 +12,53 @@ import io
 import typing as ty
 from collections.abc import Iterable, Mapping, Sequence
 from collections.abc import Set as AbstractSet
+from typing import TYPE_CHECKING
 
 import logic_asts.base as logic
+from typing_extensions import Writer, overload
 
 import morphata.hoa.acc_expr as acc_expr
 
-if ty.TYPE_CHECKING:
+if TYPE_CHECKING:
     from morphata.acceptance import AcceptanceCondition
     from morphata.automaton import Automaton
+    from morphata.symbolic.automaton import SymbolicAutomaton
+    from morphata.symbolic.bdd import Function, Manager
 
 
+@overload
 def automaton_to_hoa(
-    aut: Automaton[int, ty.Any, ty.Any],
+    aut: "Automaton[int, ty.Any, ty.Any]",
+    *,
+    name: str | None = ...,
+    properties: "Sequence[str] | None" = ...,
+    out: None = ...,
+) -> str: ...
+
+
+@overload
+def automaton_to_hoa(
+    aut: "Automaton[int, ty.Any, ty.Any]",
+    *,
+    name: str | None = ...,
+    properties: "Sequence[str] | None" = ...,
+    out: "Writer[str]",
+) -> None: ...
+
+
+def automaton_to_hoa(
+    aut: "Automaton[int, ty.Any, ty.Any]",
     *,
     name: str | None = None,
-    properties: Sequence[str] | None = None,
-) -> str:
-    """Serialize *aut* to an HOA v1 string.
+    properties: "Sequence[str] | None" = None,
+    out: "Writer[str] | None" = None,
+) -> "str | None":
+    """Serialize *aut* to HOA v1.
+
+    If ``out`` is ``None`` (the default), build the HOA in an internal
+    ``io.StringIO`` and return the resulting string. If ``out`` is
+    provided, stream the HOA directly into it and return ``None``; the
+    caller owns flushing / closing.
 
     Requirements on *aut*:
 
@@ -50,7 +80,8 @@ def automaton_to_hoa(
     ap_to_index = {ap: i for i, ap in enumerate(ap_order)}
     acc_name, acc_expr_text, num_sets, acc_state_sets = _acceptance_to_hoa(aut.acceptance)
 
-    buf = io.StringIO()
+    owns_buffer = out is None
+    buf: Writer[str] = io.StringIO() if out is None else out
     _write_header(
         buf,
         aut=aut,
@@ -69,7 +100,186 @@ def automaton_to_hoa(
         ap_to_index=ap_to_index,
         acc_state_sets=acc_state_sets,
     )
-    return buf.getvalue()
+    if owns_buffer:
+        assert isinstance(buf, io.StringIO)
+        return buf.getvalue()
+    return None
+
+
+@overload
+def symbolic_automaton_to_hoa(
+    sym: "SymbolicAutomaton[ty.Any]",
+    *,
+    name: str | None = ...,
+    properties: Sequence[str] | None = ...,
+    out: None = ...,
+) -> str: ...
+
+
+@overload
+def symbolic_automaton_to_hoa(
+    sym: "SymbolicAutomaton[ty.Any]",
+    *,
+    name: str | None = ...,
+    properties: Sequence[str] | None = ...,
+    out: Writer[str],
+) -> None: ...
+
+
+def symbolic_automaton_to_hoa(
+    sym: "SymbolicAutomaton[ty.Any]",
+    *,
+    name: str | None = None,
+    properties: Sequence[str] | None = None,
+    out: Writer[str] | None = None,
+) -> str | None:
+    """Serialize a :class:`SymbolicAutomaton` to HOA v1 directly from its BDDs.
+
+    Walks ``sym.transitions`` row-by-row. For each cached
+    ``(guard_bdd, succ_bdd)`` pair, decodes both BDDs into compact
+    ``logic_asts.BoolExpr`` trees via Shannon expansion
+    (:func:`~morphata.symbolic.bdd.bdd_to_boolexpr`) and emits one HOA
+    edge per disjunct of the successor expression, with a single label
+    expression per row. Cube structure of the guard is preserved -- variables
+    absent from a given path through the BDD are projected out -- so the
+    output size is proportional to the BDD shape, not to ``2^|support|``.
+
+    ``out`` semantics match :func:`automaton_to_hoa`: when ``None``, an
+    internal ``StringIO`` accumulates the output and is returned;
+    otherwise the output streams into ``out`` and the function returns
+    ``None``.
+
+    Literal-true / literal-false successor BDDs (``mgr.true`` /
+    ``mgr.false``) are handled by emitting synthetic sink states with
+    self-loops, mirroring :func:`_materialize_sinks` on the IR side. The
+    BDD manager is not mutated. As on the IR side, sink materialisation
+    is only implemented for :class:`~morphata.acceptance.Finite`
+    acceptance; omega-regular conditions with literal successors raise
+    ``NotImplementedError``.
+
+    Raises
+    ------
+    ValueError
+        If the cached transition table is empty but ``sym.num_states > 0``.
+    NotImplementedError
+        If literal-true / literal-false successors are present and the
+        acceptance condition is not :class:`~morphata.acceptance.Finite`.
+    """
+    from morphata.acceptance import Finite
+    from morphata.symbolic.bdd import bdd_to_boolexpr
+
+    if sym.num_states > 0 and not sym.transitions:
+        raise ValueError(
+            "symbolic_automaton_to_hoa requires a populated transition cache; "
+            "reconstruct SymbolicAutomaton with cache_transitions=True."
+        )
+
+    mgr = sym.manager
+
+    needs_true = sym.initial == mgr.true
+    needs_false = sym.initial == mgr.false
+    for s in range(sym.num_states):
+        for _, succ_bdd in sym.transitions.get(s, ()):
+            if succ_bdd == mgr.true:
+                needs_true = True
+            elif succ_bdd == mgr.false:
+                needs_false = True
+
+    if (needs_true or needs_false) and not isinstance(sym.acceptance, Finite):
+        raise NotImplementedError(
+            "HOA export: literal-true / literal-false successor BDDs require "
+            "sink-state materialisation, which is only implemented for "
+            f"Finite acceptance; got {type(sym.acceptance).__name__}."
+        )
+
+    next_idx = sym.num_states
+    true_sink: int | None = None
+    false_sink: int | None = None
+    if needs_true:
+        true_sink = next_idx
+        next_idx += 1
+    if needs_false:
+        false_sink = next_idx
+        next_idx += 1
+    total_states = next_idx
+
+    ap_order = sorted(sym.ap_registry, key=repr)
+    ap_to_index: dict[ty.Any, int] = {ap: i for i, ap in enumerate(ap_order)}
+    ap_decoder_map: dict[str, ty.Any] = {var: ap for ap, var in sym.ap_registry.items()}
+
+    def _ap_decode(name: str) -> ty.Any:  # noqa: ANN401
+        try:
+            return ap_decoder_map[name]
+        except KeyError as exc:
+            raise ValueError(f"Guard BDD references variable {name!r} not in the AP registry.") from exc
+
+    acc_name, acc_expr_text, num_sets, acc_state_sets = _acceptance_to_hoa(sym.acceptance)
+    if true_sink is not None:
+        # Finite acceptance: extend set 0 (the accepting set) with the
+        # true-sink. ``_acceptance_to_hoa(Finite)`` always returns
+        # ``{0: ...}``.
+        augmented_sets: dict[int, AbstractSet[int]] = dict(acc_state_sets)
+        augmented_sets[0] = frozenset(augmented_sets.get(0, frozenset())) | {true_sink}
+        acc_state_sets = augmented_sets
+    states = list(range(sym.num_states))
+
+    owns_buffer = out is None
+    buf: Writer[str] = io.StringIO() if owns_buffer else out  # type: ignore[assignment]
+
+    buf.write("HOA: v1\n")
+    if name is not None:
+        buf.write(f'name: "{name}"\n')
+    buf.write(f"States: {total_states}\n")
+    if sym.initial == mgr.true:
+        assert true_sink is not None
+        buf.write(f"Start: {true_sink}\n")
+    elif sym.initial == mgr.false:
+        assert false_sink is not None
+        buf.write(f"Start: {false_sink}\n")
+    else:
+        initial_expr = ty.cast("logic.BoolExpr[int]", bdd_to_boolexpr(sym.initial))
+        for start_line in _initial_start_lines(initial_expr):
+            buf.write(f"Start: {start_line}\n")
+    ap_words = " ".join(f'"{ap}"' for ap in ap_order)
+    buf.write(f"AP: {len(ap_order)}{(' ' + ap_words) if ap_order else ''}\n")
+    if acc_name is not None:
+        buf.write(f"acc-name: {acc_name}\n")
+    buf.write(f"Acceptance: {num_sets} {acc_expr_text}\n")
+    if properties:
+        buf.write("properties: " + " ".join(properties) + "\n")
+
+    buf.write("--BODY--\n")
+    for s in states:
+        sets_for_s = sorted(idx for idx, members in acc_state_sets.items() if s in members)
+        marker = (" {" + " ".join(str(i) for i in sets_for_s) + "}") if sets_for_s else ""
+        buf.write(f"State: {s}{marker}\n")
+        for guard_bdd, succ_bdd in sym.transitions.get(s, ()):
+            if succ_bdd == mgr.true:
+                assert true_sink is not None
+                dsts = [str(true_sink)]
+            elif succ_bdd == mgr.false:
+                assert false_sink is not None
+                dsts = [str(false_sink)]
+            else:
+                succ_expr = ty.cast("logic.BoolExpr[int]", bdd_to_boolexpr(succ_bdd))
+                dsts = _state_expr_to_edges(succ_expr)
+            guard_expr = bdd_to_boolexpr(guard_bdd, var_decoder=_ap_decode)
+            label = _label_to_hoa(guard_expr, ap_to_index)
+            for dst in dsts:
+                buf.write(f"[{label}] {dst}\n")
+    for sink in (true_sink, false_sink):
+        if sink is None:
+            continue
+        sets_for_sink = sorted(idx for idx, members in acc_state_sets.items() if sink in members)
+        marker = (" {" + " ".join(str(i) for i in sets_for_sink) + "}") if sets_for_sink else ""
+        buf.write(f"State: {sink}{marker}\n")
+        buf.write(f"[t] {sink}\n")
+    buf.write("--END--\n")
+
+    if owns_buffer:
+        assert isinstance(buf, io.StringIO)
+        return buf.getvalue()
+    return None
 
 
 # ---------------------------------------------------------------------------
@@ -181,7 +391,7 @@ def _materialize_sinks(
 
 
 def _write_header(
-    buf: io.StringIO,
+    buf: Writer[str],
     *,
     aut: Automaton[int, ty.Any, ty.Any],
     states: list[int],
@@ -255,7 +465,7 @@ def _flatten_or(expr: logic.BoolExpr[ty.Any]) -> list[logic.BoolExpr[ty.Any]]:
 
 
 def _write_body(
-    buf: io.StringIO,
+    buf: Writer[str],
     *,
     aut: Automaton[int, ty.Any, ty.Any],
     states: list[int],
@@ -351,6 +561,69 @@ def _conj_to_dst(expr: logic.BoolExpr[int], *, context: str) -> str:
     raise ValueError(f"HOA {context} expression must be a disjunction of conjunctions of state variables; got {expr!r}.")
 
 
+# ---------------------------------------------------------------------------
+# BDD-direct helpers (symbolic_automaton_to_hoa)
+# ---------------------------------------------------------------------------
+
+
+def _cube_to_hoa_label(
+    cube: Mapping[str, bool],
+    bdd_var_to_ap_index: Mapping[str, int],
+) -> str:
+    """Render a single BDD cube over AP variables as an HOA label.
+
+    *cube* is a ``{bdd_var_name: bool}`` dict from ``dd``'s
+    ``BDD.pick_iter``; variables absent from the BDD's support are
+    don't-cares and do not appear in the output.
+    *bdd_var_to_ap_index* maps the BDD variable name back to the AP's
+    HOA index. Literals in the output are sorted by AP index for
+    deterministic output.
+    """
+    if not cube:
+        return "t"
+    literals: list[tuple[int, bool]] = []
+    for var_name, polarity in cube.items():
+        try:
+            idx = bdd_var_to_ap_index[var_name]
+        except KeyError as exc:
+            raise ValueError(f"BDD cube references variable {var_name!r} not in the AP registry.") from exc
+        literals.append((idx, polarity))
+    literals.sort(key=lambda iv: iv[0])
+    parts = [(str(idx) if polarity else f"!{idx}") for idx, polarity in literals]
+    if len(parts) == 1:
+        return parts[0]
+    return "(" + " & ".join(parts) + ")"
+
+
+def _bdd_state_cubes(node: "Function", *, mgr: "Manager") -> list[str]:
+    """Enumerate satisfying cubes of *node* over state variables as HOA dst strings.
+
+    *node* is a ``dd.Function`` over the state variables ``q0..q{n-1}``;
+    *mgr* is the owning ``dd.BDD`` manager (``pick_iter`` lives on it,
+    not on Function objects). We enumerate minterms over the BDD's
+    *support* (i.e. no ``care_vars`` argument), so a point-successor
+    function naturally yields one cube.
+
+    For each cube:
+
+    - Positive state variables -> the cube's HOA destination
+      ``"d1&d2&..."`` (a single integer when there is one positive).
+    - Negative state variables in the cube are dropped from the output
+      (HOA `dst` expressions list only the chosen states).
+
+    A cube with zero positive state variables is treated as a bug and
+    raises ``ValueError``; the caller is responsible for rejecting
+    literal-false successor BDDs before reaching here.
+    """
+    cubes: list[str] = []
+    for cube in mgr.pick_iter(node):
+        positives = sorted(int(name[1:]) for name, val in cube.items() if val)
+        if not positives:
+            raise ValueError("Successor BDD cube has no positive state variable; cannot render an HOA destination.")
+        cubes.append("&".join(str(i) for i in positives))
+    return cubes
+
+
 # ---------------------------------------------------------------------------
 # Acceptance
 # ---------------------------------------------------------------------------

{morphata-2.0.4 → morphata-2.0.6}/src/morphata/symbolic/__init__.py

@@ -10,7 +10,10 @@ This subpackage provides:
 - :mod:`morphata.symbolic.automaton`: :class:`SymbolicAutomaton`, a
   representation that wraps an :class:`~morphata.automaton.Automaton`
   so the initial state set and every cached transition are live BDD
-  nodes in a single ``dd.BDD`` manager.
+  nodes in a single ``dd.BDD`` manager.  Also exposes
+  :func:`successors_for_alphabet`, a freestanding enumerator that
+  yields ``(symbol, succ_bdd)`` per declared symbol without
+  materialising a per-state transition relation.
 - :mod:`morphata.symbolic.transforms`: BDD-level structural transforms
   -- :func:`~morphata.symbolic.transforms.nfa_from_afa` (dealternation),
   :func:`~morphata.symbolic.transforms.determinize` (subset construction
@@ -21,6 +24,7 @@ This subpackage provides:
 """
 
 from morphata.symbolic.automaton import SymbolicAutomaton as SymbolicAutomaton
+from morphata.symbolic.automaton import successors_for_alphabet as successors_for_alphabet
 from morphata.symbolic.bdd import AP_VAR_FORMAT as AP_VAR_FORMAT
 from morphata.symbolic.bdd import STATE_VAR_FORMAT as STATE_VAR_FORMAT
 from morphata.symbolic.bdd import APRegistry as APRegistry

{morphata-2.0.4 → morphata-2.0.6}/src/morphata/symbolic/automaton.py

@@ -32,7 +32,7 @@ see :mod:`morphata.symbolic.transforms`.
 from __future__ import annotations
 
 import typing
-from collections.abc import Callable, Hashable, Iterable, Mapping, Sequence
+from collections.abc import Callable, Hashable, Iterable, Iterator, Mapping, Sequence
 from collections.abc import Set as AbstractSet
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Generic
@@ -44,6 +44,10 @@ from morphata.automaton import Automaton, BoolExpr
 from morphata.hoa import ParsedAutomaton
 
 if TYPE_CHECKING:
+    from pathlib import Path
+
+    from typing_extensions import Writer
+
     from morphata.alphabet import BooleanAlphabet
 from morphata.symbolic.bdd import (
     APRegistry,
@@ -230,11 +234,43 @@ class SymbolicAutomaton(Generic[AP]):
         *,
         name: str | None = None,
         properties: Sequence[str] | None = None,
-    ) -> str:
-        """Serialize ``self`` to an HOA v1 string via :func:`automaton_to_hoa`."""
-        from morphata.hoa import automaton_to_hoa
+        out: "Writer[str] | None" = None,
+    ) -> str | None:
+        """Serialize ``self`` to HOA v1 via :func:`symbolic_automaton_to_hoa`.
+
+        Walks the cached transition BDDs directly -- no
+        ``logic_asts.BoolExpr`` intermediates. When ``out`` is given,
+        streams output into it and returns ``None``; otherwise returns
+        the full HOA string.
+        """
+        from morphata.hoa import symbolic_automaton_to_hoa
+
+        return symbolic_automaton_to_hoa(self, name=name, properties=properties, out=out)
+
+    def to_bdd_json(self, path: "str | Path") -> None:
+        """Persist ``self`` to a BDD JSON cache via :func:`to_bdd_json`.
+
+        Writes ``path`` (the BDD nodes, via :mod:`dd`'s multi-root JSON
+        dump) and a sibling ``path + ".meta.json"`` (acceptance, AP
+        registry, transition root layout). Intended as an internal
+        fast-path cache; HOA remains the right format for sharing
+        automata with other tools.
+        """
+        from morphata.symbolic.persistence import to_bdd_json
+
+        to_bdd_json(self, path)
+
+    @staticmethod
+    def from_bdd_json(
+        path: "str | Path",
+        *,
+        alphabet: "BooleanAlphabet[Any, str]",
+        manager: Manager | None = None,
+    ) -> "SymbolicAutomaton[str]":
+        """Reload a :class:`SymbolicAutomaton` written by :meth:`to_bdd_json`."""
+        from morphata.symbolic.persistence import from_bdd_json
 
-        return automaton_to_hoa(self.to_automaton(), name=name, properties=properties)
+        return from_bdd_json(path, alphabet=alphabet, manager=manager)
 
     def to_min_dfa(self) -> "SymbolicAutomaton[AP]":
         """Determinize and minimize ``self`` into a minimal DFA.
@@ -349,6 +385,83 @@ class SymbolicAutomaton(Generic[AP]):
         )
 
 
+# ---------------------------------------------------------------------------
+# Alphabet-aware enumeration
+# ---------------------------------------------------------------------------
+
+
+def successors_for_alphabet(
+    sym_aut: "SymbolicAutomaton[AP]",
+    source: int,
+    alphabet: "BooleanAlphabet[Any, AP]",
+    symbols: Iterable[Any],
+) -> Iterator[tuple[Any, Function]]:
+    """Yield ``(symbol, succ_bdd)`` for each ``symbol in symbols`` whose
+    cofactor of the source's outgoing transitions is not ``mgr.false``.
+
+    Each yielded ``succ_bdd`` is a BDD over state variables encoding the
+    set of successors of ``source`` on ``symbol``. For DFA-shaped
+    automata it is a single state variable; for non-deterministic
+    shapes it is the OR of active successors.
+
+    Cost is bounded by ``|symbols| * len(sym_aut.transitions[source])``
+    ``mgr.let`` calls on per-row guards (each typically very small).
+    No per-state transition relation is materialised.
+
+    Yield order is a stable contract: pairs are yielded in the same
+    order ``symbols`` is iterated, with ``mgr.false`` symbols omitted.
+    Callers may walk the input alongside the yielded pairs with a two-
+    pointer pattern instead of materialising an intermediate dict.
+
+    Equivalence to ``step``: for any ``symbol``, the yielded
+    ``succ_bdd`` equals ``sym_aut.step(mgr.var(state_var_name(source)),
+    symbol)``; symbols whose ``step`` result is ``mgr.false`` are not
+    yielded.
+
+    Parameters
+    ----------
+    sym_aut
+        SymbolicAutomaton constructed with ``cache_transitions=True``.
+    source
+        Source state index in ``range(sym_aut.num_states)``.
+    alphabet
+        Boolean labeling alphabet over the same AP space as
+        ``sym_aut.ap_registry``.
+    symbols
+        Symbols to enumerate. Iterated exactly once.
+
+    Raises
+    ------
+    ValueError
+        If ``sym_aut`` was constructed with ``cache_transitions=False``
+        (no per-row pairs to cofactor), or if ``alphabet.predicates``
+        contains an AP not present in ``sym_aut.ap_registry``.
+    """
+    if sym_aut.num_states > 0 and not sym_aut.transitions:
+        raise ValueError(
+            "successors_for_alphabet requires a populated transition cache; "
+            "reconstruct SymbolicAutomaton with cache_transitions=True."
+        )
+    unknown = set(alphabet.predicates) - set(sym_aut.ap_registry)
+    if unknown:
+        raise ValueError(f"alphabet has unknown predicates not in ap_registry: {sorted(map(repr, unknown))}")
+
+    mgr = sym_aut.manager
+    rows = sym_aut.transitions[source]
+    ap_registry = sym_aut.ap_registry
+
+    for symbol in symbols:
+        truths = alphabet.labeling(symbol)
+        ap_point: dict[str, Function] = {ap_registry[ap]: (mgr.true if ap in truths else mgr.false) for ap in ap_registry}
+        succ_acc: Function = mgr.false
+        for guard_bdd, succ_bdd in rows:
+            restricted = mgr.let(ap_point, guard_bdd)
+            if restricted == mgr.true:
+                succ_acc = mgr.apply("or", succ_acc, succ_bdd)
+        if succ_acc != mgr.false:
+            yield symbol, succ_acc
+
+
 # ---------------------------------------------------------------------------
 # Private helpers
 # ---------------------------------------------------------------------------