Document: disableRetries/maxAttempts bound only defect/invoker retries, not a handler-thrown RetryableError loop

[schickling-assistant]

Observed behavior

On the pinned restate-server floor, the test-harness disableRetries mode and the per-handler maxAttempts retry policy bound only the defect / invoker retry path. They do not bound a loop driven by a handler that keeps throwing a retryable error (Restate.retryable / RetryableError): such a handler re-arms indefinitely regardless of disableRetries / maxAttempts, because the retryable signal is the durable-step retry path, distinct from the invoker attempt budget those controls cap.

This is already noted in passing in the VRS sync audit; this issue tracks the follow-up to (a) document the distinction clearly in the user-facing guides, and (b) confirm whether this is intended Restate retry semantics or worth raising as an upstream question.

Scope

• Document the disableRetries / maxAttempts vs. handler-thrown-RetryableError distinction in the testing + error-boundary guides (what each control actually bounds).
• Determine whether the behavior is intended Restate semantics (durable-step retries are deliberately not bounded by the invoker attempt budget) or a surprising interaction worth an upstream question; capture the conclusion.

Notes

Possible upstream relevance — keep this as a standalone item so an upstream question can carry its own state if needed.

Refs #757.

Posted on behalf of @schickling

field	value
agent_name	🥇 cl2-pyrite
agent_session_id	a71a7fca-0ccf-427e-9e57-51aea841dc74
agent_tool	Claude Code
agent_tool_version	2.1.165
agent_runtime	Claude Code 2.1.165
agent_model	claude-opus-4-8
runtime_profile	/nix/store/sz4ll7nq7qbwcsw65pw13w5hw61lnvk5-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/nhbhipdhwmcqh669bpr15g39hr17cqbb-agent-skills-corpus/share/agent-skills/manifest.json
worktree	effect-utils/schickling/2026-06-08-restate-effect
machine	dev3
tooling_profile	dotfiles@7360c0d