@brickkit/redis-world 0.11.0 → 0.12.0

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.
@@ -0,0 +1,2345 @@
1
+ import { EventSchema, FIRST_EVENT_SLOT, HookSchema, StepSchema, WorkflowRunSchema, entityResolveData, eventIdToSlot, isLegacySpecVersion, mintedSpecVersion, requiresNewerWorld, slotToEventId, stripEventDataRefs, validateAttributeChanges } from "@workflow/world";
2
+ import { EntityConflictError, HookNotFoundError, RunExpiredError, RunNotSupportedError, TooEarlyError, WorkflowRunNotFoundError, WorkflowWorldError } from "@workflow/errors";
3
+ import { createHash } from "node:crypto";
4
+ import { globalSingleton } from "@workflow/utils";
5
+ import { encodeTime, monotonicFactory, ulid } from "ulid";
6
+ import { EventEmitter } from "node:events";
7
+ // src/run-id.ts
8
+ const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
9
+ const MAX_TIME = 2 ** 48 - 1;
10
+ const MAX_KEY_LENGTH = 1024;
11
+ function keyedRandomness(key) {
12
+ const digest = createHash("sha256").update(key).digest();
13
+ let bits = 0n;
14
+ for (let index = 0; index < 10; index++) bits = bits << 8n | BigInt(digest[index]);
15
+ let out = "";
16
+ for (let group = 15; group >= 0; group--) out += CROCKFORD[Number(bits >> BigInt(group * 5) & 31n)];
17
+ return out;
18
+ }
19
+ /**
20
+ * The run id the SDK asks the world for when a run starts. Without options it is
21
+ * a fresh ULID. With `runKey` and `runKeyTime` it is the same ULID every time, so
22
+ * starting the same run twice creates one run: the second start finds it already
23
+ * there.
24
+ *
25
+ * The id is a real ULID. Its time is `runKeyTime`, not the clock, because the SDK
26
+ * seeds a workflow's clock from the time in its run id. Pass the time the run is
27
+ * for, such as when the event it handles happened, and the same time on every
28
+ * attempt.
29
+ *
30
+ * @param options - The options given to `start()`. `runKey` is a non-empty string
31
+ * that names the run (at most 1024 characters), and `runKeyTime` is milliseconds
32
+ * since the epoch.
33
+ * @returns The id without its `wrun_` prefix, which the SDK adds.
34
+ * @throws When `runKey` is not a usable string, or comes without a valid `runKeyTime`.
35
+ */
36
+ function createRunId(options) {
37
+ const key = options?.runKey;
38
+ if (key === void 0) return ulid();
39
+ if (typeof key !== "string" || !key || key.length > MAX_KEY_LENGTH) throw new TypeError(`runKey must be a non-empty string of at most ${MAX_KEY_LENGTH} characters`);
40
+ const time = options?.runKeyTime;
41
+ if (typeof time !== "number" || !Number.isInteger(time) || time < 0 || time > MAX_TIME) throw new TypeError("runKey needs runKeyTime, the time the run is for in milliseconds since the epoch, so the run id stays a valid ULID with a true time");
42
+ return encodeTime(time, 10) + keyedRandomness(key);
43
+ }
44
+ /**
45
+ * The idempotency key for the message that starts a run, which is the only
46
+ * message that carries the run's input. `start()` sends no key of its own, so a
47
+ * second start of the same run would otherwise queue a second first delivery.
48
+ *
49
+ * The key only covers a first message that is still queued or running. Once the
50
+ * run has started, the queue does not enqueue the message at all (see
51
+ * `runHasStarted` in `createQueue`): the runtime runs a run's first step from the
52
+ * first message, in parallel with `run_created`, so a late second one would run
53
+ * that step's code again.
54
+ *
55
+ * @param message - The queue payload.
56
+ * @returns A key for a run's first message, and `undefined` for every other message.
57
+ */
58
+ function initialMessageKey(message) {
59
+ const { runId, runInput } = message ?? {};
60
+ return typeof runId === "string" && runInput !== void 0 ? `start:${runId}` : void 0;
61
+ }
62
+ // src/internal/debug.ts
63
+ /**
64
+ * Creates a namespaced debug logger.
65
+ * Logs to stderr to avoid corrupting CLI JSON output on stdout.
66
+ *
67
+ * Control via WORKFLOW_DEBUG environment variable:
68
+ * WORKFLOW_DEBUG=1 // Enable all
69
+ * WORKFLOW_DEBUG=mysql-world // Specific namespace
70
+ * WORKFLOW_DEBUG=mysql-world,redis-world // Multiple namespaces
71
+ */
72
+ function createDebugLogger(namespace) {
73
+ return (...args) => {
74
+ const debug = process.env.WORKFLOW_DEBUG;
75
+ if (!debug) return;
76
+ if (!(debug === "1" || debug === "true" || debug === "*" || debug.split(",").some((ns) => ns.trim() === namespace))) return;
77
+ const prefix = `[${(/* @__PURE__ */ new Date()).toISOString()}] [${namespace}]`;
78
+ const message = args.map((arg) => typeof arg === "object" ? JSON.stringify(arg, null, 2) : String(arg)).join(" ");
79
+ process.stderr.write(`${prefix} ${message}\n`);
80
+ };
81
+ }
82
+ // src/internal/util.ts
83
+ var Mutex = class {
84
+ promise = Promise.resolve();
85
+ andThen(fn) {
86
+ this.promise = this.promise.then(() => fn(), () => fn());
87
+ return this.promise;
88
+ }
89
+ };
90
+ function compact(obj) {
91
+ const value = {};
92
+ for (const key in obj) if (obj[key] !== null) value[key] = obj[key];
93
+ else value[key] = void 0;
94
+ return value;
95
+ }
96
+ /**
97
+ * Reference counting helper for managing resource lifecycle
98
+ */
99
+ var Rc = class {
100
+ count = 0;
101
+ disposeFn;
102
+ constructor(disposeFn) {
103
+ this.disposeFn = disposeFn;
104
+ }
105
+ inc() {
106
+ this.count++;
107
+ }
108
+ async dec() {
109
+ this.count--;
110
+ if (this.count === 0 && this.disposeFn) await this.disposeFn();
111
+ }
112
+ getCount() {
113
+ return this.count;
114
+ }
115
+ };
116
+ // src/internal/serialization.ts
117
+ /** Standard Date fields used across all worlds */
118
+ const DATE_FIELDS = /* @__PURE__ */ new Set([
119
+ "createdAt",
120
+ "updatedAt",
121
+ "startedAt",
122
+ "completedAt",
123
+ "retryAfter"
124
+ ]);
125
+ /**
126
+ * JSON reviver that converts ISO date strings to Date objects.
127
+ * Use with JSON.parse(json, dateReviver).
128
+ */
129
+ function dateReviver(key, value) {
130
+ if (DATE_FIELDS.has(key) && typeof value === "string") {
131
+ const date = new Date(value);
132
+ return Number.isNaN(date.getTime()) ? value : date;
133
+ }
134
+ return value;
135
+ }
136
+ /**
137
+ * JSON replacer that encodes Uint8Array as a tagged object with base64 data.
138
+ */
139
+ function uint8ArrayReplacer(_key, value) {
140
+ if (value instanceof Uint8Array) return {
141
+ __type: "Uint8Array",
142
+ data: Buffer.from(value).toString("base64")
143
+ };
144
+ return value;
145
+ }
146
+ /**
147
+ * JSON reviver that decodes tagged Uint8Array objects
148
+ * (`{ __type: 'Uint8Array', data: '<base64>' }`) and ISO date strings.
149
+ */
150
+ function uint8ArrayReviver(key, value) {
151
+ if (value && typeof value === "object") {
152
+ const obj = value;
153
+ if (obj.__type === "Uint8Array" && typeof obj.data === "string") return new Uint8Array(Buffer.from(obj.data, "base64"));
154
+ }
155
+ return dateReviver(key, value);
156
+ }
157
+ /** The tag `uint8ArrayReviver` decodes. Absent, only dates need reviving. */
158
+ const BINARY_TAG = "\"__type\"";
159
+ /** Revive `DATE_FIELDS` in place at any depth — the same reach as
160
+ * `dateReviver` under `JSON.parse`, just without the per-node JSON interop. */
161
+ function reviveDatesDeep(value) {
162
+ if (value === null || typeof value !== "object") return value;
163
+ if (Array.isArray(value)) {
164
+ for (let i = 0; i < value.length; i++) value[i] = reviveDatesDeep(value[i]);
165
+ return value;
166
+ }
167
+ const obj = value;
168
+ for (const key in obj) {
169
+ const child = obj[key];
170
+ if (DATE_FIELDS.has(key) && typeof child === "string") {
171
+ const date = new Date(child);
172
+ if (!Number.isNaN(date.getTime())) {
173
+ obj[key] = date;
174
+ continue;
175
+ }
176
+ }
177
+ obj[key] = reviveDatesDeep(child);
178
+ }
179
+ return obj;
180
+ }
181
+ /**
182
+ * Is there a `Uint8Array` anywhere in the graph?
183
+ *
184
+ * Must stay exact: `JSON.stringify` turns a bare `Uint8Array` into
185
+ * `{"0":1,...}` without complaint, so a miss is data corruption, not a slow
186
+ * path. The walk allocates nothing, which is why it beats the replacer over
187
+ * the same nodes.
188
+ */
189
+ function hasBinary(value) {
190
+ if (value === null || typeof value !== "object") return false;
191
+ if (value instanceof Uint8Array) return true;
192
+ if (Array.isArray(value)) {
193
+ for (let i = 0; i < value.length; i++) if (hasBinary(value[i])) return true;
194
+ return false;
195
+ }
196
+ for (const key in value) if (hasBinary(value[key])) return true;
197
+ return false;
198
+ }
199
+ /** Stringify with Uint8Array support. */
200
+ function stringify(value) {
201
+ return hasBinary(value) ? JSON.stringify(value, uint8ArrayReplacer) : JSON.stringify(value);
202
+ }
203
+ /** Parse with Uint8Array and Date support. */
204
+ function parse(text) {
205
+ if (text.includes(BINARY_TAG)) return JSON.parse(text, uint8ArrayReviver);
206
+ return reviveDatesDeep(JSON.parse(text));
207
+ }
208
+ // src/util.ts
209
+ const debug = createDebugLogger("redis-world");
210
+ // src/reaper.ts
211
+ const TERMINAL = [
212
+ "completed",
213
+ "failed",
214
+ "cancelled"
215
+ ];
216
+ const DEFAULT_SWEEP_INTERVAL_MS = 6e4;
217
+ const DEFAULT_BATCH_SIZE = 200;
218
+ const UNLINK_CHUNK = 500;
219
+ function validateRetention(retention) {
220
+ if (!retention) return;
221
+ for (const status of TERMINAL) {
222
+ const keep = retention[status];
223
+ if (!keep) continue;
224
+ for (const field of ["age", "count"]) {
225
+ const value = keep[field];
226
+ if (value !== void 0 && (!Number.isInteger(value) || value < 0)) throw new TypeError(`retention.${status}.${field} must be a non-negative integer, received ${String(value)}`);
227
+ }
228
+ }
229
+ for (const field of ["sweepIntervalMs", "batchSize"]) {
230
+ const value = retention[field];
231
+ if (value !== void 0 && (!Number.isInteger(value) || value < 1)) throw new TypeError(`retention.${field} must be a positive integer, received ${String(value)}`);
232
+ }
233
+ }
234
+ function hasRetention(retention) {
235
+ return !!retention && TERMINAL.some((status) => retention[status] !== void 0);
236
+ }
237
+ /**
238
+ * Deletes finished runs once they pass their retention. Safe to run on every
239
+ * worker: one lock per interval picks a single sweeper, and deleting a run is
240
+ * idempotent anyway. A run's own key and index entries go last, in one
241
+ * transaction, so a crash part-way leaves the run listed and the next sweep
242
+ * finishes the job.
243
+ */
244
+ function createReaper(options) {
245
+ const { redis, keyPrefix, retention, log = debug } = options;
246
+ const intervalMs = retention.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
247
+ const batchSize = retention.batchSize ?? DEFAULT_BATCH_SIZE;
248
+ const lockKey = `${keyPrefix}reaper:lock`;
249
+ const byStatusKey = (status) => `${keyPrefix}runs:by_status:${status}`;
250
+ let timer;
251
+ let running = Promise.resolve();
252
+ /** Runs past retention, oldest first: too old, or beyond the newest `count`. */
253
+ async function expired(status) {
254
+ const keep = retention[status];
255
+ if (!keep) return [];
256
+ const ids = /* @__PURE__ */ new Set();
257
+ if (keep.age !== void 0) {
258
+ const cutoff = Date.now() - keep.age * 1e3;
259
+ for (const id of await redis.zrangebyscore(byStatusKey(status), "-inf", cutoff, "LIMIT", 0, batchSize)) ids.add(id);
260
+ }
261
+ if (keep.count !== void 0) {
262
+ const stop = -(keep.count + 1);
263
+ for (const id of await redis.zrange(byStatusKey(status), "0", String(stop))) {
264
+ if (ids.size >= batchSize) break;
265
+ ids.add(id);
266
+ }
267
+ }
268
+ return [...ids].slice(0, batchSize);
269
+ }
270
+ async function unlink(keys) {
271
+ for (let i = 0; i < keys.length; i += UNLINK_CHUNK) await redis.unlink(...keys.slice(i, i + UNLINK_CHUNK));
272
+ }
273
+ async function scan(pattern) {
274
+ const found = [];
275
+ let cursor = "0";
276
+ do {
277
+ const [next, batch] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 1e3);
278
+ cursor = next;
279
+ found.push(...batch);
280
+ } while (cursor !== "0");
281
+ return found;
282
+ }
283
+ /** Delete one run if it is still finished. Returns whether it was deleted. */
284
+ async function deleteRun(runId, listedAs) {
285
+ const metaKey = `${keyPrefix}run:meta:${runId}`;
286
+ const meta = await redis.get(metaKey);
287
+ const status = meta?.split("|")[0];
288
+ if (!status || !TERMINAL.includes(status)) {
289
+ if (!meta) await redis.zrem(byStatusKey(listedAs), runId);
290
+ return false;
291
+ }
292
+ const runKey = `${keyPrefix}run:${runId}`;
293
+ const runJson = await redis.get(runKey);
294
+ const workflowName = runJson ? JSON.parse(runJson).workflowName : void 0;
295
+ const eventsKey = `${keyPrefix}events:data:${runId}`;
296
+ const correlationIds = /* @__PURE__ */ new Set();
297
+ let hasResume = false;
298
+ for (const raw of await redis.hvals(eventsKey)) try {
299
+ const event = JSON.parse(raw);
300
+ if (event.correlationId) correlationIds.add(event.correlationId);
301
+ if (event.eventType === "hook_received") hasResume = true;
302
+ } catch {}
303
+ const stepIds = await redis.zrange(`${keyPrefix}steps:by_run:${runId}`, "0", "-1");
304
+ const hookIds = await redis.zrange(`${keyPrefix}hooks:by_run:${runId}`, "0", "-1");
305
+ const streamNames = await redis.smembers(`${keyPrefix}streams:by_run:${runId}`);
306
+ const keys = [
307
+ eventsKey,
308
+ `${keyPrefix}run:attrs:${runId}`,
309
+ `${keyPrefix}steps:by_run:${runId}`,
310
+ `${keyPrefix}hooks:by_run:${runId}`,
311
+ `${keyPrefix}hooks:tokens:${runId}`,
312
+ `${keyPrefix}streams:by_run:${runId}`,
313
+ ...[...correlationIds].map((id) => `${keyPrefix}events:by_correlation:${runId}:${id}`),
314
+ ...stepIds.flatMap((id) => [`${keyPrefix}step:${runId}:${id}`, `${keyPrefix}step:status:${runId}:${id}`]),
315
+ ...hookIds.map((id) => `${keyPrefix}hook:${id}`),
316
+ ...streamNames.map((name) => `${keyPrefix}stream:${runId}:${name}`)
317
+ ];
318
+ if (hasResume) keys.push(...await scan(`${keyPrefix}events:resume:${runId}:*`));
319
+ await unlink(keys);
320
+ const tx = redis.multi().zrem(`${keyPrefix}runs:index`, runId).zrem(byStatusKey(status), runId).unlink(metaKey, runKey);
321
+ if (workflowName) tx.zrem(`${keyPrefix}runs:by_name:${workflowName}`, runId);
322
+ await tx.exec();
323
+ return true;
324
+ }
325
+ async function sweep() {
326
+ if (await redis.set(lockKey, "1", "PX", Math.max(1e3, Math.floor(intervalMs / 2)), "NX") !== "OK") return 0;
327
+ let deleted = 0;
328
+ for (const status of TERMINAL) for (const runId of await expired(status)) try {
329
+ if (await deleteRun(runId, status)) deleted++;
330
+ } catch (err) {
331
+ log("reaper failed to delete run", runId, err);
332
+ }
333
+ return deleted;
334
+ }
335
+ return {
336
+ sweep,
337
+ start() {
338
+ if (timer) return;
339
+ const tick = () => {
340
+ running = sweep().catch((err) => log("reaper sweep failed", err));
341
+ };
342
+ timer = setInterval(tick, intervalMs);
343
+ timer.unref();
344
+ },
345
+ async stop() {
346
+ if (timer) clearInterval(timer);
347
+ timer = void 0;
348
+ await running;
349
+ }
350
+ };
351
+ }
352
+ // src/storage.ts
353
+ /** Per-run event ceiling reported to core, mirroring the Vercel World. */
354
+ const DEFAULT_MAX_EVENTS_PER_RUN = 25e3;
355
+ /** Resolve the per-run event ceiling surfaced as `EventResult.maxEvents`:
356
+ * explicit config, then `WORKFLOW_MAX_EVENTS`, then the default. A
357
+ * non-positive configured value throws rather than being ignored. */
358
+ function resolveMaxEventsPerRun(configured) {
359
+ if (configured !== void 0) {
360
+ if (!Number.isInteger(configured) || configured <= 0) throw new TypeError(`maxEventsPerRun must be a positive integer, received ${String(configured)}`);
361
+ return configured;
362
+ }
363
+ const raw = process.env.WORKFLOW_MAX_EVENTS;
364
+ const parsed = raw !== void 0 ? Number(raw) : NaN;
365
+ return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_EVENTS_PER_RUN;
366
+ }
367
+ /** Events that mutate the run, so validation needs its full body. Everything
368
+ * else only reads status/specVersion and is served from the run meta key. */
369
+ const RUN_LIFECYCLE_EVENT_TYPES = /* @__PURE__ */ new Set([
370
+ "run_started",
371
+ "run_completed",
372
+ "run_failed",
373
+ "run_cancelled"
374
+ ]);
375
+ /** Sentinel from the event scripts when a creation-dedup check rejects. */
376
+ const LUA_DUPLICATE_CREATION = -8;
377
+ /**
378
+ * Stand-in for the event id inside the event JSON the caller hands to a script.
379
+ * The id is a log position (`evnt_` + the 1-based slot), and a position may only
380
+ * be chosen at the commit (see `LUA_APPEND_EVENT`), so the script writes it into
381
+ * the JSON itself. `serializeEvent` always emits `eventId` as the first key, so
382
+ * the first match is ours whatever the payload holds. A constant, not a random
383
+ * value: two bundled copies of this module can share one connection's scripts.
384
+ */
385
+ const EVENT_ID_PLACEHOLDER = "__brick_event_id__";
386
+ /**
387
+ * Lua helper shared by every script that appends to a run's event log.
388
+ *
389
+ * A run's events live in one hash, `eventId -> JSON`. The log is dense and
390
+ * 1-based, and a script runs atomically, so the next slot is the hash length
391
+ * plus one and no other writer can interleave between reading it and writing the
392
+ * event. That is the whole race story: the slot is chosen at the commit, in the
393
+ * same operation that appends, and a writer that is behind simply lands on the
394
+ * next free slot (the caller reports what it skipped).
395
+ *
396
+ * `appendEvent(eventsKey, correlationKey, json)` returns the new event id.
397
+ * `correlationKey` may be nil. The id is written into `json` in place of the
398
+ * placeholder, so what is stored is exactly what the reader parses.
399
+ */
400
+ const LUA_APPEND_EVENT = `
401
+ local function appendEvent(eventsKey, correlationKey, json)
402
+ local slot = redis.call('HLEN', eventsKey) + 1
403
+ local digits = string.format('%d', slot)
404
+ local eventId = 'evnt_' .. string.rep('0', 26 - #digits) .. digits
405
+ local from, to = string.find(json, '${EVENT_ID_PLACEHOLDER}', 1, true)
406
+ json = string.sub(json, 1, from - 1) .. eventId .. string.sub(json, to + 1)
407
+ redis.call('HSET', eventsKey, eventId, json)
408
+ if correlationKey then
409
+ redis.call('ZADD', correlationKey, slot, eventId)
410
+ end
411
+ return eventId
412
+ end
413
+
414
+ -- A run's status from its meta key ('<status>|<specVersion>'), or false when absent.
415
+ local function runStatus(metaKey)
416
+ local meta = redis.call('GET', metaKey)
417
+ if not meta then
418
+ return false
419
+ end
420
+ return string.match(meta, '^([^|]*)')
421
+ end
422
+
423
+ local function isTerminal(status)
424
+ return status == 'completed' or status == 'failed' or status == 'cancelled'
425
+ end
426
+ `;
427
+ /** Stringify an object with Uint8Array support. Delegates to the shared
428
+ * helper, which tags binary as base64; the previous number-array encoding
429
+ * cost ~450x more CPU to re-parse and ~2.7x more storage at 2MB. */
430
+ function stringifyWithUint8Array(obj) {
431
+ return stringify(obj);
432
+ }
433
+ /** Parse JSON with Uint8Array and Date support. The shared reviver decodes
434
+ * both the base64 tag and the legacy number-array tag, so rows already in
435
+ * Redis keep reading back correctly. */
436
+ function parseWithUint8Array(json) {
437
+ return parse(json);
438
+ }
439
+ /**
440
+ * Filter hook data based on resolveData parameter
441
+ */
442
+ function filterHookData(hook, resolveData) {
443
+ if (resolveData === "none" && "metadata" in hook) {
444
+ const { metadata: _, ...rest } = hook;
445
+ return {
446
+ metadata: void 0,
447
+ ...rest
448
+ };
449
+ }
450
+ return hook;
451
+ }
452
+ function filterStepData(step, resolveData) {
453
+ if (resolveData === "none") {
454
+ const { input: _, output: __, ...rest } = step;
455
+ return {
456
+ input: void 0,
457
+ output: void 0,
458
+ ...rest
459
+ };
460
+ }
461
+ return step;
462
+ }
463
+ function filterRunData(run, resolveData) {
464
+ if (resolveData === "none") {
465
+ const { input: _, output: __, ...rest } = run;
466
+ return {
467
+ input: void 0,
468
+ output: void 0,
469
+ ...rest
470
+ };
471
+ }
472
+ return run;
473
+ }
474
+ /**
475
+ * Read up to `want` members of one or more sorted-set indexes, in score order,
476
+ * resuming after `cursor`. With several indexes the members are merged into one
477
+ * ordering, which is how a listing across statuses avoids scanning an index of
478
+ * every run there has ever been.
479
+ *
480
+ * A cursor is the last member's `<score>|<id>`, not its rank: a rank means
481
+ * nothing once that member has left the index (a run that changed status, a
482
+ * hook that was disposed), and paging would fail halfway through a listing. A
483
+ * position by score and id stays valid wherever the member went. Members that
484
+ * share a score are ordered by id, as Redis orders them.
485
+ */
486
+ async function pageIndex(redis, indexKeys, cursor, want, order = "desc") {
487
+ let after;
488
+ if (cursor) {
489
+ const sep = cursor.indexOf("|");
490
+ const score = sep > 0 ? Number(cursor.slice(0, sep)) : NaN;
491
+ if (Number.isNaN(score)) throw new WorkflowWorldError(`Invalid pagination cursor "${cursor}"`, { status: 400 });
492
+ after = {
493
+ score,
494
+ id: cursor.slice(sep + 1)
495
+ };
496
+ }
497
+ const bound = after ? String(after.score) : order === "desc" ? "+inf" : "-inf";
498
+ const readOne = async (indexKey) => {
499
+ const out = [];
500
+ const batch = Math.max(want, 50);
501
+ let offset = 0;
502
+ while (out.length < want) {
503
+ const raw = order === "desc" ? await redis.zrevrangebyscore(indexKey, bound, "-inf", "WITHSCORES", "LIMIT", offset, batch) : await redis.zrangebyscore(indexKey, bound, "+inf", "WITHSCORES", "LIMIT", offset, batch);
504
+ for (let i = 0; i < raw.length && out.length < want; i += 2) {
505
+ const id = raw[i];
506
+ const score = Number(raw[i + 1]);
507
+ if (after && score === after.score && (order === "desc" ? id >= after.id : id <= after.id)) continue;
508
+ out.push({
509
+ id,
510
+ score,
511
+ cursor: `${raw[i + 1]}|${id}`
512
+ });
513
+ }
514
+ offset += raw.length / 2;
515
+ if (raw.length / 2 < batch) break;
516
+ }
517
+ return out;
518
+ };
519
+ const keys = Array.isArray(indexKeys) ? indexKeys : [indexKeys];
520
+ if (keys.length === 1) return readOne(keys[0]);
521
+ const merged = (await Promise.all(keys.map(readOne))).flat();
522
+ const direction = order === "desc" ? -1 : 1;
523
+ merged.sort((x, y) => direction * (x.score - y.score || (x.id < y.id ? -1 : x.id > y.id ? 1 : 0)));
524
+ return merged.slice(0, want);
525
+ }
526
+ /**
527
+ * Atomically create a run entity with all its indexes AND its creation
528
+ * event. SETNX arbitrates duplicates: when the run already exists, NO
529
+ * index, meta, or event write happens (a replayed run_created must not
530
+ * reset index scores, re-insert a terminal run into the pending status
531
+ * index, or append a second creation event).
532
+ *
533
+ * KEYS[1] = run key
534
+ * KEYS[2] = runs index key
535
+ * KEYS[3] = runs by name key
536
+ * KEYS[4] = runs by status key (pending)
537
+ * KEYS[5] = run meta key
538
+ * KEYS[6] = events key (the run's log)
539
+ * KEYS[7] = run attributes key
540
+ * ARGV[1] = run JSON
541
+ * ARGV[2] = run ID
542
+ * ARGV[3] = score (timestamp)
543
+ * ARGV[4] = run meta value (`<status>|<specVersion>`)
544
+ * ARGV[5] = event JSON (event id left as the placeholder)
545
+ * ARGV[6..] = attribute key, value pairs to seed
546
+ * Returns: [1, eventId] when created, [0, runJson] on replay.
547
+ */
548
+ const LUA_CREATE_RUN_WITH_EVENT = `${LUA_APPEND_EVENT}
549
+ local wasCreated = redis.call('SETNX', KEYS[1], ARGV[1])
550
+ if wasCreated == 0 then
551
+ return {0, redis.call('GET', KEYS[1])}
552
+ end
553
+ local score = tonumber(ARGV[3])
554
+ redis.call('ZADD', KEYS[2], score, ARGV[2])
555
+ redis.call('ZADD', KEYS[3], score, ARGV[2])
556
+ redis.call('ZADD', KEYS[4], score, ARGV[2])
557
+ redis.call('SET', KEYS[5], ARGV[4])
558
+ for i = 6, #ARGV, 2 do
559
+ redis.call('HSET', KEYS[7], ARGV[i], ARGV[i + 1])
560
+ end
561
+ return {1, appendEvent(KEYS[6], nil, ARGV[5])}
562
+ `;
563
+ /**
564
+ * Move a run to a new status, release its hooks when it finishes, and append the
565
+ * lifecycle event, all in one execution. They are one script because a crash
566
+ * between them would leave a terminal run with no terminal event (every retry is
567
+ * then refused as terminal) or a started run with no `run_started` (the redelivery
568
+ * takes the resume path and appends nothing).
569
+ *
570
+ * KEYS[1] = run key
571
+ * KEYS[2] = old status index key
572
+ * KEYS[3] = new status index key
573
+ * KEYS[4] = run meta key
574
+ * KEYS[5] = events key
575
+ * KEYS[6] = hooks index key
576
+ * KEYS[7] = hooks token-map key
577
+ * ARGV[1] = updated run JSON
578
+ * ARGV[2] = run ID
579
+ * ARGV[3] = score (timestamp)
580
+ * ARGV[4] = run meta value (`<status>|<specVersion>`)
581
+ * ARGV[5] = the status the caller read the run in
582
+ * ARGV[6] = event JSON
583
+ * ARGV[7] = "1" to release the run's hooks (a terminal transition)
584
+ * ARGV[8] = hook key prefix
585
+ * ARGV[9] = hooks-by-token key prefix
586
+ * Returns: [1, eventId] on success, [0, ''] if the run is absent, [-2, status] if
587
+ * the run is no longer in the status the caller read (another writer
588
+ * moved it first; nothing is written)
589
+ */
590
+ const LUA_TRANSITION_RUN = `${LUA_APPEND_EVENT}
591
+ if redis.call('EXISTS', KEYS[1]) == 0 then
592
+ return {0, ''}
593
+ end
594
+
595
+ local current = runStatus(KEYS[4])
596
+ if current and current ~= ARGV[5] then
597
+ return {-2, current}
598
+ end
599
+
600
+ redis.call('SET', KEYS[1], ARGV[1])
601
+ redis.call('SET', KEYS[4], ARGV[4])
602
+ redis.call('ZREM', KEYS[2], ARGV[2])
603
+ redis.call('ZADD', KEYS[3], tonumber(ARGV[3]), ARGV[2])
604
+
605
+ if ARGV[7] == '1' then
606
+ local pairsFlat = redis.call('HGETALL', KEYS[7])
607
+ for i = 1, #pairsFlat, 2 do
608
+ local hookId = pairsFlat[i]
609
+ local tokenKey = ARGV[9] .. pairsFlat[i + 1]
610
+ redis.call('DEL', ARGV[8] .. hookId)
611
+ -- Only a token this hook still owns: a stale entry must not wipe a claim
612
+ -- another run has taken since.
613
+ if redis.call('GET', tokenKey) == hookId then
614
+ redis.call('DEL', tokenKey)
615
+ end
616
+ end
617
+ redis.call('DEL', KEYS[7])
618
+ redis.call('DEL', KEYS[6])
619
+ end
620
+
621
+ return {1, appendEvent(KEYS[5], nil, ARGV[6])}
622
+ `;
623
+ /**
624
+ * Atomically create a step entity with its index AND its creation event.
625
+ * SETNX arbitrates duplicates: a replayed step_created writes nothing. A step is
626
+ * never created on a finished run.
627
+ *
628
+ * KEYS[1] = step key
629
+ * KEYS[2] = steps index key
630
+ * KEYS[3] = events key
631
+ * KEYS[4] = events by correlation key
632
+ * KEYS[5] = step status key (see `LUA_STORE_EVENT`)
633
+ * KEYS[6] = run meta key
634
+ * ARGV[1] = step JSON
635
+ * ARGV[2] = step ID (correlationId)
636
+ * ARGV[3] = score (timestamp)
637
+ * ARGV[4] = event JSON
638
+ * ARGV[5] = step status value (`<status>|<attempt>`)
639
+ * Returns: [1, eventId] when created, [0, stepJson] on replay, [-6, status] when
640
+ * the run is terminal
641
+ */
642
+ const LUA_CREATE_STEP_WITH_EVENT = `${LUA_APPEND_EVENT}
643
+ local status = runStatus(KEYS[6])
644
+ if status and isTerminal(status) then
645
+ return {-6, status}
646
+ end
647
+ local wasCreated = redis.call('SETNX', KEYS[1], ARGV[1])
648
+ if wasCreated == 0 then
649
+ return {0, redis.call('GET', KEYS[1])}
650
+ end
651
+ redis.call('ZADD', KEYS[2], tonumber(ARGV[3]), ARGV[2])
652
+ redis.call('SET', KEYS[5], ARGV[5])
653
+ return {1, appendEvent(KEYS[3], KEYS[4], ARGV[4])}
654
+ `;
655
+ /**
656
+ * Lazy step start: a `step_started` that carries the step's input also creates
657
+ * the step. The step entity (already running, attempt 1), the synthetic
658
+ * `step_created` and the `step_started` land together, so replay still sees the
659
+ * creation, and exactly one concurrent caller wins the SETNX and runs the body.
660
+ *
661
+ * KEYS[1] = step key
662
+ * KEYS[2] = steps index key
663
+ * KEYS[3] = events key
664
+ * KEYS[4] = events by correlation key
665
+ * KEYS[5] = step status key (see `LUA_STORE_EVENT`)
666
+ * KEYS[6] = run meta key
667
+ * ARGV[1] = step JSON (running)
668
+ * ARGV[2] = step ID (correlationId)
669
+ * ARGV[3] = score (timestamp)
670
+ * ARGV[4] = step_created event JSON
671
+ * ARGV[5] = step_started event JSON
672
+ * ARGV[6] = step status value (`running|1`)
673
+ * Returns: [1, createdEventId, startedEventId] when created, [0, stepJson] when
674
+ * the step already exists (the caller lost the claim), [-6, status]
675
+ * when the run is terminal
676
+ */
677
+ const LUA_CREATE_STEP_STARTED = `${LUA_APPEND_EVENT}
678
+ local status = runStatus(KEYS[6])
679
+ if status and isTerminal(status) then
680
+ return {-6, status}
681
+ end
682
+ local wasCreated = redis.call('SETNX', KEYS[1], ARGV[1])
683
+ if wasCreated == 0 then
684
+ return {0, redis.call('GET', KEYS[1])}
685
+ end
686
+ redis.call('ZADD', KEYS[2], tonumber(ARGV[3]), ARGV[2])
687
+ redis.call('SET', KEYS[5], ARGV[6])
688
+ local createdId = appendEvent(KEYS[3], KEYS[4], ARGV[4])
689
+ local startedId = appendEvent(KEYS[3], KEYS[4], ARGV[5])
690
+ return {1, createdId, startedId}
691
+ `;
692
+ /**
693
+ * Atomically claim a hook token and create the hook entity, its indexes,
694
+ * token-map entry, AND its creation event. The by-token key is the claim
695
+ * arbiter (SETNX):
696
+ * - A DIFFERENT hookId already owning the token -> cross-run conflict; the
697
+ * rightful owner's token mapping is left untouched. If that owner's hook no
698
+ * longer exists (a crash during cleanup left the token behind), the token is
699
+ * free and is taken over here, in the same execution, so a concurrent claim
700
+ * can never be wiped.
701
+ * - The SAME hookId owning the token with the entity present -> duplicate.
702
+ * Entity + event are written in the same atomic script, so a crash can
703
+ * never leave a hook entity without its hook_created event (or vice versa). A
704
+ * hook is never created on a finished run, which would hold its token forever.
705
+ *
706
+ * KEYS[1] = hook key
707
+ * KEYS[2] = hooks by token key
708
+ * KEYS[3] = hooks index key
709
+ * KEYS[4] = hooks token-map key (hash of hookId -> token, per run)
710
+ * KEYS[5] = events key
711
+ * KEYS[6] = events by correlation key
712
+ * KEYS[7] = run meta key
713
+ * ARGV[1] = hook JSON
714
+ * ARGV[2] = hook ID (correlationId)
715
+ * ARGV[3] = score (timestamp)
716
+ * ARGV[4] = the token, recorded in the token map so terminal-run cleanup can
717
+ * drop token lookups without reading every hook body
718
+ * ARGV[5] = event JSON
719
+ * ARGV[6] = hook key prefix
720
+ * Returns: [2, owningHookId] on token conflict,
721
+ * [0, hookJson] when the hook already exists, or has existed (created
722
+ * and since disposed),
723
+ * [1, eventId] on success,
724
+ * [-6, status] when the run is terminal
725
+ */
726
+ const LUA_CREATE_HOOK_WITH_EVENT = `${LUA_APPEND_EVENT}
727
+ local status = runStatus(KEYS[7])
728
+ if status and isTerminal(status) then
729
+ return {-6, status}
730
+ end
731
+ -- Disposal removes the hook and its token, so a stale writer that loaded the log
732
+ -- before the hook existed would otherwise create it again behind its disposal.
733
+ -- The creation event is the record that it already happened.
734
+ if redis.call('ZCARD', KEYS[6]) > 0 then
735
+ return {0, ''}
736
+ end
737
+ local claimed = redis.call('SETNX', KEYS[2], ARGV[2])
738
+ if claimed == 0 then
739
+ local owner = redis.call('GET', KEYS[2])
740
+ if owner ~= ARGV[2] then
741
+ if redis.call('EXISTS', ARGV[6] .. owner) == 1 then
742
+ return {2, owner}
743
+ end
744
+ redis.call('SET', KEYS[2], ARGV[2])
745
+ end
746
+ end
747
+ local wasCreated = redis.call('SETNX', KEYS[1], ARGV[1])
748
+ if wasCreated == 0 then
749
+ return {0, redis.call('GET', KEYS[1])}
750
+ end
751
+ redis.call('ZADD', KEYS[3], tonumber(ARGV[3]), ARGV[2])
752
+ redis.call('HSET', KEYS[4], ARGV[2], ARGV[4])
753
+ return {1, appendEvent(KEYS[5], KEYS[6], ARGV[5])}
754
+ `;
755
+ /**
756
+ * Atomically dispose a hook: delete the hook key, its token lookup (only while
757
+ * it still points at this hook), its index entry and its token-map entry, and
758
+ * append `hook_disposed`. One script, because a crash between the delete and the
759
+ * append would lose the event, and a delete racing a `hook_received` must not
760
+ * leave the received event behind the disposal in the log.
761
+ *
762
+ * KEYS[1] = hook key
763
+ * KEYS[2] = hooks by token key
764
+ * KEYS[3] = hooks index key
765
+ * KEYS[4] = hooks token-map key
766
+ * KEYS[5] = events key
767
+ * KEYS[6] = events by correlation key
768
+ * ARGV[1] = hook ID (correlationId)
769
+ * ARGV[2] = event JSON
770
+ * Returns: [1, eventId] if disposed, [0, ''] if the hook was not found
771
+ */
772
+ const LUA_DISPOSE_HOOK = `${LUA_APPEND_EVENT}
773
+ if redis.call('DEL', KEYS[1]) == 0 then
774
+ return {0, ''}
775
+ end
776
+ if redis.call('GET', KEYS[2]) == ARGV[1] then
777
+ redis.call('DEL', KEYS[2])
778
+ end
779
+ redis.call('ZREM', KEYS[3], ARGV[1])
780
+ redis.call('HDEL', KEYS[4], ARGV[1])
781
+ return {1, appendEvent(KEYS[5], KEYS[6], ARGV[2])}
782
+ `;
783
+ /**
784
+ * Atomically append an event to the run's log and its correlation index,
785
+ * optionally writing an entity first so the mutation and its event commit
786
+ * together.
787
+ *
788
+ * KEYS[1] = events key
789
+ * KEYS[2] = events by correlation key (or unused placeholder)
790
+ * KEYS[3] = entity key (or unused placeholder)
791
+ * KEYS[4] = hook resume claim key (or unused placeholder)
792
+ * KEYS[5] = step status key (or unused placeholder)
793
+ * KEYS[6] = run meta key (or unused placeholder)
794
+ * KEYS[7] = hook key (or unused placeholder)
795
+ * ARGV[1] = event JSON
796
+ * ARGV[2] = has correlation ("1" or "0")
797
+ * ARGV[3] = creation dedup: "1" rejects when the correlation index already holds
798
+ * an event (a wait or hook conflict recorded once), "2" rejects when it
799
+ * already holds two (a wait completed once)
800
+ * ARGV[4] = entity JSON to write to KEYS[3] ('' to write nothing)
801
+ * ARGV[5] = resume claim payload ('' when the event is not a lazy hook resume)
802
+ * ARGV[6] = the step's new status ('' when the event writes no step)
803
+ * ARGV[7] = the attempt the caller read ('' to skip the check)
804
+ * ARGV[8] = the step's new attempt ('' to keep the current one)
805
+ * ARGV[9] = "1" to refuse when the run is terminal
806
+ * ARGV[10] = "1" to refuse when the hook (KEYS[7]) does not exist
807
+ *
808
+ * A lazy hook resume is claimed per (run, resumeId): the first writer appends and
809
+ * records `<eventId>|<claim payload>`, a later one appends nothing and gets the
810
+ * recorded claim back, so both writers converge on one event.
811
+ *
812
+ * A step write is a transition out of the state the caller read, so it is checked
813
+ * where the state lives: a terminal step takes no further write, and a write that
814
+ * read an older attempt than the step now has lost to another writer. Without
815
+ * this two deliveries could both record an outcome, and the log would hold both.
816
+ * The attempt counter is kept here, not taken from the caller's possibly stale
817
+ * copy of the step, so it only moves forward.
818
+ *
819
+ * The run and hook guards live here because the checks the caller makes before
820
+ * calling are stale by the time the event is appended: a `hook_received` must not
821
+ * land behind the hook's disposal or the run's end, which no replay can consume.
822
+ *
823
+ * Returns: [1, eventId] on success, [-8, ''] when creation dedup rejects,
824
+ * [-7, ''] when completion dedup rejects, [3, claim] when a resume claim
825
+ * already exists, [-3, status] when the step is already terminal,
826
+ * [-4, attempt] when the step has moved past the attempt the caller
827
+ * read, [-6, status] when the run is terminal, [-5, ''] when the hook
828
+ * is gone
829
+ */
830
+ const LUA_STORE_EVENT = `${LUA_APPEND_EVENT}
831
+ if ARGV[5] ~= '' then
832
+ local claim = redis.call('GET', KEYS[4])
833
+ if claim then
834
+ return {3, claim}
835
+ end
836
+ end
837
+
838
+ if ARGV[10] == '1' and redis.call('EXISTS', KEYS[7]) == 0 then
839
+ return {-5, ''}
840
+ end
841
+
842
+ if ARGV[9] == '1' then
843
+ local status = runStatus(KEYS[6])
844
+ if status and isTerminal(status) then
845
+ return {-6, status}
846
+ end
847
+ end
848
+
849
+ if ARGV[3] == '1' and redis.call('ZCARD', KEYS[2]) > 0 then
850
+ return {${LUA_DUPLICATE_CREATION}, ''}
851
+ end
852
+ if ARGV[3] == '2' and redis.call('ZCARD', KEYS[2]) > 1 then
853
+ return {-7, ''}
854
+ end
855
+
856
+ if ARGV[6] ~= '' then
857
+ local current = redis.call('GET', KEYS[5])
858
+ -- No key (a step written before it existed): the caller's read is the best
859
+ -- attempt there is. Assuming 0 would make every later start look stale.
860
+ local attempt = '0'
861
+ if ARGV[7] ~= '' then
862
+ attempt = ARGV[7]
863
+ end
864
+ if current then
865
+ local status
866
+ status, attempt = string.match(current, '^([^|]*)|?(.*)$')
867
+ if status == 'completed' or status == 'failed' or status == 'cancelled' then
868
+ return {-3, status}
869
+ end
870
+ if ARGV[7] ~= '' and attempt ~= ARGV[7] then
871
+ return {-4, attempt}
872
+ end
873
+ end
874
+ if ARGV[8] ~= '' then
875
+ attempt = ARGV[8]
876
+ end
877
+ redis.call('SET', KEYS[5], ARGV[6] .. '|' .. attempt)
878
+ end
879
+
880
+ if ARGV[4] ~= '' then
881
+ redis.call('SET', KEYS[3], ARGV[4])
882
+ end
883
+
884
+ local correlationKey = nil
885
+ if ARGV[2] == '1' then
886
+ correlationKey = KEYS[2]
887
+ end
888
+ local eventId = appendEvent(KEYS[1], correlationKey, ARGV[1])
889
+ if ARGV[5] ~= '' then
890
+ redis.call('SET', KEYS[4], eventId .. '|' .. ARGV[5])
891
+ end
892
+ return {1, eventId}
893
+ `;
894
+ /**
895
+ * Atomically apply a batch of attribute changes and append the `attr_set` event.
896
+ * Attributes live in a hash of their own, not in the run JSON, so two writers
897
+ * changing different keys never overwrite each other.
898
+ *
899
+ * KEYS[1] = run attributes key
900
+ * KEYS[2] = events key
901
+ * KEYS[3] = events by correlation key (or unused placeholder)
902
+ * KEYS[4] = run meta key
903
+ * ARGV[1] = event JSON
904
+ * ARGV[2] = has correlation ("1" or "0")
905
+ * ARGV[3] = "1" to refuse a repeat for this correlation id (a replayed write)
906
+ * ARGV[4..] = triples: attribute key, value, op ("set" or "del")
907
+ * Returns: [1, eventId], [-6, status] when the run is terminal, [-8, ''] when
908
+ * this correlation id already set attributes
909
+ */
910
+ const LUA_SET_ATTRIBUTES = `${LUA_APPEND_EVENT}
911
+ local status = runStatus(KEYS[4])
912
+ if status and isTerminal(status) then
913
+ return {-6, status}
914
+ end
915
+ if ARGV[3] == '1' and ARGV[2] == '1' and redis.call('ZCARD', KEYS[3]) > 0 then
916
+ return {${LUA_DUPLICATE_CREATION}, ''}
917
+ end
918
+ for i = 4, #ARGV, 3 do
919
+ if ARGV[i + 2] == 'del' then
920
+ redis.call('HDEL', KEYS[1], ARGV[i])
921
+ else
922
+ redis.call('HSET', KEYS[1], ARGV[i], ARGV[i + 1])
923
+ end
924
+ end
925
+ local correlationKey = nil
926
+ if ARGV[2] == '1' then
927
+ correlationKey = KEYS[3]
928
+ end
929
+ return {1, appendEvent(KEYS[2], correlationKey, ARGV[1])}
930
+ `;
931
+ /** Registered via `defineCommand` so ioredis dispatches with `EVALSHA` rather
932
+ * than shipping the script body every call. `LUA_STORE_EVENT` is ~1 KB and
933
+ * runs once per workflow event. */
934
+ const SCRIPTS = {
935
+ wfCreateRunWithEvent: {
936
+ numberOfKeys: 7,
937
+ lua: LUA_CREATE_RUN_WITH_EVENT
938
+ },
939
+ wfSetAttributes: {
940
+ numberOfKeys: 4,
941
+ lua: LUA_SET_ATTRIBUTES
942
+ },
943
+ wfTransitionRun: {
944
+ numberOfKeys: 7,
945
+ lua: LUA_TRANSITION_RUN
946
+ },
947
+ wfCreateStepWithEvent: {
948
+ numberOfKeys: 6,
949
+ lua: LUA_CREATE_STEP_WITH_EVENT
950
+ },
951
+ wfCreateStepStarted: {
952
+ numberOfKeys: 6,
953
+ lua: LUA_CREATE_STEP_STARTED
954
+ },
955
+ wfCreateHookWithEvent: {
956
+ numberOfKeys: 7,
957
+ lua: LUA_CREATE_HOOK_WITH_EVENT
958
+ },
959
+ wfDisposeHook: {
960
+ numberOfKeys: 6,
961
+ lua: LUA_DISPOSE_HOOK
962
+ },
963
+ wfStoreEvent: {
964
+ numberOfKeys: 7,
965
+ lua: LUA_STORE_EVENT
966
+ }
967
+ };
968
+ /** Clients that already have the scripts attached; every storage factory
969
+ * calls this with the same shared connection, so it must be idempotent. */
970
+ const scriptState = globalSingleton("@brickkit/redis-world//scripts", 1, () => ({ clients: /* @__PURE__ */ new WeakSet() }));
971
+ function withScripts(redis) {
972
+ if (!scriptState.clients.has(redis)) {
973
+ for (const [name, def] of Object.entries(SCRIPTS)) redis.defineCommand(name, {
974
+ numberOfKeys: def.numberOfKeys,
975
+ lua: def.lua
976
+ });
977
+ scriptState.clients.add(redis);
978
+ }
979
+ return redis;
980
+ }
981
+ /** Compact `<status>|<specVersion>` marker beside the run blob, so validation
982
+ * reads those two fields without transferring the run's input/output. */
983
+ function runMetaValue(status, specVersion) {
984
+ return `${status}|${specVersion ?? ""}`;
985
+ }
986
+ function parseRunMeta(value) {
987
+ const sep = value.indexOf("|");
988
+ if (sep === -1) return { status: value };
989
+ const version = value.slice(sep + 1);
990
+ return {
991
+ status: value.slice(0, sep),
992
+ specVersion: version === "" ? void 0 : Number(version)
993
+ };
994
+ }
995
+ /**
996
+ * Create storage for workflow runs using Redis hashes and sorted sets
997
+ */
998
+ function createRunsStorage(config) {
999
+ const { redis, keyPrefix } = config;
1000
+ const runKey = (id) => `${keyPrefix}run:${id}`;
1001
+ const runAttributesKey = (id) => `${keyPrefix}run:attrs:${id}`;
1002
+ const runsIndexKey = () => `${keyPrefix}runs:index`;
1003
+ const runsByNameKey = (name) => `${keyPrefix}runs:by_name:${name}`;
1004
+ const runsByStatusKey = (status) => `${keyPrefix}runs:by_status:${status}`;
1005
+ /** The statuses a list filter allows, or undefined for any. `status` takes one
1006
+ * status or an array; an empty array matches nothing, unlike omitting it. */
1007
+ function allowedStatuses(params) {
1008
+ const status = params?.status;
1009
+ if (status === void 0) return void 0;
1010
+ return Array.isArray(status) ? status : [status];
1011
+ }
1012
+ function selectIndexKeys(params) {
1013
+ if (params?.workflowName) return [runsByNameKey(params.workflowName)];
1014
+ const statuses = allowedStatuses(params);
1015
+ if (statuses) return statuses.map(runsByStatusKey);
1016
+ return [runsIndexKey()];
1017
+ }
1018
+ function parseRunsFromPipeline(results, params) {
1019
+ const runs = [];
1020
+ for (let i = 0; i + 1 < (results?.length ?? 0); i += 2) {
1021
+ const result = results[i];
1022
+ if (!result?.[1]) continue;
1023
+ const run = parseWithUint8Array(result[1]);
1024
+ run.attributes = results[i + 1]?.[1] ?? {};
1025
+ const statuses = allowedStatuses(params);
1026
+ const statusMatches = !statuses || statuses.includes(run.status);
1027
+ const nameMatches = !params?.workflowName || run.workflowName === params.workflowName;
1028
+ if (statusMatches && nameMatches) {
1029
+ const resolveData = params?.resolveData ?? "all";
1030
+ const parsed = WorkflowRunSchema.parse(compact(run));
1031
+ runs.push(filterRunData(parsed, resolveData));
1032
+ }
1033
+ }
1034
+ return runs;
1035
+ }
1036
+ return {
1037
+ get: (async (id, params) => {
1038
+ const replies = await redis.pipeline().get(runKey(id)).hgetall(runAttributesKey(id)).exec();
1039
+ const data = replies?.[0]?.[1];
1040
+ if (!data) throw new WorkflowRunNotFoundError(id);
1041
+ const run = parseWithUint8Array(data);
1042
+ run.attributes = replies?.[1]?.[1] ?? {};
1043
+ return filterRunData(WorkflowRunSchema.parse(compact(run)), params?.resolveData ?? "all");
1044
+ }),
1045
+ list: (async (params) => {
1046
+ const limit = params?.pagination?.limit ?? 20;
1047
+ const fromCursor = params?.pagination?.cursor;
1048
+ if (allowedStatuses(params)?.length === 0) return {
1049
+ data: [],
1050
+ hasMore: false,
1051
+ cursor: null
1052
+ };
1053
+ const indexKeys = selectIndexKeys(params);
1054
+ const order = params?.pagination?.sortOrder ?? "desc";
1055
+ const runs = [];
1056
+ let scanFrom = fromCursor;
1057
+ while (runs.length <= limit) {
1058
+ const entries = await pageIndex(redis, indexKeys, scanFrom, limit + 1, order);
1059
+ if (entries.length === 0) break;
1060
+ const pipeline = redis.pipeline();
1061
+ for (const { id } of entries) {
1062
+ pipeline.get(runKey(id));
1063
+ pipeline.hgetall(runAttributesKey(id));
1064
+ }
1065
+ const results = await pipeline.exec();
1066
+ const cursorOf = new Map(entries.map((entry) => [entry.id, entry.cursor]));
1067
+ for (const run of parseRunsFromPipeline(results, params)) runs.push({
1068
+ run,
1069
+ cursor: cursorOf.get(run.runId)
1070
+ });
1071
+ if (entries.length < limit + 1) break;
1072
+ scanFrom = entries.at(-1).cursor;
1073
+ }
1074
+ const values = runs.slice(0, limit);
1075
+ const hasMore = runs.length > limit;
1076
+ return {
1077
+ data: values.map((entry) => entry.run),
1078
+ hasMore,
1079
+ cursor: values.at(-1)?.cursor ?? null
1080
+ };
1081
+ })
1082
+ };
1083
+ }
1084
+ /**
1085
+ * Create storage for workflow events using Redis hashes and sorted sets.
1086
+ *
1087
+ * A run's log is one hash (`eventId -> JSON`). Event ids are log positions, so
1088
+ * the log is dense and 1-based, and every script that appends to it picks the
1089
+ * next position itself, atomically with the write (see `LUA_APPEND_EVENT`).
1090
+ */
1091
+ function createEventsStorage(config) {
1092
+ const { redis, keyPrefix } = config;
1093
+ const scripts = withScripts(redis);
1094
+ const ulid = monotonicFactory();
1095
+ const maxEventsPerRun = resolveMaxEventsPerRun(config.maxEventsPerRun);
1096
+ const eventsKey = (runId) => `${keyPrefix}events:data:${runId}`;
1097
+ const eventsByCorrelationKey = (runId, correlationId) => `${keyPrefix}events:by_correlation:${runId}:${correlationId}`;
1098
+ const resumeClaimKey = (runId, resumeId) => `${keyPrefix}events:resume:${runId}:${resumeId}`;
1099
+ const runKey = (id) => `${keyPrefix}run:${id}`;
1100
+ const runAttributesKey = (id) => `${keyPrefix}run:attrs:${id}`;
1101
+ const runMetaKey = (id) => `${keyPrefix}run:meta:${id}`;
1102
+ const runsIndexKey = () => `${keyPrefix}runs:index`;
1103
+ const runsByNameKey = (name) => `${keyPrefix}runs:by_name:${name}`;
1104
+ const runsByStatusKey = (status) => `${keyPrefix}runs:by_status:${status}`;
1105
+ const stepKey = (runId, stepId) => `${keyPrefix}step:${runId}:${stepId}`;
1106
+ const stepsIndexKey = (runId) => `${keyPrefix}steps:by_run:${runId}`;
1107
+ const stepStatusKey = (runId, stepId) => `${keyPrefix}step:status:${runId}:${stepId}`;
1108
+ const hookKey = (hookId) => `${keyPrefix}hook:${hookId}`;
1109
+ const hooksByTokenKey = (token) => `${keyPrefix}hooks:by_token:${token}`;
1110
+ const hooksIndexKey = (runId) => `${keyPrefix}hooks:by_run:${runId}`;
1111
+ const hooksTokenMapKey = (runId) => `${keyPrefix}hooks:tokens:${runId}`;
1112
+ /** Events per `HMGET`; keeps a long log from building one huge command. */
1113
+ const READ_CHUNK = 500;
1114
+ /** The most events an inline delta or skipped-slot report carries; the
1115
+ * caller continues from the cursor (or reloads) when `hasMore` is set. */
1116
+ const MAX_INLINE_EVENTS = 200;
1117
+ /** A run with its current attributes, which live apart from the run body. */
1118
+ async function withAttributes(run) {
1119
+ const attributes = await redis.hgetall(runAttributesKey(run.runId));
1120
+ return {
1121
+ ...run,
1122
+ attributes
1123
+ };
1124
+ }
1125
+ /** `[key, value, ...]` for a script, from an attribute record. */
1126
+ const flattenAttributes = (attributes) => Object.entries(attributes ?? {}).flat();
1127
+ /** Serialize an event for a script: `eventId` first, holding the placeholder. */
1128
+ function serializeEvent(event) {
1129
+ const { eventId: _eventId, ...rest } = event;
1130
+ return stringifyWithUint8Array({
1131
+ eventId: EVENT_ID_PLACEHOLDER,
1132
+ ...rest
1133
+ });
1134
+ }
1135
+ /** Read events by id out of one run's log, skipping any that are absent. */
1136
+ async function readEvents(runId, eventIds) {
1137
+ const events = [];
1138
+ for (let i = 0; i < eventIds.length; i += READ_CHUNK) {
1139
+ const values = await redis.hmget(eventsKey(runId), ...eventIds.slice(i, i + READ_CHUNK));
1140
+ for (const value of values) if (value) events.push(EventSchema.parse(compact(parseWithUint8Array(value))));
1141
+ }
1142
+ return events;
1143
+ }
1144
+ /** Events at slots `from..to` inclusive, in slot order. */
1145
+ async function readSlots(runId, from, to) {
1146
+ const ids = [];
1147
+ for (let slot = Math.max(from, FIRST_EVENT_SLOT); slot <= to; slot++) ids.push(slotToEventId(slot));
1148
+ return readEvents(runId, ids);
1149
+ }
1150
+ /**
1151
+ * Move a run from `oldStatus` to `newStatus`, release its hooks when it
1152
+ * finishes, and append the lifecycle event: one script, so a crash or a racing
1153
+ * writer can never leave the status and the log disagreeing. `moved` means the
1154
+ * run was no longer in `oldStatus` by the time the script ran, and nothing was
1155
+ * written.
1156
+ */
1157
+ async function transitionRun(runId, oldStatus, newStatus, updatedRun, at, event, releaseHooks) {
1158
+ const result = await scripts.wfTransitionRun(runKey(runId), runsByStatusKey(oldStatus), runsByStatusKey(newStatus), runMetaKey(runId), eventsKey(runId), hooksIndexKey(runId), hooksTokenMapKey(runId), stringifyWithUint8Array(updatedRun), runId, at.getTime().toString(), runMetaValue(newStatus, updatedRun.specVersion), oldStatus, serializeEvent(event), releaseHooks ? "1" : "0", `${keyPrefix}hook:`, `${keyPrefix}hooks:by_token:`);
1159
+ if (result[0] === 1) return {
1160
+ kind: "ok",
1161
+ eventId: result[1]
1162
+ };
1163
+ if (result[0] === -2) return {
1164
+ kind: "moved",
1165
+ status: result[1]
1166
+ };
1167
+ return { kind: "absent" };
1168
+ }
1169
+ /** Append an event whose id the script picks. Returns the stored event. */
1170
+ async function appendEvent(runId, event, options = {}) {
1171
+ const correlationId = event.correlationId;
1172
+ const result = await scripts.wfStoreEvent(eventsKey(runId), correlationId ? eventsByCorrelationKey(runId, correlationId) : "__unused__", options.entityKey ?? "__unused__", options.resume ? resumeClaimKey(runId, options.resume.id) : "__unused__", options.step?.key ?? "__unused__", options.runMustBeLive ? runMetaKey(runId) : "__unused__", options.hookMustExist && correlationId ? hookKey(correlationId) : "__unused__", serializeEvent(event), correlationId ? "1" : "0", options.dedup === "creation" ? "1" : options.dedup === "completion" ? "2" : "0", options.entityJson ?? "", options.resume?.claim ?? "", options.step?.status ?? "", options.step?.expectedAttempt === void 0 ? "" : String(options.step.expectedAttempt), options.step?.newAttempt === void 0 ? "" : String(options.step.newAttempt), options.runMustBeLive ? "1" : "0", options.hookMustExist ? "1" : "0");
1173
+ switch (result[0]) {
1174
+ case LUA_DUPLICATE_CREATION: return { kind: "duplicate" };
1175
+ case -7: return { kind: "alreadyCompleted" };
1176
+ case -3: return {
1177
+ kind: "stepTerminal",
1178
+ status: result[1]
1179
+ };
1180
+ case -4: return {
1181
+ kind: "stepMoved",
1182
+ attempt: result[1]
1183
+ };
1184
+ case -5: return { kind: "hookGone" };
1185
+ case -6: return {
1186
+ kind: "runTerminal",
1187
+ status: result[1]
1188
+ };
1189
+ case 3: return {
1190
+ kind: "claimed",
1191
+ claim: result[1]
1192
+ };
1193
+ default: return {
1194
+ kind: "stored",
1195
+ event: EventSchema.parse({
1196
+ ...event,
1197
+ eventId: result[1]
1198
+ })
1199
+ };
1200
+ }
1201
+ }
1202
+ /** The events a bumped write skipped over: those between the slot the writer
1203
+ * asked for (`eventCount + 1`) and the one it landed on. */
1204
+ async function reportSkippedSlots(result, askedFor, resolveData) {
1205
+ if (!result.event) return result;
1206
+ const committedSlot = eventIdToSlot(result.event.eventId);
1207
+ if (committedSlot === null || askedFor < 0 || committedSlot <= askedFor + 1) return result;
1208
+ const span = committedSlot - askedFor - 1;
1209
+ const upto = Math.min(committedSlot - 1, askedFor + MAX_INLINE_EVENTS);
1210
+ const skipped = await readSlots(result.event.runId, askedFor + 1, upto);
1211
+ return {
1212
+ ...result,
1213
+ events: skipped.map((event) => stripEventDataRefs(event, resolveData)),
1214
+ cursor: null,
1215
+ hasMore: skipped.length < span
1216
+ };
1217
+ }
1218
+ /** The inline delta: everything after `sinceCursor`, as `events.list` would
1219
+ * return it right after the write. */
1220
+ async function deltaSince(result, sinceCursor, resolveData) {
1221
+ if (!result.event) return result;
1222
+ const sinceSlot = eventIdToSlot(sinceCursor);
1223
+ if (sinceSlot === null) return result;
1224
+ const total = await redis.hlen(eventsKey(result.event.runId));
1225
+ const upto = Math.min(total, sinceSlot + MAX_INLINE_EVENTS);
1226
+ const page = await readSlots(result.event.runId, sinceSlot + 1, upto);
1227
+ return {
1228
+ ...result,
1229
+ events: page.map((event) => stripEventDataRefs(event, resolveData)),
1230
+ cursor: page.at(-1)?.eventId ?? sinceCursor,
1231
+ hasMore: upto < total
1232
+ };
1233
+ }
1234
+ const isTerminal = (status) => [
1235
+ "completed",
1236
+ "failed",
1237
+ "cancelled"
1238
+ ].includes(status);
1239
+ /** How many times a step write recomputes after losing a race for the step. */
1240
+ const MAX_STALE_RETRIES = 5;
1241
+ async function createEvent(runId, data, params, staleRetries = 0) {
1242
+ const now = /* @__PURE__ */ new Date();
1243
+ const resolveData = params?.resolveData ?? "all";
1244
+ const entityData = entityResolveData(resolveData);
1245
+ let effectiveRunId;
1246
+ if (data.eventType === "run_created" && (!runId || runId === "")) effectiveRunId = `wrun_${ulid()}`;
1247
+ else if (!runId) throw new Error("runId is required for non-run_created events");
1248
+ else effectiveRunId = runId;
1249
+ const effectiveSpecVersion = data.specVersion ?? mintedSpecVersion();
1250
+ const buildEvent = (overrides = {}) => ({
1251
+ ...data,
1252
+ runId: effectiveRunId,
1253
+ createdAt: /* @__PURE__ */ new Date(),
1254
+ specVersion: effectiveSpecVersion,
1255
+ ...overrides
1256
+ });
1257
+ let run;
1258
+ let step;
1259
+ let hook;
1260
+ let lifecycleEvent;
1261
+ let pendingEntityKey;
1262
+ let pendingEntityJson;
1263
+ let pendingStep;
1264
+ let currentRun = null;
1265
+ let existingRun = null;
1266
+ async function loadRunBody() {
1267
+ const runData = await redis.get(runKey(effectiveRunId));
1268
+ if (runData) {
1269
+ existingRun = parseWithUint8Array(runData);
1270
+ currentRun = {
1271
+ status: existingRun.status,
1272
+ specVersion: existingRun.specVersion
1273
+ };
1274
+ }
1275
+ }
1276
+ if (data.eventType !== "run_created" && !["step_completed", "step_retrying"].includes(data.eventType)) {
1277
+ if (RUN_LIFECYCLE_EVENT_TYPES.has(data.eventType)) await loadRunBody();
1278
+ else {
1279
+ const meta = await redis.get(runMetaKey(effectiveRunId));
1280
+ if (meta) currentRun = parseRunMeta(meta);
1281
+ }
1282
+ }
1283
+ if (data.eventType === "run_started" && !currentRun && "eventData" in data && data.eventData) {
1284
+ const runInputData = data.eventData;
1285
+ if (runInputData.deploymentId && runInputData.workflowName && runInputData.input !== void 0) {
1286
+ const seeds = runInputData.attributes ?? {};
1287
+ validateAttributeChanges(Object.entries(seeds).map(([key, value]) => ({
1288
+ key,
1289
+ value
1290
+ })), { allowReservedAttributes: runInputData.allowReservedAttributes === true });
1291
+ const newRun = {
1292
+ runId: effectiveRunId,
1293
+ deploymentId: runInputData.deploymentId,
1294
+ workflowName: runInputData.workflowName,
1295
+ specVersion: effectiveSpecVersion,
1296
+ input: runInputData.input,
1297
+ executionContext: runInputData.executionContext,
1298
+ ...runInputData.encryptionPublicKey && { encryptionPublicKey: runInputData.encryptionPublicKey },
1299
+ ...runInputData.dynamicWorkflowCode !== void 0 && { dynamicWorkflowCode: runInputData.dynamicWorkflowCode },
1300
+ status: "pending",
1301
+ output: void 0,
1302
+ error: void 0,
1303
+ completedAt: void 0,
1304
+ startedAt: void 0,
1305
+ createdAt: now,
1306
+ updatedAt: now
1307
+ };
1308
+ const result = await scripts.wfCreateRunWithEvent(runKey(effectiveRunId), runsIndexKey(), runsByNameKey(runInputData.workflowName), runsByStatusKey("pending"), runMetaKey(effectiveRunId), eventsKey(effectiveRunId), runAttributesKey(effectiveRunId), stringifyWithUint8Array(newRun), effectiveRunId, now.getTime().toString(), runMetaValue("pending", effectiveSpecVersion), serializeEvent({
1309
+ eventType: "run_created",
1310
+ eventData: {
1311
+ deploymentId: runInputData.deploymentId,
1312
+ workflowName: runInputData.workflowName,
1313
+ input: runInputData.input,
1314
+ executionContext: runInputData.executionContext,
1315
+ ...runInputData.attributes && { attributes: runInputData.attributes },
1316
+ ...runInputData.allowReservedAttributes && { allowReservedAttributes: true },
1317
+ ...runInputData.encryptionPublicKey && { encryptionPublicKey: runInputData.encryptionPublicKey }
1318
+ },
1319
+ runId: effectiveRunId,
1320
+ createdAt: now,
1321
+ specVersion: effectiveSpecVersion
1322
+ }), ...flattenAttributes(seeds));
1323
+ if (result[0] === 1) {
1324
+ currentRun = {
1325
+ status: "pending",
1326
+ specVersion: effectiveSpecVersion
1327
+ };
1328
+ existingRun = newRun;
1329
+ } else {
1330
+ const parsed = parseWithUint8Array(result[1]);
1331
+ currentRun = {
1332
+ status: parsed.status,
1333
+ specVersion: parsed.specVersion
1334
+ };
1335
+ existingRun = parsed;
1336
+ }
1337
+ }
1338
+ }
1339
+ if (currentRun) {
1340
+ if (requiresNewerWorld(currentRun.specVersion)) throw new RunNotSupportedError(currentRun.specVersion, mintedSpecVersion());
1341
+ if (isLegacySpecVersion(currentRun.specVersion)) throw new RunNotSupportedError(currentRun.specVersion, mintedSpecVersion());
1342
+ }
1343
+ if (currentRun && isTerminal(currentRun.status)) {
1344
+ const terminalStatus = currentRun.status;
1345
+ const runTerminalEvents = [
1346
+ "run_started",
1347
+ "run_completed",
1348
+ "run_failed"
1349
+ ];
1350
+ if (data.eventType === "run_cancelled" && terminalStatus === "cancelled") {
1351
+ const stored = await appendEvent(effectiveRunId, buildEvent());
1352
+ if (stored.kind !== "stored") throw new EntityConflictError("Duplicate run_cancelled");
1353
+ return {
1354
+ event: stripEventDataRefs(stored.event, entityData),
1355
+ run: existingRun ? await withAttributes(WorkflowRunSchema.parse(compact(existingRun))) : void 0
1356
+ };
1357
+ }
1358
+ if (data.eventType === "run_started") throw new RunExpiredError(`Workflow run "${effectiveRunId}" is already in terminal state "${terminalStatus}"`);
1359
+ if (data.eventType === "step_started") throw new RunExpiredError(`Cannot start step on run in terminal state "${terminalStatus}"`);
1360
+ if (runTerminalEvents.includes(data.eventType) || data.eventType === "run_cancelled") throw new EntityConflictError(`Cannot transition run from terminal state "${terminalStatus}"`);
1361
+ if (data.eventType === "step_created" || data.eventType === "hook_created" || data.eventType === "wait_created") throw new EntityConflictError(`Cannot create new entities on run in terminal state "${terminalStatus}"`);
1362
+ }
1363
+ let validatedStep = null;
1364
+ const lazyStepStart = data.eventType === "step_started" && typeof data.eventData?.stepName === "string" && data.eventData?.input !== void 0;
1365
+ if (["step_started", "step_retrying"].includes(data.eventType) && data.correlationId) {
1366
+ const stepData = await redis.get(stepKey(effectiveRunId, data.correlationId));
1367
+ if (stepData) validatedStep = parseWithUint8Array(stepData);
1368
+ if (!validatedStep && !lazyStepStart) throw new WorkflowWorldError(`Step "${data.correlationId}" not found`, { status: 404 });
1369
+ if (lazyStepStart && validatedStep) throw new EntityConflictError(`Step "${data.correlationId}" already created`);
1370
+ if (validatedStep) {
1371
+ if (isTerminal(validatedStep.status)) throw new EntityConflictError(`Cannot modify step in terminal state "${validatedStep.status}"`);
1372
+ if (currentRun && isTerminal(currentRun.status)) {
1373
+ if (validatedStep.status !== "running") throw new RunExpiredError(`Cannot modify non-running step on run in terminal state "${currentRun.status}"`);
1374
+ }
1375
+ }
1376
+ }
1377
+ let validatedHook = null;
1378
+ const hookEventsRequiringExistence = ["hook_disposed", "hook_received"];
1379
+ const isResumeRetryCandidate = data.eventType === "hook_received" && params?.resumeId;
1380
+ if (hookEventsRequiringExistence.includes(data.eventType) && data.correlationId && !isResumeRetryCandidate) {
1381
+ const existingHook = await redis.get(hookKey(data.correlationId));
1382
+ if (!existingHook) throw new HookNotFoundError(data.correlationId);
1383
+ validatedHook = parseWithUint8Array(existingHook);
1384
+ }
1385
+ if (data.eventType === "run_created") {
1386
+ const eventData = data.eventData;
1387
+ if (eventData.dynamicWorkflowCodeRef !== void 0) throw new WorkflowWorldError("dynamicWorkflowCodeRef is not supported by this world", { status: 501 });
1388
+ const seeds = eventData.attributes ?? {};
1389
+ validateAttributeChanges(Object.entries(seeds).map(([key, value]) => ({
1390
+ key,
1391
+ value
1392
+ })), { allowReservedAttributes: eventData.allowReservedAttributes === true });
1393
+ const newRun = {
1394
+ runId: effectiveRunId,
1395
+ deploymentId: eventData.deploymentId,
1396
+ workflowName: eventData.workflowName,
1397
+ specVersion: effectiveSpecVersion,
1398
+ input: eventData.input,
1399
+ executionContext: eventData.executionContext,
1400
+ ...eventData.encryptionPublicKey && { encryptionPublicKey: eventData.encryptionPublicKey },
1401
+ ...eventData.dynamicWorkflowCode !== void 0 && { dynamicWorkflowCode: eventData.dynamicWorkflowCode },
1402
+ status: "pending",
1403
+ output: void 0,
1404
+ error: void 0,
1405
+ completedAt: void 0,
1406
+ startedAt: void 0,
1407
+ createdAt: now,
1408
+ updatedAt: now
1409
+ };
1410
+ const event = buildEvent({ createdAt: now });
1411
+ const result = await scripts.wfCreateRunWithEvent(runKey(effectiveRunId), runsIndexKey(), runsByNameKey(eventData.workflowName), runsByStatusKey("pending"), runMetaKey(effectiveRunId), eventsKey(effectiveRunId), runAttributesKey(effectiveRunId), stringifyWithUint8Array(newRun), effectiveRunId, now.getTime().toString(), runMetaValue("pending", effectiveSpecVersion), serializeEvent(event), ...flattenAttributes(seeds));
1412
+ if (result[0] === 0) throw new EntityConflictError(`Workflow run "${effectiveRunId}" already exists`);
1413
+ run = WorkflowRunSchema.parse({
1414
+ ...compact(newRun),
1415
+ attributes: seeds
1416
+ });
1417
+ const parsed = EventSchema.parse({
1418
+ ...event,
1419
+ eventId: result[1]
1420
+ });
1421
+ return {
1422
+ event: stripEventDataRefs(parsed, entityData),
1423
+ run,
1424
+ maxEvents: maxEventsPerRun
1425
+ };
1426
+ }
1427
+ if (data.eventType === "run_started") {
1428
+ const resumeResponse = async (current) => {
1429
+ const resumed = current ? await withAttributes(WorkflowRunSchema.parse(compact(current))) : void 0;
1430
+ return {
1431
+ run: resumed ? filterRunData(resumed, entityData) : void 0,
1432
+ ...resumed ? { maxEvents: maxEventsPerRun } : {}
1433
+ };
1434
+ };
1435
+ if (currentRun?.status === "running") return resumeResponse(existingRun);
1436
+ if (!existingRun) throw new WorkflowRunNotFoundError(effectiveRunId);
1437
+ const existing = existingRun;
1438
+ const updatedRun = {
1439
+ ...existing,
1440
+ status: "running",
1441
+ startedAt: now,
1442
+ updatedAt: now
1443
+ };
1444
+ const { eventData: _startData, ...startEvent } = buildEvent({ createdAt: now });
1445
+ const moved = await transitionRun(effectiveRunId, existing.status, "running", updatedRun, now, startEvent, false);
1446
+ if (moved.kind === "absent") throw new WorkflowRunNotFoundError(effectiveRunId);
1447
+ if (moved.kind === "moved") {
1448
+ if (isTerminal(moved.status)) throw new RunExpiredError(`Workflow run "${effectiveRunId}" is already in terminal state "${moved.status}"`);
1449
+ await loadRunBody();
1450
+ return resumeResponse(existingRun);
1451
+ }
1452
+ run = WorkflowRunSchema.parse(compact(updatedRun));
1453
+ lifecycleEvent = EventSchema.parse({
1454
+ ...startEvent,
1455
+ eventId: moved.eventId
1456
+ });
1457
+ }
1458
+ if (data.eventType === "run_completed" || data.eventType === "run_failed" || data.eventType === "run_cancelled") {
1459
+ if (!existingRun) throw new WorkflowRunNotFoundError(effectiveRunId);
1460
+ const existing = existingRun;
1461
+ let updatedRun;
1462
+ let newStatus;
1463
+ if (data.eventType === "run_completed") {
1464
+ const eventData = data.eventData;
1465
+ newStatus = "completed";
1466
+ updatedRun = {
1467
+ ...existing,
1468
+ status: "completed",
1469
+ output: eventData.output,
1470
+ completedAt: now,
1471
+ updatedAt: now
1472
+ };
1473
+ } else if (data.eventType === "run_failed") {
1474
+ const eventData = data.eventData;
1475
+ newStatus = "failed";
1476
+ updatedRun = {
1477
+ ...existing,
1478
+ status: "failed",
1479
+ error: eventData.error,
1480
+ errorCode: eventData.errorCode,
1481
+ completedAt: now,
1482
+ updatedAt: now
1483
+ };
1484
+ } else {
1485
+ newStatus = "cancelled";
1486
+ updatedRun = {
1487
+ ...existing,
1488
+ status: "cancelled",
1489
+ completedAt: now,
1490
+ updatedAt: now
1491
+ };
1492
+ }
1493
+ const terminalEvent = buildEvent({ createdAt: now });
1494
+ const moved = await transitionRun(effectiveRunId, existing.status, newStatus, updatedRun, now, terminalEvent, true);
1495
+ if (moved.kind === "absent") throw new WorkflowRunNotFoundError(effectiveRunId);
1496
+ if (moved.kind === "moved") throw new EntityConflictError(`Cannot transition run "${effectiveRunId}" to "${newStatus}": it already left "${existing.status}" for "${moved.status}"`);
1497
+ run = WorkflowRunSchema.parse(compact(updatedRun));
1498
+ lifecycleEvent = EventSchema.parse({
1499
+ ...terminalEvent,
1500
+ eventId: moved.eventId
1501
+ });
1502
+ }
1503
+ if (data.eventType === "step_created") {
1504
+ const eventData = data.eventData;
1505
+ const newStep = {
1506
+ runId: effectiveRunId,
1507
+ stepId: data.correlationId,
1508
+ stepName: eventData.stepName,
1509
+ input: eventData.input,
1510
+ status: "pending",
1511
+ attempt: 0,
1512
+ specVersion: effectiveSpecVersion,
1513
+ createdAt: now,
1514
+ updatedAt: now
1515
+ };
1516
+ const event = buildEvent({ createdAt: now });
1517
+ const result = await scripts.wfCreateStepWithEvent(stepKey(effectiveRunId, data.correlationId), stepsIndexKey(effectiveRunId), eventsKey(effectiveRunId), eventsByCorrelationKey(effectiveRunId, data.correlationId), stepStatusKey(effectiveRunId, data.correlationId), runMetaKey(effectiveRunId), stringifyWithUint8Array(newStep), data.correlationId, now.getTime().toString(), serializeEvent(event), "pending|0");
1518
+ if (result[0] === -6) throw new EntityConflictError(`Cannot create new entities on run in terminal state "${result[1]}"`);
1519
+ if (result[0] === 0) throw new EntityConflictError(`Step "${data.correlationId}" already exists`);
1520
+ step = StepSchema.parse(compact(newStep));
1521
+ const parsed = EventSchema.parse({
1522
+ ...event,
1523
+ eventId: result[1]
1524
+ });
1525
+ return {
1526
+ event: stripEventDataRefs(parsed, entityData),
1527
+ step
1528
+ };
1529
+ }
1530
+ const dedup = data.eventType === "wait_created" ? "creation" : data.eventType === "wait_completed" ? "completion" : void 0;
1531
+ if (data.eventType === "step_started") {
1532
+ if (validatedStep?.retryAfter && validatedStep.retryAfter.getTime() > Date.now()) throw new TooEarlyError(`Cannot start step "${data.correlationId}": retryAfter timestamp has not been reached yet`, { retryAfter: Math.ceil((validatedStep.retryAfter.getTime() - Date.now()) / 1e3) });
1533
+ if (lazyStepStart) {
1534
+ const lazyData = data.eventData;
1535
+ const startedStep = {
1536
+ runId: effectiveRunId,
1537
+ stepId: data.correlationId,
1538
+ stepName: lazyData.stepName,
1539
+ input: lazyData.input,
1540
+ status: "running",
1541
+ attempt: 1,
1542
+ startedAt: now,
1543
+ specVersion: effectiveSpecVersion,
1544
+ createdAt: now,
1545
+ updatedAt: now
1546
+ };
1547
+ const { input: _input, ...startedEventData } = lazyData;
1548
+ const createdEvent = {
1549
+ eventType: "step_created",
1550
+ correlationId: data.correlationId,
1551
+ runId: effectiveRunId,
1552
+ createdAt: now,
1553
+ specVersion: effectiveSpecVersion,
1554
+ eventData: {
1555
+ stepName: lazyData.stepName,
1556
+ ...lazyData.workflowName !== void 0 && { workflowName: lazyData.workflowName },
1557
+ input: lazyData.input
1558
+ }
1559
+ };
1560
+ const startedEvent = buildEvent({
1561
+ createdAt: now,
1562
+ eventData: startedEventData
1563
+ });
1564
+ const result = await scripts.wfCreateStepStarted(stepKey(effectiveRunId, data.correlationId), stepsIndexKey(effectiveRunId), eventsKey(effectiveRunId), eventsByCorrelationKey(effectiveRunId, data.correlationId), stepStatusKey(effectiveRunId, data.correlationId), runMetaKey(effectiveRunId), stringifyWithUint8Array(startedStep), data.correlationId, now.getTime().toString(), serializeEvent(createdEvent), serializeEvent(startedEvent), "running|1");
1565
+ if (result[0] === -6) throw new RunExpiredError(`Cannot start step on run in terminal state "${result[1]}"`);
1566
+ if (result[0] === 0) throw new EntityConflictError(`Step "${data.correlationId}" already created`);
1567
+ step = StepSchema.parse(compact(startedStep));
1568
+ const parsed = EventSchema.parse({
1569
+ ...startedEvent,
1570
+ eventId: result[2]
1571
+ });
1572
+ return {
1573
+ event: stripEventDataRefs(parsed, entityData),
1574
+ step,
1575
+ stepCreated: true
1576
+ };
1577
+ }
1578
+ const isFirstStart = !validatedStep?.startedAt;
1579
+ const existing = validatedStep;
1580
+ if (existing) {
1581
+ const updatedStep = {
1582
+ ...existing,
1583
+ status: "running",
1584
+ attempt: existing.attempt + 1,
1585
+ ...isFirstStart ? { startedAt: now } : {},
1586
+ retryAfter: void 0,
1587
+ updatedAt: now
1588
+ };
1589
+ pendingEntityKey = stepKey(effectiveRunId, data.correlationId);
1590
+ pendingEntityJson = stringifyWithUint8Array(updatedStep);
1591
+ pendingStep = {
1592
+ key: stepStatusKey(effectiveRunId, data.correlationId),
1593
+ status: "running",
1594
+ expectedAttempt: existing.attempt,
1595
+ newAttempt: updatedStep.attempt
1596
+ };
1597
+ step = StepSchema.parse(compact(updatedStep));
1598
+ }
1599
+ }
1600
+ if (data.eventType === "step_completed") {
1601
+ const eventData = data.eventData;
1602
+ const existingData = await redis.get(stepKey(effectiveRunId, data.correlationId));
1603
+ if (existingData) {
1604
+ const existing = parseWithUint8Array(existingData);
1605
+ if (isTerminal(existing.status)) throw new EntityConflictError(`Cannot modify step in terminal state "${existing.status}"`);
1606
+ const updatedStep = {
1607
+ ...existing,
1608
+ status: "completed",
1609
+ output: eventData.result,
1610
+ completedAt: now,
1611
+ updatedAt: now
1612
+ };
1613
+ pendingEntityKey = stepKey(effectiveRunId, data.correlationId);
1614
+ pendingEntityJson = stringifyWithUint8Array(updatedStep);
1615
+ pendingStep = {
1616
+ key: stepStatusKey(effectiveRunId, data.correlationId),
1617
+ status: "completed",
1618
+ expectedAttempt: existing.attempt
1619
+ };
1620
+ step = StepSchema.parse(compact(updatedStep));
1621
+ } else throw new WorkflowWorldError(`Step "${data.correlationId}" not found`, { status: 404 });
1622
+ }
1623
+ if (data.eventType === "step_failed") {
1624
+ const eventData = data.eventData;
1625
+ const existingData = await redis.get(stepKey(effectiveRunId, data.correlationId));
1626
+ if (existingData) {
1627
+ const existing = parseWithUint8Array(existingData);
1628
+ if (isTerminal(existing.status)) throw new EntityConflictError(`Cannot modify step in terminal state "${existing.status}"`);
1629
+ const updatedStep = {
1630
+ ...existing,
1631
+ status: "failed",
1632
+ error: eventData.error,
1633
+ completedAt: now,
1634
+ updatedAt: now
1635
+ };
1636
+ pendingEntityKey = stepKey(effectiveRunId, data.correlationId);
1637
+ pendingEntityJson = stringifyWithUint8Array(updatedStep);
1638
+ pendingStep = {
1639
+ key: stepStatusKey(effectiveRunId, data.correlationId),
1640
+ status: "failed",
1641
+ expectedAttempt: existing.attempt
1642
+ };
1643
+ step = StepSchema.parse(compact(updatedStep));
1644
+ } else throw new WorkflowWorldError(`Step "${data.correlationId}" not found`, { status: 404 });
1645
+ }
1646
+ if (data.eventType === "step_retrying") {
1647
+ const eventData = data.eventData;
1648
+ const existing = validatedStep;
1649
+ if (existing) {
1650
+ const updatedStep = {
1651
+ ...existing,
1652
+ status: "pending",
1653
+ error: eventData.error,
1654
+ retryAfter: eventData.retryAfter,
1655
+ updatedAt: now
1656
+ };
1657
+ pendingEntityKey = stepKey(effectiveRunId, data.correlationId);
1658
+ pendingEntityJson = stringifyWithUint8Array(updatedStep);
1659
+ pendingStep = {
1660
+ key: stepStatusKey(effectiveRunId, data.correlationId),
1661
+ status: "pending",
1662
+ expectedAttempt: existing.attempt
1663
+ };
1664
+ step = StepSchema.parse(compact(updatedStep));
1665
+ }
1666
+ }
1667
+ if (data.eventType === "hook_created") {
1668
+ const eventData = data.eventData;
1669
+ const newHook = {
1670
+ runId: effectiveRunId,
1671
+ hookId: data.correlationId,
1672
+ token: eventData.token,
1673
+ ownerId: "",
1674
+ projectId: "",
1675
+ environment: "",
1676
+ metadata: eventData.metadata,
1677
+ specVersion: effectiveSpecVersion,
1678
+ createdAt: now,
1679
+ ...eventData.isWebhook !== void 0 && { isWebhook: eventData.isWebhook },
1680
+ ...eventData.isSystem !== void 0 && { isSystem: eventData.isSystem }
1681
+ };
1682
+ const event = buildEvent({ createdAt: now });
1683
+ const result = await scripts.wfCreateHookWithEvent(hookKey(data.correlationId), hooksByTokenKey(eventData.token), hooksIndexKey(effectiveRunId), hooksTokenMapKey(effectiveRunId), eventsKey(effectiveRunId), eventsByCorrelationKey(effectiveRunId, data.correlationId), runMetaKey(effectiveRunId), stringifyWithUint8Array(newHook), data.correlationId, now.getTime().toString(), eventData.token, serializeEvent(event), `${keyPrefix}hook:`);
1684
+ if (result[0] === -6) throw new EntityConflictError(`Cannot create new entities on run in terminal state "${result[1]}"`);
1685
+ if (result[0] === 2) {
1686
+ const owningHookId = result[1];
1687
+ let conflictingRunId;
1688
+ const owningHookData = await redis.get(hookKey(owningHookId));
1689
+ if (owningHookData) conflictingRunId = parseWithUint8Array(owningHookData).runId;
1690
+ const stored = await appendEvent(effectiveRunId, {
1691
+ eventType: "hook_conflict",
1692
+ correlationId: data.correlationId,
1693
+ eventData: {
1694
+ token: eventData.token,
1695
+ ...conflictingRunId ? { conflictingRunId } : {}
1696
+ },
1697
+ runId: effectiveRunId,
1698
+ createdAt: now,
1699
+ specVersion: effectiveSpecVersion
1700
+ }, {
1701
+ dedup: "creation",
1702
+ runMustBeLive: true
1703
+ });
1704
+ if (stored.kind === "runTerminal") throw new EntityConflictError(`Cannot create new entities on run in terminal state "${stored.status}"`);
1705
+ if (stored.kind !== "stored") throw new EntityConflictError(`Hook "${data.correlationId}" conflict already recorded`);
1706
+ return {
1707
+ event: stripEventDataRefs(stored.event, entityData),
1708
+ run,
1709
+ step,
1710
+ hook: void 0
1711
+ };
1712
+ }
1713
+ if (result[0] === 0) throw new EntityConflictError(`Hook "${data.correlationId}" already created`);
1714
+ hook = HookSchema.parse(compact(newHook));
1715
+ const parsed = EventSchema.parse({
1716
+ ...event,
1717
+ eventId: result[1]
1718
+ });
1719
+ return {
1720
+ event: stripEventDataRefs(parsed, entityData),
1721
+ hook
1722
+ };
1723
+ }
1724
+ if (data.eventType === "hook_disposed" && data.correlationId) {
1725
+ if (!validatedHook) throw new EntityConflictError(`Hook "${data.correlationId}" already disposed`);
1726
+ const event = buildEvent();
1727
+ const result = await scripts.wfDisposeHook(hookKey(data.correlationId), hooksByTokenKey(validatedHook.token), hooksIndexKey(effectiveRunId), hooksTokenMapKey(effectiveRunId), eventsKey(effectiveRunId), eventsByCorrelationKey(effectiveRunId, data.correlationId), data.correlationId, serializeEvent(event));
1728
+ if (result[0] === 0) throw new EntityConflictError(`Hook "${data.correlationId}" already disposed`);
1729
+ const parsed = EventSchema.parse({
1730
+ ...event,
1731
+ eventId: result[1]
1732
+ });
1733
+ return { event: stripEventDataRefs(parsed, entityData) };
1734
+ }
1735
+ if (data.eventType === "attr_set") {
1736
+ if (!currentRun) throw new WorkflowRunNotFoundError(effectiveRunId);
1737
+ const eventData = data.eventData;
1738
+ validateAttributeChanges(eventData.changes, {
1739
+ existingKeys: await redis.hkeys(runAttributesKey(effectiveRunId)),
1740
+ allowReservedAttributes: eventData.allowReservedAttributes === true
1741
+ });
1742
+ const event = buildEvent();
1743
+ const correlationId = data.correlationId;
1744
+ const result = await scripts.wfSetAttributes(runAttributesKey(effectiveRunId), eventsKey(effectiveRunId), correlationId ? eventsByCorrelationKey(effectiveRunId, correlationId) : "__unused__", runMetaKey(effectiveRunId), serializeEvent(event), correlationId ? "1" : "0", data.eventData?.writer?.type === "workflow" ? "1" : "0", ...eventData.changes.flatMap((change) => [
1745
+ change.key,
1746
+ change.value ?? "",
1747
+ change.value === null ? "del" : "set"
1748
+ ]));
1749
+ if (result[0] === -6) throw new EntityConflictError(`Cannot set attributes on run in terminal state "${result[1]}"`);
1750
+ if (result[0] === LUA_DUPLICATE_CREATION) throw new EntityConflictError(`attr_set for correlationId "${correlationId}" already exists in run "${effectiveRunId}"`);
1751
+ await loadRunBody();
1752
+ return {
1753
+ event: stripEventDataRefs(EventSchema.parse({
1754
+ ...event,
1755
+ eventId: result[1]
1756
+ }), entityData),
1757
+ run: existingRun ? await withAttributes(WorkflowRunSchema.parse(compact(existingRun))) : void 0
1758
+ };
1759
+ }
1760
+ const resume = data.eventType === "hook_received" && params?.resumeId ? {
1761
+ id: params.resumeId,
1762
+ claim: `${params.resumePayloadDigest ?? ""}|${data.correlationId}`
1763
+ } : void 0;
1764
+ const stored = lifecycleEvent ? {
1765
+ kind: "stored",
1766
+ event: lifecycleEvent
1767
+ } : await appendEvent(effectiveRunId, buildEvent(), {
1768
+ entityKey: pendingEntityKey,
1769
+ entityJson: pendingEntityJson,
1770
+ dedup,
1771
+ resume,
1772
+ step: pendingStep,
1773
+ runMustBeLive: data.eventType === "hook_received" || data.eventType === "wait_created" || data.eventType === "step_started",
1774
+ hookMustExist: data.eventType === "hook_received"
1775
+ });
1776
+ if (stored.kind === "duplicate") throw new EntityConflictError(`"${data.correlationId}" already exists`);
1777
+ if (stored.kind === "alreadyCompleted") throw new EntityConflictError(`Wait "${data.correlationId}" already completed`);
1778
+ if (stored.kind === "stepTerminal") throw new EntityConflictError(`Cannot modify step in terminal state "${stored.status}"`);
1779
+ if (stored.kind === "stepMoved") {
1780
+ if (data.eventType !== "step_started" && staleRetries < MAX_STALE_RETRIES) return createEvent(runId, data, params, staleRetries + 1);
1781
+ throw new EntityConflictError(`Step "${data.correlationId}" was moved by another delivery (attempt ${stored.attempt})`);
1782
+ }
1783
+ if (stored.kind === "runTerminal") {
1784
+ if (data.eventType === "step_started") throw new RunExpiredError(`Cannot start step on run in terminal state "${stored.status}"`);
1785
+ throw new EntityConflictError(`Cannot add ${data.eventType} to run in terminal state "${stored.status}"`);
1786
+ }
1787
+ if (stored.kind === "hookGone") throw new HookNotFoundError(data.correlationId);
1788
+ if (stored.kind === "claimed") {
1789
+ const [claimedEventId, claimedDigest, claimedHookId] = stored.claim.split("|");
1790
+ if (claimedHookId !== data.correlationId) throw new EntityConflictError(`hook_received resumeId "${params.resumeId}" already recorded for a different hook`);
1791
+ if (params?.resumePayloadDigest && claimedDigest && claimedDigest !== params.resumePayloadDigest) throw new EntityConflictError(`hook_received resumeId "${params.resumeId}" already recorded with a different payload`);
1792
+ const [existingEvent] = await readEvents(effectiveRunId, [claimedEventId]);
1793
+ if (!existingEvent) throw new WorkflowWorldError(`Event not found: ${claimedEventId}`, { status: 404 });
1794
+ return { event: stripEventDataRefs(existingEvent, entityData) };
1795
+ }
1796
+ let preloaded;
1797
+ if (data.eventType === "run_started" && run && params?.skipPreload !== true) {
1798
+ const total = await redis.hlen(eventsKey(effectiveRunId));
1799
+ const all = await readSlots(effectiveRunId, FIRST_EVENT_SLOT, total);
1800
+ preloaded = {
1801
+ events: all.map((e) => stripEventDataRefs(e, resolveData)),
1802
+ cursor: all.at(-1)?.eventId ?? null,
1803
+ hasMore: false
1804
+ };
1805
+ }
1806
+ return {
1807
+ event: stripEventDataRefs(stored.event, entityData),
1808
+ run: run ? await withAttributes(run) : void 0,
1809
+ step,
1810
+ hook,
1811
+ ...preloaded,
1812
+ ...run ? { maxEvents: maxEventsPerRun } : {}
1813
+ };
1814
+ }
1815
+ return {
1816
+ create: (async (runId, data, params) => {
1817
+ const result = await createEvent(runId, data, params);
1818
+ if (!result.event || result.events !== void 0) return result;
1819
+ const resolveData = params?.resolveData ?? "all";
1820
+ if (typeof params?.sinceCursor === "string") return deltaSince(result, params.sinceCursor, resolveData);
1821
+ if (params?.eventCount !== void 0) return reportSkippedSlots(result, params.eventCount, resolveData);
1822
+ return result;
1823
+ }),
1824
+ async get(runId, eventId, params) {
1825
+ const data = await redis.hget(eventsKey(runId), eventId);
1826
+ if (!data) throw new WorkflowWorldError(`Event not found: ${eventId}`, { status: 404 });
1827
+ const event = EventSchema.parse(compact(parseWithUint8Array(data)));
1828
+ return stripEventDataRefs(event, params?.resolveData ?? "all");
1829
+ },
1830
+ async list(params) {
1831
+ const sortOrder = params.pagination?.sortOrder || "asc";
1832
+ const fromCursor = params.pagination?.cursor;
1833
+ const total = await redis.hlen(eventsKey(params.runId));
1834
+ const limit = params.pagination?.limit ?? Math.max(total, 1);
1835
+ let cursorSlot = null;
1836
+ if (fromCursor) {
1837
+ cursorSlot = eventIdToSlot(fromCursor);
1838
+ if (cursorSlot === null) throw new WorkflowWorldError(`Invalid pagination cursor "${fromCursor}"`, { status: 400 });
1839
+ }
1840
+ let events;
1841
+ let hasMore;
1842
+ if (sortOrder === "desc") {
1843
+ const last = cursorSlot === null ? total : Math.min(cursorSlot - 1, total);
1844
+ const first = Math.max(FIRST_EVENT_SLOT, last - limit + 1);
1845
+ events = (await readSlots(params.runId, first, last)).reverse();
1846
+ hasMore = first > FIRST_EVENT_SLOT;
1847
+ } else {
1848
+ const first = (cursorSlot ?? 0) + 1;
1849
+ const last = Math.min(total, first + limit - 1);
1850
+ events = await readSlots(params.runId, first, last);
1851
+ hasMore = last < total;
1852
+ }
1853
+ const resolveData = params.resolveData ?? "all";
1854
+ return {
1855
+ data: events.map((event) => stripEventDataRefs(event, resolveData)),
1856
+ cursor: events.at(-1)?.eventId ?? fromCursor ?? null,
1857
+ hasMore
1858
+ };
1859
+ },
1860
+ async listByCorrelationId(params) {
1861
+ const limit = params.pagination?.limit ?? 100;
1862
+ const sortOrder = params.pagination?.sortOrder || "asc";
1863
+ const fromCursor = params.pagination?.cursor;
1864
+ const indexKey = eventsByCorrelationKey(params.runId, params.correlationId);
1865
+ let ids;
1866
+ if (sortOrder === "desc") {
1867
+ const cursorSlot = fromCursor ? eventIdToSlot(fromCursor) : null;
1868
+ const max = cursorSlot === null ? "+inf" : `(${cursorSlot}`;
1869
+ ids = await redis.zrevrangebyscore(indexKey, max, "-inf", "LIMIT", 0, limit + 1);
1870
+ } else {
1871
+ const cursorSlot = fromCursor ? eventIdToSlot(fromCursor) : null;
1872
+ const min = cursorSlot === null ? "-inf" : `(${cursorSlot}`;
1873
+ ids = await redis.zrangebyscore(indexKey, min, "+inf", "LIMIT", 0, limit + 1);
1874
+ }
1875
+ const page = ids.slice(0, limit);
1876
+ const events = await readEvents(params.runId, page);
1877
+ const resolveData = params.resolveData ?? "all";
1878
+ return {
1879
+ data: events.map((event) => stripEventDataRefs(event, resolveData)),
1880
+ cursor: events.at(-1)?.eventId ?? fromCursor ?? null,
1881
+ hasMore: ids.length > limit
1882
+ };
1883
+ }
1884
+ };
1885
+ }
1886
+ /**
1887
+ * Create storage for workflow steps using Redis hashes and sorted sets
1888
+ */
1889
+ function createStepsStorage(config) {
1890
+ const { redis, keyPrefix } = config;
1891
+ const stepKey = (runId, stepId) => `${keyPrefix}step:${runId}:${stepId}`;
1892
+ const stepsIndexKey = (runId) => `${keyPrefix}steps:by_run:${runId}`;
1893
+ async function getStepData(key, stepId, params) {
1894
+ const data = await redis.get(key);
1895
+ if (!data) throw new WorkflowWorldError(`Step not found: ${stepId}`, { status: 404 });
1896
+ const step = parseWithUint8Array(data);
1897
+ return filterStepData(StepSchema.parse(compact(step)), params?.resolveData ?? "all");
1898
+ }
1899
+ return {
1900
+ get: (async (runId, stepId, params) => getStepData(stepKey(runId, stepId), stepId, params)),
1901
+ list: (async (params) => {
1902
+ const limit = params?.pagination?.limit ?? 20;
1903
+ const fromCursor = params?.pagination?.cursor;
1904
+ const entries = await pageIndex(redis, stepsIndexKey(params.runId), fromCursor, limit + 1, params?.pagination?.sortOrder ?? "desc");
1905
+ const pipeline = redis.pipeline();
1906
+ for (const { id } of entries) pipeline.get(stepKey(params.runId, id));
1907
+ const results = await pipeline.exec();
1908
+ const resolveData = params?.resolveData ?? "all";
1909
+ const steps = [];
1910
+ for (const [i, result] of (results ?? []).entries()) if (result?.[1]) {
1911
+ const step = parseWithUint8Array(result[1]);
1912
+ const parsed = StepSchema.parse(compact(step));
1913
+ steps.push({
1914
+ step: filterStepData(parsed, resolveData),
1915
+ cursor: entries[i].cursor
1916
+ });
1917
+ }
1918
+ const values = steps.slice(0, limit);
1919
+ const hasMore = steps.length > limit;
1920
+ return {
1921
+ data: values.map((entry) => entry.step),
1922
+ hasMore,
1923
+ cursor: values.at(-1)?.cursor ?? null
1924
+ };
1925
+ })
1926
+ };
1927
+ }
1928
+ /**
1929
+ * Create storage for hooks using Redis hashes and sorted sets
1930
+ */
1931
+ function createHooksStorage(config) {
1932
+ const { redis, keyPrefix } = config;
1933
+ const hookKeyFn = (hookId) => `${keyPrefix}hook:${hookId}`;
1934
+ const hooksByTokenKey = (token) => `${keyPrefix}hooks:by_token:${token}`;
1935
+ const hooksIndexKey = (runId) => `${keyPrefix}hooks:by_run:${runId}`;
1936
+ async function liveHooksIndexKeys() {
1937
+ return (await Promise.all(["pending", "running"].map((status) => redis.zrange(`${keyPrefix}runs:by_status:${status}`, "0", "-1")))).flat().map(hooksIndexKey);
1938
+ }
1939
+ return {
1940
+ async get(hookId, params) {
1941
+ const data = await redis.get(hookKeyFn(hookId));
1942
+ if (!data) throw new HookNotFoundError(hookId);
1943
+ const hook = parseWithUint8Array(data);
1944
+ return filterHookData(HookSchema.parse(compact(hook)), params?.resolveData ?? "all");
1945
+ },
1946
+ async getByToken(token, params) {
1947
+ const hookId = await redis.get(hooksByTokenKey(token));
1948
+ if (!hookId) throw new HookNotFoundError(token);
1949
+ return this.get(hookId, params);
1950
+ },
1951
+ async list(params) {
1952
+ const limit = params?.pagination?.limit ?? 100;
1953
+ const fromCursor = params?.pagination?.cursor;
1954
+ const entries = await pageIndex(redis, params.runId ? hooksIndexKey(params.runId) : await liveHooksIndexKeys(), fromCursor, limit + 1, params?.pagination?.sortOrder ?? "asc");
1955
+ const pipeline = redis.pipeline();
1956
+ for (const { id } of entries) pipeline.get(hookKeyFn(id));
1957
+ const results = await pipeline.exec();
1958
+ const hooks = [];
1959
+ for (const [i, result] of (results ?? []).entries()) if (result?.[1]) {
1960
+ const hook = parseWithUint8Array(result[1]);
1961
+ const parsed = HookSchema.parse(compact(hook));
1962
+ hooks.push({
1963
+ hook: filterHookData(parsed, params?.resolveData ?? "all"),
1964
+ cursor: entries[i].cursor
1965
+ });
1966
+ }
1967
+ const values = hooks.slice(0, limit);
1968
+ const hasMore = hooks.length > limit;
1969
+ return {
1970
+ data: values.map((entry) => entry.hook),
1971
+ cursor: values.at(-1)?.cursor ?? null,
1972
+ hasMore
1973
+ };
1974
+ }
1975
+ };
1976
+ }
1977
+ // src/streamer.ts
1978
+ function parseStreamPublishMessage(raw) {
1979
+ let parsed;
1980
+ try {
1981
+ parsed = JSON.parse(raw);
1982
+ } catch {
1983
+ return null;
1984
+ }
1985
+ if (!parsed || typeof parsed !== "object") return null;
1986
+ const { runId, streamId, entryId, data, eof, prevId } = parsed;
1987
+ if (typeof runId !== "string" || typeof streamId !== "string") return null;
1988
+ if (typeof entryId !== "string" || typeof prevId !== "string") return null;
1989
+ if (typeof data !== "string" || typeof eof !== "boolean") return null;
1990
+ return {
1991
+ runId,
1992
+ streamId,
1993
+ entryId,
1994
+ data,
1995
+ eof,
1996
+ prevId
1997
+ };
1998
+ }
1999
+ /** A reader also re-reads the stream this often, in case a notification and the
2000
+ * reconnect hook both missed something. Notifications are the fast path. */
2001
+ const CATCH_UP_INTERVAL_MS = 2e3;
2002
+ /**
2003
+ * Compare two Redis stream entry IDs (`<ms>-<seq>`) numerically.
2004
+ *
2005
+ * String comparison is NOT safe here: within one millisecond `...-10` compares
2006
+ * lexicographically smaller than `...-9`, which would drop chunks (and the eof
2007
+ * marker) once the sequence number crosses a digit boundary.
2008
+ */
2009
+ function compareStreamEntryIds(a, b) {
2010
+ const [aMs, aSeq] = a.split("-").map(Number);
2011
+ const [bMs, bSeq] = b.split("-").map(Number);
2012
+ return aMs - bMs || aSeq - bSeq;
2013
+ }
2014
+ /**
2015
+ * Append one or more chunks, index the stream under its run, and notify
2016
+ * subscribers in one round trip. The publish could not be pipelined with the
2017
+ * append because it needs the entry ID `XADD` generates; Lua makes that
2018
+ * dependency server-side. Each chunk rides along in its message so subscribers
2019
+ * do not `XRANGE` per notification.
2020
+ *
2021
+ * A stream that already holds its eof marker is closed: the append is dropped
2022
+ * and nothing is published. Readers stop at the first eof anyway, so this only
2023
+ * keeps the invariant that the eof marker, when present, is the final entry.
2024
+ * `getInfo` relies on it to answer from `XLEN` and the tail entry alone, and a
2025
+ * producer retrying a lost-ACK `close()` would otherwise break it.
2026
+ *
2027
+ * KEYS[1] = stream key
2028
+ * KEYS[2] = streams-by-run key
2029
+ * ARGV[1] = notification channel
2030
+ * ARGV[2] = run ID
2031
+ * ARGV[3] = stream name
2032
+ * ARGV[4] = 'true' | 'false' (eof marker, applied to every chunk below)
2033
+ * ARGV[5..] = base64 chunk data, in write order
2034
+ * Returns: 1 if appended, 0 if the stream was already closed
2035
+ */
2036
+ const LUA_APPEND_AND_PUBLISH = `
2037
+ local streamKey = KEYS[1]
2038
+ local runIndexKey = KEYS[2]
2039
+ local channel = ARGV[1]
2040
+ local runId = ARGV[2]
2041
+ local streamId = ARGV[3]
2042
+ local eof = ARGV[4]
2043
+
2044
+ local tail = redis.call('XREVRANGE', streamKey, '+', '-', 'COUNT', 1)
2045
+ if #tail > 0 and tail[1][2][4] == 'true' then
2046
+ return 0
2047
+ end
2048
+
2049
+ local prevId = ''
2050
+ if #tail > 0 then
2051
+ prevId = tail[1][1]
2052
+ end
2053
+
2054
+ for i = 5, #ARGV do
2055
+ local data = ARGV[i]
2056
+ local entryId = redis.call('XADD', streamKey, '*', 'data', data, 'eof', eof)
2057
+ redis.call('PUBLISH', channel, cjson.encode({
2058
+ runId = runId,
2059
+ streamId = streamId,
2060
+ entryId = entryId,
2061
+ data = data,
2062
+ eof = eof == 'true',
2063
+ prevId = prevId
2064
+ }))
2065
+ prevId = entryId
2066
+ end
2067
+ redis.call('SADD', runIndexKey, streamId)
2068
+ return 1
2069
+ `;
2070
+ /**
2071
+ * Create a streamer implementation using Redis Streams.
2072
+ *
2073
+ * Uses Redis auto-generated stream entry IDs (timestamp-sequence format)
2074
+ * instead of custom IDs, since Redis Streams require IDs in
2075
+ * `<millisecondsTime>-<sequenceNumber>` format.
2076
+ *
2077
+ * Key layout (every key is scoped to the run that owns the stream, so two runs
2078
+ * can use the same stream name without sharing chunks):
2079
+ * - `<prefix>stream:<runId>:<name>` Redis Stream of the chunks plus the eof marker
2080
+ * - `<prefix>streams:by_run:<runId>` Set of the run's stream names
2081
+ * - `<prefix>stream_notify` pub/sub channel carrying live chunks
2082
+ */
2083
+ function createStreamer(config) {
2084
+ const { redis, keyPrefix } = config;
2085
+ const events = new EventEmitter();
2086
+ const mutexes = /* @__PURE__ */ new Map();
2087
+ const withStreamMutex = async (key, fn) => {
2088
+ let entry = mutexes.get(key);
2089
+ if (!entry) {
2090
+ entry = {
2091
+ mutex: new Mutex(),
2092
+ rc: new Rc(() => {
2093
+ mutexes.delete(key);
2094
+ })
2095
+ };
2096
+ mutexes.set(key, entry);
2097
+ }
2098
+ entry.rc.inc();
2099
+ try {
2100
+ return await entry.mutex.andThen(fn);
2101
+ } finally {
2102
+ await entry.rc.dec();
2103
+ }
2104
+ };
2105
+ redis.defineCommand("wfStreamAppend", {
2106
+ numberOfKeys: 2,
2107
+ lua: LUA_APPEND_AND_PUBLISH
2108
+ });
2109
+ const scripted = redis;
2110
+ const streamKey = (runId, name) => `${keyPrefix}stream:${runId}:${name}`;
2111
+ const streamsByRunKey = (runId) => `${keyPrefix}streams:by_run:${runId}`;
2112
+ const STREAM_CHANNEL = `${keyPrefix}stream_notify`;
2113
+ const emitterKey = (runId, name) => `strm:${runId}:${name}`;
2114
+ const subscriber = redis.duplicate();
2115
+ const subscriptionReady = subscriber.subscribe(STREAM_CHANNEL).then(() => {});
2116
+ const resync = new EventEmitter();
2117
+ resync.setMaxListeners(0);
2118
+ let subscriberConnected = false;
2119
+ subscriber.on("ready", () => {
2120
+ if (subscriberConnected) resync.emit("resync");
2121
+ subscriberConnected = true;
2122
+ });
2123
+ subscriber.on("message", async (channel, message) => {
2124
+ if (channel !== STREAM_CHANNEL) return;
2125
+ try {
2126
+ const parsed = parseStreamPublishMessage(message);
2127
+ if (!parsed) return;
2128
+ const key = emitterKey(parsed.runId, parsed.streamId);
2129
+ if (!events.listenerCount(key)) return;
2130
+ await withStreamMutex(key, async () => {
2131
+ events.emit(key, {
2132
+ id: parsed.entryId,
2133
+ data: Buffer.from(parsed.data, "base64"),
2134
+ eof: parsed.eof,
2135
+ prevId: parsed.prevId
2136
+ });
2137
+ });
2138
+ } catch (error) {
2139
+ console.error("Error processing stream notification:", error);
2140
+ }
2141
+ });
2142
+ const toBase64 = (chunk) => (Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)).toString("base64");
2143
+ const append = async (runId, name, eof, encodedChunks) => {
2144
+ await subscriptionReady;
2145
+ await scripted.wfStreamAppend(streamKey(runId, name), streamsByRunKey(runId), STREAM_CHANNEL, runId, name, eof ? "true" : "false", ...encodedChunks);
2146
+ };
2147
+ return {
2148
+ streams: {
2149
+ async write(_runId, name, chunk) {
2150
+ const runId = await _runId;
2151
+ await append(runId, name, false, [toBase64(chunk)]);
2152
+ },
2153
+ async writeMulti(_runId, name, chunks) {
2154
+ if (chunks.length === 0) return;
2155
+ const runId = await _runId;
2156
+ await append(runId, name, false, chunks.map(toBase64));
2157
+ },
2158
+ async close(_runId, name) {
2159
+ const runId = await _runId;
2160
+ await append(runId, name, true, [""]);
2161
+ },
2162
+ async get(runId, name, startIndex) {
2163
+ const key = emitterKey(runId, name);
2164
+ const cleanups = [];
2165
+ let cleanedUp = false;
2166
+ const cleanup = () => {
2167
+ if (cleanedUp) return;
2168
+ cleanedUp = true;
2169
+ for (const fn of cleanups) fn();
2170
+ };
2171
+ return new ReadableStream({
2172
+ async start(controller) {
2173
+ let lastEntryId = "";
2174
+ let offset = startIndex ?? 0;
2175
+ let buffer = [];
2176
+ function enqueue(msg) {
2177
+ if (cleanedUp) return;
2178
+ if (lastEntryId !== "" && compareStreamEntryIds(lastEntryId, msg.id) >= 0) return;
2179
+ lastEntryId = msg.id;
2180
+ if (offset > 0 && !msg.eof) {
2181
+ offset--;
2182
+ return;
2183
+ }
2184
+ if (msg.data.byteLength) controller.enqueue(new Uint8Array(msg.data));
2185
+ if (msg.eof) {
2186
+ cleanup();
2187
+ controller.close();
2188
+ }
2189
+ }
2190
+ let catchingUp = false;
2191
+ let again = false;
2192
+ async function catchUp() {
2193
+ if (cleanedUp || buffer) return;
2194
+ if (catchingUp) {
2195
+ again = true;
2196
+ return;
2197
+ }
2198
+ catchingUp = true;
2199
+ try {
2200
+ do {
2201
+ again = false;
2202
+ const entries = await redis.xrange(streamKey(runId, name), lastEntryId === "" ? "-" : `(${lastEntryId}`, "+");
2203
+ for (const [id, fields] of entries) enqueue({
2204
+ id,
2205
+ data: Buffer.from(fields[1], "base64"),
2206
+ eof: fields[3] === "true"
2207
+ });
2208
+ } while (again && !cleanedUp);
2209
+ } catch {} finally {
2210
+ catchingUp = false;
2211
+ }
2212
+ }
2213
+ function deliverLive(data) {
2214
+ if (data.prevId !== void 0 && data.prevId !== lastEntryId) {
2215
+ catchUp();
2216
+ return;
2217
+ }
2218
+ enqueue(data);
2219
+ }
2220
+ function onData(data) {
2221
+ if (buffer) {
2222
+ buffer.push(data);
2223
+ return;
2224
+ }
2225
+ deliverLive(data);
2226
+ }
2227
+ events.on(key, onData);
2228
+ cleanups.push(() => {
2229
+ events.off(key, onData);
2230
+ });
2231
+ const chunks = await redis.xrange(streamKey(runId, name), "-", "+").catch((err) => {
2232
+ cleanup();
2233
+ throw err;
2234
+ });
2235
+ const parsedChunks = [];
2236
+ for (const [id, fields] of chunks) {
2237
+ const data = Buffer.from(fields[1], "base64");
2238
+ const eof = fields[3] === "true";
2239
+ parsedChunks.push({
2240
+ id,
2241
+ data,
2242
+ eof
2243
+ });
2244
+ }
2245
+ if (offset < 0) {
2246
+ const firstEof = parsedChunks.findIndex((chunk) => chunk.eof);
2247
+ const dataCount = firstEof === -1 ? parsedChunks.length : firstEof;
2248
+ offset = Math.max(0, dataCount + offset);
2249
+ }
2250
+ const buffered = buffer ?? [];
2251
+ buffer = null;
2252
+ for (const chunk of parsedChunks) enqueue(chunk);
2253
+ for (const chunk of buffered) deliverLive(chunk);
2254
+ resync.on("resync", catchUp);
2255
+ const timer = setInterval(() => void catchUp(), CATCH_UP_INTERVAL_MS);
2256
+ timer.unref();
2257
+ cleanups.push(() => {
2258
+ resync.off("resync", catchUp);
2259
+ clearInterval(timer);
2260
+ });
2261
+ await catchUp();
2262
+ },
2263
+ cancel() {
2264
+ cleanup();
2265
+ }
2266
+ });
2267
+ },
2268
+ async list(runId) {
2269
+ return await redis.smembers(streamsByRunKey(runId)) ?? [];
2270
+ },
2271
+ async getChunks(runId, name, options) {
2272
+ const limit = Math.min(options?.limit ?? 100, 1e3);
2273
+ let dataIndex = 0;
2274
+ let start = "-";
2275
+ if (options?.cursor) try {
2276
+ const decoded = JSON.parse(Buffer.from(options.cursor, "base64").toString("utf-8"));
2277
+ if (typeof decoded.i === "number") dataIndex = decoded.i;
2278
+ if (typeof decoded.id === "string") start = `(${decoded.id}`;
2279
+ } catch {
2280
+ dataIndex = 0;
2281
+ start = "-";
2282
+ }
2283
+ const entries = await redis.xrange(streamKey(runId, name), start, "+", "COUNT", limit + 1);
2284
+ const data = [];
2285
+ let done = false;
2286
+ let hasMore = false;
2287
+ let lastId = null;
2288
+ for (const [id, fields] of entries) {
2289
+ if (fields[3] === "true") {
2290
+ done = true;
2291
+ break;
2292
+ }
2293
+ if (data.length >= limit) {
2294
+ hasMore = true;
2295
+ break;
2296
+ }
2297
+ data.push({
2298
+ index: dataIndex,
2299
+ data: new Uint8Array(Buffer.from(fields[1], "base64"))
2300
+ });
2301
+ dataIndex++;
2302
+ lastId = id;
2303
+ }
2304
+ return {
2305
+ data,
2306
+ cursor: hasMore && lastId ? Buffer.from(JSON.stringify({
2307
+ i: dataIndex,
2308
+ id: lastId
2309
+ })).toString("base64") : null,
2310
+ hasMore,
2311
+ done
2312
+ };
2313
+ },
2314
+ async getInfo(runId, name) {
2315
+ const key = streamKey(runId, name);
2316
+ const [length, tail] = await Promise.all([redis.xlen(key), redis.xrevrange(key, "+", "-", "COUNT", 1)]);
2317
+ const done = tail.length > 0 && tail[0][1][3] === "true";
2318
+ return {
2319
+ tailIndex: length - (done ? 1 : 0) - 1,
2320
+ done
2321
+ };
2322
+ }
2323
+ },
2324
+ async close() {
2325
+ await subscriber.quit();
2326
+ }
2327
+ };
2328
+ }
2329
+ // src/shared.ts
2330
+ function createStorage(redis, keyPrefix, maxEventsPerRun) {
2331
+ const config = {
2332
+ redis,
2333
+ keyPrefix,
2334
+ maxEventsPerRun
2335
+ };
2336
+ return {
2337
+ runs: createRunsStorage(config),
2338
+ events: createEventsStorage(config),
2339
+ hooks: createHooksStorage(config),
2340
+ steps: createStepsStorage(config)
2341
+ };
2342
+ }
2343
+ export { validateRetention as a, uint8ArrayReplacer as c, initialMessageKey as d, hasRetention as i, createDebugLogger as l, createStreamer as n, debug as o, createReaper as r, hasBinary as s, createStorage as t, createRunId as u };
2344
+
2345
+ //# sourceMappingURL=shared-Bhvu4aZA.js.map