morphata 2.2.3__tar.gz → 2.3.0__tar.gz

morphata-2.3.0/.agents/plans/2026-10-16-canonical-rfsa.md

@@ -0,0 +1,456 @@
+# Canonical RFSA Implementation Plan
+
+> **For implementation:** Execute the dependency chain in order and update each
+> checkbox. All tasks are sequential. Agent delegation, commits, and remote
+> actions are not authorized. Perform a separate whole-change review before
+> handing the local diff back to the author.
+
+**Goal:** Construct the canonical finite-word RFSA without constructing a full
+DFA or minimizing a DFA in the production path.
+
+**Architecture:** Implement the cover-aware subset construction from Section 5
+of Denis, Lemay, and Terlutte, using an online basis of non-coverable reachable
+state subsets. Apply it twice, with language reversal before each pass. Keep
+the algorithm in the existing symbolic transforms module and expose one
+`to_min_rfsa` operation alongside `to_min_dfa`.
+
+**Tech Stack:** Python 3.12+, existing `SymbolicAutomaton`, Pollywog-backed BDD
+guards, `Finite` acceptance, pytest, Hypothesis, Ruff, Zuban, BasedPyright,
+Sphinx. No new dependencies.
+
+**Spec:** This plan, based on the author's request for the canonical RFSA
+construction without full determinization and the verified literature below.
+
+**Assumptions:**
+
+- The public name is `to_min_rfsa`, matching `to_min_dfa`.
+- Finite AFAs are accepted through the existing dealternation performed by
+  `reverse_language`; this normalization can itself grow exponentially.
+- Canonical means unique up to state renaming, with prime residual states and
+  saturated transitions. It does not promise canonical integer IDs or bytes.
+- `initial`, `predicate_exploration_order`, and `abort_on_max_size` follow the
+  existing transform conventions, with the bound accounting specified below.
+- Public RFSA diagnostics, arbitrary NFA minimization, experiment tooling, and
+  changes to existing transform behavior are outside this plan.
+
+## Global Constraints
+
+- "Local changes only."
+- "No scheduled, recurring, background, or looping execution, and no spawning
+  agents without my approval or an agreed plan that authorizes their work."
+- "If `.jj` exists in the project root, use `jj`."
+- "Morphata must not depend on Automata Encoders."
+- "Use NumPy/numpydoc-style sections for Python docstrings. Use RST math markup
+  inside those sections and in the main docstring body."
+- Use the activated environment directly. Do not install dependencies or use
+  environment wrappers. Stop and report a missing tool.
+- This is a planning artifact. Implementation requires the author's subsequent
+  instruction; the repository defaults to read-only work.
+- Keep this plan local and ignored. Preserve existing changes, including
+  `.envrc.recommended` and `CHANGELOG.md`; do not include them in this work.
+- Do not introduce new production modules, public intermediate constructions,
+  compatibility layers, or refactors of `explore_and_transform`.
+
+## Review Focus
+
+- A subset discovered early becomes coverable later: Task 1 late-cover test
+  and basis invariant. Removed states must leave no output references.
+- Skipping expansion must preserve all reachable subset generators: Task 1
+  exhaustive two-state oracle and closure proof.
+- Set inclusion is different from BDD implication between state disjunctions:
+  Task 1 uses `frozenset[int]` and ordinary subset comparison throughout.
+- Language equality alone does not establish canonicality: Task 2 compares
+  residual-labelled states, initial/final sets, and all transition guards
+  against a separate small-DFA reference.
+- No hidden full DFA construction or alphabet enumeration: Task 2 sentinel
+  tests, compressed-language fixtures, and whole-change review.
+- Partial transitions, constants, empty language, alphabet restrictions, and
+  selected initial formulas: Tasks 1 and 2 named boundary tests.
+- Resource accounting and exponential cases: Task 1 admission-bound tests and
+  Task 2 public documentation. No polynomial-time or output-sensitive claim.
+
+---
+
+## Verified sources and current repository
+
+- Zotero key `denis2002residual`, Item ID
+  `http://zotero.org/users/5809761/items/8MQULFLR`; verified PDF:
+  `/home/anand/Zotero/storage/7RJJJLZ5/Denis et al. - 2002 - Residual finite state automata.pdf`.
+  Definition 4.5 specifies canonical states and saturation. Section 5,
+  Lemma 5.1 and Theorem 5.2 establish the two-pass construction. The end of
+  Section 5 and Proposition 6.2 establish the relevant exponential limits.
+- `src/morphata/symbolic/transforms.py:582-675`: `reverse_language` removes
+  alternation, materializes constant successors, reverses edges, swaps initial
+  and accepting states, and prunes unreachable states.
+- `src/morphata/symbolic/transforms.py:108-273`: `explore_and_transform` fixes
+  output states and edges during exploration. An online basis can later lose
+  states, so use a private worklist in the RFSA construction; leave this driver
+  unchanged.
+- `src/morphata/symbolic/bdd.py`: `partition_by_state_residual`,
+  `state_vars_in_support`, `state_set_to_bdd`, and `relation_from_rows` provide
+  symbolic successor partitions and output construction.
+- `src/morphata/symbolic/automaton.py:746-787`: public transform-method pattern.
+  `src/morphata/symbolic/__init__.py` provides explicit free-function exports.
+- `tests/symbolic/test_transforms.py` establishes transform behavior and
+  bounded property-test patterns; `tests/conftest.py` provides fresh manager
+  fixtures. Create one dedicated RFSA test file to keep this substantial test
+  family out of the existing large transforms test file.
+- `CONTRIBUTING.md`, `justfile`, and `pytest.toml` establish verification
+  commands. Run direct commands; `pytest -q` includes configured source and
+  documentation doctests. Sphinx uses `docs/refs.bib`.
+
+## Construction contract and notation
+
+For a normalized finite NFA \(A=(Q,I,F,\delta)\), all initial/successor formulas
+are disjunctions of indexed states, possibly false. Interpret the false
+formula as the empty subset; true successors must have been materialized by
+the existing normalization. Let \(\mathcal R\) be its reachable state subsets.
+Define
+
+\[
+\operatorname{covered}(S,B)
+\iff S=\bigcup\{T\in B\mid T\subsetneq S\}.
+\]
+
+The union of an empty family is empty, so the empty subset is always covered.
+The construction \(C(A)\) has the non-coverable members of \(\mathcal R\) as
+states. With final basis \(B\), emit
+
+\[
+I_C=\{S\in B\mid S\subseteq I\},\qquad
+F_C=\{S\in B\mid S\cap F\ne\varnothing\},\qquad
+\delta_C(S,a)=\{T\in B\mid T\subseteq\delta(S,a)\}.
+\]
+
+The public result is \(C((C(A^R))^R)\). The first pass produces a reachable
+RFSA for the reversed language; the second pass is canonical under Theorem
+5.2. Do not assert canonicality for the first pass on an arbitrary input NFA.
+
+### Online basis and proof obligation
+
+This scheduling optimization is an implementation adaptation of the paper's
+construction; the paper's definition alone does not prove the optimization.
+
+1. Begin with an empty basis and offer the initial subset. For a candidate
+   already in the basis, do nothing. For a covered candidate, do not store or
+   expand it. Otherwise admit and queue it.
+2. After an admission, remove any basis member now covered by the other
+   members. Skip removed members when popping pending work. A member currently
+   being expanded may finish expansion from its immutable subset snapshot.
+3. Expand a retained subset \(S\) by partitioning the BDD relation
+   \(\bigvee_{q\in S}\Delta(q)\), restricted to
+   `aut.alphabet.domain(manager)`. Offer the successor subset for each
+   satisfiable guard. Never enumerate alphabet valuations.
+4. Continue until the worklist is empty. Only then assign output state IDs and
+   construct the saturated initial formula and transition rows from the final
+   basis. Temporary successor partitions may be recomputed during emission;
+   do not retain a complete subset-transition graph or permanent visited table.
+
+Required argument: every discarded subset remains a union of current basis
+members. Replacing a basis member with a cover preserves that invariant, and
+NFA transition images distribute over union. At termination the basis is
+transition-closed up to union, so it generates all reachable subsets. Every
+retained subset was itself reached from the source initial subset; combining
+these facts and irredundancy identifies the final basis with the non-coverable
+members of \(\mathcal R\). Strict subset covers also show that a removed
+subset cannot later need admission again. Keep this reasoning near the helper.
+
+Use `frozenset[int]` for source subsets and BDDs for guards/relations. Boolean
+implication on independent state variables does not test accepted-language
+inclusion. This construction requires neither language hashing nor language
+inclusion queries.
+
+### Bounds and exceptional cases
+
+- The private pass counts cumulative basis admissions, including members later
+  removed. Raise existing `MacroStateLimitError(count)` immediately after the
+  first admission exceeding `abort_on_max_size`. A duplicate or covered
+  candidate does not increment the count. Do not retain all candidates to count
+  them. This bounds admissions, not BDD memory or wall-clock time.
+- The public operation forwards the bound independently to each existing
+  reversal/normalization stage and each private pass. It is not a bound on
+  final RFSA size. Existing normalization can exceed a zero bound even for an
+  empty language; do not add different special-case semantics to the wrapper.
+- An empty basis emits a zero-state automaton with false initial condition and
+  `Finite(frozenset())`. Do not materialize an empty-language RFSA state.
+- Keep a nonempty residual containing the empty word accepting. Include every
+  eligible initial state and transition, including non-maximal targets.
+- Preserve manager and alphabet identity. Canonicality holds over the supplied
+  alphabet domain. Finite AFAs are normalized using existing code; reject
+  omega acceptance with `NotImplementedError` before construction.
+- Assign final IDs contiguously from zero by sorting the integer tuple of each
+  source subset lexicographically. This fixes the private helper's subset-to-ID
+  correspondence for its tests. Predicate exploration order controls guard exploration and
+  must cover predicates in the relation/domain. State numbering is outside the
+  language-level canonicality guarantee.
+
+## Task 1: Implement the private cover-aware NFA construction
+
+**Files:**
+
+- Modify: `src/morphata/symbolic/transforms.py`, beside the existing reversal
+  and finite-word transforms (`reverse_language` currently at lines 582-675).
+- Create: `tests/symbolic/test_rfsa.py` for RFSA fixtures and correctness tests.
+
+**Interfaces:**
+
+- Consumes: an already normalized, finite, non-alternating `SymbolicAutomaton`
+  whose constant true successors have been materialized.
+- Produces the private function:
+
+```python
+def _residualize_nfa[AP: Hashable, Symbol](
+    aut: SymbolicAutomaton[AP, Symbol],
+    *,
+    predicate_exploration_order: Sequence[AP] | None = None,
+    abort_on_max_size: int | None = None,
+) -> SymbolicAutomaton[AP, Symbol]: ...
+```
+
+**Parallelization:** Sequential; Task 2 depends on this helper and modifies the
+same implementation and test files.
+
+- [x] **Step 1: Write the failing basis and boundary tests.** Add:
+  - `test_residualize_matches_exhaustive_two_state_subsets`: enumerate all
+    256 two-state/two-symbol transition relations and all four initial subsets
+    in a test-only reference; compare the non-coverable reachable subsets with
+    those represented by the helper's final initial/final/transition structure.
+    Use the specified sorted subset-to-index correspondence and compare every
+    row, initial set, and final set. Fix source acceptance to `{1}`. Bound
+    manager lifetime per transition relation; exercise both symbols.
+  - `test_residualize_removes_late_cover`: initial `{0,1}`, transitions
+    `0 --a--> 0`, `1 --b--> 1`, all other transitions empty, both accepting.
+    Expect two accepting states, both initial, with separate `a`/`b` loops;
+    the initially admitted `{0,1}` must disappear completely.
+  - `test_residualize_skips_covered_candidate`: initial `{0}`,
+    `0 --a--> {1}`, `0 --b--> {0,1}`, `1 --a--> {1}`, `1 --b--> {0}`.
+    Set source acceptance to `{1}` and `predicate_exploration_order=('b','a')`,
+    which visits the singleton `a` valuation first under False-before-True
+    ordering. With cap 2, expect success, the two singleton basis states, and
+    both successor targets on the `b` edge from the initial state.
+  - `test_residualize_empty_subset`: zero-state false-initial input produces
+    zero states and empty acceptance.
+  - `test_residualize_admission_bound`: the late-cover example admits three
+    subsets cumulatively; cap 2 raises with `.explored == 3`, cap 3 succeeds
+    with two output states. The covered-candidate fixture above succeeds at
+    cap 2, including repeated visits to its covered union.
+  - `test_residualize_preserves_finite_domain`: include an unused letter `c`
+    in `finite_alphabet({'a','b','c'})`; partial transitions on it must reject,
+    and guards must respect the full alphabet domain.
+
+- [x] **Step 2: Run `pytest tests/symbolic/test_rfsa.py -q`.** Expect failure
+  because `_residualize_nfa` is absent. Keep the exhaustive reference isolated
+  to tests; it may enumerate subsets and alphabet symbols.
+
+- [x] **Step 3: Implement `_residualize_nfa` with the online basis and proof
+  above.** Keep set-cover checking local to this helper. Emit all final-basis
+  subsets contained in each successor image; an arbitrary irredundant cover
+  would omit saturated transitions. Build fresh output caches and acceptance
+  containing output state IDs only. Do not adapt `explore_and_transform` or
+  add calls to `determinize`, `minimize_dfa`, `to_min_dfa`, language equivalence,
+  hashing, or alphabet enumeration.
+
+- [x] **Step 4: Run the new tests and nearby transforms tests.**
+  `pytest tests/symbolic/test_rfsa.py tests/symbolic/test_transforms.py -q`
+  must pass. Verify the set-cover argument term by term using the installed
+  `verifying-mathematical-notation` skill; explicitly distinguish source
+  subsets, output IDs, and residual languages.
+
+- [x] **Step 5: Run focused static checks.**
+  `ruff check src/morphata/symbolic/transforms.py tests/symbolic/test_rfsa.py`
+  and `ruff format --check src/morphata/symbolic/transforms.py tests/symbolic/test_rfsa.py`
+  must pass. Run `zuban check` and `basedpyright`; report any pre-existing
+  failures separately without changing unrelated files.
+
+- [x] **Step 6: Review the local Task 1 diff.**
+  `jj diff -- src/morphata/symbolic/transforms.py tests/symbolic/test_rfsa.py`.
+  Leave it uncommitted; inspect all changes before starting Task 2.
+
+## Task 2: Expose and verify the canonical two-pass operation
+
+**Files:**
+
+- Modify: `src/morphata/symbolic/transforms.py` for the free function.
+- Modify: `src/morphata/symbolic/automaton.py:746-787` vicinity for the method.
+- Modify: `src/morphata/symbolic/__init__.py` for the explicit export.
+- Modify: `tests/symbolic/test_rfsa.py` for the public contract and oracle.
+- Modify: `docs/concepts/symbolic.rst`, finite-word transformation pipeline.
+- Modify: `docs/api/morphata.symbolic.rst`, free-function listing.
+- Modify: `docs/refs.bib`, add only verified `denis2002residual` metadata.
+
+**Interfaces:**
+
+- Consumes: Task 1's `_residualize_nfa` and existing `reverse_language`.
+- Produces the exported free function and corresponding method:
+
+```python
+def to_min_rfsa[AP: Hashable, Symbol](
+    aut: SymbolicAutomaton[AP, Symbol],
+    *,
+    initial: Function[AP, int] | None = None,
+    predicate_exploration_order: Sequence[AP] | None = None,
+    abort_on_max_size: int | None = None,
+) -> SymbolicAutomaton[AP, Symbol]: ...
+
+def to_min_rfsa(
+    self,
+    *,
+    initial: Function[AP, int] | None = None,
+    predicate_exploration_order: Sequence[AP] | None = None,
+    abort_on_max_size: int | None = None,
+) -> SymbolicAutomaton[AP, Symbol]: ...
+```
+
+**Parallelization:** Sequential after Task 1. No independent agent tasks.
+
+- [x] **Step 1: Add failing public-contract and canonicality tests.**
+  - `test_to_min_rfsa_finite_language`: use `finite_alphabet({'a','b','c'})`
+    and the language `{aa,ab,ba,cb}`. Expect four RFSA states and six minimal
+    DFA states in the test reference. Compare prime residual identities and all
+    saturated guards, not just the four-state count.
+  - `test_to_min_rfsa_matches_small_dfa_reference`: implement a test-only oracle
+    from a minimal DFA: enumerate its rooted residuals, compute strict language
+    containment by emptiness of differences, discard residuals covered by the
+    union of smaller residuals, and construct all initial/final/edge conditions
+    from Definition 4.5. Label languages with exact `CanonicalDfaHasher.canonical_bytes`
+    on their minimized rooted DFAs, using the same predicates/domain. Compare
+    every output state's label, initial and final label sets, and guard BDD for
+    each pair of labels. A hash digest alone is insufficient. Use bounded
+    generated NFAs with 1-3 states, two letters, 30 examples, and fresh managers.
+  - `test_to_min_rfsa_compressed_suffix_family`: the `n`-th symbol from the end
+    is `1`, for fixed `n=4,6` over `finite_alphabet({'0','1'})`. Build the NFA
+    with initial state 0 looping on both letters and additionally entering 1
+    on `1`; states 1 through `n-1` advance on either letter; only `n` accepts.
+    Expect RFSA sizes 5/7 and reference DFA sizes 16/64. Compare acceptance
+    with `len(word) >= n and word[-n] == '1'` on all words through length `n+1`.
+  - `test_to_min_rfsa_does_not_determinize`: after creating fixtures/oracle,
+    patch the free `determinize` and `minimize_dfa` and the corresponding
+    `SymbolicAutomaton.determinize`/`to_min_dfa` entrypoints to raise. The public
+    construction must still return the expected compressed RFSA. Check word
+    acceptance while patches are installed; run any DFA oracle outside them.
+  - `test_to_min_rfsa_does_not_enumerate_alphabet`: replace `alphabet.symbols`
+    with a raising callable and run the public operation on a powerset alphabet
+    with irrelevant predicates. Check same manager/alphabet identity and sample
+    word acceptance. Avoid a timing threshold.
+  - `test_to_min_rfsa_constants_and_partial_moves`: parameterize empty,
+    epsilon-only, universal, and nonempty partial NFAs. Expected state counts
+    are 0, 1, 1, and the reference count respectively. Empty/epsilon-only outputs
+    have no fabricated dead state; universal output has an accepting self-loop.
+  - `test_to_min_rfsa_selected_initial`: choose a disconnected component with
+    `initial=manager.q_var(q)`; also test false, true, a disjunction, and a
+    conjunction through existing dealternation. Compare against the selected
+    language, never the stored original initial condition.
+  - `test_to_min_rfsa_normalizes_alternation`: a small conjunction/disjunction
+    AFA agrees with the full-DFA oracle and returns disjunctive NFA successors.
+  - `test_to_min_rfsa_rejects_omega`: Buchi input raises `NotImplementedError`.
+  - `test_to_min_rfsa_bound_and_method`: free function and method agree, a
+    sufficient cap succeeds, and insufficient cap raises `MacroStateLimitError`.
+    Cover final canonicality under input state renaming and a second RFSA pass
+    through the residual-labelled oracle comparison, without requiring equal IDs.
+
+- [x] **Step 2: Run the public tests and observe the missing interface.**
+  `pytest tests/symbolic/test_rfsa.py -q -k to_min_rfsa` must fail because the
+  public free function/method is absent.
+
+- [x] **Step 3: Add the public free function, method, and export.**
+  Check finite acceptance, then call `reverse_language` with the selected
+  initial formula, `_residualize_nfa`, `reverse_language`, `_residualize_nfa`.
+  Forward order/bound parameters at each stage. Apply `initial` only at the
+  first reversal. Do not add a DFA fallback or silently return a noncanonical
+  result when a cap is reached. Keep the method a thin wrapper like existing
+  transforms; do not force a deterministic cache flag.
+
+- [x] **Step 4: Document the exact contract and verified citation.**
+  Use NumPy-style sections/RST math in the new docstrings. Explain prime
+  residuals, saturated edges, the online cover invariant, partial NFA output,
+  canonicality up to isomorphism, and per-stage bounds. Add a small runnable
+  finite-language example to the concepts page and list the free function in
+  the API page. Obtain the entry with `zotero_ls citation export denis2002residual`
+  and append its verified metadata to `docs/refs.bib`; do not alter other
+  entries. Use the RST citation role with key `denis2002residual`. State that the full DFA is
+  avoided but basis/intermediate/output size can still be exponential. Do not
+  promise canonical serialization or unrestricted minimal-NFA size.
+
+- [x] **Step 5: Run focused validation.**
+  `pytest tests/symbolic/test_rfsa.py tests/symbolic/test_transforms.py tests/symbolic/test_language_equivalence.py tests/symbolic/test_compose.py -q`
+  must pass, including oracle adjacency/saturation checks and both sentinels.
+
+- [x] **Step 6: Run final validation once after the change is complete.**
+
+```bash
+ruff format --check src/morphata/symbolic/transforms.py src/morphata/symbolic/automaton.py src/morphata/symbolic/__init__.py tests/symbolic/test_rfsa.py
+ruff check src/morphata/symbolic/transforms.py src/morphata/symbolic/automaton.py src/morphata/symbolic/__init__.py tests/symbolic/test_rfsa.py
+zuban check
+basedpyright
+pytest -q
+sphinx-build -b html docs/ docs/_build/html
+```
+
+  Expected: successful formatting, lint, type checking, complete configured
+  tests/doctests, and Sphinx build without new diagnostics. If failures arise,
+  identify whether they are introduced or pre-existing; do not broaden scope
+  to unrelated fixes. Re-run only affected checks after a repair.
+
+- [x] **Step 7: Perform the separate whole-change review.**
+  Review the final diff against the formulas, basis proof, all Review Focus
+  items, no-determinization/alphabet-enumeration constraints, and existing
+  local changes. Record actual validation results. Leave implementation and
+  documentation local and uncommitted for author review.
+
+## Planning validation and handoff
+
+Only this plan was written during planning. A separate finite-set calculation
+matched the online basis to exhaustive reachable-subset enumeration in all
+1,024 two-state/two-symbol transition/initial configurations. The same
+calculation produced 5/7 states for the fixed suffix families with `n=4,6`.
+This checks the proposed basis schedule on bounded examples; it is not a
+production implementation or a substitute for the proof and repository tests.
+
+Recommend direct sequential implementation after review: both tasks modify
+the same algorithm/test files and Task 2 relies on Task 1. Parallel agents
+offer no independent work here and are not authorized. Confirm or correct
+the proposed API, bound semantics, and scope before implementation.
+
+## Implementation progress
+
+Task 1: 310 tests passed; Ruff and Zuban passed. BasedPyright reported only
+the expected temporary unused-private-helper warning before Task 2 integration.
+
+Task 2: 380 focused tests passed. Ruff formatting/lint, Zuban, BasedPyright,
+and Sphinx passed with no diagnostics. The separate whole-change review checked
+source-subset/output-ID separation, preservation of covers under replacement,
+transition closure under union, saturation, and the absence of production
+determinization or alphabet enumeration.
+
+Property testing found that an output basis can exceed the source state count;
+output BDD variables are now declared before emission, with a fixed three-state
+input/four-state-output regression. Exploratory tight caps in the compression
+fixtures were removed: the plan specifies cumulative admissions, whose count
+depends on exploration order, separately from final state count. The dedicated
+late-cover admission-bound tests retain exact expected counts.
+
+Raw `pytest -q` encountered four collection errors in stale generated
+`docs/_build/html/_downloads` examples importing removed `morphata.encoders`
+modules. Full source/test/documentation-doctest validation is being run with
+`pytest -q --ignore=docs/_build`; no test configuration or generated files were
+changed to bypass those stale examples.
+
+### Mathematical review
+
+- Source of truth: the construction contract in this plan and Definition 4.5,
+  Lemma 5.1, and Theorem 5.2 of the verified local paper.
+- Symbol ledger: source subsets are `frozenset[int]`; the basis is `basis`;
+  source transition images come from OR-folded source rows; guards are BDDs
+  restricted to `alphabet.domain`; output IDs are assigned only after closure.
+- Verified correspondences: strict set covers preserve the generated union
+  family; source images distribute over union; accepting subsets intersect
+  the source accepting set; initial/target subsets use non-strict containment.
+- Mismatches or ambiguities: none remain in the reviewed implementation. The
+  online scheduling adaptation and its exponential limits are documented.
+- Recommended fix: none outstanding. All changes remain local and uncommitted.
+
+Final validation: `pytest -q --ignore=docs/_build` completed with 770 passed,
+11 xfailed, and 16 dependency warnings in 418.58 seconds. Sphinx rebuilt
+successfully; Ruff formatting/lint, Zuban, and BasedPyright all passed. The
+raw-command generated-document collection issue is recorded above. Both tasks
+and the whole-change review are complete; no commits or remote actions occurred.

{morphata-2.2.3 → morphata-2.3.0}/.envrc

@@ -21,4 +21,6 @@ fi
 
 dotenv_if_exists
 
+export PIXI_FROZEN=true
+
 eval "$(pixi shell-hook)"

{morphata-2.2.3 → morphata-2.3.0}/AGENTS.md

@@ -29,6 +29,13 @@ The narrow exception: a **surgical, already-decided edit** the author has spelle
 Do exactly that and nothing more.
 When unsure whether a change qualifies, treat it as out of scope and ask.
 
+## Project Boundaries
+
+Morphata owns automata representations, algebraic operations, semiring operators,
+and execution. Automata Encoders owns symbolic input features, trainable
+encoders, training/evaluation tools, and comparison baselines. Morphata must
+not depend on Automata Encoders.
+
 ## Development Environment
 
 The development shell already has the project virtual environment activated,
@@ -38,3 +45,8 @@ etc. are on `PATH` directly.
 Just invoke the tool.
 If a tool is missing, stop and tell the user rather than trying to bootstrap
 or reinstall the environment.
+
+## Documentation
+
+Use NumPy/numpydoc-style sections for Python docstrings. Use RST math markup
+inside those sections and in the main docstring body.

{morphata-2.2.3 → morphata-2.3.0}/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 2.3.0 — 2026-10-21
+
+This is *another* hefty release,
+and has been the culmination of `morphata` being used to dogfood multiple other
+projects --- I will not reveal the level of success of those other projects though ---
+which has allowed me to harden `morphata` and also add a bunch of relevant features.
+
+### Added
+
+- `BooleanAlphabet.as_guard` turns a concrete symbol into its BDD guard.
+
+- `to_min_rfsa`, also available as `SymbolicAutomaton.to_min_rfsa`,
+  constructs canonical residual finite-state automata using cover-aware subset
+  exploration and language reversal, without building the full DFA.
+  Follows the same API as the other transformers.
+
+- `SymbolicAutomaton` now has helpers for determining if its language is empty, whether
+  it contains the language of another automaton, and a helper to return relational edges
+  (for nondeterministic automata only).
+
+- `JaxBatchedMatrixOperator` runs batches of integer-encoded words over dense matrix
+  operators using JAX's `lax.scan`.
+  You can run every word on every operator, or pair each word with one operator.
+  Padded words with different lengths are supported too.
+
+- A JAX min-max Boolean algebra with a choice of native or smooth surrogate gradients.
+  The forward pass still computes exact min and max;
+  the surrogate gives the backward pass a smoother signal.
+
+- Automaton sampling helpers in `morphata.utils.sampling`,
+  covering random DFAs and AFAs, structured language families, temporal specifications,
+  and local mutations.
+  Useful when you want some variety in the automata you are working with.
+
+- `factor_initial=True` on `remove_alternation`, `determinize`,
+  and `to_min_dfa` transforms the components of the initial formula separately,
+  then combines them smallest-first.
+  Another option for constructions where exploring everything together gets large.
+
+- `EditDistanceAutomaton` converts a given symbolic automaton to a min-plus weighted
+  automaton that computes the edit distance between a word and the given automaton.
+  Additionally, we have lifted this word-language edit distance to a quasimetric
+  that computes a directed Hausdorff distance to the `EditDistanceAutomaton` from some
+  other automaton.
+
+- `unsigned_levenshtein_distance` computes the worst-case number of edits needed to
+  repair a source word into the target language.
+  It returns zero when the source language is contained in the target.
+  `signed_levenshtein_distance` reports a containment margin
+  when the source language is contained in the target,
+  and the same repair cost otherwise.
+
+- `language_separation_distance` computes the minimum edit distance between any pair of
+  words from two languages.
+  It returns infinity if either is empty.
+
+### Changed
+
+- Persistent automata now retain the original predicate objects.
+  `morphata.storage.configure_converter` lets you use your own cattrs converter
+  and predicate serialization hooks, with consistent ordering across backends.
+  The JSON helpers remain for string predicates.
+
+- Custom alphabet domain callbacks now need to accept `care_vars`.
+  `BooleanAlphabet.intersect_with_domain` uses this to constrain guards using only
+  the predicates those guards actually mention.
+
+### Fixed
+
+- DFA minimization now compares guards on the full alphabet domain, so guards
+  that differ only on impossible predicate valuations do not split equivalent states.
+
+- Symbolic transformations reuse alphabet domains within each construction stage.
+  Dealternation, determinization,
+  and RFSA subset exploration cache projected domains by the combined relation's
+  predicate support and apply them before partitioning.
+
+- Canonical finite-alphabet traversal now restricts transitions before partitioning,
+  so impossible predicate valuations do not affect BFS state numbering.
+
+- `compose_automata` now removes pruned states from the finite accepting set too.
+  Previously, accepting states could survive in the bookkeeping
+  after their transition rows had been removed.
+
+- `has_conjunctive_state_terms` previously did not correctly handle successor states
+  that were just Boolean constants, i.e., unmaterialized accepting/rejecting sinks.
+
 ## 2.2.3 — 2026-09-22
 
 This is a hefty release, but all really cool things that I am super proud of

{morphata-2.2.3 → morphata-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: morphata
-Version: 2.2.3
+Version: 2.3.0
 Summary: Representation theory for automata, made practical.
 Project-URL: Documentation, https://docs.anandb.dev/morphata
 Project-URL: Repository, https://git.anandb.dev/morphata.git
@@ -11,7 +11,7 @@ License-File: LICENSE
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.12
-Requires-Dist: algebraic-arrays>=1.3.0
+Requires-Dist: algebraic-arrays>=1.3.10
 Requires-Dist: attrs>=25.4.0
 Requires-Dist: bitarray>=3.10.0
 Requires-Dist: cattrs>=26.1.0
@@ -24,7 +24,8 @@ Requires-Dist: typing-extensions>=4.14
 Provides-Extra: dot
 Requires-Dist: pydot>=4.0.1; extra == 'dot'
 Provides-Extra: jax
-Requires-Dist: jax>=0.8; extra == 'jax'
+Requires-Dist: flax; extra == 'jax'
+Requires-Dist: jax<0.11.2,>=0.8; extra == 'jax'
 Provides-Extra: torch
 Requires-Dist: torch>=2.0; extra == 'torch'
 Description-Content-Type: text/x-rst

{morphata-2.2.3 → morphata-2.3.0}/bench/README.md

@@ -20,6 +20,12 @@ To get pytest-benchmark's tabular wall-time output:
   JAX-only scale cases are opt-in via
   `MORPHATA_RUN_SCALE_BENCHMARKS=1`; run each scale case in a fresh process under
   a hard memory limit.
+- `test_transforms_perf.py` -- alternation removal and determinization over
+  single-root conjoined-eventuality and until-chain AFA families, plus composed
+  eventuality AFAs whose initial formulas have multiple state variables. The
+  composed cases compare the monolithic and opt-in factored-initial
+  constructions. Results are grouped by transform, construction, and formula
+  size. Regular cases stop at size 10.
 - `test_sere_nlm_perf.py` -- NLM-intersection state-space blowup.
   Cases: `NLMInter(a0..a_{n-1})` for n in 2..6, `NLMInter(a_i;b_i)`
   for n in 2..4, plus length-matching `Inter` baselines.