fix: a saga sequences with flatTap, not a nesting ladder

[btravers]

Closes #68. Files the lint half upstream as btravstack/unthrown#247.

The trap, measured

An AsyncResult is eager: constructing it starts the work. So the readable
spelling of a sequence — one const per step, then chained — is a race, and
a silent one: it type-checks and it returns a Result.

sibling consts : start:a start:b end:b end:a     ← both started at once
flatTap        : start:a end:a start:b end:b     ← sequential

The repo's answer was to construct every later step inside the previous one's
flatMap. Correct, and one level of indentation per step — fulfillOrder was
five steps deep with compensations deeper still.

The answer already existed

unthrown ships two non-nesting sequential forms and this repo used neither:

• flatTap — runs a failable step, discards its value, passes the
  original one through. What a saga needs when a later step depends on an
  earlier step's success.
• DoAsync().bind(...) — the same idea with an accumulating scope, for when
  it depends on the earlier step's value.

flatTap is the fit here: both sagas only ever needed the success, so DoAsync
would have forced bind names for values nobody reads. Both sagas also lost their
.map(() => value) tail, since flatTap already preserves it.

What changed

fulfillOrder's three steps and chargeOrder's two are now siblings at one
indent level. The remaining nesting is inside the compensations, which nest
because releaseStock → cancelPlacement → re-Err genuinely is nested.

Error triage, compensation order and declared error types are untouched.

Verification

• The five existing specs pass, including the two that assert ordering —
  "place, reserve, ship, in order" and "compensates a shipping refusal in
  reverse order: release, then cancel". Those predate this change, so a
  regression to the racing spelling fails a test rather than shipping.
• The rewrite was spiked against the real contract before being written, and the
  race/no-race behaviour above was measured, not reasoned about.

Documented where a saga author lands

The trap was previously stated in one place: a comment inside the workflow
file, which you only read once you are already writing one. It is now in the
root CLAUDE.md conventions, docs/how-to/split-a-worker-into-slices.md,
docs/reference/temporal.md, and the example page's "One subtlety worth
stealing" section — which had been teaching the ladder as the answer.

The gate: filed upstream, not built here

Acceptance 3 wants a gate that makes the racing spelling fail. That is a lint
rule and it belongs in @unthrown/oxlint, so it is
btravstack/unthrown#247.

The issue records the part that makes it non-trivial: sibling construction is
not itself wrong — it is exactly how deliberate concurrency is spelled for
allAsync. The rule has to flag sibling construction followed by sequential
consumption, not sibling construction.

Found while there

docs/examples/order-temporal-worker.md's workflow sample was missing
tenantId on three activity calls — pre-existing drift from when the Temporal
example became multi-tenant, the same class as #75 but on the Temporal side.
Surfaced only because the fence was extracted and compiled; fixed in place.

Gate

format --check · lint · typecheck 31/31 · knip · test 29/29 ·
build 10/10 · docs build — all green.

[Copilot]

Pull request overview

Refactors the Temporal example’s saga workflows to stay sequential without deep nesting by using flatTap, and updates the documentation/conventions to teach and reinforce the “AsyncResult eagerness” trap (including fixing a docs drift where tenantId was missing in the workflow sample).

Changes:

• Rewrite fulfillOrder and chargeOrder to sequence steps with flatTap (preserving prior error triage and compensation behavior).
• Document the sequencing rule (“flatTap / DoAsync, never sibling consts”) in Temporal reference/how-to docs and the Temporal example page.
• Fix the Temporal example docs sample to include tenantId on activity calls.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
examples/order-temporal-worker/src/workflows.ts	Replace nesting-ladder sequencing with flatTap while preserving ordering, triage, and compensation.
docs/reference/temporal.md	Add a reference section explaining the eagerness trap and recommending flatTap / DoAsync.
docs/how-to/split-a-worker-into-slices.md	Add the same sequencing guidance where saga authors are likely to land.
docs/examples/order-temporal-worker.md	Update the workflow sample for multi-tenancy (tenantId) and explain flatTap-based sequencing.
CLAUDE.md	Codify the repo convention: sequence AsyncResult work with flatTap / DoAsync, not sibling consts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.