core: automata engine #14

Merged
yuuhikaze merged 4 commits from core into master 2026-10-23 23:25:14 -05:00
Owner

Closes #12. Resolves #5 (ε encoding).

What changed

Fulfills the [friend] core brief in docs/TASKS.md. rgxr-core stays pure: no IO, and its only dependencies are still serde + thiserror. The types and serde attributes are unchanged; the wire format is byte-stable.

  • run — ε-closed active set per step, step 0 symbol: null
  • to_dfa — subset construction from the initial closure; only reachable subsets are built
  • minimize — Hopcroft partition refinement after dropping unreachable states
  • union / intersection (n-ary), difference — reachable product of ε-free, completed operands
  • concatenation — disjoint union, with ε from each operand's accepting states to the next initial state
  • complement — flips accepting states on a total DFA
  • regex_to_nfa — recursive-descent parser (no regex crate) + Thompson construction
  • fa_to_regex — state elimination with fresh start/accept nodes and a simplifying AST; output re-parses

Modules: nfa (closure, naming, ε-removal, completion), run, dfa, ops, regex. docs/CONTRACT.md and openapi.yaml document ε and the naming table.

Gates

cargo fmt --check                     → clean
cargo clippy --workspace --all-targets → 0 warnings
cargo test --workspace                → 77 passed, 0 failed
                                        (api 40, core unit 11, core acceptance 26)

Acceptance tests (crates/rgxr-core/tests/acceptance.rs)

Black-box, public API only. The oracles are independent of engine code: a separate set simulator, brute-force string enumeration up to length 6–8, Moore table-filling, and a seeded xorshift generator for random automata.

  1. a*b example: run on "ab", "aab", "b", "", with the exact trace JSON including "symbol":null
  2. (a|b)*abb → to_dfa → minimize: 4 states, matches ends_with("abb") on every string up to length 8
  3. union (3-ary), intersection, difference and concatenation on 150 random ε-NFAs, compared against brute force
  4. complement flips acceptance on 41 DFAs
  5. fa_to_regex(regex_to_nfa(r)) ≡ r over a 24-regex battery (edge cases, escapes, Unicode) and on 150 random ε-NFAs
  6. minimize on 200 random DFAs: state count equals table-filling, language equal, idempotent
  7. hand-written to_dfa golden; all constructions byte-identical across runs; serde round-trip byte-identical
  8. complement/minimize on NFAs → NotADeterministicFa containing "run to_dfa first"; existing validate() rejections unchanged

Semantic decisions

  • ε is the transition symbol "" (#5). It is never in alphabet. validate() accepts it as a transition key and rejects "" inside alphabet (new rejection, FaError::Other). Any ε-transition makes the Fa nondeterministic.
  • Characters outside the alphabet in run empty the active set: the input is rejected, but no error is returned.
  • Same-alphabet rule: union/intersection/difference return invalid_fa when alphabets differ, as openapi.yaml states. concatenation merges alphabets instead (no rule for it in openapi).
  • Products: operands are ε-removed and completed with a sink ∅ first. That makes union on NFAs correct, and union/intersection/difference of DFAs return DFAs. difference(a, b) = a ∩ complement(to_dfa(b)).
  • Naming follows CONTRACT.md's derived-state table: subsets q0,q1 with ∅ for the empty subset; products (s1,…,sn); concatenation keeps original names (#k on collision); minimize names each class after its smallest member, so minimizing an already-minimal DFA returns it unchanged; #k suffixes for every collision.
  • regex_to_nfa names states q0…qn by BFS rank. This deviates from the brief's literal "never q{counter}" rule. Thompson states have no semantic content, and BFS rank over a deterministic graph depends only on the regex, so names stay stable across runs, which is what the rule protects. Recorded in CONTRACT.md.
  • a** is valid: postfix operators stack, a** ≡ a*, and a*+? parses.
  • Empty branches are ε: "", (), a| and | all parse.
  • Parse errors are FaError::Regex (→ invalid_regex) naming a 1-based position: unclosed (, unmatched ), nothing to repeat, dangling \.
  • Empty language in fa_to_regex → FaError::Other (→ invalid_fa), because the syntax has no ∅. An ε-only language prints as the empty string.
  • fa_to_regex readability: elimination runs on the ε-free automaton and, for inputs of 16 states or fewer, also on minimize(to_dfa(fa)). The shorter result wins, with ties going to ε-free. Elimination order is fewest new edges first, ties broken by state-name order. The simplifier folds ∅/ε identities, r r* → r+, r* r* → r*, ε|r+ → r*, absorption (r* absorbs r and r+), and nullable ?.
  • Multi-char symbols stay structural in every construction. fa_to_regex ignores them, because run can never consume them.

Follow-ups (other owners)

  • api: replace the 501 placeholders in crates/rgxr-api/src/engine.rs with the commented one-line call sites (issue opened separately)
  • render/web: label "" edges as ε
Closes #12. Resolves #5 (ε encoding). ## What changed Fulfills the `[friend] core` brief in docs/TASKS.md. `rgxr-core` stays pure: no IO, and its only dependencies are still `serde` + `thiserror`. The types and serde attributes are unchanged; the wire format is byte-stable. - `run` — ε-closed active set per step, step 0 `symbol: null` - `to_dfa` — subset construction from the initial closure; only reachable subsets are built - `minimize` — Hopcroft partition refinement after dropping unreachable states - `union` / `intersection` (n-ary), `difference` — reachable product of ε-free, completed operands - `concatenation` — disjoint union, with ε from each operand's accepting states to the next initial state - `complement` — flips accepting states on a total DFA - `regex_to_nfa` — recursive-descent parser (no regex crate) + Thompson construction - `fa_to_regex` — state elimination with fresh start/accept nodes and a simplifying AST; output re-parses Modules: `nfa` (closure, naming, ε-removal, completion), `run`, `dfa`, `ops`, `regex`. `docs/CONTRACT.md` and `openapi.yaml` document ε and the naming table. ## Gates ``` cargo fmt --check → clean cargo clippy --workspace --all-targets → 0 warnings cargo test --workspace → 77 passed, 0 failed (api 40, core unit 11, core acceptance 26) ``` ## Acceptance tests (`crates/rgxr-core/tests/acceptance.rs`) Black-box, public API only. The oracles are independent of engine code: a separate set simulator, brute-force string enumeration up to length 6–8, Moore table-filling, and a seeded xorshift generator for random automata. 1. `a*b` example: `run` on "ab", "aab", "b", "", with the exact trace JSON including `"symbol":null` 2. `(a|b)*abb` → `to_dfa` → `minimize`: 4 states, matches `ends_with("abb")` on every string up to length 8 3. union (3-ary), intersection, difference and concatenation on 150 random ε-NFAs, compared against brute force 4. complement flips acceptance on 41 DFAs 5. `fa_to_regex(regex_to_nfa(r))` ≡ `r` over a 24-regex battery (edge cases, escapes, Unicode) and on 150 random ε-NFAs 6. minimize on 200 random DFAs: state count equals table-filling, language equal, idempotent 7. hand-written `to_dfa` golden; all constructions byte-identical across runs; serde round-trip byte-identical 8. complement/minimize on NFAs → `NotADeterministicFa` containing "run to_dfa first"; existing `validate()` rejections unchanged ## Semantic decisions - **ε is the transition symbol `""`** (#5). It is never in `alphabet`. `validate()` accepts it as a transition key and rejects `""` inside `alphabet` (new rejection, `FaError::Other`). Any ε-transition makes the Fa nondeterministic. - **Characters outside the alphabet in `run`** empty the active set: the input is rejected, but no error is returned. - **Same-alphabet rule:** union/intersection/difference return `invalid_fa` when alphabets differ, as `openapi.yaml` states. `concatenation` merges alphabets instead (no rule for it in openapi). - **Products:** operands are ε-removed and completed with a sink `∅` first. That makes union on NFAs correct, and union/intersection/difference of DFAs return DFAs. `difference(a, b)` = `a ∩ complement(to_dfa(b))`. - **Naming** follows CONTRACT.md's derived-state table: subsets `q0,q1` with `∅` for the empty subset; products `(s1,…,sn)`; concatenation keeps original names (`#k` on collision); minimize names each class after its smallest member, so minimizing an already-minimal DFA returns it unchanged; `#k` suffixes for every collision. - **`regex_to_nfa` names states `q0…qn` by BFS rank.** This deviates from the brief's literal "never `q{counter}`" rule. Thompson states have no semantic content, and BFS rank over a deterministic graph depends only on the regex, so names stay stable across runs, which is what the rule protects. Recorded in CONTRACT.md. - **`a**` is valid:** postfix operators stack, `a**` ≡ `a*`, and `a*+?` parses. - **Empty branches are ε:** `""`, `()`, `a|` and `|` all parse. - **Parse errors** are `FaError::Regex` (→ `invalid_regex`) naming a 1-based position: unclosed `(`, unmatched `)`, nothing to repeat, dangling `\`. - **Empty language in `fa_to_regex`** → `FaError::Other` (→ `invalid_fa`), because the syntax has no ∅. An ε-only language prints as the empty string. - **`fa_to_regex` readability:** elimination runs on the ε-free automaton and, for inputs of 16 states or fewer, also on `minimize(to_dfa(fa))`. The shorter result wins, with ties going to ε-free. Elimination order is fewest new edges first, ties broken by state-name order. The simplifier folds ∅/ε identities, `r r* → r+`, `r* r* → r*`, `ε|r+ → r*`, absorption (`r*` absorbs `r` and `r+`), and nullable `?`. - **Multi-char symbols** stay structural in every construction. `fa_to_regex` ignores them, because `run` can never consume them. ## Follow-ups (other owners) - api: replace the 501 placeholders in `crates/rgxr-api/src/engine.rs` with the commented one-line call sites (issue opened separately) - render/web: label `""` edges as `ε`
Encode ε as reserved transition symbol "" (decision in #5), list naming
candidates per construction, and pin regex rules: stacked postfix
operators, empty branches, escapes, empty-language error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt5Kc71LcLjqfyZWoZosqh
Add run with ε-closed traces, subset construction, Hopcroft
minimization, n-ary product operations, concatenation, complement,
recursive-descent regex parser with Thompson construction, and state
elimination back to regex.

Refs #12

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt5Kc71LcLjqfyZWoZosqh
test(core): add acceptance suite against brute-force oracles
Some checks failed
ci / rust (pull_request) Failing after 1m22s
ci / web (pull_request) Has been cancelled
caaa6837a3
Cover brief items 1-8: traces, (a|b)*abb pipeline, random NFA boolean
ops, complement, regex round trips, Hopcroft vs table-filling,
byte-stable goldens, and error messages.

Refs #12

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt5Kc71LcLjqfyZWoZosqh
yuuhikaze force-pushed core from caaa6837a3
Some checks failed
ci / rust (pull_request) Failing after 1m22s
ci / web (pull_request) Has been cancelled
to b53fd97c15
Some checks failed
ci / rust (pull_request) Failing after 5s
ci / web (pull_request) Successful in 12m19s
2026-10-23 23:01:40 -05:00
Compare
fix(core): bound fa_to_regex against exponential blow-up
Some checks failed
ci / rust (pull_request) Failing after 15s
ci / web (pull_request) Has been cancelled
cfd914bcc1
Eliminate on minimal DFA first (subset construction capped at 512
states), then on ε-free automaton, each under a 4096-node budget per
edge. ε-heavy Thompson NFAs such as ((a|b)*|())+ previously exhausted
memory; they now yield (a|b)*. Oversized results return invalid_fa.

Refs #12

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tt5Kc71LcLjqfyZWoZosqh
Author
Owner

status: rebased on master (render + web merged) and review fix pushed (cfd914b).

Independent review (fuzzed 3000 random NFA pairs with hostile state names like a,b, ∅ and (a,b), plus 695 random regex round trips): no wrong languages, no panics, no merged states, and Hopcroft refinement is correct. Every simplifier rewrite was checked by hand and preserves the language. One confirmed bug, now fixed:

  • fa_to_regex grew exponentially on ε-heavy NFAs. ((a|b)*|())+ exhausted memory, and (()())*(|())*(()|b()*)* produced a 475k-char regex for b*. Fix: eliminate on the minimal DFA first (subset construction capped at 512 states), then on the ε-free automaton, each under a 4096-node budget per edge. These inputs now produce (a|b)* and b* exactly; they are a regression test now.
  • New semantic decision: a conversion whose regex would exceed the budget returns FaError::Other → 400 invalid_fa ("too large to build") instead of exhausting memory. Recorded in CONTRACT.md.

Gates on cfd914b: fmt clean · clippy 0 warnings · cargo test --workspace 90 passed (api 40, core 11 + 27, render 12).

CI: "Set up job" fails on runner egress to code.forgejo.org (infra; see !11 → runner-image work). docs-html/ is not regenerated in this PR: tern's TUI does not run in a headless sandbox. Needs one nix develop path:. --command tern from a real terminal.

status: rebased on master (render + web merged) and review fix pushed (`cfd914b`). **Independent review** (fuzzed 3000 random NFA pairs with hostile state names like `a,b`, `∅` and `(a,b)`, plus 695 random regex round trips): no wrong languages, no panics, no merged states, and Hopcroft refinement is correct. Every simplifier rewrite was checked by hand and preserves the language. One confirmed bug, now fixed: - **`fa_to_regex` grew exponentially on ε-heavy NFAs.** `((a|b)*|())+` exhausted memory, and `(()())*(|())*(()|b()*)*` produced a 475k-char regex for `b*`. Fix: eliminate on the minimal DFA first (subset construction capped at 512 states), then on the ε-free automaton, each under a 4096-node budget per edge. These inputs now produce `(a|b)*` and `b*` exactly; they are a regression test now. - **New semantic decision:** a conversion whose regex would exceed the budget returns `FaError::Other` → 400 `invalid_fa` ("too large to build") instead of exhausting memory. Recorded in CONTRACT.md. Gates on `cfd914b`: fmt clean · clippy 0 warnings · `cargo test --workspace` 90 passed (api 40, core 11 + 27, render 12). CI: "Set up job" fails on runner egress to `code.forgejo.org` (infra; see !11 → runner-image work). `docs-html/` is not regenerated in this PR: tern's TUI does not run in a headless sandbox. Needs one `nix develop path:. --command tern` from a real terminal.
yuuhikaze force-pushed core from cfd914bcc1
Some checks failed
ci / rust (pull_request) Failing after 15s
ci / web (pull_request) Has been cancelled
to d21a0348a5
Some checks failed
ci / web (pull_request) Successful in 29s
ci / rust (pull_request) Failing after 1m40s
2026-10-23 23:24:56 -05:00
Compare
yuuhikaze merged commit 16d2bb92ba into master 2026-10-23 23:25:14 -05:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
k8s-services/rgxr!14
No description provided.