feat(flow): support custom persistence key in @persist

[lucasgomide]

Adds a key parameter to @persist so flows can use any state attribute (e.g. conversation_id) as the persistence key instead of always falling back to state.id. When the named attribute is missing or falsy, raises a clear ValueError identifying the missing key.

---

Note

Medium Risk
Changes core persistence key selection and error handling, which can affect how existing flows are saved/loaded if users adopt key or rely on prior error messages.

Overview
@persist now accepts an optional key parameter to choose which state attribute (Pydantic/object) or dict key is used as the persistence identifier, defaulting to the existing state.id behavior.

Persistence now raises a clear ValueError when the custom key is missing or falsy, and tests were added to cover Pydantic, dict-based states, and the failure path. Documentation across EN/AR/KO/PT-BR was updated with examples and behavior notes for custom persistence keys.

^{Reviewed by Cursor Bugbot for commit 9efe193. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6f1f907. Configure here.}

[iris-clawd]

Looks good 👍

Code:

• Clean threading of key through all wrapper paths (sync, async, class-level, method-level) — nothing missed.
• Good separation between custom-key ValueError and the default id-missing error, so existing flows are unaffected.
• The str(e) or LOG_MESSAGES["id_missing"] fix in the except (TypeError, ValueError) block correctly preserves the custom key error message instead of swallowing it.

Tests:

• Pydantic, dict, and missing-key error cases all covered. The assertion that load_state(flow.state.id) is None in the Pydantic test is a nice touch — proves the custom key was actually used as the lookup, not just ignored.

Docs:

• Consistent examples across all 4 languages, all 3 doc pages.

One minor note (non-blocking): if someone passes key="id" explicitly, it would behave identically to omitting it — which is fine, but might be worth a one-liner in the docstring mentioning it's a no-op in that case. Totally optional.

💬 259