Wake on flag

The escalation boundaryDashboardHTTPSDKconditionalbatchwakeOnFlagflagBatchItem

A contributor flags one pending item and the workflow wakes at once with what has arrived and the flag, so it can reroute the order.

The situation

A matching station finds one item in an order is damaged. Waiting for the rest of the batch is pointless: the order needs a manager now.

The recipe

const result = await conditional<Record<string, unknown>>(signalId, {
  role: 'matching',
  metadata: { orderId },
  batch: itemKeys,
  wakeOnFlag: true,
});
if (result && result.$trigger === 'flag') return sendToManager(orderId, result.$flags);

curl -X POST https://lt.acme.dev/api/escalations/$ID/flag-batch-item \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{ "itemKey": "item-2", "label": "damaged", "payload": { "note": "cracked housing" } }'

A flag writes envelope.batch_flags[itemKey] with its label, payload, the caller as actor and the database at. Without wakeOnFlag the key stays pending and still fills; with it, the first flag ends the wait.

The guarantee

The flag and the wake are one statement: the row resolves with the caller recorded in metadata.resolved_by, and the workflow receives the filled items, $flags and $trigger: 'flag'. A key already filled answers 409. See Batches and accumulators.

The escalation boundary