@ultimat3/jobs 30.9.0 → 31.0.0

package/src/index.ts

@@ -20,36 +20,28 @@ export type {
   BackfillInput,
   BackfillPage,
   BackfillPages,
-  BackfillReport,
   ScopedBackfillDefinition,
   ScopedBackfillInput,
 } from './backfill';
 export { backfill, DEFAULT_BACKFILL_BATCH } from './backfill';
 export {
-  BackfillAppliedError,
-  BackfillEnvironmentError,
-  BackfillMigrationPendingError,
   BackfillPendingError,
   BackfillRunningError,
-  BackfillSourceInvalidError,
-  BackfillStalledError,
   BackfillUnknownError,
 } from './backfill-errors';
 export type { BackfillGate, BackfillGateInput } from './backfill-gate';
-export { checkBackfillEnvironment, gateBackfill } from './backfill-gate';
+export { gateBackfill } from './backfill-gate';
 export type { BackfillProgress } from './backfill-inspect';
-export { backfillForRun, inspectBackfills, toBackfillProgress } from './backfill-inspect';
+export { inspectBackfills, toBackfillProgress } from './backfill-inspect';
 export type {
   BackfillFilter,
   BackfillLedger,
   BackfillRun,
   BackfillStatus,
-  BackfillVerdict,
 } from './backfill-ledger';
 export {
   BACKFILL_STATUSES,
   backfillChecksum,
-  decideBackfill,
   isBackfillStatus,
   memoryBackfillLedger,
 } from './backfill-ledger';
@@ -78,48 +70,32 @@ export {
 } from './backfill-registry';
 export type { AnnounceExhaustedOptions, ExhaustedCounts } from './claim-exhausted';
 export { announceExhausted } from './claim-exhausted';
-export type { JobConcurrency, KeyedConcurrency, WhenBusy } from './concurrency';
-export { MAX_CONCURRENCY_KEY_LENGTH, WHEN_BUSY } from './concurrency';
+export type { JobConcurrency, KeyedConcurrency } from './concurrency';
 export { consumer } from './consumer';
-export { ConsumerInvalidError, ConsumerSelfEnqueueError } from './consumer-errors';
-export {
-  CONSUMER_LINGER_MS,
-  CONSUMER_PROGRESS_NOTE,
-  DEFAULT_CONSUMER_BATCH,
-} from './consumer-loop';
+export { CONSUMER_LINGER_MS } from './consumer-loop';
 // `stampConsumer` is deliberately absent, for the reason `stampBackfill` is.
 export type { ConsumerDeclaration, ConsumerRow } from './consumer-registry';
-export {
-  consumerDeclarationOf,
-  consumerRow,
-  isConsumer,
-  registeredConsumers,
-} from './consumer-registry';
+export { consumerRow, registeredConsumers } from './consumer-registry';
 export type {
-  ConsumerBatch,
   ConsumerCursor,
   ConsumerDefinition,
   ConsumerHandle,
   ConsumerInput,
-  ConsumerReport,
 } from './consumer-types';
 export type { JobConcurrencyDescriptor, JobDescriptor } from './describe';
 export type {
-  AckOptions,
   ClaimedJob,
   ClaimIdentity,
   ClaimOptions,
   ConflictPolicy,
   EnqueueRequest,
   EnqueueResult,
-  HeartbeatOptions,
   JobDriver,
   JobRecord,
   JobState,
   NackOptions,
   QueueDemand,
   QueueStats,
-  SettleBy,
 } from './driver';
 export {
   assertClaimBounds,
@@ -133,8 +109,6 @@ export {
   LEASE_LAPSED_FINAL_ATTEMPT,
   LIVE_STATES,
   nackState,
-  resetJobDriver,
-  setJobDriver,
 } from './driver';
 export type { MemoryJobDriver, MemoryJobDriverOptions } from './driver-memory';
 export { memoryJobDriver } from './driver-memory';
@@ -148,50 +122,17 @@ export { signalEnqueued, signalStaged } from './enqueue-signal';
 export type { JobErrorCode } from './error-codes';
 export { JOB_ERROR_CODES, JOB_ERROR_TITLES } from './error-codes';
 export {
-  ActionJobUnbridgedError,
-  CancelUnsupportedError,
-  ClaimQueuesEmptyError,
   DriverUnavailableError,
-  IdempotencyRequiredError,
   JobAbortedError,
   JobDrainedError,
   JobDuplicateError,
-  JobEnqueueBatchTooLargeError,
-  JobMaxAttemptsError,
-  JobNameTakenError,
   JobNotCancellableError,
-  JobRowStatusUnknownError,
-  JobSlotLostError,
-  JobTenantRequiredError,
   JobTimeoutError,
   LeaseLostError,
-  OutboxNoTxError,
-  StepDuplicateError,
 } from './errors';
-export {
-  ConcurrencyUnenforceableError,
-  JobConcurrencyInvalidError,
-  JobConcurrencyKeyInvalidError,
-  JobKeyBusyError,
-} from './errors-concurrency';
-export { JobDeclarationInvalidError } from './errors-declaration';
-export {
-  JobNotPromotableError,
-  JobNotRemovableError,
-  JobOnSettledFailedError,
-  JobPageInvalidError,
-} from './errors-operator';
-export { JobNotFoundError, JobNotRequeueableError } from './errors-requeue';
-export {
-  COMPENSATE_PREFIX,
-  JobCompensationFailedError,
-  StepCompensateUndeclaredError,
-  StepNameReservedError,
-  StepNotResolvableError,
-  StepOutcomeUnknownError,
-  UNWINDING_STEP,
-} from './errors-saga';
-export { JobEventInvalidError, StepOutputUnserializableError } from './errors-steps';
+export { ConcurrencyUnenforceableError, JobKeyBusyError } from './errors-concurrency';
+export { JobNotFoundError } from './errors-requeue';
+export { COMPENSATE_PREFIX, StepNameReservedError, UNWINDING_STEP } from './errors-saga';
 export { JobTenantMismatchError } from './errors-tenant';
 export type { EventBus, JobEvent, MemoryEventBusOptions, PublishOptions } from './events';
 export {
@@ -200,47 +141,28 @@ export {
   eventsPurgeTarget,
   memoryEventBus,
   publishEvent,
-  resetEventBus,
-  setEventBus,
 } from './events';
 export type { PostgresEventBusOptions } from './events-pg';
 export { postgresEventBus } from './events-pg';
 export type { ExecuteJobOptions } from './execute';
 export { executeJob } from './execute';
 export type { JobExecution, JobOutcome } from './execute-result';
-export type { ExportDefinition, ExportReport } from './export';
-export { DEFAULT_EXPORT_BATCH, DEFAULT_EXPORT_MAX_PART_BYTES, exportRows } from './export';
-export { ExportPartTooLargeError, ExportRowInvalidError } from './export-errors';
-export type { EncodePageInput, ExportFormat, ExportRecord, ExportValue } from './export-format';
-export { csvHeader, EXPORT_EXTENSION, EXPORT_FORMATS, encodeExportPage } from './export-format';
-export type { ExportManifest, ExportSink, MemoryExportSink } from './export-sink';
-export {
-  EXPORT_PART_DIGITS,
-  exportManifestKey,
-  exportPartKey,
-  memoryExportSink,
-} from './export-sink';
+export type { ExportDefinition } from './export';
+export { exportRows } from './export';
+export type { EncodePageInput, ExportValue } from './export-format';
+export { EXPORT_FORMATS, encodeExportPage } from './export-format';
+export type { ExportSink, MemoryExportSink } from './export-sink';
+export { memoryExportSink } from './export-sink';
 export type { CallerFailure } from './failure-row';
 export { callerFailure } from './failure-row';
+export { personalDataProblems, unerasedPersonalData, unreachedPersonalData } from './gdpr-coverage';
+export { PersonalDataUnerasedError, PersonalDataUnreachedError } from './gdpr-errors';
 export { IDLE_POLL_CEILING_MS } from './idle-backoff';
-export type { ImportDefinition, ImportReport } from './import';
-export {
-  DEFAULT_IMPORT_BATCH,
-  DEFAULT_IMPORT_MAX_RECORD_BYTES,
-  DEFAULT_IMPORT_MAX_ROW_ERRORS,
-  DEFAULT_IMPORT_PAGE_BYTES,
-  importRows,
-} from './import';
-export {
-  ImportHeaderMismatchError,
-  ImportRecordTooLargeError,
-  ImportTooManyErrorsError,
-} from './import-errors';
-export type { ImportRejection } from './import-format';
+export type { ImportDefinition } from './import';
+export { importRows } from './import';
 export { IMPORT_REJECTIONS } from './import-format';
-export type { ImportRowError } from './import-pass';
 export { importErrorKey } from './import-pass';
-export type { ImportObject, ImportSource, MemoryImportSource } from './import-source';
+export type { ImportSource, MemoryImportSource } from './import-source';
 export { memoryImportSource } from './import-source';
 export type {
   DeadLetterEntry,
@@ -269,7 +191,6 @@ export type {
   BulkFilter,
   BulkResult,
   CounterBucketMs,
-  CounterOutcome,
   CounterTotals,
   JobCounter,
   JobFilter,
@@ -282,26 +203,15 @@ export type {
   WorkerRecord,
 } from './introspection';
 export {
-  COUNTER_BUCKET_MS,
   COUNTER_TIERS,
   DEFAULT_JOB_PAGE,
   jobCursor,
   MAX_BULK_ROWS,
-  MAX_ERROR_STACK_LENGTH,
   MAX_JOB_PAGE,
-  MAX_PROGRESS_NOTE_LENGTH,
   MAX_TASK_FIRES,
-  MAX_WORKER_IN_FLIGHT,
-  PROGRESS_INTERVAL_MS,
   PROMOTABLE_STATES,
 } from './introspection';
-export type {
-  AnyJobHandle,
-  JobActor,
-  JobDefinition,
-  JobHandle,
-  JobRunArgs,
-} from './job';
+export type { AnyJobHandle, JobDefinition, JobHandle, JobRunArgs } from './job';
 export {
   describeJobs,
   getJob,
@@ -317,24 +227,15 @@ export type { JobsRetentionOptions } from './jobs-retention';
 export { jobsPurgeTarget } from './jobs-retention';
 export type { HeldLease, LeaseStore, MemoryLeaseStore, MemoryLeaseStoreOptions } from './leases';
 export { jobLeaseKey, memoryLeaseStore } from './leases';
-export type {
-  Lease,
-  LimitConfig,
-  Limiter,
-  LimitKey,
-  LimitReason,
-  LimitSnapshot,
-  RateLimit,
-} from './limits';
-export { concurrencyLimiter, NO_TENANT, tenantKeyFrom } from './limits';
-export {
-  queueDeadJobs,
-  queueDemand,
-  queueOldestReady,
-  recordQueueDeadJobs,
-  recordQueueDemand,
-  recordQueueOldestReady,
-} from './metrics';
+export type { LedgerDefinition, LedgerEntry, LedgerPosting } from './ledger';
+export { assertBalancedPosting, ledger, ledgerLines } from './ledger';
+export type { EntityLedgerBookOptions, LedgerBook, LedgerLine } from './ledger-book';
+export { entityLedgerBook } from './ledger-book';
+export type { Lease, LimitConfig, Limiter, LimitSnapshot, RateLimit } from './limits';
+export { concurrencyLimiter, NO_TENANT } from './limits';
+export type { HeldLock, WithLockOptions } from './lock';
+export { withLock } from './lock';
+export { queueDemand, recordQueueDemand } from './metrics';
 export type {
   EnqueueOptions,
   JobsFacade,
@@ -360,6 +261,8 @@ export type { OutboxRelay, RelayOptions } from './outbox-relay';
 export { outboxRelay } from './outbox-relay';
 export type { OutboxRetentionOptions } from './outbox-retention';
 export { outboxPurgeTarget } from './outbox-retention';
+export type { PartitionsDefinition, PartitionsJob } from './partitions';
+export { partitionedEntities, partitions } from './partitions';
 export type { ProgressFn } from './progress';
 export type {
   PurgeDefinition,
@@ -371,16 +274,13 @@ export type {
 export { DEFAULT_PURGE_CRON, purge } from './purge';
 export type { PurgeBatching } from './purge-batches';
 export type { PurgeEntities } from './purge-entities';
-export {
-  resetPurgeCoverage,
-  retainedEntities,
-  retainTarget,
-  unsweptEntities,
-} from './purge-entities';
+export { resetPurgeCoverage, retainTarget, unsweptEntities } from './purge-entities';
 export type { PgListener, QueueWake, QueueWakeOptions } from './queue-wake';
 export { startQueueWake } from './queue-wake';
-export type { RefreshViewDefinition, RefreshViewReport } from './refresh-view';
+export type { RefreshViewDefinition } from './refresh-view';
 export { refreshView } from './refresh-view';
+export type { ReindexDefinition } from './reindex';
+export { reindex } from './reindex';
 export type { IntervalScheduler } from './renewal-timer';
 export type { BackoffStrategy, Random, RetryDecision, RetryPolicy } from './retry';
 export {
@@ -394,52 +294,28 @@ export {
   UNWIND_MARGIN,
 } from './retry';
 export type { JobRetryDecision, JobStopReason } from './retry-classification';
-export { failureForRow, nextRetryForError } from './retry-classification';
-export type {
-  RollupBucket,
-  RollupDefinition,
-  RollupInput,
-  RollupReport,
-  RollupTarget,
-} from './rollup';
+export { nextRetryForError } from './retry-classification';
+export type { RollupBucket, RollupDefinition, RollupInput, RollupTarget } from './rollup';
 export { rollup } from './rollup';
-export { RefreshViewInvalidError, RollupInvalidError } from './rollup-errors';
-export type {
-  CronResolver,
-  DispatchedOccurrence,
-  Scheduler,
-  SchedulerOptions,
-} from './scheduler';
-export {
-  COUNTER_ROLLUP_INTERVAL_MS,
-  jobScheduler,
-  PAUSE_RECHECK_MS,
-} from './scheduler';
+export type { CronResolver, Scheduler, SchedulerOptions } from './scheduler';
+export { COUNTER_ROLLUP_INTERVAL_MS, jobScheduler } from './scheduler';
 export type { LeaderElection } from './scheduler-leader';
 export { soleLeader } from './scheduler-leader';
 export { nextTaskRun } from './scheduler-occurrences';
 export type { PostgresLeaseLeaderOptions } from './scheduler-pg';
-export {
-  currentLeader,
-  DEFAULT_LEADER_TTL_MS,
-  LEASE_RENEWALS_PER_TTL,
-  postgresLeaseLeader,
-  postgresSchedulerState,
-} from './scheduler-pg';
+export { DEFAULT_LEADER_TTL_MS, postgresLeaseLeader, postgresSchedulerState } from './scheduler-pg';
 export type { ScheduledFire, SchedulerState } from './scheduler-state';
-export { fireThroughDriver, memorySchedulerState } from './scheduler-state';
+export { memorySchedulerState } from './scheduler-state';
 export type { JobCompleted, JobFailed, JobSettled } from './settled';
 export { ON_SETTLED_ATTEMPTS, ON_SETTLED_TIMEOUT_MS } from './settled';
 export { currentStep } from './step-scope';
 export type {
-  CompensateContext,
   EventLookup,
   StepApi,
   StepFence,
   StepRecord,
   StepRunner,
   StepRunnerOptions,
-  StepRunOptions,
   StepStatus,
   StepStore,
   WaitForEventOptions,
@@ -460,27 +336,14 @@ export type {
   RetainedTarget,
   Subject,
   SubjectInit,
-  SubjectRef,
   SubjectTarget,
   SubjectTargetEntry,
-  SubjectTargetPage,
   SubjectTreatment,
 } from './subject';
-export { DEFAULT_SUBJECT_BATCH, defineSubject, registeredSubjects, resetSubjects } from './subject';
+export { defineSubject, registeredSubjects, resetSubjects } from './subject';
 export type { SubjectEraseReport, SubjectTally } from './subject-erase-pass';
-export {
-  SubjectCycleError,
-  SubjectTableUndeclaredError,
-  SubjectTreatmentInvalidError,
-} from './subject-errors';
-export type { SubjectExportReport, SubjectIndexEntry } from './subject-export-pass';
 export type { SubjectExportDefinition, SubjectJobDefinition } from './subject-jobs';
-export {
-  plannedSubject,
-  subjectErase,
-  subjectEraseTables,
-  subjectExport,
-} from './subject-jobs';
+export { subjectErase, subjectEraseTables, subjectExport } from './subject-jobs';
 export type {
   SubjectPlan,
   SubjectPlanInput,
@@ -495,7 +358,6 @@ export type {
   TaskDescriptor,
   TaskEnqueueEntry,
   TaskHandle,
-  TaskJobResult,
 } from './task';
 export { getTask, isTaskHandle, registeredTasks, resetTasks, restoreTasks, task } from './task';
 /**
@@ -510,39 +372,16 @@ export type {
   WebhookDefinition,
   WebhookDeliveryInput,
   WebhookEndpoint,
-  WebhookEvent,
-  WebhookReport,
   WebhookTenant,
 } from './webhook';
 export { DEFAULT_WEBHOOK_DISABLE_AFTER, webhook } from './webhook';
 export type { WebhookFetch } from './webhook-attempt';
-export { WEBHOOK_CONTENT_TYPE } from './webhook-attempt';
-export {
-  WebhookDeliveryFailedError,
-  WebhookDeliveryRejectedError,
-  WebhookDeliveryThrottledError,
-  WebhookEndpointDisabledError,
-  WebhookEndpointInvalidError,
-  WebhookEndpointUnknownError,
-  WebhookEventInvalidError,
-  WebhookEventUnknownError,
-} from './webhook-errors';
 export type { MemoryWebhookLedger, WebhookAttempt, WebhookLedger } from './webhook-ledger';
-export { DEFAULT_MAX_WEBHOOK_ATTEMPTS, memoryWebhookLedger } from './webhook-ledger';
+export { memoryWebhookLedger } from './webhook-ledger';
 export { webhookReceiver, webhookReceiverRoutes } from './webhook-receiver';
-export {
-  WEBHOOK_EVENT_ID_PATTERN,
-  WEBHOOK_RECEIVER_RETRY_AFTER_SECONDS,
-  WebhookEventIdInvalidError,
-  WebhookReceiverInvalidError,
-  WebhookReceiverUnavailableError,
-} from './webhook-receiver-errors';
+export { WEBHOOK_EVENT_ID_PATTERN } from './webhook-receiver-errors';
 export type {
-  ReceivedEvent,
   ReceivedEventFacts,
-  WebhookAnswer,
-  WebhookHandleArgs,
-  WebhookInbound,
   WebhookReceiver,
   WebhookReceiverDefinition,
   WebhookReceiverInput,

package/src/inspect-operator.ts

@@ -13,7 +13,7 @@ function operatorOf(driver: JobDriver): JobIntrospection {
   if (driver.introspect === undefined) {
     throw new NotImplementedError({
       cause: `the operator surface of the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
-      fix: 'call setJobDriver(postgresJobDriver()) at boot — the pg driver implements introspect — then: x jobs list --json',
+      fix: 'postgresJobDriver({ executor })   # jobs: in apps/<app>/runtime.ts, or drop that field and the boot builds it over DATABASE_URL — the pg driver implements introspect — then: x jobs list --json',
     });
   }
   return driver.introspect;
@@ -63,7 +63,7 @@ export function resolveJobStep(
   if (operator.resolveStep === undefined) {
     throw new NotImplementedError({
       cause: `the "${driver.name}" jobs driver keeps no step records an operator can resolve: its introspect has no resolveStep`,
-      fix: 'setJobDriver(postgresJobDriver())   # at boot: the pg and memory drivers implement resolveStep — then x jobs resolve-step <id> <step> --ran --output <json>',
+      fix: 'postgresJobDriver({ executor })   # jobs: in apps/<app>/runtime.ts, or drop that field and the boot builds it over DATABASE_URL — the pg and memory drivers implement resolveStep — then x jobs resolve-step <id> <step> --ran --output <json>',
     });
   }
   return operator.resolveStep(jobId, step, resolution);

package/src/inspect.ts

@@ -117,7 +117,7 @@ function requireIntrospection(driver: JobDriver): NonNullable<JobDriver['introsp
   if (driver.introspect === undefined) {
     throw new NotImplementedError({
       cause: `introspection for the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
-      fix: 'call setJobDriver(postgresJobDriver()) at boot — only the pg driver implements introspect — then: x jobs list --json',
+      fix: 'postgresJobDriver({ executor })   # jobs: in apps/<app>/runtime.ts, or drop that field and the boot builds it over DATABASE_URL — only the pg driver implements introspect — then: x jobs list --json',
     });
   }
   return driver.introspect;

package/src/job-instrument.ts

@@ -0,0 +1,115 @@
+// What the queue reports while it works: the `job.enqueue` producer span and event around every
+// enqueue, and the stable messaging attributes both the producer and the consumer span carry. One
+// file so `job.ts` (the enqueue door) and `worker-run.ts` (the run) spell the semconv names once.
+
+import type { SpanAttributes } from '@ultimat3/core';
+import { instrument, SEMCONV, SEMCONV_VALUES, subscribed, withSpan } from '@ultimat3/core';
+import type { EnqueueRequest, EnqueueResult } from './driver';
+import { ambientTraceparent } from './enqueue-record';
+
+/** The attributes every job span carries, producer and consumer alike. */
+export function messagingAttributes(
+  operation: 'send' | 'process',
+  queue: string,
+  job: string,
+): SpanAttributes {
+  return {
+    [SEMCONV.messagingSystem]: SEMCONV_VALUES.messagingSystemUltimate,
+    [SEMCONV.messagingOperationType]:
+      operation === 'send'
+        ? SEMCONV_VALUES.messagingOperationSend
+        : SEMCONV_VALUES.messagingOperationProcess,
+    [SEMCONV.messagingOperationName]: operation === 'send' ? 'enqueue' : 'perform',
+    [SEMCONV.messagingDestinationName]: queue,
+    'ultimate.job.name': job,
+  };
+}
+
+/**
+ * Run an enqueue under its producer span and tell the bus about each job it created. The span is
+ * open while the row is written, so the `traceparent` the row carries (`ambientTraceparent()`) is
+ * THIS span's — the run's consumer span becomes its child, as OpenTelemetry's messaging model
+ * says. A deduped enqueue still reports: the caller asked, and the id names the live job.
+ */
+export async function instrumentedEnqueue<R extends EnqueueResult | readonly EnqueueResult[]>(
+  job: string,
+  queue: string,
+  enqueue: () => Promise<R>,
+): Promise<R> {
+  const results = await withSpan(
+    `job.${job}.enqueue`,
+    async (span) => {
+      const answered = await enqueue();
+      const list = listOf(answered);
+      const [only] = list;
+      if (list.length === 1 && only !== undefined) {
+        span.setAttribute(SEMCONV.messagingMessageId, only.id);
+      } else {
+        span.setAttribute('ultimate.job.count', list.length);
+      }
+      return answered;
+    },
+    { kind: 'producer', attributes: messagingAttributes('send', queue, job) },
+  );
+  if (subscribed('job.enqueue')) {
+    for (const { id } of listOf(results)) {
+      instrument('job.enqueue', { job, queue, id });
+    }
+  }
+  return results;
+}
+
+/**
+ * A scheduler fire — one task's jobs and its watermark in ONE store write, so no per-job span can
+ * wrap it — under one producer span named for the TASK. Each request is stamped with that span's
+ * `traceparent` before the write, so every run it starts is the span's child; each job the write
+ * created is one `job.enqueue`. `undefined` (another dispatcher fired it) reports nothing.
+ */
+export async function instrumentedFire(
+  task: string,
+  requests: readonly EnqueueRequest[],
+  fire: (stamped: readonly EnqueueRequest[]) => Promise<readonly EnqueueResult[] | undefined>,
+): Promise<readonly EnqueueResult[] | undefined> {
+  const [first] = requests;
+  const oneQueue =
+    first !== undefined && requests.every((request) => request.queue === first.queue);
+  const results = await withSpan(
+    `job.${task}.enqueue`,
+    (span) => {
+      const trace = ambientTraceparent();
+      span.setAttribute('ultimate.job.count', requests.length);
+      return fire(
+        trace === undefined
+          ? requests
+          : requests.map((request) => ({ ...request, traceparent: trace })),
+      );
+    },
+    {
+      kind: 'producer',
+      attributes: {
+        [SEMCONV.messagingSystem]: SEMCONV_VALUES.messagingSystemUltimate,
+        [SEMCONV.messagingOperationType]: SEMCONV_VALUES.messagingOperationSend,
+        [SEMCONV.messagingOperationName]: 'enqueue',
+        ...(oneQueue ? { [SEMCONV.messagingDestinationName]: first.queue } : {}),
+        'ultimate.task.name': task,
+      },
+    },
+  );
+  if (results !== undefined && subscribed('job.enqueue')) {
+    requests.forEach((request, index) => {
+      const id = results[index]?.id;
+      if (id !== undefined && id !== '') {
+        instrument('job.enqueue', { job: request.name, queue: request.queue, id });
+      }
+    });
+  }
+  return results;
+}
+
+/** One enqueue's answer or many, as a list — a function, so a generic `R` narrows through it. */
+const listOf = (value: EnqueueResult | readonly EnqueueResult[]): readonly EnqueueResult[] =>
+  isList(value) ? value : [value];
+
+const isList = (
+  value: EnqueueResult | readonly EnqueueResult[],
+): value is readonly EnqueueResult[] => Array.isArray(value);

package/src/job.ts

@@ -18,10 +18,12 @@ import { DEFAULT_QUEUE } from './driver';
 import { IdempotencyRequiredError, JobNameTakenError } from './errors';
 import { JobDeclarationInvalidError, missingJobFields } from './errors-declaration';
 import type { EnqueueManyOptions } from './job-enqueue-many';
+import { instrumentedEnqueue } from './job-instrument';
 import { NO_TENANT, tenantKeyFrom } from './limits';
 import type { EnqueueOptions } from './outbox';
 import { jobsFacade } from './outbox';
 import { DEFAULT_RETRY } from './retry';
+import { assertRetryJitter } from './retry-jitter';
 import type { JobSettled } from './settled';
 import { ON_SETTLED_TIMEOUT_MS } from './settled';
 import { assertJobTenant, jobTenantFor } from './tenant';
@@ -30,7 +32,36 @@ export type { AnyJobHandle, JobActor, JobDefinition, JobHandle, JobRunArgs } fro
 
 import type { AnyJobHandle, JobActor, JobDefinition, JobHandle, JobRunArgs } from './job-types';
 
-const registry = new Map<string, AnyJobHandle>();
+/**
+ * The registry, and its name-sorted list cached until the next write. Every claim reads the list
+ * (`dropExhausted`), and a sort per claim bought nothing: the registry changes at boot. Every
+ * write goes through these three, so no path can change the map and keep a stale list.
+ */
+class JobRegistry extends Map<string, AnyJobHandle> {
+  #sorted: readonly AnyJobHandle[] | undefined;
+
+  override set(name: string, handle: AnyJobHandle): this {
+    this.#sorted = undefined;
+    return super.set(name, handle);
+  }
+
+  override delete(name: string): boolean {
+    this.#sorted = undefined;
+    return super.delete(name);
+  }
+
+  override clear(): void {
+    this.#sorted = undefined;
+    super.clear();
+  }
+
+  sorted(): readonly AnyJobHandle[] {
+    this.#sorted ??= Object.freeze([...this.values()].sort((a, b) => byName(a.name, b.name)));
+    return this.#sorted;
+  }
+}
+
+const registry = new JobRegistry();
 /** Process-monotonic — `resetJobs()` deliberately leaves it alone. */
 let anonymous = 0;
 
@@ -67,6 +98,7 @@ export function job<I, R = unknown>(definition: JobDefinition<I, R>): JobHandle<
   // `1.5`, which the memory driver ran and Postgres refused at the first enqueue (`$7::int`).
   // Zero is not "never retries" — that is `attempts: 1` — it is a job that never executes at all.
   finiteCount(`job "${name}"`, 'retry.attempts', definition.retry.attempts, 1);
+  assertRetryJitter(name, definition.retry.jitter);
   // `concurrency: 0` is not "no cap" — it is a fleet slot table that grants nothing, and the job
   // is permanently unrunnable with no log line. Refused where it is written, plain or keyed.
   const concurrency = resolveConcurrency(name, definition.concurrency);
@@ -151,11 +183,16 @@ export function job<I, R = unknown>(definition: JobDefinition<I, R>): JobHandle<
       // the cast restores exactly the types the declaration wrote.
       return definition.onSettled?.(settled as JobSettled<I, R>) ?? Promise.resolve();
     },
+    // Under the producer span, so the row's `traceparent` is the enqueue's own (`job-instrument.ts`).
     enqueue(input: I, options?: EnqueueOptions): Promise<EnqueueResult> {
-      return jobsFacade().enqueue(handle, input, options);
+      return instrumentedEnqueue(handle.name, options?.queue ?? handle.queue, () =>
+        jobsFacade().enqueue(handle, input, options),
+      );
     },
     enqueueMany(inputs: readonly I[], options?: EnqueueManyOptions) {
-      return jobsFacade().enqueueMany(handle, inputs, options);
+      return instrumentedEnqueue(handle.name, options?.queue ?? handle.queue, () =>
+        jobsFacade().enqueueMany(handle, inputs, options),
+      );
     },
     as(actor: JobActor | null, input: I, options: EnqueueOptions = {}): Promise<EnqueueResult> {
       const tenantId = options.tenantId ?? tenantFor(actor);
@@ -267,7 +304,7 @@ export function getJob(name: string): AnyJobHandle | undefined {
 const byName = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
 
 export function registeredJobs(): readonly AnyJobHandle[] {
-  return [...registry.values()].sort((a, b) => byName(a.name, b.name));
+  return registry.sorted();
 }
 
 /**