fix(sdk): report the missing done(), not the step the author awaited (#183)

[kjgbot]

Fixes #183.

A body that awaited its only step and forgot done() was refused as:

unawaited_step: flow "missing-completion" returned with unawaited steps: run-1 (f.run)

The step was awaited. The defect was the missing completion, and there is a code for exactly that.

Cause

Found by probing, not by reading. isHandled decides whether an operation was consumed by asking whether the completion depends on it, and returns false outright when there is no completion:

isHandled(operation) {
  const completion = this.completionAsyncId;
  ...
  if (completion === undefined || ...) return false;

With no done() there is no completion async id to trace from, so every operation is unhandled by construction. verifyAuthoredOperations ran before the completion check, computed an answer its own precondition did not support, and reported the symptom as the cause — telling the author to await something they had already awaited, and saying nothing about what they actually forgot.

Fix

The completion check runs first, stopping operations and closing the lifecycle the way the body-failure path already does.

A body that both forgets done() and leaves a step unawaited now reports the missing completion. That is the honest order rather than a convenience: the unawaited-step verdict is not computable until there is a completion to compute it against, and once the author adds done() the verification runs normally and catches it.

Test

requires an explicit completion after journal-backed steps goes back to asserting missing_completion — the code it asserted before #140 dropped it. #184 had to weaken it to the refusal's class precisely because of this bug, so this closes that loop too.

Mutation: moving verification back before the completion check fails exactly that test with expected AuthoredFlowExecutionError: unawaited_ste… to match object { code: 'missing_completion' }. The full transcript, with runnable commands and verbatim output, is in the commit message; sha256 b7eed1ca before, restored to b7eed1ca after (rebuilt from main and re-patched rather than un-edited).

Full SDK suite at this head: 33 test files total — 32 passed, 1 skipped — and 665 tests total: 662 passed, 3 skipped. Typecheck clean.

Signoff: local 3-lens preswarm, maintainability / history / structure all REVIEW_PASSED.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FtQSAcGDta5VH9xiZFT4sR

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 1edc2ef5-5fc0-459a-83f1-a083e5793a28

📥 Commits

Reviewing files that changed from the base of the PR and between 092a25f and 5858102.

📒 Files selected for processing (2)

• sdk/src/authored-flow-executor.ts
• sdk/tests/authored-flow.test.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Authored-flow finalization now checks for done() before verifying unawaited operations. Missing completion stops tracked operations, closes the lifecycle, and throws missing_completion. The regression test asserts this error code.

Changes

Authored-flow completion handling

Layer / File(s)	Summary
Completion validation and regression coverage sdk/src/authored-flow-executor.ts, sdk/tests/authored-flow.test.ts	The executor validates completion before operation verification and performs cleanup before throwing missing_completion. The test checks the specific error code and documents the validation order.

Estimated code review effort: 2 (Simple) | ~10 minutes

Poem

A rabbit checks the flow at dawn
done() is found, or cleanup runs on
Unawaited steps wait their turn
A precise error helps tests learn
The lifecycle closes, and pages turn

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Essentials by visiting https://app.coderabbit.ai/settings/billing.

_{Comment @coderabbitai help to get the list of available commands.}