feat(graph): add statum-graph export crate

Cargo.toml

@@ -1,6 +1,14 @@
 [workspace]
 resolver = "2"
-members = ["module_path_extractor", "macro_registry", "statum-core", "statum-macros", "statum", "statum-examples"]
+members = [
+    "module_path_extractor",
+    "macro_registry",
+    "statum-core",
+    "statum-macros",
+    "statum",
+    "statum-examples",
+    "statum-graph",
+]
 
 [patch.crates-io]
 module_path_extractor = { path = "module_path_extractor" }
@@ -10,5 +18,5 @@ statum = { path = "statum" }
 
 [workspace.metadata.scripts]
 version-bump = "cargo script scripts/update_version.rs -- 1.0.0"
-publish = "cargo publish -p module_path_extractor && cargo publish -p macro_registry && cargo publish -p statum-core && cargo publish -p statum-macros && cargo publish -p statum"
+publish = "cargo publish -p module_path_extractor && cargo publish -p macro_registry && cargo publish -p statum-core && cargo publish -p statum-macros && cargo publish -p statum && cargo publish -p statum-graph"
 publish-dry-run = "bash scripts/check_publish_dry_run.sh"

README.md

@@ -170,6 +170,10 @@ See [docs/introspection.md](docs/introspection.md) for the full guide and
 [statum-examples/src/toy_demos/16-machine-introspection.rs](statum-examples/src/toy_demos/16-machine-introspection.rs)
 for a runnable example.
 
+If you want a ready-made renderer for that graph surface, the workspace also
+ships [statum-graph](statum-graph/README.md), which exports machine-local
+topology and Mermaid output directly from `MachineIntrospection::GRAPH`.
+
 For source-local labels and descriptions, use `#[present(...)]` on the machine,
 state variants, and transition methods. If you also want typed metadata in the
 generated `machine::PRESENTATION` constant, declare

docs/introspection.md

@@ -91,6 +91,10 @@ From there, a consumer can ask for:
 - a transition by source state and method name
 - the exact legal targets for a transition site
 
+If you want a ready-made static graph export instead of writing your own
+renderer, `statum-graph` builds `MachineDoc` values and Mermaid output directly
+from this graph surface.
+
 ## Transition Identity
 
 State ids are generated as a machine-scoped enum like `flow::StateId`.

statum-graph/Cargo.toml

@@ -0,0 +1,26 @@
+[dependencies.statum]
+path = "../statum"
+version = "0.6.9"
+
+[dev-dependencies]
+insta = "1.43"
+
+[package]
+authors = ["Eran Boodnero <eran@eran.codes>"]
+categories = ["development-tools", "rust-patterns"]
+description = "Static graph export for Statum machine introspection"
+documentation = "https://docs.rs/statum-graph"
+edition = "2021"
+keywords = [
+    "typestate",
+    "graph",
+    "mermaid",
+    "workflow",
+    "state-machine",
+]
+license = "MIT"
+name = "statum-graph"
+readme = "README.md"
+repository = "https://github.com/eboody/statum"
+rust-version = "1.93"
+version = "0.6.9"

statum-graph/README.md

@@ -0,0 +1,76 @@
+# statum-graph
+
+`statum-graph` exports static machine topology directly from
+`statum::MachineIntrospection::GRAPH`.
+
+It is authoritative only for machine-local structure:
+
+- machine identity
+- states
+- transition sites
+- exact legal targets
+- roots derivable from the static graph itself
+
+It does not model runtime-selected branches, orchestration across multiple
+machines, or consumer-owned explanation metadata.
+
+## Install
+
+```toml
+[dependencies]
+statum = "0.6.9"
+statum-graph = "0.6.9"
+```
+
+## Example
+
+```rust
+use statum::{machine, state, transition};
+use statum_graph::{render, MachineDoc};
+
+#[state]
+enum FlowState {
+    Draft,
+    Review,
+    Accepted,
+    Rejected,
+}
+
+#[machine]
+struct Flow<FlowState> {}
+
+#[transition]
+impl Flow<Draft> {
+    fn submit(self) -> Flow<Review> {
+        self.transition()
+    }
+}
+
+#[transition]
+impl Flow<Review> {
+    fn decide(
+        self,
+        accept: bool,
+    ) -> ::core::result::Result<Flow<Accepted>, Flow<Rejected>> {
+        if accept {
+            Ok(self.accept())
+        } else {
+            Err(self.reject())
+        }
+    }
+
+    fn accept(self) -> Flow<Accepted> {
+        self.transition()
+    }
+
+    fn reject(self) -> Flow<Rejected> {
+        self.transition()
+    }
+}
+
+let doc = MachineDoc::from_machine::<Flow<Draft>>();
+let mermaid = render::mermaid(&doc);
+
+assert!(mermaid.contains("s1 -->|decide| s2"));
+assert!(mermaid.contains("s1 -->|decide| s3"));
+```