[skill-drift] update(sentry-cloudflare-sdk): document Workflows step context, rollback options, and final-attempt-only error capture #281

cc getsentry/team-javascript-sdks

PR getsentry/sentry-javascript#22180 (feat(cloudflare): Support Cloudflare types v5 & newer wrangler versions, merged 2026-07-13) changed packages/cloudflare/src/workflows.ts in ways that drift from references/sdks/cloudflare/durable-objects.md (## Workflows section):

1. Step context parameter. WrappedWorkflowStep.do() now accepts a callback typed as (ctx: WorkflowStepContext) => Promise<T>. On Cloudflare Workflows runtimes from April 2026 onward, the runtime passes a step context object (with attempt and config.retries.limit) as the callback's first argument. The reference's Setup example only shows zero-arg callbacks (async () => {...}) and never mentions this parameter.

2. Behavior change: final-attempt-only error capture. The reference currently states (Overview + Best Practices Add iOS/Swift setup skill from sentry-agent-skills #5): "Capture errors in workflow steps with handled: true (since steps may retry)" — implying every attempt's error is captured. The new code only does this unconditionally when step context is unavailable. When step context is available (feature-detected via typeof attempt === 'number' && typeof retryLimit === 'number'), the SDK now captures an error only on the final attempt (attempt > retryLimit), to avoid duplicate events across retries. This is a real behavior change that needs careful, accurate wording — it depends on the Workflows runtime version, not just the SDK version.

3. New rollbackOptions parameter. step.do() gained an optional trailing rollbackOptions argument (both overloads: do(name, callback, rollbackOptions?) and do(name, config, callback, rollbackOptions?)), passed through unmodified to the underlying this._step.do(...). This corresponds to Cloudflare Workflows' native step-rollback feature. I could not verify the exact shape of WorkflowStepRollbackOptions — it's declared in the external @cloudflare/workers-types package (bumped in this PR to 5.20260710.1), not in the sentry-javascript repo, so I had no way to confirm field names from source. A first draft of this doc should pull the real shape from Cloudflare's own Workflows docs/types rather than guessing.

4. Peer dependency widened. packages/cloudflare/package.json peerDependencies changed from "@cloudflare/workers-types": "^4.x" to "^4.x || ^5.x" (devDependency bumped to 5.20260710.1, wrangler to 4.61.0). The reference doesn't currently document a required @cloudflare/workers-types/wrangler version anywhere, so this may not need a line item, but worth a decision either way.

5. Span attribute nuance. cloudflare.workflow.retries.delay is now explicitly omitted (undefined) when config.retries.delay is a function (workers-types v5 added WorkflowDelayFunction), since function values aren't valid span attributes. The reference's Step Span Attributes table just says "Retry delay (if set)" — minor, could use a one-line caveat.

Why create_issue instead of create_pr: item 3 requires verifying an external type's exact shape that I don't have reliable access to from this repo (guessing risked publishing a fabricated field name), and item 2 is a genuine behavior change spanning three sections of durable-objects.md (Overview, a new subsection for step context, and Best Practices #5) that deserves a careful, accurate rewrite rather than a mechanical table edit.

Other PRs reviewed in this run and found not doc-actionable (internal-only, no public surface change): #22104 (Durable Object proxy newTarget bugfix — no documented API change), #22152/#22155/#22153/#22081/#22052/#22060 (internal @sentry/core utility/type refactors, no references/sdks/cloudflare/ impact).