@graphrefly/ts 0.0.0 → 0.0.1

package/dist/work-queue/index.cjs

@@ -0,0 +1,1132 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/work-queue/index.ts
+var work_queue_exports = {};
+__export(work_queue_exports, {
+  workQueue: () => workQueue
+});
+module.exports = __toCommonJS(work_queue_exports);
+
+// src/protocol/messages.ts
+var SENTINEL = void 0;
+
+// src/ctx/types.ts
+function depWaves(ctx, depIndex) {
+  return ctx.waveData[depIndex] ?? [];
+}
+function depBatch(ctx, depIndex) {
+  const waves = depWaves(ctx, depIndex);
+  if (waves.length === 0) return null;
+  const flattened = waves.flat().filter((v) => v !== SENTINEL);
+  return flattened.length === 0 ? [] : flattened;
+}
+
+// src/messaging/internal.ts
+var busStates = /* @__PURE__ */ new WeakMap();
+function getMessageBusState(bus) {
+  return busStates.get(bus);
+}
+function attachMessageBusDeferredCommandSink(graph, bus, commands) {
+  const state = getMessageBusState(bus);
+  if (state === void 0) throw new Error("messageBus: unknown implementation");
+  if (state.graph !== graph) throw new Error("messageBus: command sink graph must match");
+  const busCommands = bus.commands;
+  if (busCommands === void 0) throw new Error("messageBus: missing commands node");
+  const boundary = commands;
+  const unsubscribe = commands.subscribe((msg) => {
+    if (msg[0] !== "DATA") return;
+    const command = msg[1];
+    const send = () => busCommands.down([["DATA", command]]);
+    if (boundary.__deferBoundary === void 0) send();
+    else boundary.__deferBoundary(send);
+  });
+  return unsubscribe;
+}
+
+// src/work-queue/index.ts
+function workQueue(graph, opts) {
+  assertNonEmpty(opts.queueId, "workQueue.queueId");
+  assertNonEmpty(opts.topic, "workQueue.topic");
+  assertNonEmpty(opts.subscriptionId, "workQueue.subscriptionId");
+  const name = opts.name ?? `workQueue/${opts.queueId}`;
+  const now = opts.now ?? Date.now;
+  const leaseDurationMs = opts.leaseDurationMs ?? 3e4;
+  const retry = opts.retry ?? { maxAttempts: 3, delayMs: 0 };
+  const admission = opts.bus.subscription({
+    topic: opts.topic,
+    subscriptionId: opts.subscriptionId,
+    from: opts.from ?? "earliest",
+    name: `${name}/admission`
+  });
+  const commands = graph.node(
+    [],
+    (ctx) => {
+      for (const command of depBatch(ctx, 0) ?? []) ctx.down([["DATA", command]]);
+    },
+    {
+      name: `${name}/commands`,
+      factory: "workQueueCommands",
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+  const state = {
+    recordSeq: 0,
+    leaseSeq: 0,
+    works: /* @__PURE__ */ new Map(),
+    sourceSeqs: /* @__PURE__ */ new Set(),
+    commandIds: /* @__PURE__ */ new Set(),
+    idempotencyKeys: /* @__PURE__ */ new Set(),
+    records: [],
+    deadLetters: []
+  };
+  const admissionKick = graph.node([], null, {
+    name: `${name}/admissionKick`,
+    factory: "workQueueAdmissionKick",
+    initial: "poll",
+    completeWhenDepsComplete: false,
+    errorWhenDepsError: false
+  });
+  const admissionPages = graph.node(
+    [admission.available, admissionKick, opts.bus.messages, opts.bus.status],
+    (ctx) => {
+      for (const page of depBatch(ctx, 0) ?? []) {
+        ctx.down([["DATA", page]]);
+      }
+      let shouldPull = (depBatch(ctx, 1)?.length ?? 0) > 0;
+      for (const message of depBatch(ctx, 2) ?? []) {
+        if (message.topic === opts.topic) shouldPull = true;
+      }
+      for (const status2 of depBatch(ctx, 3) ?? []) {
+        if (shouldPollAdmission(status2, opts.topic, opts.subscriptionId)) {
+          shouldPull = true;
+        }
+      }
+      if (shouldPull) {
+        ctx.upNext([["PULL", { pullId: admission.availablePullId, params: { limit: 100 } }]], 0);
+      }
+    },
+    {
+      name: `${name}/admissionPages`,
+      factory: "workQueueAdmissionPages",
+      partial: true,
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+  const runtime = graph.node(
+    [commands, admissionPages],
+    (ctx) => {
+      for (const page of depBatch(ctx, 1) ?? []) {
+        for (const msg of page.messages) {
+          for (const event of admitMessage(opts, state, msg, now())) ctx.down([["DATA", event]]);
+        }
+      }
+      for (const command of depBatch(ctx, 0) ?? []) {
+        const commandTime = commandNowMs(command, now());
+        for (const event of reduceQueueCommand(
+          opts,
+          state,
+          command,
+          commandTime,
+          leaseDurationMs,
+          retry
+        )) {
+          ctx.down([["DATA", event]]);
+        }
+      }
+    },
+    {
+      name: `${name}/runtime`,
+      factory: "workQueueRuntime",
+      partial: true,
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+  const records = graph.node(
+    [runtime],
+    (ctx) => {
+      for (const event of depBatch(ctx, 0) ?? []) {
+        const typed = event;
+        if (typed.kind === "record") ctx.down([["DATA", typed.record]]);
+      }
+    },
+    {
+      name: `${name}/records`,
+      factory: "workQueueRecords",
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+  const status = graph.node(
+    [runtime],
+    (ctx) => {
+      for (const event of depBatch(ctx, 0) ?? []) {
+        const typed = event;
+        if (typed.kind === "status") ctx.down([["DATA", typed.status]]);
+      }
+    },
+    {
+      name: `${name}/status`,
+      factory: "workQueueStatus",
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+  const issues = graph.node(
+    [runtime],
+    (ctx) => {
+      for (const event of depBatch(ctx, 0) ?? []) {
+        const typed = event;
+        if (typed.kind === "issue") ctx.down([["DATA", typed.issue]]);
+      }
+    },
+    {
+      name: `${name}/issues`,
+      factory: "workQueueIssues",
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+  const admissionAckCommands = graph.node(
+    [records],
+    (ctx) => {
+      for (const record of depBatch(ctx, 0) ?? []) {
+        const command = admissionAckCommand(record);
+        if (command !== void 0) ctx.down([["DATA", command]]);
+      }
+    },
+    {
+      name: `${name}/admissionAckCommands`,
+      factory: "workQueueAdmissionAckCommands",
+      completeWhenDepsComplete: false,
+      errorWhenDepsError: false
+    }
+  );
+  attachMessageBusDeferredCommandSink(graph, opts.bus, admissionAckCommands);
+  graph.retain(runtime, { reason: `${name}.workQueue.runtime` });
+  const queue = {
+    commands,
+    records,
+    status,
+    issues,
+    submit(payload, submitOpts = {}) {
+      const command = opts.bus.publish(
+        opts.topic,
+        submitPayload(payload, {
+          ...submitOpts.workId === void 0 ? {} : { workId: submitOpts.workId },
+          ...submitOpts.priority === void 0 ? {} : { priority: submitOpts.priority },
+          ...submitOpts.tags === void 0 ? {} : { tags: submitOpts.tags },
+          ...submitOpts.requirements === void 0 ? {} : { requirements: submitOpts.requirements },
+          ...submitOpts.notBeforeMs === void 0 ? {} : { notBeforeMs: submitOpts.notBeforeMs },
+          ...submitOpts.deadlineMs === void 0 ? {} : { deadlineMs: submitOpts.deadlineMs }
+        }),
+        {
+          commandId: submitOpts.commandId ?? nextCommandId(opts.queueId, "submit"),
+          idempotencyKey: submitOpts.idempotencyKey
+        }
+      );
+      return command;
+    },
+    claim(claimOpts) {
+      return publishQueueCommand(commands, {
+        ...claimOpts,
+        kind: "claim",
+        commandId: claimOpts.commandId ?? nextCommandId(opts.queueId, "claim")
+      });
+    },
+    renewLease(renewOpts) {
+      return publishQueueCommand(commands, {
+        ...renewOpts,
+        kind: "renew-lease",
+        commandId: renewOpts.commandId ?? nextCommandId(opts.queueId, "renew")
+      });
+    },
+    release(releaseOpts) {
+      return publishQueueCommand(commands, {
+        ...releaseOpts,
+        kind: "release",
+        commandId: releaseOpts.commandId ?? nextCommandId(opts.queueId, "release")
+      });
+    },
+    complete(completeOpts) {
+      return publishQueueCommand(commands, {
+        ...completeOpts,
+        kind: "complete",
+        commandId: completeOpts.commandId ?? nextCommandId(opts.queueId, "complete")
+      });
+    },
+    fail(failOpts) {
+      return publishQueueCommand(commands, {
+        ...failOpts,
+        kind: "fail",
+        commandId: failOpts.commandId ?? nextCommandId(opts.queueId, "fail")
+      });
+    },
+    cancel(cancelOpts) {
+      return publishQueueCommand(commands, {
+        ...cancelOpts,
+        kind: "cancel",
+        commandId: cancelOpts.commandId ?? nextCommandId(opts.queueId, "cancel")
+      });
+    },
+    schedule(scheduleOpts) {
+      return publishQueueCommand(commands, {
+        ...scheduleOpts,
+        kind: "schedule",
+        commandId: scheduleOpts.commandId ?? nextCommandId(opts.queueId, "schedule")
+      });
+    },
+    expireLeases(expireOpts = {}) {
+      return publishQueueCommand(commands, {
+        ...expireOpts,
+        kind: "expire-leases",
+        commandId: expireOpts.commandId ?? nextCommandId(opts.queueId, "expire")
+      });
+    },
+    available(projectionOpts = {}) {
+      const availablePullId = /* @__PURE__ */ Symbol(`${name}/available`);
+      const available = graph.node(
+        [records],
+        (ctx) => {
+          const params = pullParams(ctx.pull);
+          ctx.down([["DATA", availablePage(state, params)]]);
+        },
+        {
+          name: projectionOpts.name ?? `${name}/available`,
+          factory: "workQueueAvailable",
+          pullId: availablePullId,
+          partial: true,
+          completeWhenDepsComplete: false,
+          errorWhenDepsError: false
+        }
+      );
+      return { available, availablePullId, status, issues };
+    },
+    work(workId, projectionOpts = {}) {
+      const snapshotPullId = /* @__PURE__ */ Symbol(`${name}/${workId}/snapshot`);
+      const snapshot = graph.node(
+        [records],
+        (ctx) => {
+          ctx.down([["DATA", workSnapshot(state, workId)]]);
+        },
+        {
+          name: projectionOpts.name ?? `${name}/${workId}`,
+          factory: "workQueueWorkSnapshot",
+          pullId: snapshotPullId,
+          partial: true,
+          completeWhenDepsComplete: false,
+          errorWhenDepsError: false
+        }
+      );
+      return { snapshot, snapshotPullId, status, issues };
+    },
+    deadLetter(projectionOpts = {}) {
+      const snapshotPullId = /* @__PURE__ */ Symbol(`${name}/deadLetter`);
+      const snapshot = graph.node(
+        [records],
+        (ctx) => {
+          const params = pullParams(ctx.pull);
+          ctx.down([["DATA", deadLetterPage(state, params)]]);
+        },
+        {
+          name: projectionOpts.name ?? `${name}/deadLetter`,
+          factory: "workQueueDeadLetter",
+          pullId: snapshotPullId,
+          partial: true,
+          completeWhenDepsComplete: false,
+          errorWhenDepsError: false
+        }
+      );
+      return { snapshot, snapshotPullId, status, issues };
+    }
+  };
+  return queue;
+}
+function shouldPollAdmission(status, topic, subscriptionId) {
+  if (status.topic !== topic) return false;
+  if (status.kind === "message-published" || status.kind === "retention-trimmed") return true;
+  return status.subscriptionId === subscriptionId && (status.kind === "subscription-acked" || status.kind === "subscription-sought");
+}
+function admissionAckCommand(record) {
+  const messageBus = admissionMessageBus(record);
+  if (messageBus === void 0) return void 0;
+  return {
+    kind: "ack",
+    topic: messageBus.topic,
+    subscriptionId: messageBus.subscriptionId,
+    seq: messageBus.seq,
+    commandId: `${record.queueId}:admission-ack:${messageBus.topic}:${messageBus.subscriptionId}:${messageBus.seq}`
+  };
+}
+function admissionMessageBus(record) {
+  return "messageBus" in record ? record.messageBus : void 0;
+}
+function admitMessage(opts, state, message, nowMs) {
+  const source = `${message.topic}:${message.seq}`;
+  if (state.sourceSeqs.has(source)) return [];
+  state.sourceSeqs.add(source);
+  const submitted = decodeSubmittedPayload(message.payload);
+  const payload = submitted.payload;
+  const payloadRecord = payloadAsRecord(submitted.meta);
+  const workId = typeof payloadRecord.workId === "string" ? payloadRecord.workId : `${opts.queueId}:${message.topic}:${message.seq}`;
+  if (state.works.has(workId)) {
+    const record2 = appendRecord(state, opts.queueId, {
+      kind: "admission-deduped",
+      workId,
+      messageBus: { topic: message.topic, seq: message.seq, subscriptionId: opts.subscriptionId },
+      reason: "duplicate-work",
+      existingWorkId: workId,
+      recordedAtMs: nowMs
+    });
+    return [
+      recordEvent(record2),
+      statusEvent(opts.queueId, "admission-rejected", nowMs, {
+        workId,
+        recordSeq: record2.recordSeq,
+        issueCode: "duplicate-work"
+      })
+    ];
+  }
+  const work = {
+    workId,
+    payload,
+    state: typeof payloadRecord.notBeforeMs === "number" && payloadRecord.notBeforeMs > nowMs ? "scheduled" : "ready",
+    admissionSeq: message.seq,
+    priority: numberOrUndefined(payloadRecord.priority),
+    tags: stringArrayOrUndefined(payloadRecord.tags),
+    requirements: stringArrayOrUndefined(payloadRecord.requirements),
+    notBeforeMs: numberOrUndefined(payloadRecord.notBeforeMs),
+    deadlineMs: numberOrUndefined(payloadRecord.deadlineMs),
+    attempt: 0
+  };
+  state.works.set(workId, work);
+  const record = appendRecord(state, opts.queueId, {
+    kind: "work-admitted",
+    workId,
+    payload,
+    messageBus: { topic: message.topic, seq: message.seq, subscriptionId: opts.subscriptionId },
+    priority: work.priority,
+    tags: work.tags,
+    requirements: work.requirements,
+    notBeforeMs: work.notBeforeMs,
+    deadlineMs: work.deadlineMs,
+    recordedAtMs: nowMs
+  });
+  return [
+    recordEvent(record),
+    statusEvent(opts.queueId, "admission-accepted", nowMs, { workId, recordSeq: record.recordSeq })
+  ];
+}
+function reduceQueueCommand(opts, state, command, nowMs, leaseDurationMs, retry) {
+  const invalid = validateQueueCommand(opts.queueId, command);
+  if (invalid !== void 0)
+    return rejectQueueCommand(opts.queueId, command, invalid.code, invalid.message, nowMs);
+  if (state.commandIds.has(command.commandId)) {
+    return rejectQueueCommand(
+      opts.queueId,
+      command,
+      "duplicate-command",
+      "duplicate commandId",
+      nowMs
+    );
+  }
+  if (command.idempotencyKey !== void 0 && state.idempotencyKeys.has(command.idempotencyKey)) {
+    return rejectQueueCommand(
+      opts.queueId,
+      command,
+      "duplicate-command",
+      "duplicate idempotencyKey",
+      nowMs
+    );
+  }
+  state.commandIds.add(command.commandId);
+  if (command.idempotencyKey !== void 0) state.idempotencyKeys.add(command.idempotencyKey);
+  switch (command.kind) {
+    case "claim":
+      return claimWork(opts.queueId, state, command, nowMs, leaseDurationMs);
+    case "renew-lease":
+      return renewLease(opts.queueId, state, command, nowMs, leaseDurationMs);
+    case "release":
+      return releaseWork(opts.queueId, state, command, nowMs);
+    case "complete":
+      return completeWork(opts.queueId, state, command, nowMs);
+    case "fail":
+      return failWork(opts.queueId, state, command, nowMs, retry);
+    case "cancel":
+      return cancelWork(opts.queueId, state, command, nowMs);
+    case "schedule":
+      return scheduleWork(opts.queueId, state, command, nowMs);
+    case "expire-leases":
+      return expireLeases(opts.queueId, state, command, nowMs);
+    case "submit":
+      return [
+        statusEvent(opts.queueId, "command-accepted", nowMs, {
+          commandId: command.commandId,
+          details: { submitUsesMessageBus: true }
+        })
+      ];
+  }
+}
+function claimWork(queueId, state, command, nowMs, defaultLeaseDurationMs) {
+  const limit = positiveLimit(command.limit ?? command.requestedWorkIds?.length ?? 1);
+  const requested = new Set(command.requestedWorkIds ?? []);
+  const events = [];
+  for (const work of [...state.works.values()].filter((entry) => requested.size === 0 ? true : requested.has(entry.workId)).filter((entry) => isExpiredLease(entry, nowMs))) {
+    events.push(...materializeLeaseExpired(queueId, state, work, command.commandId, nowMs));
+  }
+  const candidates = [...state.works.values()].filter((work) => requested.size === 0 ? true : requested.has(work.workId)).filter((work) => isReady(work, nowMs)).sort((a, b) => a.admissionSeq - b.admissionSeq).slice(0, limit);
+  if (candidates.length === 0)
+    return [
+      ...events,
+      ...requested.size === 0 ? rejectQueueCommand(queueId, command, "not-ready", "no ready work", nowMs) : claimMissEvents(queueId, state, command, requested, /* @__PURE__ */ new Set(), nowMs)
+    ];
+  const claimed = /* @__PURE__ */ new Set();
+  for (const work of candidates) {
+    claimed.add(work.workId);
+    work.state = "leased";
+    work.attempt += 1;
+    work.leaseId = `${work.workId}:lease:${++state.leaseSeq}`;
+    work.workerId = command.workerId;
+    work.leaseExpiresAtMs = nowMs + (command.leaseDurationMs ?? defaultLeaseDurationMs);
+    const record = appendRecord(state, queueId, {
+      kind: "work-claimed",
+      workId: work.workId,
+      commandId: command.commandId,
+      leaseId: work.leaseId,
+      attempt: work.attempt,
+      workerId: command.workerId,
+      claimedAtMs: nowMs,
+      leaseExpiresAtMs: work.leaseExpiresAtMs,
+      recordedAtMs: nowMs
+    });
+    events.push(
+      recordEvent(record),
+      statusEvent(queueId, "command-accepted", nowMs, {
+        workId: work.workId,
+        commandId: command.commandId,
+        recordSeq: record.recordSeq
+      })
+    );
+  }
+  if (requested.size > 0) {
+    events.push(...claimMissEvents(queueId, state, command, requested, claimed, nowMs));
+  }
+  return events;
+}
+function claimMissEvents(queueId, state, command, requested, claimed, nowMs) {
+  const events = [];
+  for (const workId of requested) {
+    if (claimed.has(workId)) continue;
+    const work = state.works.get(workId);
+    if (work === void 0) {
+      events.push(
+        ...rejectQueueCommand(
+          queueId,
+          command,
+          "unknown-work",
+          `unknown work '${workId}'`,
+          nowMs
+        )
+      );
+      continue;
+    }
+    if (isReady(work, nowMs)) continue;
+    const code = isTerminal(work.state) ? "terminal-work" : work.state === "leased" ? "already-leased" : "not-ready";
+    events.push(
+      ...rejectQueueCommand(
+        queueId,
+        command,
+        code,
+        `requested work '${workId}' is not claimable`,
+        nowMs
+      )
+    );
+  }
+  return events;
+}
+function renewLease(queueId, state, command, nowMs, defaultLeaseDurationMs) {
+  const checked = currentLease(queueId, state, command, nowMs);
+  if ("issue" in checked) return [checked.issue];
+  if ("events" in checked) return checked.events;
+  const work = checked.work;
+  const previous = work.leaseExpiresAtMs;
+  work.leaseExpiresAtMs = command.leaseExpiresAtMs ?? nowMs + (command.leaseDurationMs ?? defaultLeaseDurationMs);
+  const record = appendRecord(state, queueId, {
+    kind: "lease-renewed",
+    workId: work.workId,
+    commandId: command.commandId,
+    leaseId: command.leaseId,
+    attempt: command.attempt,
+    workerId: command.workerId,
+    previousLeaseExpiresAtMs: previous,
+    leaseExpiresAtMs: work.leaseExpiresAtMs,
+    renewedAtMs: nowMs,
+    recordedAtMs: nowMs
+  });
+  return [
+    recordEvent(record),
+    statusEvent(queueId, "command-accepted", nowMs, {
+      workId: work.workId,
+      commandId: command.commandId,
+      recordSeq: record.recordSeq
+    })
+  ];
+}
+function releaseWork(queueId, state, command, nowMs) {
+  const checked = currentLease(queueId, state, command, nowMs);
+  if ("issue" in checked) return [checked.issue];
+  if ("events" in checked) return checked.events;
+  const work = checked.work;
+  work.state = "ready";
+  work.leaseId = void 0;
+  work.workerId = void 0;
+  work.leaseExpiresAtMs = void 0;
+  const record = appendRecord(state, queueId, {
+    kind: "work-released",
+    workId: work.workId,
+    commandId: command.commandId,
+    leaseId: command.leaseId,
+    attempt: command.attempt,
+    workerId: command.workerId,
+    releasedAtMs: nowMs,
+    reason: command.reason,
+    recordedAtMs: nowMs
+  });
+  return [
+    recordEvent(record),
+    statusEvent(queueId, "command-accepted", nowMs, {
+      workId: work.workId,
+      commandId: command.commandId,
+      recordSeq: record.recordSeq
+    })
+  ];
+}
+function completeWork(queueId, state, command, nowMs) {
+  const checked = currentLease(queueId, state, command, nowMs);
+  if ("issue" in checked) return [checked.issue];
+  if ("events" in checked) return checked.events;
+  const work = checked.work;
+  work.state = "completed";
+  clearLease(work);
+  work.terminalRecordSeq = state.recordSeq + 2;
+  const attempt = appendRecord(state, queueId, {
+    kind: "attempt-completed",
+    workId: work.workId,
+    commandId: command.commandId,
+    leaseId: command.leaseId,
+    attempt: command.attempt,
+    workerId: command.workerId,
+    result: command.result,
+    recordedAtMs: nowMs
+  });
+  const done = appendRecord(state, queueId, {
+    kind: "work-completed",
+    workId: work.workId,
+    commandId: command.commandId,
+    leaseId: command.leaseId,
+    attempt: command.attempt,
+    workerId: command.workerId,
+    result: command.result,
+    recordedAtMs: nowMs
+  });
+  return [
+    recordEvent(attempt),
+    recordEvent(done),
+    statusEvent(queueId, "command-accepted", nowMs, {
+      workId: work.workId,
+      commandId: command.commandId,
+      recordSeq: done.recordSeq
+    })
+  ];
+}
+function failWork(queueId, state, command, nowMs, retry) {
+  const checked = currentLease(queueId, state, command, nowMs);
+  if ("issue" in checked) return [checked.issue];
+  if ("events" in checked) return checked.events;
+  const work = checked.work;
+  const failed = appendRecord(state, queueId, {
+    kind: "attempt-failed",
+    workId: work.workId,
+    commandId: command.commandId,
+    leaseId: command.leaseId,
+    attempt: command.attempt,
+    workerId: command.workerId,
+    error: command.error,
+    retryable: command.retryable,
+    recordedAtMs: nowMs
+  });
+  const maxAttempts = retry.maxAttempts ?? 3;
+  if (command.retryable === false || work.attempt >= maxAttempts) {
+    work.state = "dead-lettered";
+    clearLease(work);
+    work.retryAtMs = void 0;
+    const dead = appendRecord(state, queueId, {
+      kind: "work-dead-lettered",
+      workId: work.workId,
+      commandId: command.commandId,
+      reason: command.retryable === false ? "non-retryable" : "attempts-exhausted",
+      exhaustedAttempts: work.attempt,
+      recordedAtMs: nowMs
+    });
+    state.deadLetters.push(dead);
+    return [
+      recordEvent(failed),
+      recordEvent(dead),
+      statusEvent(queueId, "command-accepted", nowMs, {
+        workId: work.workId,
+        commandId: command.commandId,
+        recordSeq: dead.recordSeq
+      })
+    ];
+  }
+  const delayMs = retry.delayMs ?? 0;
+  work.state = delayMs > 0 ? "retry-wait" : "ready";
+  work.retryAtMs = nowMs + delayMs;
+  clearLease(work);
+  const retryRecord = appendRecord(state, queueId, {
+    kind: "retry-scheduled",
+    workId: work.workId,
+    commandId: command.commandId,
+    retryAtMs: work.retryAtMs,
+    delayMs,
+    reason: "retry-policy",
+    recordedAtMs: nowMs
+  });
+  return [
+    recordEvent(failed),
+    recordEvent(retryRecord),
+    statusEvent(queueId, "command-accepted", nowMs, {
+      workId: work.workId,
+      commandId: command.commandId,
+      recordSeq: retryRecord.recordSeq
+    })
+  ];
+}
+function cancelWork(queueId, state, command, nowMs) {
+  const work = state.works.get(command.workId);
+  if (work === void 0)
+    return [issueEvent(queueId, "unknown-work", "unknown work", nowMs, command)];
+  if (isTerminal(work.state))
+    return [issueEvent(queueId, "terminal-work", "work is terminal", nowMs, command)];
+  work.state = "canceled";
+  const canceledLeaseId = work.leaseId;
+  const attempt = work.attempt || void 0;
+  const record = appendRecord(state, queueId, {
+    kind: "work-canceled",
+    workId: work.workId,
+    commandId: command.commandId,
+    reason: command.reason,
+    canceledAtMs: nowMs,
+    canceledLeaseId,
+    attempt,
+    recordedAtMs: nowMs
+  });
+  clearLease(work);
+  return [
+    recordEvent(record),
+    statusEvent(queueId, "command-accepted", nowMs, {
+      workId: work.workId,
+      commandId: command.commandId,
+      recordSeq: record.recordSeq
+    })
+  ];
+}
+function scheduleWork(queueId, state, command, nowMs) {
+  const work = state.works.get(command.workId);
+  if (work === void 0)
+    return [issueEvent(queueId, "unknown-work", "unknown work", nowMs, command)];
+  if (isTerminal(work.state))
+    return [issueEvent(queueId, "terminal-work", "work is terminal", nowMs, command)];
+  work.state = "scheduled";
+  work.notBeforeMs = command.notBeforeMs;
+  work.deadlineMs = command.deadlineMs;
+  const record = appendRecord(state, queueId, {
+    kind: "work-scheduled",
+    workId: work.workId,
+    commandId: command.commandId,
+    scheduleId: command.scheduleId,
+    scheduleAtMs: command.scheduleAtMs,
+    runAtMs: command.runAtMs,
+    notBeforeMs: command.notBeforeMs,
+    deadlineMs: command.deadlineMs,
+    reason: command.reason,
+    recordedAtMs: nowMs
+  });
+  return [
+    recordEvent(record),
+    statusEvent(queueId, "command-accepted", nowMs, {
+      workId: work.workId,
+      commandId: command.commandId,
+      recordSeq: record.recordSeq
+    })
+  ];
+}
+function expireLeases(queueId, state, command, nowMs) {
+  const workIds = new Set(command.workIds ?? []);
+  const limit = positiveLimit(command.limit ?? Number.MAX_SAFE_INTEGER);
+  const expired = [...state.works.values()].filter(
+    (work) => work.state === "leased" && work.leaseExpiresAtMs !== void 0 && work.leaseExpiresAtMs <= nowMs
+  ).filter((work) => workIds.size === 0 || workIds.has(work.workId)).slice(0, limit);
+  if (expired.length === 0)
+    return [statusEvent(queueId, "maintenance-noop", nowMs, { commandId: command.commandId })];
+  const events = [];
+  for (const work of expired) {
+    events.push(...materializeLeaseExpired(queueId, state, work, command.commandId, nowMs));
+  }
+  events.push(
+    statusEvent(queueId, "maintenance-applied", nowMs, {
+      commandId: command.commandId,
+      details: { expired: expired.length }
+    })
+  );
+  return events;
+}
+function currentLease(queueId, state, command, nowMs) {
+  const work = state.works.get(command.workId);
+  if (work === void 0)
+    return { issue: issueEvent(queueId, "unknown-work", "unknown work", nowMs, command) };
+  if (isTerminal(work.state))
+    return { issue: issueEvent(queueId, "terminal-work", "work is terminal", nowMs, command) };
+  if (work.state !== "leased")
+    return {
+      issue: issueEvent(queueId, "lease-not-current", "work is not leased", nowMs, command)
+    };
+  if (work.leaseId !== command.leaseId)
+    return { issue: issueEvent(queueId, "stale-lease", "lease is not current", nowMs, command) };
+  if (work.attempt !== command.attempt)
+    return { issue: issueEvent(queueId, "attempt-mismatch", "attempt mismatch", nowMs, command) };
+  if (work.workerId !== command.workerId)
+    return { issue: issueEvent(queueId, "worker-mismatch", "worker mismatch", nowMs, command) };
+  if (isExpiredLease(work, nowMs))
+    return {
+      events: materializeLeaseExpired(queueId, state, work, command.commandId, nowMs, {
+        command,
+        code: "lease-expired",
+        message: "lease expired"
+      })
+    };
+  return { work };
+}
+function availablePage(state, params) {
+  const limit = positiveLimit(params.limit ?? 100);
+  const orderByWorkId = params.afterWorkId !== void 0 && params.afterAdmissionSeq === void 0;
+  const all = [...state.works.values()].filter((work) => isReadyForProjection(work, params.nowMs)).filter((work) => params.afterWorkId === void 0 || work.workId > params.afterWorkId).filter(
+    (work) => params.afterAdmissionSeq === void 0 || work.admissionSeq > params.afterAdmissionSeq
+  ).sort(
+    (a, b) => orderByWorkId ? a.workId.localeCompare(b.workId) : a.admissionSeq - b.admissionSeq || a.workId.localeCompare(b.workId)
+  );
+  const items = all.map((work) => ({
+    workId: work.workId,
+    state: work.state,
+    payload: work.payload,
+    admissionSeq: work.admissionSeq,
+    priority: work.priority,
+    tags: work.tags,
+    requirements: work.requirements,
+    notBeforeMs: work.notBeforeMs,
+    retryAtMs: work.retryAtMs,
+    deadlineMs: work.deadlineMs
+  }));
+  const page = items.slice(0, limit);
+  return {
+    items: page,
+    ...items.length > limit && page.length > 0 ? { nextAfterWorkId: page[page.length - 1]?.workId } : {},
+    ...items.length > limit && page.length > 0 ? { nextAfterAdmissionSeq: page[page.length - 1]?.admissionSeq } : {},
+    hasMore: items.length > limit,
+    asOfRecordSeq: state.recordSeq
+  };
+}
+function workSnapshot(state, workId) {
+  const work = state.works.get(workId);
+  return {
+    workId,
+    state: work?.state,
+    payload: work?.payload,
+    ...work?.state !== "leased" || work.leaseId === void 0 ? {} : {
+      activeLease: {
+        leaseId: work.leaseId,
+        attempt: work.attempt,
+        workerId: work.workerId,
+        leaseExpiresAtMs: work.leaseExpiresAtMs
+      }
+    },
+    records: state.records.filter((record) => record.workId === workId),
+    asOfRecordSeq: state.recordSeq
+  };
+}
+function materializeLeaseExpired(queueId, state, work, commandId, nowMs, rejection) {
+  const record = appendRecord(state, queueId, {
+    kind: "lease-expired",
+    workId: work.workId,
+    ...commandId === void 0 ? {} : { commandId },
+    leaseId: work.leaseId,
+    attempt: work.attempt,
+    workerId: work.workerId,
+    leaseExpiresAtMs: work.leaseExpiresAtMs,
+    expiredAtMs: nowMs,
+    recordedAtMs: nowMs
+  });
+  work.state = "ready";
+  clearLease(work);
+  const events = [recordEvent(record)];
+  if (rejection !== void 0) {
+    events.push(
+      ...rejectQueueCommand(
+        queueId,
+        rejection.command,
+        rejection.code,
+        rejection.message,
+        nowMs,
+        commandId
+      )
+    );
+  }
+  return events;
+}
+function isExpiredLease(work, nowMs) {
+  return work.state === "leased" && work.leaseExpiresAtMs !== void 0 && work.leaseExpiresAtMs <= nowMs;
+}
+function clearLease(work) {
+  work.leaseId = void 0;
+  work.workerId = void 0;
+  work.leaseExpiresAtMs = void 0;
+}
+function deadLetterPage(state, params) {
+  const limit = positiveLimit(params.limit ?? 100);
+  const entries = state.deadLetters.filter((record) => {
+    if (params.afterDeadLetterSeq !== void 0 && record.recordSeq <= params.afterDeadLetterSeq)
+      return false;
+    if (params.afterWorkId !== void 0 && (record.workId ?? "") <= params.afterWorkId)
+      return false;
+    return true;
+  });
+  const page = entries.slice(0, limit);
+  return {
+    entries: page,
+    ...entries.length > limit && page.length > 0 ? { nextAfterDeadLetterSeq: page[page.length - 1]?.recordSeq } : {},
+    hasMore: entries.length > limit,
+    asOfRecordSeq: state.recordSeq
+  };
+}
+function appendRecord(state, queueId, record) {
+  const full = { ...record, queueId, recordSeq: ++state.recordSeq };
+  state.records.push(full);
+  return full;
+}
+function recordEvent(record) {
+  return { kind: "record", record };
+}
+function statusEvent(queueId, kind, timestampMs, fields = {}) {
+  return {
+    kind: "status",
+    status: {
+      kind,
+      queueId,
+      timestampMs,
+      ...fields.workId === void 0 ? {} : { workId: fields.workId },
+      ...fields.commandId === void 0 ? {} : { commandId: fields.commandId },
+      ...fields.recordSeq === void 0 ? {} : { recordSeq: fields.recordSeq },
+      ...fields.asOfRecordSeq === void 0 ? {} : { asOfRecordSeq: fields.asOfRecordSeq },
+      ...fields.issueCode === void 0 ? {} : { issueCode: fields.issueCode },
+      ...fields.details === void 0 ? {} : { details: fields.details }
+    }
+  };
+}
+function issueEvent(queueId, code, message, timestampMs, details) {
+  return {
+    kind: "issue",
+    issue: {
+      kind: "issue",
+      code,
+      message,
+      severity: "error",
+      source: "workQueue",
+      details,
+      metadata: { queueId, timestampMs }
+    }
+  };
+}
+function rejectQueueCommand(queueId, command, code, message, nowMs, commandId = commandIdFrom(command)) {
+  return [
+    issueEvent(queueId, code, message, nowMs, command),
+    statusEvent(queueId, "command-rejected", nowMs, {
+      ...commandId === void 0 ? {} : { commandId },
+      issueCode: code
+    })
+  ];
+}
+function validateQueueCommand(queueId, command) {
+  if (!isObjectRecord(command))
+    return { code: "malformed-command", message: "command must be an object" };
+  if (typeof command.kind !== "string")
+    return { code: "malformed-command", message: "command kind is required" };
+  if (!isWorkQueueCommandKind(command.kind))
+    return { code: "malformed-command", message: `unknown command kind '${command.kind}'` };
+  if (typeof command.commandId !== "string" || command.commandId.length === 0)
+    return { code: "malformed-command", message: "commandId must be a non-empty string" };
+  if (command.queueId !== void 0 && command.queueId !== queueId)
+    return { code: "queue-mismatch", message: "command queueId does not match this queue" };
+  switch (command.kind) {
+    case "submit":
+      return command.payload === void 0 ? { code: "malformed-command", message: "submit payload is required" } : void 0;
+    case "claim":
+      if (typeof command.workerId !== "string" || command.workerId.length === 0)
+        return { code: "malformed-command", message: "claim workerId is required" };
+      if (command.limit !== void 0 && !isPositiveInteger(command.limit))
+        return { code: "malformed-command", message: "claim limit must be a positive integer" };
+      if (command.requestedWorkIds !== void 0 && (!Array.isArray(command.requestedWorkIds) || !command.requestedWorkIds.every((id) => typeof id === "string" && id.length > 0))) {
+        return { code: "malformed-command", message: "requestedWorkIds must be strings" };
+      }
+      if (command.leaseDurationMs !== void 0 && !isPositiveInteger(command.leaseDurationMs))
+        return {
+          code: "malformed-command",
+          message: "leaseDurationMs must be a positive integer"
+        };
+      return void 0;
+    case "renew-lease":
+      if (command.leaseDurationMs !== void 0 && !isPositiveInteger(command.leaseDurationMs))
+        return {
+          code: "malformed-command",
+          message: "leaseDurationMs must be a positive integer"
+        };
+      if (command.leaseExpiresAtMs !== void 0 && !isFiniteNumber(command.leaseExpiresAtMs))
+        return { code: "malformed-command", message: "leaseExpiresAtMs must be finite" };
+      return validateLeaseCommand(command);
+    case "release":
+    case "complete":
+    case "fail":
+      return validateLeaseCommand(command);
+    case "cancel":
+      return requiredString(command.workId, "workId");
+    case "schedule": {
+      const workIdError = requiredString(command.workId, "workId");
+      if (workIdError !== void 0) return workIdError;
+      if (!isFiniteNumber(command.notBeforeMs))
+        return { code: "malformed-command", message: "notBeforeMs must be finite" };
+      if (command.deadlineMs !== void 0 && !isFiniteNumber(command.deadlineMs))
+        return { code: "malformed-command", message: "deadlineMs must be finite" };
+      return void 0;
+    }
+    case "expire-leases":
+      if (command.limit !== void 0 && !isPositiveInteger(command.limit))
+        return {
+          code: "malformed-command",
+          message: "expire-leases limit must be a positive integer"
+        };
+      if (command.workIds !== void 0 && (!Array.isArray(command.workIds) || !command.workIds.every((id) => typeof id === "string" && id.length > 0))) {
+        return { code: "malformed-command", message: "workIds must be strings" };
+      }
+      return void 0;
+  }
+}
+function validateLeaseCommand(command) {
+  for (const key of ["workId", "leaseId", "workerId"]) {
+    const err = requiredString(command[key], key);
+    if (err !== void 0) return err;
+  }
+  if (!isPositiveInteger(command.attempt))
+    return { code: "malformed-command", message: "attempt must be a positive integer" };
+  return void 0;
+}
+function requiredString(value, name) {
+  return typeof value === "string" && value.length > 0 ? void 0 : { code: "malformed-command", message: `${name} must be a non-empty string` };
+}
+function commandIdFrom(command) {
+  return isObjectRecord(command) && typeof command.commandId === "string" ? command.commandId : void 0;
+}
+function isWorkQueueCommandKind(kind) {
+  return kind === "submit" || kind === "claim" || kind === "renew-lease" || kind === "release" || kind === "complete" || kind === "fail" || kind === "cancel" || kind === "schedule" || kind === "expire-leases";
+}
+function isObjectRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPositiveInteger(value) {
+  return Number.isInteger(value) && value > 0;
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function publishQueueCommand(node, command) {
+  node.down([["DATA", command]]);
+  return command;
+}
+var commandSeq = 0;
+function nextCommandId(queueId, kind) {
+  commandSeq += 1;
+  return `${queueId}:${kind}:${commandSeq}`;
+}
+function isReady(work, nowMs) {
+  if (work.state === "scheduled")
+    return work.notBeforeMs !== void 0 && work.notBeforeMs <= nowMs;
+  if (work.state === "retry-wait") return work.retryAtMs !== void 0 && work.retryAtMs <= nowMs;
+  return work.state === "ready";
+}
+function isReadyForProjection(work, nowMs) {
+  if (work.state === "scheduled" || work.state === "retry-wait") {
+    return nowMs === void 0 ? false : isReady(work, nowMs);
+  }
+  return isReady(work, 0);
+}
+function isTerminal(state) {
+  return state === "completed" || state === "canceled" || state === "dead-lettered";
+}
+function payloadAsRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function numberOrUndefined(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function stringArrayOrUndefined(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : void 0;
+}
+function pullParams(pull) {
+  return typeof pull?.params === "object" && pull.params !== null && !Array.isArray(pull.params) ? pull.params : {};
+}
+var SUBMIT_ENVELOPE = "__graphreflyWorkQueueSubmit";
+function submitPayload(payload, meta) {
+  if (Object.keys(meta).length === 0) return payload;
+  return { [SUBMIT_ENVELOPE]: true, payload, ...meta };
+}
+function decodeSubmittedPayload(payload) {
+  if (isObjectRecord(payload) && payload[SUBMIT_ENVELOPE] === true && Object.hasOwn(payload, "payload")) {
+    const { payload: inner, [SUBMIT_ENVELOPE]: _tag, ...meta } = payload;
+    return { payload: inner, meta };
+  }
+  return { payload, meta: payloadAsRecord(payload) };
+}
+function commandNowMs(command, fallback) {
+  return typeof command.nowMs === "number" && Number.isFinite(command.nowMs) ? command.nowMs : fallback;
+}
+function positiveLimit(limit) {
+  if (!Number.isInteger(limit) || limit < 1)
+    throw new Error("workQueue: limit must be a positive integer");
+  return limit;
+}
+function assertNonEmpty(value, owner) {
+  if (typeof value !== "string" || value.length === 0)
+    throw new Error(`${owner} must be a non-empty string`);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  workQueue
+});
+//# sourceMappingURL=index.cjs.map