Feature Request: Persistence API

[sda97ghb]

Currently, persisting the state of a StateChart (especially complex ones with hierarchy or parallelism) often requires relying on internal implementation details. I am proposing the addition of a formal, public API for serialization and deserialization to ensure robust persistence across different storage backends.

Proposed Requirements

1. Standardized Data Format: Define a clear, versioned schema (e.g., JSON Schema) that represents the full configuration of a running state machine.
2. Public API: Provide a documented public API for:
   1. Exporting the current state configuration to the schema format.
   2. Re-instantiating a StateChart instance from that format.
3. Full Feature Support: The persistence mechanism must accurately capture and restore:
   1. Compound States: The StateChart must be re-instantiated in exactly the same inner/nested state it was in before saving.
   2. Parallel States: All parallel regions must be restored so that every active branch is exactly as it was before the save.
   3. History States: Snapshots of both deep and shallow history states to ensure transitions back into compounds work correctly after a reload.
4. No Side Effects on Re-instantiation: Guards and callbacks should not be re-evaluated during re-instantiation, as they would have already executed prior to the save. Possibly, add a setting to change this behavior.

Use Cases

This is essential for long-running workflows and entities where the state machine instance cannot reside in memory indefinitely, e.g.:

• Web applications saving state to DB between requests
• Distributed systems and serverless environments where a state machine must "sleep" in storage and "wake up" on a different node without losing its position in a complex hierarchy or parallel flow

Considerations

• Re-binding of the custom models
• Delayed events

[fgmacedo]

Hi @sda97ghb, thanks a lot for taking the time to write this proposal, it's really well structured and the use cases are spot on.

There's significant overlap with #597, which is an RFC focused specifically on the problem of model.state becoming an OrderedSet in compound/parallel machines (breaking the direct mapping to a DB column) and discusses serialization approaches for the current configuration (leaf-only flag, model protocol, codec).

I see #597 as a natural subset of this issue: solving "how the configuration goes to storage" is the first step toward a complete persistence API. This issue (#618) goes further, especially on:

• History states (deep/shallow), snapshot and restore
• Pending delayed events
• Re-binding of custom models
• Versioned schema and documented public API
• Guarantee that guards/callbacks are not re-evaluated on re-instantiation

I'd like to keep both issues open and treat #597 as the first scope slice of #618. Feedback on the approaches discussed in #597 will help unblock the path here as well.