sagas: engine ignores .correlate() extractor - all workflows collapse onto one shared instance

[rickylabs]

Summary

The saga engine's instance resolution never consults the definition's .correlate()
extractor. It keys instances on message.correlationKey ?? "<sagaId>:<messageType>".

Consequence: unless the publisher sets an explicit correlationKey on every message, all
logically distinct workflows collapse onto one shared saga instance. In the reproduction, every
incident in the system shared a single escalation saga.

.correlate() appears prominently in every example on the sagas capability page.

Found by a wave-four demo agent with no prior exposure to NetScript. Related: #1064, and the
sagaCompensate drop filed alongside this — same surface, same session.

Why this is the most dangerous of the three

The other two saga findings fail loudly enough to notice: one hangs, one produces no effect.
This one succeeds and produces wrong state. Two incidents raised minutes apart silently share
escalation level, deadline timers, and page history. Nothing errors. Nothing logs. The system looks
healthy and is corrupting workflow state.

It is also the hardest to catch in a demo or a test, because it only manifests once two
instances overlap — a single-workflow happy-path test passes cleanly.

Observed

Instance resolution uses:

message.correlationKey ?? `${sagaId}:${messageType}`

With no correlationKey on the published message, every IncidentTriggered maps to the same key,
so a second incident resumes the first incident's state machine rather than starting its own.

The agent found this by dumping KV keys directly — there is no error path that surfaces it.

Expected

Given a definition that declares an extractor:

defineSaga('escalation')
  .correlate((message) => message.payload.incidentId)
  ...

...the engine should use that extractor to derive the instance key, and only fall back to
correlationKey / the composite default when no extractor is declared.

Acceptance

• The engine calls the definition's .correlate() extractor when one is declared, and uses its
  result as the instance key
• Documented precedence for instance-key resolution (extractor → explicit correlationKey →
  default), stated on the sagas capability page
• A test asserts that two concurrent workflows with different correlation values get
  separate instances — the single-instance happy path does not cover this
• If .correlate() is genuinely not wired yet, it fails loudly at definition-build time rather
  than being accepted and ignored, and the examples stop showing it as functional

Provenance

Wave-four demo run 1 (Claude Fable 5, high effort), 2026-08-03. ~20 min lost (combined with the
sagaCompensate finding); would have cost far more without a direct KV key dump.
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. Every test was run against the pre-fix engine to prove it fails there.

1. The engine calls the definition's .correlate() extractor and uses its result as the instance key

packages/plugin-sagas-core/src/runtime/saga-engine.ts: resolveCorrelationKey now takes the
definition and selects the matching correlation rule (specific eventType before the *
wildcard) before any fallback. One resolved key then feeds both the correlation index and
resolveInstanceId, so the two can no longer disagree.

This issue described one wrong branch. There were two, failing in opposite directions:

message.correlationKey ?? message.id ?? `${sagaId}:${message.type}`

• no correlationKey → every workflow collapses onto one instance (the reported symptom);
• a unique message.id → every message forks its own instance and none ever resumes.

message.id is now never an instance key. Both directions are covered by tests.

2. Documented precedence (extractor → explicit correlationKey → default)

docs/site/durable-workflows/sagas.md gains an Instance-key precedence section stating the
three-step order and, explicitly, that the transport-level message id is never an instance key.
(docs/site/capabilities/durable-sagas.md is a redirect stub to that page.)

3. A test asserts two concurrent workflows with different correlation values get separate instances

native runtime separates concurrent workflows by definition correlation extractor — a real
Promise.all of two publishes with different extractor values (workflow-a, workflow-b):

await Promise.all([
  runtime.publish({ id: 'message-a', type: 'Increment', payload: { workflowId: 'workflow-a' } }),
  runtime.publish({ id: 'message-b', type: 'Increment', payload: { workflowId: 'workflow-b' } }),
]);
assertEquals(store.envelopes.get('extracted-correlation:workflow-a')?.state, { count: 1 });
assertEquals(store.envelopes.get('extracted-correlation:workflow-b')?.state, { count: 1 });
assertEquals(store.envelopes.size, 2);

Against the pre-fix engine this test FAILS — the supervisor ran it on main to confirm, rather
than taking it on trust. It is the box's whole point that a single-instance happy path passes
against the broken code, so this one had to be proven red.

Two supporting tests, both also FAILED pre-fix:

• native runtime resumes one extracted workflow across distinct message ids — the opposite
  direction: same business key, different message.id, must resume one instance (count: 2).
• native runtime falls back from undefined extractor to explicit key then stable default — proves
  the precedence order itself, not just the happy branch.

4. If .correlate() is not wired, fail loudly at definition-build time

Not applicable — the antecedent is false. .correlate() is now genuinely wired and honoured, so
there is nothing to reject at build time and no reason to stop showing it in examples. Ticked on
that basis, not because a build-time guard was added.