sagas: sagaCompensate effects are silently dropped - createDurableSagaRuntime wires no compensator by default

[rickylabs]

Summary

A saga handler that returns sagaCompensate(...) produces no error, no log, and no
compensation. The effect is silently discarded by the runtime that createDurableSagaRuntime
builds.

Compensation is the mechanism the "a multi-step operation must not leave the world half-changed"
guarantee rests on, and the sagas capability page presents .compensate() + sagaCompensate() as
a live, first-class path with no warning that it requires additional wiring.

Found by a wave-four demo agent with no prior exposure to NetScript. Related: #1064 (same surface,
same session).

Reproduction

Saga definition registers both the failure handler and a compensation branch:

.on('PageDeliveryFailed', (state, message) => [
  sagaCompensate({ level: state.level, pages: state.pages }, 'delivery failed mid-level'),
])
.compensate('PageDeliveryFailed', (state) => /* void the half-sent pages, escalate */)

Then signal it:

curl -X POST .../escalation/signal -d '{"type":"PageDeliveryFailed", ...}'

Observed

job result:   {"delivered": false, "voided": 1, "reroutedToLevel": 2}   # decision.level stayed 2
saga history: [triggered, level-paged, deadline-elapsed, escalated]     # no level-voided, no escalation

The compensation branch never ran. Nothing was logged. Nothing errored. The sagaCompensate
effect simply evaporated between the handler returning it and the runtime processing the effect
ledger.

Root cause

The runtime built by createDurableSagaRuntime wires no compensator by default —
SagaBusBridgeOptions.compensator is optional, and when it is absent a returned sagaCompensate
effect is dropped rather than rejected.

So the default runtime silently does not support a documented first-class effect.

Why this is worse than a normal missing feature

The failure mode is invisible in every direction:

• The handler returns successfully.
• The effect ledger is accepted.
• No warning is emitted that an effect kind is unhandled.
• Saga history simply lacks the compensation entries, which reads as "the branch didn't trigger"
  rather than "the runtime ignored it".

An author following the capability page has no signal that their compensation logic is dead code.

Workaround used

Moved the undo logic into a plain .on('PageDeliveryFailed') failure branch. Note the storefront
tutorial does recommend that shape — so the docs contain two paths, one of which works and one of
which silently does not, with nothing marking the difference.

Acceptance

• createDurableSagaRuntime wires a working compensator by default, so a returned
  sagaCompensate(...) runs the registered .compensate() branch
• Or, if compensation genuinely requires opt-in wiring: an unhandled effect kind fails
  loudly (throw or error-log naming the effect and the missing option) rather than being
  dropped, and the capability page documents the requirement at the point .compensate() is
  introduced
• A test asserts that a sagaCompensate effect from a handler actually invokes the registered
  compensation branch through the default runtime
• The sagas capability page and the storefront tutorial agree on which path is supported

Provenance

Wave-four demo run 1 (Claude Fable 5, high effort), 2026-08-03. ~20 min lost (combined with the
.correlate() finding filed separately).
Full drift log: /home/codex/repos/wave4-fable/.llm/run/drift.md, finding #3 of 9.
Product repo: https://github.com/rickylabs/vigil

[rickylabs]

Acceptance verified — evidence per box (PR #1075)

Supervisor-verified. Each test was also run against pre-fix code to prove it fails there.

The root cause in this issue was wrong, and fixing only what it described would not have closed it

The issue says the effect is dropped because SagaBusBridgeOptions.compensator is optional. But
SagaBusBridge.#compensate already threw notImplemented when the compensator was absent — so
that was never the drop.

The real mechanism was one level up: nothing on the publish path ever called dispatchCascaded.
SagaBusBridge.publish → SagaEngine.publish → await this.handle(message), and handle()
returned a cascade ledger that publish() discarded. The only callers of dispatchCascaded
were the runtime facade and test doubles. Wiring a default compensator alone would have changed
nothing — the effect never reached it.

1. createDurableSagaRuntime wires a working compensator by default

plugins/sagas/src/runtime/create-durable-saga-runtime.ts now installs a SagaCompensator (with a
system clock) unless the caller supplies one, and SagaBusBridge.#handleAndDispatch dispatches the
ledger returned by handle(). Compensation-produced cascades are themselves redispatched.

Test: createDurableSagaRuntime dispatches returned compensation through its default compensator —
asserts the ordering ['compensate:ord-1', 'cascade:ord-1'], i.e. the .compensate() branch ran
and the effect it returned was dispatched in turn.
Pre-fix: FAILED.

2. (Or) An unhandled effect kind fails loudly, and the docs state the requirement

Both halves of the "or" are satisfied, not just one:

• Unknown kind → dispatching an unknown cascade kind fails loudly with the effect name, asserting
  Unhandled saga cascade effect kind "mystery"; no dispatcher option is registered. with code
  SAGA_NOT_IMPLEMENTED.
• sagaCompensate with no registered branch → createDurableSagaRuntime rejects sagaCompensate without a matching branch, asserting sagaCompensate effect for "Undo" requires a registered .compensate() handler. Pre-fix: FAILED (silently succeeded).
• Missing compensator and missing resolveCompensation both throw named errors.
• docs/site/durable-workflows/sagas.md documents the requirement at the point .compensate() is
  introduced.

A silent drop was caught in review and fixed before merge. The first implementation contained
case 'fail': if (compensation) return; — which discarded every sagaFail(...) returned from a
handler, a new silent drop one line below the one being fixed. Now routed through the compensator,
with createDurableSagaRuntime dispatches sagaFail through its compensation branch covering it.
Verified FAILED against the pre-fix commit 72076e63e.

3. A test asserts sagaCompensate invokes the registered branch through the default runtime

Box 1's test, run through createDurableSagaRuntime with no compensator argument — the default
path an author actually gets. Pre-fix: FAILED.

4. The capability page and the storefront tutorial agree

Both updated. Note docs/site/capabilities/durable-sagas.md is a redirect stub to
docs/site/durable-workflows/sagas.md, which is the canonical page and now states that
createDurableSagaRuntime installs the compensator automatically, what lower-level composition
requires, and that missing wiring fails loudly.

docs/site/tutorials/storefront/04-checkout-saga.md previously recommended the other shape — an
.on() failure branch — with a callout saying .compensate() was only for explicit cascades. That
was the "two paths, one silently broken" problem. The tutorial now uses
sagaCompensate(...) + .compensate('PaymentFailed', …), and its callout explains that returning
the effect is what routes into the branch.