[igalshilman]

explicit_recovery as a handler and service key

This makes the preview explicit_recovery option a key, like every other option and like explicit_cancellation (#264), instead of a decorator:

@counter.handler(explicit_recovery=True)                    # one handler
async def add(ctx: ObjectContext, n: int) -> None: ...

counter = VirtualObject("counter", explicit_recovery=True)  # all of its handlers

• The key:
  • Exists on handler() and a workflow's main(), and on the Service, VirtualObject and Workflow constructors. Off by default.
  • Its docs mark it as preview and state what explicit recovery means for a handler: each attempt's calls and sends are new requests (give them an idempotency key that is the same on every attempt), ctx.run runs again on every attempt, and awakeables are not supported.
• The decorator is removed. restate._preview.explicit_recovery was never released, so it's deleted rather than deprecated.
• tests/explicit_recovery.py uses the key.

🤖 Generated with Claude Code

[pullfrog]

ℹ️ No critical issues — two documentation rough edges inline.

Reviewed changes

This review covers the single commit that turns preview explicit_recovery into a handler and service option and deprecates the decorator.

• New option on all constructors and decorators — explicit_recovery: bool = False added to the Service, VirtualObject and Workflow constructors, their handler(), Workflow.main()/_add_handler, and make_handler. It's passed by keyword, so the positional make_handler argument lists stay intact. The runtime still ORs the handler flag with the service flag in server.py, so service-level enabling works unchanged.
• Decorator deprecated — restate._preview.explicit_recovery still sets the flag but now emits a DeprecationWarning with stacklevel=2.
• Tests migrated — tests/explicit_recovery.py now uses the keyword option. It also checks that the decorator still works and warns.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}

[github-actions]

Test Results

  8 files  ±0    8 suites  ±0   3m 51s ⏱️ +3s
 71 tests ±0   71 ✅ ±0  0 💤 ±0  0 ❌ ±0 
322 runs  ±0  322 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit c6082d5. ± Comparison against base commit 5f2ab58.

[pullfrog]

✅ No new issues found. Both earlier documentation threads are addressed.

Reviewed changes

Since the last Pullfrog review, one commit changed docstrings only. There are no code or behavior changes.

• Restored the explicit-recovery caveats — the explicit_recovery docs on handler() for Service, VirtualObject and Workflow, and on Workflow.main(), now cover all three caveats: calls and sends are new requests on each attempt (so give them a stable idempotency key, e.g. one made from ctx.request().id), ctx.run runs again on every attempt, and awakeables are unsupported. The Handler field doc points readers to those docs.
• Added the .. deprecated:: 1.4.0 directive — the deprecated restate._preview.explicit_recovery docstring now follows the repo's deprecation convention, and it keeps the full caveat list.

  ^{｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}

[pullfrog]

✅ No new issues found. The code changes are clean, with one note below about the PR description.

Reviewed changes

Since the last Pullfrog review, one commit deletes the explicit_recovery decorator. The handler and service keys are now the only way to turn the option on.

• Removed restate._preview.explicit_recovery. _preview.py now holds only the explicit-cancellation helpers from #264. The imports that only the decorator used (handler_from_callable, Service, VirtualObject, Workflow, warnings) and the T TypeVar are gone. Nothing else in the repo references the decorator.
• Updated tests/explicit_recovery.py. Removed the deprecation-warning test and the misapplied-decorator ValueError test. Added assertions that the Service and Workflow constructors accept the key.

ℹ️ The removed decorator was in published releases

The PR description says restate._preview.explicit_recovery "was never released". It was: the restate-sdk 1.3.0 sdist on PyPI contains python/restate/_preview.py with def explicit_recovery, and the decorator was already in the tree at the 1.1.0 version bump. After this change, any 1.3.0 user who has from restate._preview import explicit_recovery gets an ImportError when they upgrade.

The _preview module says its APIs "might change or be removed without notice", so deleting the decorator is allowed. The decision just shouldn't rest on the claim that it never shipped.

Technical details

# Removal of a released `_preview` API

## Affected sites
- python/restate/_preview.py — `explicit_recovery` decorator deleted (shipped in restate-sdk 1.1.0–1.3.0 on PyPI)
- PR #265 description — "was never released, so it's deleted rather than deprecated"

## Required outcome
- The PR description and release notes describe the removal accurately, or the deprecated shim from 7365129 is kept for a release.

## Open questions for the human
- Is a hard removal fine under the `_preview` contract, or should 7365129's `DeprecationWarning` shim stay for one release (1.4.0) and be removed after that?

  ^{｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}