Enum derive support

.gitignore

@@ -1,5 +1,8 @@
 .idea/
 .vscode/
+.worktrees/
+
+.claude/
 
 target/
 fuzz/artifacts/

GUIDE.md

@@ -160,7 +160,7 @@ Base dependency:
 
 ```toml
 [dependencies]
-recallable = "0.1.0"
+recallable = "0.2.0"
 ```
 
 MSRV is Rust 1.88 with edition 2024.
@@ -182,15 +182,15 @@ Example dependency sets:
 ```toml
 [dependencies]
 # Readable std example
-recallable = "0.1.0"
+recallable = "0.2.0"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 ```
 
 ```toml
 [dependencies]
 # no_std + serde example
-recallable = { version = "0.1.0", default-features = false, features = ["serde"] }
+recallable = { version = "0.2.0", default-features = false, features = ["serde"] }
 serde = { version = "1", default-features = false, features = ["derive"] }
 postcard = { version = "1", default-features = false, features = ["heapless"] }
 heapless = { version = "0.9.2", default-features = false }
@@ -255,6 +255,13 @@ With the default `serde` feature enabled, it also injects:
 - `#[derive(serde::Serialize)]` on the source struct
 - `#[serde(skip)]` on fields marked `#[recallable(skip)]`
 
+Enum support is intentionally split:
+
+- assignment-only enums can use `#[recallable_model]` directly
+- enums with skipped `PhantomData<_>` marker fields can also use it directly
+- enums with nested `#[recallable]` or other `#[recallable(skip)]` fields
+  should derive `Recallable` and implement `Recall` or `TryRecall` manually
+
 Example:
 
 ```rust
@@ -356,6 +363,13 @@ Important distinction:
 - `#[recallable_model]` mutates source-side serde behavior for the common case
 - direct `#[derive(Recallable, Recall)]` does not
 
+Direct derives are also the split point for complex enums:
+
+- `#[derive(Recallable)]` supports enum-shaped mementos under the normal field rules
+- `#[derive(Recall)]` works only for assignment-only enums
+- enums with nested `#[recallable]` or skipped variant fields should derive
+  `Recallable` and implement `Recall` or `TryRecall` manually
+
 If you use direct derives and want the source struct to serialize in the same
 shape as the generated memento, you must add the serde derives and
 `#[serde(skip)]` attributes yourself.
@@ -381,6 +395,66 @@ Generated mementos are intentionally somewhat opaque:
 This design pushes callers toward "construct or deserialize a memento, then
 apply it" instead of depending on widened field visibility.
 
+### Skipped `PhantomData` and retained generics
+
+Most skipped fields simply disappear from the generated memento. The tricky case
+is when a skipped `PhantomData<_>` is the only field mentioning a generic that
+still must remain part of the memento type.
+
+```rust
+use core::any::TypeId;
+use core::marker::PhantomData;
+use recallable::Recallable;
+
+#[derive(Recallable)]
+struct BoundDependent<T: From<U>, U> {
+    value: T,
+    #[recallable(skip)]
+    marker: PhantomData<U>,
+}
+
+type Left = <BoundDependent<String, &'static str> as Recallable>::Memento;
+type Right = <BoundDependent<String, String> as Recallable>::Memento;
+
+assert_ne!(TypeId::of::<Left>(), TypeId::of::<Right>());
+```
+
+Why this needs a hidden marker:
+
+- the skipped field means there is no visible memento field of type `U`
+- `U` still matters, because the retained generic `T` depends on it through
+  `T: From<U>`
+- the generated memento type therefore needs to keep `U` alive internally
+
+The derive handles that by synthesizing an internal `PhantomData` marker on the
+generated memento.
+
+If a skipped generic is otherwise unused, the derive prunes it instead of
+preserving it:
+
+```rust
+use core::any::TypeId;
+use core::marker::PhantomData;
+use recallable::Recallable;
+
+#[derive(Recallable)]
+enum SkippedGenericEnum<T, U> {
+    Value(T),
+    Marker(#[recallable(skip)] PhantomData<U>),
+}
+
+type Left = <SkippedGenericEnum<u8, u16> as Recallable>::Memento;
+type Right = <SkippedGenericEnum<u8, u32> as Recallable>::Memento;
+
+assert_eq!(TypeId::of::<Left>(), TypeId::of::<Right>());
+```
+
+So the rule is:
+
+- if a skipped generic is no longer needed, the memento drops it
+- if it is still needed by retained generics or bounds, the derive keeps it via
+  an internal hidden marker
+
 ## Recursive fields and container-defined semantics
 
 Mark a field with `#[recallable]` when that field should use its own
@@ -476,7 +550,7 @@ the generated memento.
 
 ```toml
 [dependencies]
-recallable = { version = "0.1.0", features = ["impl_from"] }
+recallable = { version = "0.2.0", features = ["impl_from"] }
 ```
 
 ```rust
@@ -541,7 +615,7 @@ serde support by default:
 
 ```toml
 [dependencies]
-recallable = { version = "0.1.0", default-features = false }
+recallable = { version = "0.2.0", default-features = false }
 ```
 
 Then define the memento and recall behavior manually:
@@ -581,11 +655,16 @@ This manual style pairs naturally with:
 
 The derive macros support more than just simple named structs.
 
-### Supported struct shapes
+### Supported item shapes
 
 - named structs
 - tuple structs
 - unit structs
+- enums for `Recallable`
+- enums for `Recall` and `recallable_model` only when every variant field is
+  assignment-only
+- complex enums should derive `Recallable` only and supply manual `Recall` or
+  `TryRecall`
 
 ### Supported generic forms
 
@@ -637,7 +716,7 @@ write-side output format by default.
 
 ### `#[recallable_model]`
 
-Convenience attribute for the common struct model path.
+Convenience attribute for the common struct or assignment-only enum model path.
 It is the recommended default whether or not `serde` is enabled; with `serde`
 enabled it also removes extra derive boilerplate.
 
@@ -646,6 +725,8 @@ Behavior:
 - injects `Recallable` and `Recall`
 - injects `serde::Serialize` when the `serde` feature is enabled
 - injects `#[serde(skip)]` onto fields marked `#[recallable(skip)]`
+- rejects complex enums where generated `Recall` would be ambiguous; those
+  should derive `Recallable` and implement `Recall` or `TryRecall` manually
 
 ### `#[derive(Recallable)]`
 
@@ -654,16 +735,19 @@ Generates:
 - the companion memento type
 - the `Recallable` implementation
 - `From<Struct>` for the memento when `impl_from` is enabled
+- enum-shaped mementos for enums, even when `Recall` must stay manual
 
 ### `#[derive(Recall)]`
 
 Generates the `Recall` implementation.
 
 Behavior:
 
-- plain fields are assigned directly
-- `#[recallable]` fields call nested `recall`
-- `#[recallable(skip)]` fields are left untouched
+- struct fields are handled as before
+- enum derives are supported only for assignment-only variants, plus skipped
+  `PhantomData<_>` marker fields
+- enums with nested `#[recallable]` or other skipped fields should derive
+  `Recallable` and implement `Recall` or `TryRecall` manually
 
 ### `#[recallable]`
 
@@ -718,7 +802,11 @@ pub trait TryRecall: Recallable {
 
 ## Current limitations
 
-- Derive macros currently support structs only; enum support is not implemented
+- `#[derive(Recallable)]` supports enums under the normal field rules
+- `#[derive(Recall)]` and `#[recallable_model]` support enums only for
+  assignment-only variants
+- complex enums should derive `Recallable` and implement `Recall` or
+  `TryRecall` manually
 - Borrowed non-skipped state fields are rejected
 - `#[recallable]` is path-only and does not accept tuple/reference/slice/function
   syntax directly

Makefile

@@ -2,39 +2,75 @@
 
 CARGO ?= cargo
 TEST_ARGS ?= --workspace
+EXAMPLE_ARGS ?= --package recallable
 CARGO_LLVM_COV ?= cargo llvm-cov
 COVERAGE_ARGS ?= --workspace
 COVERAGE_DIR ?= target/llvm-cov
 COVERAGE_HTML_INDEX := $(COVERAGE_DIR)/html/index.html
 BROWSER_OPEN ?= open
 
-.PHONY: help test test-default test-no-default test-impl-from test-all-features coverage coverage-open
+.PHONY: help regression test validate-examples \
+	test-default test-no-default test-impl-from test-all-features \
+	examples-default examples-no-default examples-impl-from examples-all-features \
+	coverage coverage-open
 
 help:
 	@printf '%s\n' \
 		'Available targets:' \
-		'  make test               Run the full workspace test feature matrix' \
+		'  make regression         Run the full workspace test and example matrix' \
+		'  make test               Run the original workspace test feature matrix' \
+		'  make validate-examples  Run the example validation matrix' \
 		'  make test-default       Run tests with default features' \
+		'  make examples-default   Run default-feature examples' \
 		'  make test-no-default    Run tests with no default features' \
+		'  make examples-no-default Run examples with no default features' \
 		'  make test-impl-from     Run tests with impl_from enabled' \
+		'  make examples-impl-from Run impl_from examples with no default features' \
 		'  make test-all-features  Run tests with all features enabled' \
+		'  make examples-all-features Check examples with all features enabled' \
 		'  make coverage           Generate merged llvm-cov HTML and JSON reports' \
 		'  make coverage-open      Generate coverage reports and open the HTML report'
 
-test: test-default test-no-default test-impl-from test-all-features
+regression: test validate-examples
+
+test: \
+	test-default \
+	test-no-default \
+	test-impl-from \
+	test-all-features
+
+validate-examples: \
+	examples-default \
+	examples-no-default \
+	examples-impl-from \
+	examples-all-features
 
 test-default:
 	$(CARGO) test $(TEST_ARGS)
 
+examples-default:
+	$(CARGO) run $(EXAMPLE_ARGS) --example basic_model
+	$(CARGO) run $(EXAMPLE_ARGS) --example nested_generic
+	$(CARGO) run $(EXAMPLE_ARGS) --example postcard_roundtrip
+
 test-no-default:
 	$(CARGO) test $(TEST_ARGS) --no-default-features
 
+examples-no-default:
+	$(CARGO) run $(EXAMPLE_ARGS) --no-default-features --example manual_no_serde
+
 test-impl-from:
 	$(CARGO) test $(TEST_ARGS) --features impl_from
 
+examples-impl-from:
+	$(CARGO) run $(EXAMPLE_ARGS) --no-default-features --features impl_from --example impl_from_roundtrip
+
 test-all-features:
 	$(CARGO) test $(TEST_ARGS) --all-features
 
+examples-all-features:
+	$(CARGO) check $(EXAMPLE_ARGS) --examples --all-features
+
 coverage:
 	$(CARGO_LLVM_COV) clean $(COVERAGE_ARGS)
 	$(CARGO_LLVM_COV) $(COVERAGE_ARGS) --no-default-features --tests --no-report

README.md

@@ -25,9 +25,9 @@ input.
 - `Recall`: applies that memento infallibly
 - `TryRecall`: applies it fallibly with validation
 - `#[derive(Recallable)]`: generates the companion memento type
-- `#[derive(Recall)]`: generates recall logic
-- `#[recallable_model]`: convenience attribute for the common model path; with `serde` enabled it also removes extra
-  derive boilerplate
+- `#[derive(Recall)]`: generates recall logic for structs and assignment-only enums
+- `#[recallable_model]`: convenience attribute for the common struct or assignment-only enum path; with
+  `serde` enabled it also removes extra derive boilerplate
 
 The crate intentionally does not force one universal memento shape for
 container-like field types. A field type can choose whole-value replacement,
@@ -97,6 +97,19 @@ For `no_std + serde` deployments, prefer a `no_std`-compatible format such as
 - `#[derive(serde::Serialize)]` when the default `serde` feature is enabled
 - `#[serde(skip)]` for fields marked `#[recallable(skip)]`
 
+For enums, `#[recallable_model]` is intentionally narrower than `#[derive(Recallable)]`:
+
+- assignment-only enums are supported directly
+- enums with skipped `PhantomData<_>` marker fields are still supported directly
+- enums with nested `#[recallable]` or other `#[recallable(skip)]` fields should
+  derive `Recallable` and implement `Recall` or `TryRecall` manually
+
+Skipped `PhantomData<_>` can also affect generic retention on generated
+mementos. When a skipped marker is the only field mentioning a generic that
+still must remain part of the memento type, the derive keeps that generic alive
+with an internal hidden marker. The user-facing examples for that corner case
+live in the API docs and [GUIDE.md](GUIDE.md).
+
 ## Features
 
 - `serde` (default): enables macro-generated serde support; generated mementos derive
@@ -113,15 +126,15 @@ Example dependency sets:
 ```toml
 [dependencies]
 # Readable std example
-recallable = "0.1"
+recallable = "0.2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 ```
 
 ```toml
 [dependencies]
 # no_std + serde example
-recallable = { version = "0.1", default-features = false, features = ["serde"] }
+recallable = { version = "0.2", default-features = false, features = ["serde"] }
 serde = { version = "1", default-features = false, features = ["derive"] }
 postcard = { version = "1", default-features = false, features = ["heapless"] }
 heapless = { version = "0.9.2", default-features = false }
@@ -130,7 +143,7 @@ heapless = { version = "0.9.2", default-features = false }
 ```toml
 [dependencies]
 # In-memory snapshots
-recallable = { version = "0.1", features = ["impl_from"] }
+recallable = { version = "0.2", features = ["impl_from"] }
 ```
 
 ## Two Common Workflows
@@ -183,7 +196,7 @@ default:
 
 ```toml
 [dependencies]
-recallable = { version = "0.1", default-features = false }
+recallable = { version = "0.2", default-features = false }
 ```
 
 Define the memento type and recall behavior manually:
@@ -223,7 +236,13 @@ impl Recall for EngineState {
 
 ## Current Limitations
 
-- Derive macros currently support structs only: named, tuple, and unit structs
+- Derive macros support structs and enums
+- `#[derive(Recallable)]` supports enums under the normal field rules
+- `#[derive(Recall)]` and `#[recallable_model]` support enums only when every
+  non-marker variant field is assignment-only
+- Enums with skipped `PhantomData<_>` marker fields are still supported
+- Enums with nested `#[recallable]` or other `#[recallable(skip)]` fields
+  should derive `Recallable` and implement `Recall` or `TryRecall` manually
 - Borrowed state fields are rejected unless they are skipped
 - `#[recallable]` is path-only: it supports type parameters, path types, and
   associated types, but not tuple/reference/slice/function syntax directly