@workflow/core 5.0.0-beta.50 → 5.0.0-beta.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +5 -0
  2. package/dist/events-consumer.d.ts +26 -0
  3. package/dist/events-consumer.d.ts.map +1 -1
  4. package/dist/events-consumer.js +28 -1
  5. package/dist/flushable-stream.d.ts +41 -0
  6. package/dist/flushable-stream.d.ts.map +1 -1
  7. package/dist/flushable-stream.js +169 -1
  8. package/dist/log-format.js +13 -6
  9. package/dist/replay-divergence.d.ts +25 -0
  10. package/dist/replay-divergence.d.ts.map +1 -0
  11. package/dist/replay-divergence.js +61 -0
  12. package/dist/runtime/helpers.d.ts +75 -1
  13. package/dist/runtime/helpers.d.ts.map +1 -1
  14. package/dist/runtime/helpers.js +129 -2
  15. package/dist/runtime/quickjs-entrypoint.d.ts +30 -8
  16. package/dist/runtime/quickjs-entrypoint.d.ts.map +1 -1
  17. package/dist/runtime/quickjs-entrypoint.js +209 -32
  18. package/dist/runtime/quickjs-log-view.d.ts +129 -0
  19. package/dist/runtime/quickjs-log-view.d.ts.map +1 -0
  20. package/dist/runtime/quickjs-log-view.js +229 -0
  21. package/dist/runtime/step-executor.d.ts +2 -21
  22. package/dist/runtime/step-executor.d.ts.map +1 -1
  23. package/dist/runtime/step-executor.js +85 -80
  24. package/dist/runtime/suspension-handler.d.ts +0 -22
  25. package/dist/runtime/suspension-handler.d.ts.map +1 -1
  26. package/dist/runtime/suspension-handler.js +126 -75
  27. package/dist/runtime.d.ts.map +1 -1
  28. package/dist/runtime.js +262 -91
  29. package/dist/serialization.d.ts +2 -2
  30. package/dist/serialization.d.ts.map +1 -1
  31. package/dist/serialization.js +16 -13
  32. package/dist/step/context-storage.d.ts +2 -0
  33. package/dist/step/context-storage.d.ts.map +1 -1
  34. package/dist/step/context-storage.js +1 -1
  35. package/dist/step/writable-stream.d.ts.map +1 -1
  36. package/dist/step/writable-stream.js +14 -10
  37. package/dist/telemetry/semantic-conventions.d.ts +36 -0
  38. package/dist/telemetry/semantic-conventions.d.ts.map +1 -1
  39. package/dist/telemetry/semantic-conventions.js +23 -1
  40. package/dist/test-support/orchestrator-context.d.ts.map +1 -1
  41. package/dist/test-support/orchestrator-context.js +8 -2
  42. package/dist/version.d.ts +1 -1
  43. package/dist/version.js +2 -2
  44. package/dist/workflow.d.ts.map +1 -1
  45. package/dist/workflow.js +8 -3
  46. package/docs/foundations/streaming.mdx +1 -1
  47. package/docs/how-it-works/event-sourcing.mdx +27 -0
  48. package/package.json +6 -6
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Step, wait, hook and attribute correlation ids share one ULID draw per
3
+ * entity, prefixed by kind (`step_<ulid>`, `wait_<ulid>`, `hook_<ulid>`,
4
+ * `attr_<ulid>`). A replay that drew the same ordinal for a different kind of
5
+ * entity than the one the log recorded there produces an event nobody can
6
+ * consume, and the decisive fact for diagnosing that is which pending
7
+ * invocation currently holds the ordinal. This looks it up by the shared ULID
8
+ * body, so a `wait_created` the log holds at a position where the replay is
9
+ * waiting on `step_<same ulid>` names that step.
10
+ */
11
+ export function findPendingItemAtOrdinal(invocationsQueue, correlationId) {
12
+ const exact = invocationsQueue.get(correlationId);
13
+ if (exact)
14
+ return exact;
15
+ const body = ordinalBody(correlationId);
16
+ if (!body)
17
+ return undefined;
18
+ for (const [id, item] of invocationsQueue) {
19
+ if (ordinalBody(id) === body)
20
+ return item;
21
+ }
22
+ return undefined;
23
+ }
24
+ function ordinalBody(correlationId) {
25
+ const at = correlationId.indexOf('_');
26
+ return at === -1 ? undefined : correlationId.slice(at + 1);
27
+ }
28
+ function describeQueueItem(item) {
29
+ switch (item.type) {
30
+ case 'step':
31
+ return `step ${item.stepName} (${item.correlationId})`;
32
+ case 'hook':
33
+ return `hook (${item.correlationId})`;
34
+ case 'wait':
35
+ return `wait (${item.correlationId})`;
36
+ case 'attribute':
37
+ return `attribute (${item.correlationId})`;
38
+ }
39
+ item;
40
+ return 'unknown';
41
+ }
42
+ /**
43
+ * The detail appended to a `ReplayDivergenceError` raised because the replay
44
+ * could not place an event. Callers keep their own leading sentence (tests and
45
+ * users match on it) and append this after it.
46
+ *
47
+ * Example:
48
+ * `pending at this id: step drainStep (step_01K…). consumer: index=41,
49
+ * length=44, parked=0, lastConsumed=evnt_01K…`
50
+ */
51
+ export function describeDivergenceContext(event, invocationsQueue, eventsConsumer) {
52
+ const pending = event.correlationId
53
+ ? findPendingItemAtOrdinal(invocationsQueue, event.correlationId)
54
+ : undefined;
55
+ const snapshot = eventsConsumer.describe();
56
+ return [
57
+ `pending at this id: ${pending ? describeQueueItem(pending) : 'none'}.`,
58
+ `consumer: index=${snapshot.index}, length=${snapshot.length}, parked=${snapshot.parked}, lastConsumed=${snapshot.lastConsumedEventId ?? 'none'}`,
59
+ ].join(' ');
60
+ }
61
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVwbGF5LWRpdmVyZ2VuY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvcmVwbGF5LWRpdmVyZ2VuY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBSUE7Ozs7Ozs7OztHQVNHO0FBQ0gsTUFBTSxVQUFVLHdCQUF3QixDQUN0QyxnQkFBd0MsRUFDeEMsYUFBcUI7SUFFckIsTUFBTSxLQUFLLEdBQUcsZ0JBQWdCLENBQUMsR0FBRyxDQUFDLGFBQWEsQ0FBQyxDQUFDO0lBQ2xELElBQUksS0FBSztRQUFFLE9BQU8sS0FBSyxDQUFDO0lBQ3hCLE1BQU0sSUFBSSxHQUFHLFdBQVcsQ0FBQyxhQUFhLENBQUMsQ0FBQztJQUN4QyxJQUFJLENBQUMsSUFBSTtRQUFFLE9BQU8sU0FBUyxDQUFDO0lBQzVCLEtBQUssTUFBTSxDQUFDLEVBQUUsRUFBRSxJQUFJLENBQUMsSUFBSSxnQkFBZ0IsRUFBRSxDQUFDO1FBQzFDLElBQUksV0FBVyxDQUFDLEVBQUUsQ0FBQyxLQUFLLElBQUk7WUFBRSxPQUFPLElBQUksQ0FBQztJQUM1QyxDQUFDO0lBQ0QsT0FBTyxTQUFTLENBQUM7QUFDbkIsQ0FBQztBQUVELFNBQVMsV0FBVyxDQUFDLGFBQXFCO0lBQ3hDLE1BQU0sRUFBRSxHQUFHLGFBQWEsQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDdEMsT0FBTyxFQUFFLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsYUFBYSxDQUFDLEtBQUssQ0FBQyxFQUFFLEdBQUcsQ0FBQyxDQUFDLENBQUM7QUFDN0QsQ0FBQztBQUVELFNBQVMsaUJBQWlCLENBQUMsSUFBZTtJQUN4QyxRQUFRLElBQUksQ0FBQyxJQUFJLEVBQUUsQ0FBQztRQUNsQixLQUFLLE1BQU07WUFDVCxPQUFPLFFBQVEsSUFBSSxDQUFDLFFBQVEsS0FBSyxJQUFJLENBQUMsYUFBYSxHQUFHLENBQUM7UUFDekQsS0FBSyxNQUFNO1lBQ1QsT0FBTyxTQUFTLElBQUksQ0FBQyxhQUFhLEdBQUcsQ0FBQztRQUN4QyxLQUFLLE1BQU07WUFDVCxPQUFPLFNBQVMsSUFBSSxDQUFDLGFBQWEsR0FBRyxDQUFDO1FBQ3hDLEtBQUssV0FBVztZQUNkLE9BQU8sY0FBYyxJQUFJLENBQUMsYUFBYSxHQUFHLENBQUM7SUFDL0MsQ0FBQztJQUNELElBQW9CLENBQUM7SUFDckIsT0FBTyxTQUFTLENBQUM7QUFDbkIsQ0FBQztBQUVEOzs7Ozs7OztHQVFHO0FBQ0gsTUFBTSxVQUFVLHlCQUF5QixDQUN2QyxLQUFZLEVBQ1osZ0JBQXdDLEVBQ3hDLGNBQThCO0lBRTlCLE1BQU0sT0FBTyxHQUFHLEtBQUssQ0FBQyxhQUFhO1FBQ2pDLENBQUMsQ0FBQyx3QkFBd0IsQ0FBQyxnQkFBZ0IsRUFBRSxLQUFLLENBQUMsYUFBYSxDQUFDO1FBQ2pFLENBQUMsQ0FBQyxTQUFTLENBQUM7SUFDZCxNQUFNLFFBQVEsR0FBRyxjQUFjLENBQUMsUUFBUSxFQUFFLENBQUM7SUFDM0MsT0FBTztRQUNMLHVCQUF1QixPQUFPLENBQUMsQ0FBQyxDQUFDLGlCQUFpQixDQUFDLE9BQU8sQ0FBQyxDQUFDLENBQUMsQ0FBQyxNQUFNLEdBQUc7UUFDdkUsbUJBQW1CLFFBQVEsQ0FBQyxLQUFLLFlBQVksUUFBUSxDQUFDLE1BQU0sWUFBWSxRQUFRLENBQUMsTUFBTSxrQkFBa0IsUUFBUSxDQUFDLG1CQUFtQixJQUFJLE1BQU0sRUFBRTtLQUNsSixDQUFDLElBQUksQ0FBQyxHQUFHLENBQUMsQ0FBQztBQUNkLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgdHlwZSB7IEV2ZW50IH0gZnJvbSAnQHdvcmtmbG93L3dvcmxkJztcbmltcG9ydCB0eXBlIHsgRXZlbnRzQ29uc3VtZXIgfSBmcm9tICcuL2V2ZW50cy1jb25zdW1lci5qcyc7XG5pbXBvcnQgdHlwZSB7IFF1ZXVlSXRlbSB9IGZyb20gJy4vZ2xvYmFsLmpzJztcblxuLyoqXG4gKiBTdGVwLCB3YWl0LCBob29rIGFuZCBhdHRyaWJ1dGUgY29ycmVsYXRpb24gaWRzIHNoYXJlIG9uZSBVTElEIGRyYXcgcGVyXG4gKiBlbnRpdHksIHByZWZpeGVkIGJ5IGtpbmQgKGBzdGVwXzx1bGlkPmAsIGB3YWl0Xzx1bGlkPmAsIGBob29rXzx1bGlkPmAsXG4gKiBgYXR0cl88dWxpZD5gKS4gQSByZXBsYXkgdGhhdCBkcmV3IHRoZSBzYW1lIG9yZGluYWwgZm9yIGEgZGlmZmVyZW50IGtpbmQgb2ZcbiAqIGVudGl0eSB0aGFuIHRoZSBvbmUgdGhlIGxvZyByZWNvcmRlZCB0aGVyZSBwcm9kdWNlcyBhbiBldmVudCBub2JvZHkgY2FuXG4gKiBjb25zdW1lLCBhbmQgdGhlIGRlY2lzaXZlIGZhY3QgZm9yIGRpYWdub3NpbmcgdGhhdCBpcyB3aGljaCBwZW5kaW5nXG4gKiBpbnZvY2F0aW9uIGN1cnJlbnRseSBob2xkcyB0aGUgb3JkaW5hbC4gVGhpcyBsb29rcyBpdCB1cCBieSB0aGUgc2hhcmVkIFVMSURcbiAqIGJvZHksIHNvIGEgYHdhaXRfY3JlYXRlZGAgdGhlIGxvZyBob2xkcyBhdCBhIHBvc2l0aW9uIHdoZXJlIHRoZSByZXBsYXkgaXNcbiAqIHdhaXRpbmcgb24gYHN0ZXBfPHNhbWUgdWxpZD5gIG5hbWVzIHRoYXQgc3RlcC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGZpbmRQZW5kaW5nSXRlbUF0T3JkaW5hbChcbiAgaW52b2NhdGlvbnNRdWV1ZTogTWFwPHN0cmluZywgUXVldWVJdGVtPixcbiAgY29ycmVsYXRpb25JZDogc3RyaW5nXG4pOiBRdWV1ZUl0ZW0gfCB1bmRlZmluZWQge1xuICBjb25zdCBleGFjdCA9IGludm9jYXRpb25zUXVldWUuZ2V0KGNvcnJlbGF0aW9uSWQpO1xuICBpZiAoZXhhY3QpIHJldHVybiBleGFjdDtcbiAgY29uc3QgYm9keSA9IG9yZGluYWxCb2R5KGNvcnJlbGF0aW9uSWQpO1xuICBpZiAoIWJvZHkpIHJldHVybiB1bmRlZmluZWQ7XG4gIGZvciAoY29uc3QgW2lkLCBpdGVtXSBvZiBpbnZvY2F0aW9uc1F1ZXVlKSB7XG4gICAgaWYgKG9yZGluYWxCb2R5KGlkKSA9PT0gYm9keSkgcmV0dXJuIGl0ZW07XG4gIH1cbiAgcmV0dXJuIHVuZGVmaW5lZDtcbn1cblxuZnVuY3Rpb24gb3JkaW5hbEJvZHkoY29ycmVsYXRpb25JZDogc3RyaW5nKTogc3RyaW5nIHwgdW5kZWZpbmVkIHtcbiAgY29uc3QgYXQgPSBjb3JyZWxhdGlvbklkLmluZGV4T2YoJ18nKTtcbiAgcmV0dXJuIGF0ID09PSAtMSA/IHVuZGVmaW5lZCA6IGNvcnJlbGF0aW9uSWQuc2xpY2UoYXQgKyAxKTtcbn1cblxuZnVuY3Rpb24gZGVzY3JpYmVRdWV1ZUl0ZW0oaXRlbTogUXVldWVJdGVtKTogc3RyaW5nIHtcbiAgc3dpdGNoIChpdGVtLnR5cGUpIHtcbiAgICBjYXNlICdzdGVwJzpcbiAgICAgIHJldHVybiBgc3RlcCAke2l0ZW0uc3RlcE5hbWV9ICgke2l0ZW0uY29ycmVsYXRpb25JZH0pYDtcbiAgICBjYXNlICdob29rJzpcbiAgICAgIHJldHVybiBgaG9vayAoJHtpdGVtLmNvcnJlbGF0aW9uSWR9KWA7XG4gICAgY2FzZSAnd2FpdCc6XG4gICAgICByZXR1cm4gYHdhaXQgKCR7aXRlbS5jb3JyZWxhdGlvbklkfSlgO1xuICAgIGNhc2UgJ2F0dHJpYnV0ZSc6XG4gICAgICByZXR1cm4gYGF0dHJpYnV0ZSAoJHtpdGVtLmNvcnJlbGF0aW9uSWR9KWA7XG4gIH1cbiAgaXRlbSBzYXRpc2ZpZXMgbmV2ZXI7XG4gIHJldHVybiAndW5rbm93bic7XG59XG5cbi8qKlxuICogVGhlIGRldGFpbCBhcHBlbmRlZCB0byBhIGBSZXBsYXlEaXZlcmdlbmNlRXJyb3JgIHJhaXNlZCBiZWNhdXNlIHRoZSByZXBsYXlcbiAqIGNvdWxkIG5vdCBwbGFjZSBhbiBldmVudC4gQ2FsbGVycyBrZWVwIHRoZWlyIG93biBsZWFkaW5nIHNlbnRlbmNlICh0ZXN0cyBhbmRcbiAqIHVzZXJzIG1hdGNoIG9uIGl0KSBhbmQgYXBwZW5kIHRoaXMgYWZ0ZXIgaXQuXG4gKlxuICogRXhhbXBsZTpcbiAqIGBwZW5kaW5nIGF0IHRoaXMgaWQ6IHN0ZXAgZHJhaW5TdGVwIChzdGVwXzAxS+KApikuIGNvbnN1bWVyOiBpbmRleD00MSxcbiAqIGxlbmd0aD00NCwgcGFya2VkPTAsIGxhc3RDb25zdW1lZD1ldm50XzAxS+KApmBcbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGRlc2NyaWJlRGl2ZXJnZW5jZUNvbnRleHQoXG4gIGV2ZW50OiBFdmVudCxcbiAgaW52b2NhdGlvbnNRdWV1ZTogTWFwPHN0cmluZywgUXVldWVJdGVtPixcbiAgZXZlbnRzQ29uc3VtZXI6IEV2ZW50c0NvbnN1bWVyXG4pOiBzdHJpbmcge1xuICBjb25zdCBwZW5kaW5nID0gZXZlbnQuY29ycmVsYXRpb25JZFxuICAgID8gZmluZFBlbmRpbmdJdGVtQXRPcmRpbmFsKGludm9jYXRpb25zUXVldWUsIGV2ZW50LmNvcnJlbGF0aW9uSWQpXG4gICAgOiB1bmRlZmluZWQ7XG4gIGNvbnN0IHNuYXBzaG90ID0gZXZlbnRzQ29uc3VtZXIuZGVzY3JpYmUoKTtcbiAgcmV0dXJuIFtcbiAgICBgcGVuZGluZyBhdCB0aGlzIGlkOiAke3BlbmRpbmcgPyBkZXNjcmliZVF1ZXVlSXRlbShwZW5kaW5nKSA6ICdub25lJ30uYCxcbiAgICBgY29uc3VtZXI6IGluZGV4PSR7c25hcHNob3QuaW5kZXh9LCBsZW5ndGg9JHtzbmFwc2hvdC5sZW5ndGh9LCBwYXJrZWQ9JHtzbmFwc2hvdC5wYXJrZWR9LCBsYXN0Q29uc3VtZWQ9JHtzbmFwc2hvdC5sYXN0Q29uc3VtZWRFdmVudElkID8/ICdub25lJ31gLFxuICBdLmpvaW4oJyAnKTtcbn1cbiJdfQ==
@@ -1,4 +1,4 @@
1
- import type { CreateEventParams, CreateEventRequest, Event, EventResult, HealthCheckPayload, ValidQueueName, WorkflowRun, World } from '@workflow/world';
1
+ import type { CreateEventParams, CreateEventRequest, Event, EventResult, HealthCheckPayload, RunDispatchContext, ValidQueueName, WorkflowRun, World } from '@workflow/world';
2
2
  import { type PayloadKey } from '../serialization/encryption.js';
3
3
  /**
4
4
  * Validates a workflow name and returns the corresponding queue name.
@@ -329,6 +329,53 @@ export interface SlotSnapshotParams {
329
329
  * Empty for an empty log, which is the state a `run_created` write is issued
330
330
  * from: there is no position held yet to name.
331
331
  *
332
+ * ## Who names a position
333
+ *
334
+ * A World can hand events back on a write's success response through two
335
+ * params (`CreateEventParams` in `@workflow/world`): `eventCount`, which is
336
+ * answered with the events on the positions the write skipped over (the
337
+ * skipped-slot report), and `sinceCursor`, which is answered with everything
338
+ * after that cursor (the inline delta). Both exist to save the writer a
339
+ * reload. So the rule for which writes send them is not about the event type;
340
+ * it is about whether **the process that writes holds a loaded log it will
341
+ * keep deciding from**, its own next writes or the replay it resumes. A writer
342
+ * with no log has nothing to merge a page into, and whoever decides next is a
343
+ * fresh replay that loads the log anyway.
344
+ *
345
+ * Three gates, all of which must pass for a page to come back:
346
+ *
347
+ * 1. The writer names a position. Only the replay loop's `createEvent` seam
348
+ * (runtime.ts) and the suspension handler's `createGuarded` do; the QuickJS
349
+ * engine's `createEvent` (quickjs-entrypoint.ts) follows the same rule. Raw
350
+ * `world.events.create` calls send nothing.
351
+ * 2. The World reads a page for that event type. A World may decline for types
352
+ * whose writer never holds a log (step executor writes, run-terminal
353
+ * writes), whatever the client sent.
354
+ * 3. There is something to hand back: the report only when the write landed
355
+ * more than one position above `eventCount`; the delta always.
356
+ *
357
+ * | Event | Writer | Sends | Why |
358
+ * |---|---|---|---|
359
+ * | `run_created` | `start()` | nothing | no log exists yet |
360
+ * | `run_started` | replay loop, first write of a delivery | `eventCount` when a log is loaded; no cursor, the `run_started` preload owns the response fields | the preload already returns the full log |
361
+ * | `step_created`, `wait_created`, `hook_disposed`, `attr_set` | suspension handler (`createGuarded`) | `eventCount` | the handler keeps writing from, and resumes replay from, this log |
362
+ * | `step_created` | queue-consumer re-ensure (raw) | nothing | runs from a queue message, no log |
363
+ * | `hook_created` | suspension handler (node), `dispatchPendingOps` (QuickJS) | `eventCount` + `sinceCursor` (only when the suspension creates exactly one hook) | the delta is how an already-received hook resolves without a re-invocation; two creates against one cursor would give two deltas of which only the first could be taken |
364
+ * | `hook_received` | replay loop lazy resume; handler in-suspension resume | `eventCount` (preload owns the cursor fields) | both replay from the log right after |
365
+ * | `hook_received` | webhook / `resumeHook` (raw) | nothing | out-of-band, enqueues a delivery that loads the log |
366
+ * | `wait_completed` | replay loop timer path | `eventCount` | the loop keeps replaying from the log |
367
+ * | `wait_completed` | `runs.*` out-of-band (raw) | nothing | no log |
368
+ * | `step_started`, `step_retrying` | step executor | nothing | no log; the next decision is a replay that reloads or receives the delta below |
369
+ * | `step_completed`, `step_failed` | step executor | `sinceCursor` only, outside turbo, single inline step | this is where the inline execution loop gets its log back; in turbo or from a queued delivery a fresh replay loads it anyway |
370
+ * | `step_failed` | suspension handler, unserializable input | `eventCount` | the handler holds a log; rare, and follows a `step_created` that drew the page |
371
+ * | `attr_set` | `setAttributes()` API (raw) | nothing | out-of-band |
372
+ * | `run_completed`, `run_failed`, `run_cancelled` | replay loop, replay budget, `runs.cancel` | `eventCount` where the node loop's seam stamps it (the QuickJS engine sends nothing); never `sinceCursor` (`deltaRequestCursor` excludes terminal types) | terminal: nothing replays the log afterwards, so a World reads no page for them |
373
+ *
374
+ * Batched writes (`events.createBatch`) are outside all of this: a batch carries
375
+ * no per-event position and gets no page. The user-facing version of this table
376
+ * is in `docs/content/docs/v5/how-it-works/event-sourcing.mdx`; keep the two in
377
+ * step.
378
+ *
332
379
  * The maximum rather than the length, for the reason {@link maxEventSlot}
333
380
  * gives: a partially-read log holds fewer events than its highest position, and
334
381
  * counting those would make the write claim to have seen less than it has, so
@@ -360,6 +407,18 @@ export type EventCreator = (data: CreateEventRequest, params?: CreateEventParams
360
407
  * based on the presence of a `__health` query parameter.
361
408
  */
362
409
  export declare function withHealthCheck(handler: (req: Request) => Promise<Response>, worldSpecVersion?: number): (req: Request) => Promise<Response>;
410
+ /**
411
+ * The lineage root of a loaded run: its `$rootRunId` attribute, or its own id
412
+ * when it is itself a root.
413
+ */
414
+ export declare function rootRunIdFrom(attributes: Record<string, string> | undefined, runId: string): string;
415
+ /**
416
+ * The immutable run identity a step-execution message carries so its consumer
417
+ * can start the step without a blocking `runs.get` — see
418
+ * `RunDispatchContextSchema` in @workflow/world. Built at dispatch time from
419
+ * the run row the producer already holds.
420
+ */
421
+ export declare function runDispatchContext(run: Pick<WorkflowRun, 'runId' | 'deploymentId' | 'specVersion' | 'startedAt' | 'attributes'>): RunDispatchContext;
363
422
  /**
364
423
  * Idempotency key for a step's background-dispatch queue message, scoped to
365
424
  * the step's IDENTITY, correlation id plus (hashed) step name, rather than
@@ -386,6 +445,21 @@ export declare function stepDispatchIdempotencyKey(correlationId: string, stepNa
386
445
  * Queues a message to the specified queue with tracing.
387
446
  */
388
447
  export declare function queueMessage(world: World, ...args: Parameters<typeof world.queue>): Promise<void>;
448
+ /**
449
+ * Publishes several messages to one logical queue, using the World's batch
450
+ * send when it has one and falling back to concurrent single sends when it
451
+ * does not.
452
+ *
453
+ * Rejects if ANY message failed to publish, because every caller so far wants
454
+ * all-or-nothing: the recovery is to fail the delivery and let redelivery
455
+ * republish the whole set, deduped by the per-message `idempotencyKey`. That
456
+ * means a partial batch can leave some messages already out — which is
457
+ * exactly why the keys are required rather than advisory.
458
+ */
459
+ export declare function queueMessages(world: World, queueName: Parameters<typeof world.queue>[0], messages: readonly {
460
+ message: Parameters<typeof world.queue>[1];
461
+ opts?: Parameters<typeof world.queue>[2];
462
+ }[]): Promise<void>;
389
463
  /**
390
464
  * Calculates the queue overhead time in milliseconds for a given message.
391
465
  */
@@ -1 +1 @@
1
- {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/runtime/helpers.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/runtime/helpers.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,KAAK,EACN,MAAM,iBAAiB,CAAC;AAezB,OAAO,EAEL,KAAK,UAAU,EAChB,MAAM,gCAAgC,CAAC;AAgBxC;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,cAAc,CAWhB;AAWD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,GACf,kBAAkB,GAAG,SAAS,CAMhC;AAYD;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,kBAAkB,EAC/B,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,IAAI,CAAC,CAmDf;AAED,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA2ID,wBAAsB,WAAW,CAC/B,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAyF5B;AA0BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,KAAK,EAAE,EACf,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACtB,IAAI,CAaN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAiBxE;AAmCD;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,cAAc,CAAC,CAuGzB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE;IAAE,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC7D,IAAI,CAGN;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,KAAK,EAAE,EACf,MAAM,EAAE,SAAS,KAAK,EAAE,GACvB,MAAM,CAUR;AAED,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,KAAK,EAAE,EACf,MAAM,EAAE;IAAE,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACvD,iBAAiB,CAanB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,GAAG,SAAS,CASzE;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,gBAAgB,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,KAAK,EAAE,GACvB,YAAY,GAAG,SAAS,CAkC1B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAG3C;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC;IAAE,GAAG,EAAE,cAAc,CAAC;IAAC,GAAG,EAAE,YAAY,GAAG,SAAS,CAAA;CAAE,CAAC,CAejE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,KAAK,EAAE,GACvB,kBAAkB,CAGpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ;IAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CA0BnD;AAED,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,kBAAkB,EACxB,MAAM,CAAC,EAAE,iBAAiB,KACvB,OAAO,CAAC,WAAW,CAAC,CAAC;AAY1B;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAC5C,gBAAgB,CAAC,EAAE,MAAM,GACxB,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA8BrC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAC9C,KAAK,EAAE,MAAM,GACZ,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,IAAI,CACP,WAAW,EACX,OAAO,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,GAAG,YAAY,CACtE,GACA,kBAAkB,CAOpB;AAaD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,MAAM,CAER;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,KAAK,EACZ,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,iBA0BxC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,UAAU,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAC5C,QAAQ,EAAE,SAAS;IACjB,OAAO,EAAE,UAAU,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1C,EAAE,GACF,OAAO,CAAC,IAAI,CAAC,CA8Df;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IAAE,WAAW,CAAC,EAAE,IAAI,CAAA;CAAE;;cAS/D;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,WAAW,GAAG,MAAM,EAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAMjC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,WAAW,GAAG,MAAM,GAC5B,MAAM,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAQvC"}