Skip to content

Add XState v5 descriptor and target parity - #41

Merged
JovaniPink merged 1 commit into
masterfrom
v5-descriptor-target-parity
Aug 24, 2026
Merged

Add XState v5 descriptor and target parity#41
JovaniPink merged 1 commit into
masterfrom
v5-descriptor-target-parity

Conversation

@JovaniPink

@JovaniPink JovaniPink commented Aug 24, 2026

Copy link
Copy Markdown
Owner

Summary

Bring event descriptor selection and relative target resolution into stable XState v5 parity while preserving the W3C SCXML run-to-completion core.

Rationale

XState 5.32 clarified that a failed exact descriptor guard must fall through to matching partial wildcard descriptors. The existing Python selector performed exact equality only, which skipped catch-all and partial descriptors entirely. The target parser also accepted IDs and single-segment siblings but rejected common XState paths such as on.hist.

This change keeps XState descriptor matching separate from W3C bare-prefix descriptor semantics. A bare error descriptor remains exact and does not match error.platform.

Scope

  • Select descriptors in stable XState v5 priority order: exact, longest matching partial wildcard, shorter partial wildcards, and catch-all.
  • Preserve document order inside one descriptor and continue after guard failure.
  • Check an ancestor only after every local descriptor candidate fails.
  • Support partial descriptors such as event.* for both event and dotted descendants.
  • Reject infix and non-tokenized wildcard forms by leaving them nonmatching.
  • Resolve sibling, sibling-descendant, dot-prefixed child, root-child, ID, and multiple target paths.
  • Add the upstream shallow and deep unvisited parallel-history shapes using target: "on.hist".
  • Correct stale 56-case documentation to the configured 57-case SCXML suite.

Non-scope

  • W3C bare-prefix event descriptor matching.
  • New warning or validation policy for malformed wildcard descriptors.
  • General SCXML datamodel or executable-content support.
  • Changes to history execution beyond target path resolution.
  • Version changes, publication, or new conformance claims.

Validation

Local Python 3.14:

  • poetry run python -m pytest tests/ --ignore=tests/test_scxml.py: 459 passed.
  • poetry run python -m pytest tests/test_scxml.py: 57 passed.
  • poetry run mypy src/xstate/: passed.
  • poetry run mypy --strict src/xstate/algorithm.py: passed.
  • Ruff format and lint checks: passed.
  • poetry check --lock: passed.
  • poetry build: passed.
  • poetry run python scripts/validate_distribution.py: installed-wheel smoke passed.

Hosted exact head 6468d8363d49715ceb8f1efc2260907aa736289b:

  • Python 3.13 test job: passed.
  • Python 3.14 test job: passed.
  • SCXML smoke job: passed.
  • Python 3.14 code-quality job: passed.

Risks and rollback

The main risk is event selection changing for configurations that already contain wildcard-looking keys. Coverage locks exact priority, guard fallback, invalid wildcard forms, ancestor fallback, and parallel region independence. Target resolution is limited to explicit dotted traversal through configured child keys.

Rollback is a revert of this PR. No persisted data, migration, dependency, or release artifact is changed.

Review focus

  • Descriptor priority and guard fallthrough in select_transitions.
  • The boundary between XState event.* semantics and exact bare descriptors.
  • Relative target path anchoring for sibling and dot-prefixed targets.
  • Unchanged transition conflict resolution and SCXML ordering.

Stack and merge order

This is PR 1 of 3 and targets master. Merge it before bounded-microstep-traces, then actor-ref-boundary.

@JovaniPink
JovaniPink marked this pull request as ready for review August 24, 2026 18:14
@JovaniPink
JovaniPink merged commit c7af82f into master Aug 24, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant