Skip to content

[docs] Document durable reconciler usage#616

Merged
xintongsong merged 8 commits intoapache:mainfrom
joeyutong:codex/reconcile-callable-docs-upstream
Apr 17, 2026
Merged

[docs] Document durable reconciler usage#616
xintongsong merged 8 commits intoapache:mainfrom
joeyutong:codex/reconcile-callable-docs-upstream

Conversation

@joeyutong
Copy link
Copy Markdown
Contributor

@joeyutong joeyutong commented Apr 9, 2026

Linked issue: #612

Purpose of change

This PR includes:

  • documentation for the durable reconciler contract in both Python and Java
  • clarification that a reconciler can recover either a successful result or a failed outcome, and that the runtime persists and replays either terminal outcome
  • usage examples for reconciler / reconciler() in the workflow agent guide, including reconciler branches that return recovered success or raise recovered failure
  • clarification that reconciler-backed durable execution does not change the existing async support matrix
  • documentation that reconciler-based recovery relies on the persisted action state used for exactly-once action consistency
  • an additional clarification that durable-call replay and action-level replay are different: code outside durable execution is re-executed only when recovery re-enters an action that has not been recorded as completed

Tests

Not run. This is a documentation-only change.

API

No.

Documentation

  • doc-needed
  • doc-not-needed
  • doc-included

@github-actions github-actions Bot added doc-included Your PR already contains the necessary documentation updates. fixVersion/0.3.0 The feature or bug should be implemented/fixed in the 0.3.0 version. priority/major Default priority of the PR or issue. labels Apr 9, 2026
@github-actions github-actions Bot added doc-included Your PR already contains the necessary documentation updates. and removed doc-included Your PR already contains the necessary documentation updates. labels Apr 15, 2026
@joeyutong joeyutong marked this pull request as ready for review April 16, 2026 01:38
Comment thread docs/content/docs/development/workflow_agent.md Outdated
- In Python async actions, if `ctx.durable_execute_async(...)` is not awaited, the result is not recorded and cannot be replayed.

**Recovered terminal outcome with a reconciler:**
- A durable call may optionally provide a reconciler that is used only during recovery, when the same durable call is revisited and no terminal outcome has been persisted for it yet.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It feels a bit obscure. Might be better to start with the two questions that users care most: when to use this feature (call started but not completed/persisted, framework cannot decide should replay or not), and what it can do (support custom reconciling logics).

Comment thread docs/content/docs/development/workflow_agent.md Outdated
Comment thread docs/content/docs/faq/faq.md Outdated
Comment thread docs/content/docs/operations/deployment.md Outdated
Copy link
Copy Markdown
Contributor

@xintongsong xintongsong left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@xintongsong xintongsong merged commit 65ed8ae into apache:main Apr 17, 2026
45 of 46 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc-included Your PR already contains the necessary documentation updates. fixVersion/0.3.0 The feature or bug should be implemented/fixed in the 0.3.0 version. priority/major Default priority of the PR or issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants