@ultimat3/jobs 1.0.0

package/src/driver.ts

@@ -0,0 +1,143 @@
+// The queue contract. Every driver (pg, memory, redis, nats) implements exactly this, so
+// switching backends is a config line and ZERO job-code change. Six methods and no more:
+// claim/ack/nack with a visibility timeout is the smallest set that survives a worker crash.
+
+import type { StepStore } from './steps';
+
+export type JobState = 'ready' | 'delayed' | 'running' | 'suspended' | 'done' | 'failed' | 'dead';
+
+export interface JobRecord {
+  readonly id: string;
+  readonly name: string;
+  readonly queue: string;
+  readonly input: unknown;
+  /** Dedupe key from the job definition. At-least-once delivery leans on this. */
+  readonly idempotencyKey: string;
+  /** Stable across retries and suspensions — the key every step record hangs off. */
+  readonly runId: string;
+  readonly attempt: number;
+  readonly maxAttempts: number;
+  readonly state: JobState;
+  /** Epoch ms; the job is invisible until then. */
+  readonly runAt: number;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+  /** Actor's orgId, for per-tenant limits. */
+  readonly tenantId?: string;
+  readonly lastError?: string;
+  readonly claimedBy?: string;
+  readonly visibleAt?: number;
+}
+
+export type ConflictPolicy = 'dedupe' | 'error';
+
+export interface EnqueueRequest {
+  readonly name: string;
+  readonly queue: string;
+  readonly input: unknown;
+  readonly idempotencyKey: string;
+  readonly maxAttempts: number;
+  /** Epoch ms. Omit for "now". */
+  readonly runAt?: number;
+  readonly tenantId?: string;
+  /** Reuse an existing run id when resuming, so step history is preserved. */
+  readonly runId?: string;
+  readonly onConflict?: ConflictPolicy;
+}
+
+export interface EnqueueResult {
+  readonly id: string;
+  readonly runId: string;
+  /** True when an in-flight job already held this idempotency key. */
+  readonly deduped: boolean;
+}
+
+export interface ClaimOptions {
+  readonly queues: readonly string[];
+  readonly limit: number;
+  /** Lease length. A worker that dies without ack makes the job claimable again after this. */
+  readonly visibilityTimeoutMs: number;
+  readonly workerId: string;
+}
+
+export interface ClaimedJob extends JobRecord {
+  readonly claimedAt: number;
+  readonly visibleAt: number;
+}
+
+export interface NackOptions {
+  /** Delay before the job becomes claimable again. */
+  readonly delayMs: number;
+  readonly error?: string;
+  /**
+   * False for a suspension (`step.sleep`): parking a run is not a failure and must not burn
+   * a retry attempt, or a 3-day sleep would dead-letter the job.
+   */
+  readonly countsAsAttempt?: boolean;
+  readonly deadLetter?: boolean;
+}
+
+export interface QueueStats {
+  readonly queue: string;
+  readonly ready: number;
+  readonly delayed: number;
+  readonly running: number;
+  readonly suspended: number;
+  readonly dead: number;
+  /** Age in ms of the oldest claimable job — the number that decides autoscaling. */
+  readonly oldestReadyMs: number;
+}
+
+export interface JobFilter {
+  readonly queue?: string;
+  readonly name?: string;
+  readonly state?: JobState;
+  readonly limit?: number;
+}
+
+/** Optional: powers `/_x` and the MCP tools. A minimal driver may omit it. */
+export interface JobIntrospection {
+  job(jobId: string): Promise<JobRecord | undefined>;
+  list(filter?: JobFilter): Promise<readonly JobRecord[]>;
+  deadLetters(limit?: number): Promise<readonly JobRecord[]>;
+  /** Re-queue a dead/failed job. `fromStep` drops step records from that step onward. */
+  requeue(jobId: string, options?: { readonly fromStep?: string }): Promise<JobRecord>;
+}
+
+export interface JobDriver {
+  readonly name: string;
+  /** Step persistence lives with the queue: one store, one transaction boundary. */
+  readonly steps: StepStore;
+  enqueue(request: EnqueueRequest): Promise<EnqueueResult>;
+  claim(options: ClaimOptions): Promise<readonly ClaimedJob[]>;
+  ack(jobId: string): Promise<void>;
+  nack(jobId: string, options: NackOptions): Promise<void>;
+  /** Extends the lease of a long-running job so it is not double-claimed. */
+  heartbeat(jobId: string, options: { readonly visibilityTimeoutMs: number }): Promise<void>;
+  stats(): Promise<readonly QueueStats[]>;
+  readonly introspect?: JobIntrospection;
+  close?(): Promise<void>;
+}
+
+export const DEFAULT_QUEUE = 'default';
+export const DEFAULT_VISIBILITY_TIMEOUT_MS = 30_000;
+
+let ambient: JobDriver | undefined;
+
+/** Set once at boot from `app.config.ts`. Roles share one driver instance per process. */
+export function setJobDriver(driver: JobDriver): void {
+  ambient = driver;
+}
+
+export function jobDriver(): JobDriver | undefined {
+  return ambient;
+}
+
+/**
+ * Test/CLI seam: forget the ambient driver. The counterpart to `resetMailDriver()` — a test
+ * that installs a queue has to be able to put the process back, or every later file in the
+ * same bun process silently enqueues where it meant to run inline.
+ */
+export function resetJobDriver(): void {
+  ambient = undefined;
+}

package/src/errors.d.ts

@@ -0,0 +1,63 @@
+import { UltimateError } from '@ultimat3/core';
+export declare const JOB_ERROR_CODES: readonly ['X_JOB_DUPLICATE', 'X_STEP_DUPLICATE', 'X_JOB_TIMEOUT', 'X_JOB_MAX_ATTEMPTS', 'X_DRIVER_UNAVAILABLE', 'X_IDEMPOTENCY_REQUIRED', 'X_OUTBOX_NO_TX', 'X_NOT_IMPLEMENTED'];
+export type JobErrorCode = (typeof JOB_ERROR_CODES)[number];
+/** An enqueue collided with a live job holding the same idempotency key under `onConflict: 'error'`. */
+export declare class JobDuplicateError extends UltimateError {
+    constructor(input: {
+        job: string;
+        idempotencyKey: string;
+        existingId: string;
+    });
+}
+/** Two steps in one run share a name, so replay cannot tell their persisted results apart. */
+export declare class StepDuplicateError extends UltimateError {
+    constructor(input: {
+        job: string;
+        step: string;
+    });
+}
+export declare class JobTimeoutError extends UltimateError {
+    constructor(input: {
+        job: string;
+        timeoutMs: number;
+        step?: string;
+    });
+}
+/** Retries exhausted. The job is in the dead-letter queue, not lost. */
+export declare class JobMaxAttemptsError extends UltimateError {
+    constructor(input: {
+        job: string;
+        jobId: string;
+        attempts: number;
+        lastError: string;
+    });
+}
+export declare class DriverUnavailableError extends UltimateError {
+    constructor(input: {
+        driver: string;
+        cause: string;
+        fix: string;
+    });
+}
+/**
+ * The type signature already requires `idempotencyKey`; this is the runtime backstop for
+ * generated code and JS callers, so the guarantee holds at both ends.
+ */
+export declare class IdempotencyRequiredError extends UltimateError {
+    constructor(input: {
+        job: string;
+    });
+}
+/** An outbox enqueue happened with no ambient transaction to join. */
+export declare class OutboxNoTxError extends UltimateError {
+    constructor(input: {
+        job: string;
+    });
+}
+export declare class JobsNotImplementedError extends UltimateError {
+    constructor(input: {
+        feature: string;
+        fix: string;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,eAAO,MAAM,eAAe,YAC1B,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,mBAAmB,CACX,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAI5D,wGAAwG;AACxG,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,YAAY,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAO7E;CACF;AAED,8FAA8F;AAC9F,qBAAa,kBAAmB,SAAQ,aAAa;IACnD,YAAY,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAO/C;CACF;AAED,qBAAa,eAAgB,SAAQ,aAAa;IAChD,YAAY,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAUnE;CACF;AAED,wEAAwE;AACxE,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,YAAY,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAOrF;CACF;AAED,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,YAAY,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAOhE;CACF;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;IACzD,YAAY,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EAOjC;CACF;AAED,sEAAsE;AACtE,qBAAa,eAAgB,SAAQ,aAAa;IAChD,YAAY,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EAOjC;CACF;AAED,qBAAa,uBAAwB,SAAQ,aAAa;IACxD,YAAY,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAOlD;CACF"}

package/src/errors.js

@@ -0,0 +1,105 @@
+// The X_* codes owned by @ultimat3/jobs. Every one names the command or code change that
+// fixes it — a job failure an agent cannot act on is a job failure that gets retried forever.
+import { UltimateError } from '@ultimat3/core';
+export const JOB_ERROR_CODES = [
+    'X_JOB_DUPLICATE',
+    'X_STEP_DUPLICATE',
+    'X_JOB_TIMEOUT',
+    'X_JOB_MAX_ATTEMPTS',
+    'X_DRIVER_UNAVAILABLE',
+    'X_IDEMPOTENCY_REQUIRED',
+    'X_OUTBOX_NO_TX',
+    'X_NOT_IMPLEMENTED',
+];
+const docsFor = (code) => `https://ultimate.dev/errors/${code}`;
+/** An enqueue collided with a live job holding the same idempotency key under `onConflict: 'error'`. */
+export class JobDuplicateError extends UltimateError {
+    constructor(input) {
+        super({
+            code: 'X_JOB_DUPLICATE',
+            cause: `job "${input.job}" already queued as ${input.existingId} with idempotencyKey "${input.idempotencyKey}"`,
+            fix: 'pass onConflict: "dedupe" to enqueue, or make idempotencyKey narrower',
+            docs: docsFor('X_JOB_DUPLICATE'),
+        });
+    }
+}
+/** Two steps in one run share a name, so replay cannot tell their persisted results apart. */
+export class StepDuplicateError extends UltimateError {
+    constructor(input) {
+        super({
+            code: 'X_STEP_DUPLICATE',
+            cause: `job "${input.job}" used step name "${input.step}" twice in one run`,
+            fix: `rename one of them, e.g. step.run('${input.step}-2', ...) — step names are the replay key`,
+            docs: docsFor('X_STEP_DUPLICATE'),
+        });
+    }
+}
+export class JobTimeoutError extends UltimateError {
+    constructor(input) {
+        super({
+            code: 'X_JOB_TIMEOUT',
+            cause: input.step === undefined
+                ? `job "${input.job}" exceeded its ${input.timeoutMs}ms timeout`
+                : `job "${input.job}" step "${input.step}" exceeded its ${input.timeoutMs}ms timeout`,
+            fix: `raise timeout on the job definition, or split the work into step.run() calls`,
+            docs: docsFor('X_JOB_TIMEOUT'),
+        });
+    }
+}
+/** Retries exhausted. The job is in the dead-letter queue, not lost. */
+export class JobMaxAttemptsError extends UltimateError {
+    constructor(input) {
+        super({
+            code: 'X_JOB_MAX_ATTEMPTS',
+            cause: `job "${input.job}" failed ${input.attempts} times, last error: ${input.lastError}`,
+            fix: `x jobs retry ${input.jobId}`,
+            docs: docsFor('X_JOB_MAX_ATTEMPTS'),
+        });
+    }
+}
+export class DriverUnavailableError extends UltimateError {
+    constructor(input) {
+        super({
+            code: 'X_DRIVER_UNAVAILABLE',
+            cause: `jobs driver "${input.driver}" is unavailable: ${input.cause}`,
+            fix: input.fix,
+            docs: docsFor('X_DRIVER_UNAVAILABLE'),
+        });
+    }
+}
+/**
+ * The type signature already requires `idempotencyKey`; this is the runtime backstop for
+ * generated code and JS callers, so the guarantee holds at both ends.
+ */
+export class IdempotencyRequiredError extends UltimateError {
+    constructor(input) {
+        super({
+            code: 'X_IDEMPOTENCY_REQUIRED',
+            cause: `job "${input.job}" has no idempotencyKey — at-least-once delivery would run it twice`,
+            fix: `add idempotencyKey: (input) => \`${input.job}:\${input.id}\` to the job definition`,
+            docs: docsFor('X_IDEMPOTENCY_REQUIRED'),
+        });
+    }
+}
+/** An outbox enqueue happened with no ambient transaction to join. */
+export class OutboxNoTxError extends UltimateError {
+    constructor(input) {
+        super({
+            code: 'X_OUTBOX_NO_TX',
+            cause: `ctx.jobs.enqueue(${input.job}) ran outside a transaction with outbox: 'required'`,
+            fix: 'wrap the call in ctx.tx(async (tx) => ...), or enqueue with { outbox: false }',
+            docs: docsFor('X_OUTBOX_NO_TX'),
+        });
+    }
+}
+export class JobsNotImplementedError extends UltimateError {
+    constructor(input) {
+        super({
+            code: 'X_NOT_IMPLEMENTED',
+            cause: `${input.feature} is declared but not implemented in @ultimat3/jobs`,
+            fix: input.fix,
+            docs: docsFor('X_NOT_IMPLEMENTED'),
+        });
+    }
+}
+//# sourceMappingURL=errors.js.map

package/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"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"}

package/src/errors.ts

@@ -0,0 +1,165 @@
+// The X_* codes owned by @ultimat3/jobs. Every one names the command or code change that
+// fixes it — a job failure an agent cannot act on is a job failure that gets retried forever.
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const JOB_OWNED_ERROR_CODES = [
+  'X_JOB_DUPLICATE',
+  'X_STEP_DUPLICATE',
+  'X_JOB_TIMEOUT',
+  'X_JOB_MAX_ATTEMPTS',
+  'X_DRIVER_UNAVAILABLE',
+  'X_IDEMPOTENCY_REQUIRED',
+  'X_OUTBOX_NO_TX',
+] as const;
+
+/**
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `JobsNotImplementedError` below throws it; jobs keeps
+ * no title for it, because the copy this file used to hold was a second title that nothing would
+ * have failed on once core's changed.
+ */
+export const JOB_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
+
+/** Every code jobs can throw: the ones it owns plus the one it borrows. */
+export const JOB_ERROR_CODES = [...JOB_OWNED_ERROR_CODES, ...JOB_BORROWED_ERROR_CODES] as const;
+
+export type JobOwnedErrorCode = (typeof JOB_OWNED_ERROR_CODES)[number];
+export type JobErrorCode = (typeof JOB_ERROR_CODES)[number];
+
+export const JOB_ERROR_TITLES: Readonly<Record<JobOwnedErrorCode, string>> = {
+  X_JOB_DUPLICATE: 'a live key already has a job',
+  X_STEP_DUPLICATE: 'two step.run calls share a name',
+  X_JOB_TIMEOUT: 'a job exceeded its wall-clock limit',
+  X_JOB_MAX_ATTEMPTS: 'the job exhausted its retries',
+  X_DRIVER_UNAVAILABLE: 'the queue driver is unreachable',
+  X_IDEMPOTENCY_REQUIRED: 'the job has no idempotencyKey',
+  X_OUTBOX_NO_TX: 'enqueue outside a transaction',
+};
+
+// One unconditional call, so a second package claiming one of jobs' codes throws
+// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(JOB_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+const docsFor = (code: JobErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/** An enqueue collided with a live job holding the same idempotency key under `onConflict: 'error'`. */
+export class JobDuplicateError extends UltimateError {
+  constructor(input: { job: string; idempotencyKey: string; existingId: string }) {
+    super({
+      code: 'X_JOB_DUPLICATE',
+      cause: `job "${input.job}" already queued as ${input.existingId} with idempotencyKey "${input.idempotencyKey}"`,
+      fix: 'pass onConflict: "dedupe" to enqueue, or make idempotencyKey narrower',
+      docs: docsFor('X_JOB_DUPLICATE'),
+    });
+  }
+}
+
+/**
+ * Two things claim one durable name — two definitions setting the same `name:`, two handles under
+ * one export name, or one handle exported twice. Shares `X_JOB_DUPLICATE` with the enqueue-time
+ * collision because it is the same statement — this key already belongs to another job — caught
+ * one stage earlier. Left unrefused, the second claim would silently take over delivery of every
+ * row already queued under the first.
+ *
+ * The `fix` names the edit and the command that shows what is already seated. It cannot name a
+ * file: the registry holds handles, not source locations, and `name` is all a handle carries.
+ */
+export class JobNameTakenError extends UltimateError {
+  constructor(input: { kind: 'job' | 'task'; name: string }) {
+    super({
+      code: 'X_JOB_DUPLICATE',
+      cause: `two ${input.kind}s claim the name "${input.name}"`,
+      fix: `x jobs ls --json names the one already seated; rename the other's export, or its "name:" if it declares one — a ${input.kind} name is a durable queue key and is globally unique`,
+      docs: docsFor('X_JOB_DUPLICATE'),
+    });
+  }
+}
+
+/** Two steps in one run share a name, so replay cannot tell their persisted results apart. */
+export class StepDuplicateError extends UltimateError {
+  constructor(input: { job: string; step: string }) {
+    super({
+      code: 'X_STEP_DUPLICATE',
+      cause: `job "${input.job}" used step name "${input.step}" twice in one run`,
+      fix: `rename one of them, e.g. step.run('${input.step}-2', ...) — step names are the replay key`,
+      docs: docsFor('X_STEP_DUPLICATE'),
+    });
+  }
+}
+
+export class JobTimeoutError extends UltimateError {
+  constructor(input: { job: string; timeoutMs: number; step?: string }) {
+    super({
+      code: 'X_JOB_TIMEOUT',
+      cause:
+        input.step === undefined
+          ? `job "${input.job}" exceeded its ${input.timeoutMs}ms timeout`
+          : `job "${input.job}" step "${input.step}" exceeded its ${input.timeoutMs}ms timeout`,
+      fix: `raise timeout on the job definition, or split the work into step.run() calls`,
+      docs: docsFor('X_JOB_TIMEOUT'),
+    });
+  }
+}
+
+/** Retries exhausted. The job is in the dead-letter queue, not lost. */
+export class JobMaxAttemptsError extends UltimateError {
+  constructor(input: { job: string; jobId: string; attempts: number; lastError: string }) {
+    super({
+      code: 'X_JOB_MAX_ATTEMPTS',
+      cause: `job "${input.job}" failed ${input.attempts} times, last error: ${input.lastError}`,
+      fix: `x jobs retry ${input.jobId}`,
+      docs: docsFor('X_JOB_MAX_ATTEMPTS'),
+    });
+  }
+}
+
+export class DriverUnavailableError extends UltimateError {
+  constructor(input: { driver: string; cause: string; fix: string }) {
+    super({
+      code: 'X_DRIVER_UNAVAILABLE',
+      cause: `jobs driver "${input.driver}" is unavailable: ${input.cause}`,
+      fix: input.fix,
+      docs: docsFor('X_DRIVER_UNAVAILABLE'),
+    });
+  }
+}
+
+/**
+ * The type signature already requires `idempotencyKey`; this is the runtime backstop for
+ * generated code and JS callers, so the guarantee holds at both ends.
+ */
+export class IdempotencyRequiredError extends UltimateError {
+  constructor(input: { job: string }) {
+    super({
+      code: 'X_IDEMPOTENCY_REQUIRED',
+      cause: `job "${input.job}" has no idempotencyKey — at-least-once delivery would run it twice`,
+      fix: `add idempotencyKey: (input) => \`${input.job}:\${input.id}\` to the job definition`,
+      docs: docsFor('X_IDEMPOTENCY_REQUIRED'),
+    });
+  }
+}
+
+/** An outbox enqueue happened with no ambient transaction to join. */
+export class OutboxNoTxError extends UltimateError {
+  constructor(input: { job: string }) {
+    super({
+      code: 'X_OUTBOX_NO_TX',
+      cause: `ctx.jobs.enqueue(${input.job}) ran outside a transaction with outbox: 'required'`,
+      fix: 'wrap the call in ctx.tx(async (tx) => ...), or enqueue with { outbox: false }',
+      docs: docsFor('X_OUTBOX_NO_TX'),
+    });
+  }
+}
+
+export class JobsNotImplementedError extends UltimateError {
+  constructor(input: { feature: string; fix: string }) {
+    super({
+      code: 'X_NOT_IMPLEMENTED',
+      cause: `${input.feature} is declared but not implemented in @ultimat3/jobs`,
+      fix: input.fix,
+      docs: docsFor('X_NOT_IMPLEMENTED'),
+    });
+  }
+}

package/src/events.d.ts

@@ -0,0 +1,35 @@
+import type { Clock } from '@ultimat3/core';
+import type { DurationInput } from './clock';
+import type { EventLookup } from './steps';
+export interface JobEvent {
+    readonly id: string;
+    readonly name: string;
+    readonly payload: unknown;
+    /** Ties the event to one waiting run — usually an entity id. */
+    readonly correlationKey?: string;
+    readonly publishedAt: number;
+    readonly expiresAt: number;
+}
+export interface PublishOptions {
+    readonly correlationKey?: string;
+    /** How long the event stays matchable. Default 7d — longer than any sane wait. */
+    readonly ttl?: DurationInput;
+}
+export interface EventBus extends EventLookup {
+    publish(name: string, payload: unknown, options?: PublishOptions): Promise<JobEvent>;
+    list(name?: string): Promise<readonly JobEvent[]>;
+    purgeExpired(): number;
+    size(): number;
+}
+export interface MemoryEventBusOptions {
+    readonly clock?: Clock;
+    readonly defaultTtl?: DurationInput;
+    readonly maxEvents?: number;
+}
+export declare function createMemoryEventBus(options?: MemoryEventBusOptions): EventBus;
+/** Swapped at boot for the NATS/Redis-streams bus in a multi-node deployment. */
+export declare function setEventBus(bus: EventBus): void;
+export declare function eventBus(): EventBus;
+/** The one function app code calls to unblock a waiting step. */
+export declare function publishEvent(name: string, payload: unknown, options?: PublishOptions): Promise<JobEvent>;
+//# sourceMappingURL=events.d.ts.map

package/src/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["events.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,kFAAkF;IAClF,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,QAAS,SAAQ,WAAW;IAC3C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrF,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;IAClD,YAAY,IAAI,MAAM,CAAC;IACvB,IAAI,IAAI,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,QAAQ,CA0ElF;AAID,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAE/C;AAED,wBAAgB,QAAQ,IAAI,QAAQ,CAEnC;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,QAAQ,CAAC,CAEnB"}

package/src/events.js

@@ -0,0 +1,92 @@
+// The event bus `step.waitForEvent` consumes. Events are stored, not just broadcast: a step
+// that suspends at 12:00 and resumes at 12:00:30 must still see an event published at
+// 12:00:10, so a fire-and-forget emitter would silently strand every waiting run.
+import { logger, systemClock, uuid } from '@ultimat3/core';
+import { nowMs, toMs } from './clock';
+export function createMemoryEventBus(options = {}) {
+    const clock = options.clock ?? systemClock;
+    const defaultTtl = options.defaultTtl ?? 604_800_000;
+    const maxEvents = options.maxEvents ?? 10_000;
+    const events = new Map();
+    const purgeExpired = () => {
+        const at = nowMs(clock);
+        let removed = 0;
+        for (const [id, event] of events) {
+            if (event.expiresAt <= at) {
+                events.delete(id);
+                removed += 1;
+            }
+        }
+        return removed;
+    };
+    return {
+        publish(name, payload, publishOptions = {}) {
+            purgeExpired();
+            const at = nowMs(clock);
+            const event = {
+                id: uuid(),
+                name,
+                payload,
+                publishedAt: at,
+                expiresAt: at + toMs(publishOptions.ttl ?? defaultTtl),
+                ...(publishOptions.correlationKey === undefined
+                    ? {}
+                    : { correlationKey: publishOptions.correlationKey }),
+            };
+            events.set(event.id, event);
+            while (events.size > maxEvents) {
+                const oldest = events.keys().next();
+                if (oldest.done === true)
+                    break;
+                events.delete(oldest.value);
+            }
+            logger.debug('jobs.event.published', {
+                event: name,
+                correlationKey: publishOptions.correlationKey ?? null,
+            });
+            return Promise.resolve(event);
+        },
+        /**
+         * Earliest matching event at or after `afterMs`, so a resumed step consumes events in
+         * publication order rather than jumping to the newest one.
+         */
+        find(name, correlationKey, afterMs) {
+            const at = nowMs(clock);
+            let best;
+            for (const event of events.values()) {
+                if (event.name !== name)
+                    continue;
+                if (event.expiresAt <= at)
+                    continue;
+                if (event.publishedAt < afterMs)
+                    continue;
+                if (correlationKey !== undefined && event.correlationKey !== correlationKey)
+                    continue;
+                if (best === undefined || event.publishedAt < best.publishedAt)
+                    best = event;
+            }
+            return Promise.resolve(best === undefined ? undefined : { payload: best.payload, publishedAt: best.publishedAt });
+        },
+        list(name) {
+            const all = [...events.values()]
+                .filter((event) => name === undefined || event.name === name)
+                .sort((a, b) => a.publishedAt - b.publishedAt);
+            return Promise.resolve(all);
+        },
+        purgeExpired,
+        size: () => events.size,
+    };
+}
+let ambientBus = createMemoryEventBus();
+/** Swapped at boot for the NATS/Redis-streams bus in a multi-node deployment. */
+export function setEventBus(bus) {
+    ambientBus = bus;
+}
+export function eventBus() {
+    return ambientBus;
+}
+/** The one function app code calls to unblock a waiting step. */
+export function publishEvent(name, payload, options) {
+    return ambientBus.publish(name, payload, options);
+}
+//# sourceMappingURL=events.js.map

package/src/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["events.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,sFAAsF;AACtF,kFAAkF;AAGlF,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAgCtC,MAAM,UAAU,oBAAoB,CAAC,OAAO,GAA0B,EAAE;IACtE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC;IAC3C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,WAAW,CAAC;IACrD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE3C,MAAM,YAAY,GAAG,GAAW,EAAE;QAChC,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;YACjC,IAAI,KAAK,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;gBAC1B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAClB,OAAO,IAAI,CAAC,CAAC;YACf,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO;QACL,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,EAAE;YACxC,YAAY,EAAE,CAAC;YACf,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;YACxB,MAAM,KAAK,GAAa;gBACtB,EAAE,EAAE,IAAI,EAAE;gBACV,IAAI;gBACJ,OAAO;gBACP,WAAW,EAAE,EAAE;gBACf,SAAS,EAAE,EAAE,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,IAAI,UAAU,CAAC;gBACtD,GAAG,CAAC,cAAc,CAAC,cAAc,KAAK,SAAS;oBAC7C,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,cAAc,EAAE,cAAc,CAAC,cAAc,EAAE,CAAC;aACvD,CAAC;YACF,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YAC5B,OAAO,MAAM,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;gBACpC,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;oBAAE,MAAM;gBAChC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC9B,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,sBAAsB,EAAE;gBACnC,KAAK,EAAE,IAAI;gBACX,cAAc,EAAE,cAAc,CAAC,cAAc,IAAI,IAAI;aACtD,CAAC,CAAC;YACH,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QAED;;;WAGG;QACH,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO;YAChC,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;YACxB,IAAI,IAA0B,CAAC;YAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;gBACpC,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI;oBAAE,SAAS;gBAClC,IAAI,KAAK,CAAC,SAAS,IAAI,EAAE;oBAAE,SAAS;gBACpC,IAAI,KAAK,CAAC,WAAW,GAAG,OAAO;oBAAE,SAAS;gBAC1C,IAAI,cAAc,KAAK,SAAS,IAAI,KAAK,CAAC,cAAc,KAAK,cAAc;oBAAE,SAAS;gBACtF,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW;oBAAE,IAAI,GAAG,KAAK,CAAC;YAC/E,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,CACpB,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAC1F,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,IAAI;YACP,MAAM,GAAG,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;iBAC7B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;iBAC5D,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;YACjD,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;QAED,YAAY;QACZ,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI;KACxB,CAAC;AACJ,CAAC;AAED,IAAI,UAAU,GAAa,oBAAoB,EAAE,CAAC;AAElD,iFAAiF;AACjF,MAAM,UAAU,WAAW,CAAC,GAAa;IACvC,UAAU,GAAG,GAAG,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,OAAgB,EAChB,OAAwB;IAExB,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC"}