@beignet/core 0.0.32 → 0.0.34

package/src/jobs/index.ts

@@ -1,4 +1,7 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { LeaseHandle, LeaseMetadata, LocksPort } from "../locks/index.js";
+import { runWithResolvedTracingContext } from "../tracing/execution.js";
+import type { TracingPort } from "../tracing/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -10,6 +13,8 @@ export type StandardSchema = StandardSchemaV1<unknown, unknown>;
  */
 export type MaybePromise<T> = T | Promise<T>;
 
+type NoInferJob<T> = [T][T extends unknown ? 0 : never];
+
 /**
  * Infer the parsed output type from a Standard Schema.
  */
@@ -17,15 +22,30 @@ export type InferSchemaOutput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferOutput<T>;
 
 /**
- * Duration accepted by retry helpers. Numbers are milliseconds.
+ * Duration accepted by job helpers. Numbers are milliseconds.
  */
-export type JobRetryDuration =
+export type JobDuration =
   | number
   | `${number}ms`
   | `${number}s`
   | `${number}m`
   | `${number}h`;
 
+/**
+ * Duration accepted by retry helpers. Numbers are milliseconds.
+ */
+export type JobRetryDuration = JobDuration;
+
+/**
+ * Duration accepted by job timeout helpers. Numbers are milliseconds.
+ */
+export type JobTimeoutDuration = JobDuration;
+
+/**
+ * Duration accepted by job execution lease helpers. Numbers are milliseconds.
+ */
+export type JobExecutionLeaseDuration = JobDuration;
+
 /**
  * Retry strategy understood by Beignet job adapters.
  */
@@ -58,6 +78,71 @@ export interface JobRetryPredicateArgs {
  */
 export type JobRetryPredicate = (args: JobRetryPredicateArgs) => boolean;
 
+/**
+ * Dispatch-time uniqueness metadata for a job.
+ *
+ * Unique jobs are suppressed while the resolved key's lease is active.
+ * The lease is intentionally left to expire after a successful dispatch.
+ */
+export interface JobUniqueOptions {
+  /**
+   * Logical uniqueness key within this job name.
+   */
+  key: string;
+  /**
+   * How long duplicate dispatches should be suppressed.
+   */
+  ttl: JobDuration;
+}
+
+/**
+ * Arguments passed to a per-payload unique job resolver.
+ */
+export interface JobUniqueResolverArgs<Payload extends StandardSchema> {
+  /**
+   * Stable job name.
+   */
+  jobName: string;
+  /**
+   * Parsed job payload.
+   */
+  payload: StandardSchemaV1.InferOutput<Payload>;
+}
+
+/**
+ * Per-payload resolver for dispatch-time uniqueness.
+ */
+export type JobUniqueResolver<Payload extends StandardSchema> = {
+  bivarianceHack(
+    args: JobUniqueResolverArgs<Payload>,
+  ): MaybePromise<JobUniqueOptions | null | undefined>;
+}["bivarianceHack"];
+
+/**
+ * Unique job declaration value.
+ */
+export type JobUniqueConfig<Payload extends StandardSchema = StandardSchema> =
+  | JobUniqueOptions
+  | JobUniqueResolver<Payload>;
+
+/**
+ * Resolved uniqueness metadata used by dispatchers.
+ */
+export interface ResolvedJobUniqueOptions {
+  /**
+   * Logical uniqueness key returned by the job declaration.
+   */
+  key: string;
+  /**
+   * Concrete lock key used by `LocksPort`.
+   */
+  lockKey: string;
+  /**
+   * Lease TTL in milliseconds.
+   */
+  ttlMs: number;
+}
+
 /**
  * Job definition created by `defineJob(...)`.
  */
@@ -86,6 +171,18 @@ export interface JobDef<
    * Retry metadata for durable job providers.
    */
   readonly retry?: JobRetryOptions;
+  /**
+   * Optional dispatch-time uniqueness guard.
+   */
+  readonly unique?: JobUniqueConfig<Payload>;
+  /**
+   * Optional maximum execution time for each job handler attempt.
+   */
+  readonly timeout?: JobTimeoutDuration;
+  /**
+   * Optional hooks that wrap each handler attempt for this job.
+   */
+  readonly hooks?: readonly JobHook<JobDef<Name, Payload, Ctx>, Ctx>[];
   /**
    * Handle a parsed job payload.
    */
@@ -112,10 +209,174 @@ export interface JobHandleArgs<J extends JobDef, Ctx> {
    * Parsed job payload.
    */
   payload: InferJobPayload<J>;
+  /** Handler context. */
+  ctx: Ctx;
   /**
-   * Handler context.
+   * Abort signal that fires when the job's declared timeout expires.
+   *
+   * Beignet dispatchers and worker helpers provide this signal. It is optional
+   * in the type so direct handler tests can stay lightweight.
+   *
+   * JavaScript cannot forcibly stop arbitrary async work, so handlers that
+   * call cancellable APIs should pass this signal through.
    */
-  ctx: Ctx;
+  signal?: AbortSignal;
+}
+
+/**
+ * Arguments passed to job execution hooks.
+ */
+export interface JobHookArgs<J extends JobDef, Ctx>
+  extends JobHandleArgs<J, Ctx> {
+  /**
+   * Abort signal provided by the Beignet execution runner.
+   */
+  signal: AbortSignal;
+  /**
+   * One-based execution attempt when the runner can report it.
+   */
+  attempt?: number;
+  /**
+   * Maximum execution attempts when the runner can report it.
+   */
+  maxAttempts?: number;
+}
+
+/**
+ * Hook that wraps one job handler attempt.
+ *
+ * Hooks run only through Beignet dispatchers and worker helpers. Direct calls
+ * to `job.handle(...)` bypass hooks, which keeps lightweight unit tests
+ * possible.
+ */
+export type JobHook<J extends JobDef = JobDef, Ctx = unknown> = {
+  bivarianceHack(
+    args: JobHookArgs<J, Ctx>,
+    next: () => Promise<void>,
+  ): MaybePromise<void>;
+}["bivarianceHack"];
+
+/**
+ * Arguments passed to an execution lease key resolver.
+ */
+export type JobExecutionLeaseResolverArgs<J extends JobDef, Ctx> = JobHookArgs<
+  J,
+  Ctx
+>;
+
+/**
+ * Resolver for the logical execution lease key within a job name.
+ */
+export type JobExecutionLeaseKeyResolver<J extends JobDef, Ctx> = {
+  bivarianceHack(
+    args: JobExecutionLeaseResolverArgs<J, Ctx>,
+  ): MaybePromise<string>;
+}["bivarianceHack"];
+
+/**
+ * Resolver for the locks port used by an execution lease hook.
+ */
+export type JobExecutionLeaseLocksResolver<J extends JobDef, Ctx> =
+  | LocksPort
+  | {
+      bivarianceHack(
+        args: JobExecutionLeaseResolverArgs<J, Ctx>,
+      ): MaybePromise<LocksPort>;
+    }["bivarianceHack"];
+
+/**
+ * Resolver for optional diagnostics metadata attached to lease acquisition.
+ */
+export type JobExecutionLeaseMetadataResolver<J extends JobDef, Ctx> =
+  | LeaseMetadata
+  | {
+      bivarianceHack(
+        args: JobExecutionLeaseResolverArgs<J, Ctx>,
+      ): MaybePromise<LeaseMetadata | undefined>;
+    }["bivarianceHack"];
+
+/**
+ * Arguments passed when an execution lease cannot be acquired.
+ */
+export interface JobExecutionLeaseUnavailableArgs<J extends JobDef, Ctx>
+  extends JobHookArgs<J, Ctx> {
+  /**
+   * Logical lease key returned by the hook configuration.
+   */
+  key: string;
+  /**
+   * Concrete lock key passed to `LocksPort`.
+   */
+  lockKey: string;
+  /**
+   * Acquisition failure reason returned by `LocksPort`.
+   */
+  reason: "unavailable" | "timeout";
+}
+
+/**
+ * Behavior when an execution lease cannot be acquired.
+ *
+ * `"skip"` treats the attempt as successful without running the handler.
+ * `"throw"` fails the attempt with `JobExecutionLeaseUnavailableError` so the
+ * job retry policy can classify it. A function can log or throw custom errors;
+ * returning from it skips the handler.
+ */
+export type JobExecutionLeaseUnavailableBehavior<J extends JobDef, Ctx> =
+  | "skip"
+  | "throw"
+  | {
+      bivarianceHack(
+        args: JobExecutionLeaseUnavailableArgs<J, Ctx>,
+      ): MaybePromise<void>;
+    }["bivarianceHack"];
+
+/**
+ * Options for `createJobExecutionLeaseHook(...)`.
+ */
+export interface JobExecutionLeaseHookOptions<
+  J extends JobDef = JobDef,
+  Ctx = unknown,
+> {
+  /**
+   * Locks port or resolver used to acquire the execution lease.
+   */
+  locks: JobExecutionLeaseLocksResolver<J, Ctx>;
+  /**
+   * Logical lease key within this job name.
+   */
+  key: string | JobExecutionLeaseKeyResolver<J, Ctx>;
+  /**
+   * Lease time-to-live. This is the real safety boundary in serverless runtimes
+   * where an invocation may terminate before `finally` runs.
+   */
+  ttl: JobExecutionLeaseDuration;
+  /**
+   * How long to wait for an existing lease before applying `onUnavailable`.
+   *
+   * Defaults to no wait.
+   */
+  wait?: JobExecutionLeaseDuration;
+  /**
+   * Delay between acquisition attempts while waiting.
+   */
+  retryDelay?: JobExecutionLeaseDuration;
+  /**
+   * Prefix used to build the concrete lock key.
+   *
+   * Defaults to `"jobs:lease"`.
+   */
+  keyPrefix?: string;
+  /**
+   * Optional diagnostics metadata attached to the lease acquire call.
+   */
+  metadata?: JobExecutionLeaseMetadataResolver<J, Ctx>;
+  /**
+   * Behavior when the lease cannot be acquired.
+   *
+   * Defaults to `"skip"` so overlapping executions do not create retry storms.
+   */
+  onUnavailable?: JobExecutionLeaseUnavailableBehavior<J, Ctx>;
 }
 
 /**
@@ -177,6 +438,21 @@ export interface DefineJobOptions<
    * Retry metadata for durable job providers.
    */
   retry?: JobRetryOptions;
+  /**
+   * Optional dispatch-time uniqueness guard.
+   */
+  unique?: JobUniqueConfig<Payload>;
+  /**
+   * Optional maximum execution time for each job handler attempt.
+   */
+  timeout?: JobTimeoutDuration;
+  /**
+   * Optional hooks that wrap each handler attempt for this job.
+   */
+  hooks?: readonly JobHook<
+    JobDef<NoInferJob<Name>, NoInferJob<Payload>, Ctx>,
+    Ctx
+  >[];
   /**
    * Handle a parsed job payload.
    */
@@ -299,6 +575,11 @@ export interface InlineJobDispatcherOptions<Ctx> {
    * through this dispatcher.
    */
   retry?: boolean;
+  /**
+   * Hooks that wrap every job attempt executed by this dispatcher. Runner hooks
+   * wrap job-local hooks.
+   */
+  hooks?: readonly JobHook<JobDef<string, StandardSchema, Ctx>, Ctx>[];
 }
 
 /**
@@ -312,6 +593,21 @@ export const SINGLE_ATTEMPT_DISPATCH: unique symbol = Symbol.for(
   "beignet.jobs.singleAttemptDispatch",
 );
 
+/**
+ * Metadata passed to a single-attempt dispatch when another delivery layer
+ * owns retry scheduling.
+ */
+export interface SingleAttemptJobDispatchOptions {
+  /**
+   * One-based delivery attempt.
+   */
+  attempt?: number;
+  /**
+   * Maximum delivery attempts.
+   */
+  maxAttempts?: number;
+}
+
 /**
  * Shape of the single-attempt dispatch exposed under
  * `SINGLE_ATTEMPT_DISPATCH`.
@@ -319,8 +615,73 @@ export const SINGLE_ATTEMPT_DISPATCH: unique symbol = Symbol.for(
 export type SingleAttemptJobDispatch = <J extends JobDef>(
   job: J,
   payload: InferJobPayload<J>,
+  options?: SingleAttemptJobDispatchOptions,
 ) => Promise<void>;
 
+/**
+ * Job dispatcher shape accepted by job wrappers.
+ */
+export interface JobDispatcher {
+  dispatch<J extends JobDef>(
+    job: J,
+    payload: InferJobPayload<J>,
+  ): MaybePromise<void>;
+}
+
+/**
+ * Arguments passed when a unique job dispatch is suppressed.
+ */
+export interface UniqueJobDuplicateArgs<J extends JobDef = JobDef> {
+  /**
+   * Job definition whose dispatch was suppressed.
+   */
+  job: J;
+  /**
+   * Parsed job payload.
+   */
+  payload: InferJobPayload<J>;
+  /**
+   * Logical uniqueness key returned by the job declaration.
+   */
+  key: string;
+  /**
+   * Concrete lock key used by `LocksPort`.
+   */
+  lockKey: string;
+  /**
+   * Lease TTL in milliseconds.
+   */
+  ttlMs: number;
+  /**
+   * Lock acquisition reason returned by `LocksPort`.
+   */
+  reason: "unavailable" | "timeout";
+}
+
+/**
+ * Options for `createUniqueJobDispatcher(...)`.
+ */
+export interface UniqueJobDispatcherOptions {
+  /**
+   * Dispatcher to call when a job is not unique or the unique lease is acquired.
+   */
+  jobs: JobDispatcher;
+  /**
+   * Lease-backed lock port used as the uniqueness guard.
+   */
+  locks: LocksPort;
+  /**
+   * Prefix for concrete lock keys.
+   *
+   * Defaults to `"jobs:unique"`.
+   */
+  keyPrefix?: string;
+  /**
+   * Called when a duplicate dispatch is suppressed.
+   */
+  onDuplicate?: (args: UniqueJobDuplicateArgs) => MaybePromise<void>;
+}
+
 /**
  * Local/test job dispatcher that executes job handlers inline.
  */
@@ -369,6 +730,66 @@ export class JobValidationError extends Error {
   }
 }
 
+/**
+ * Error thrown when a job handler exceeds its declared timeout.
+ */
+export class JobTimeoutError extends Error {
+  /**
+   * Stable job name that timed out.
+   */
+  readonly jobName: string;
+  /**
+   * Timeout in milliseconds.
+   */
+  readonly timeoutMs: number;
+
+  constructor(args: { jobName: string; timeoutMs: number }) {
+    super(`Job "${args.jobName}" timed out after ${args.timeoutMs}ms.`);
+    this.name = "JobTimeoutError";
+    this.jobName = args.jobName;
+    this.timeoutMs = args.timeoutMs;
+  }
+}
+
+/**
+ * Error thrown when an execution lease hook is configured to fail on an
+ * unavailable lease.
+ */
+export class JobExecutionLeaseUnavailableError extends Error {
+  /**
+   * Stable job name whose execution lease was unavailable.
+   */
+  readonly jobName: string;
+  /**
+   * Logical lease key returned by the hook configuration.
+   */
+  readonly key: string;
+  /**
+   * Concrete lock key passed to `LocksPort`.
+   */
+  readonly lockKey: string;
+  /**
+   * Acquisition failure reason returned by `LocksPort`.
+   */
+  readonly reason: "unavailable" | "timeout";
+
+  constructor(args: {
+    jobName: string;
+    key: string;
+    lockKey: string;
+    reason: "unavailable" | "timeout";
+  }) {
+    super(
+      `Job "${args.jobName}" execution lease "${args.key}" is unavailable (${args.reason}).`,
+    );
+    this.name = "JobExecutionLeaseUnavailableError";
+    this.jobName = args.jobName;
+    this.key = args.key;
+    this.lockKey = args.lockKey;
+    this.reason = args.reason;
+  }
+}
+
 function formatPath(path: StandardSchemaV1.Issue["path"]): string {
   if (!path?.length) return "";
 
@@ -402,12 +823,24 @@ function assertPositiveNumber(name: string, value: number): void {
   }
 }
 
-function durationToMs(name: string, value: JobRetryDuration): number {
+function assertNonEmptyString(name: string, value: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+}
+
+function durationToMs(name: string, value: JobDuration | unknown): number {
   if (typeof value === "number") {
     assertPositiveInteger(name, value);
     return value;
   }
 
+  if (typeof value !== "string") {
+    throw new Error(
+      `${name} must be a positive millisecond value or duration string like "500ms", "30s", "5m", or "1h".`,
+    );
+  }
+
   const match = /^(\d+)(ms|s|m|h)$/.exec(value);
   if (!match) {
     throw new Error(
@@ -432,6 +865,36 @@ function durationToMs(name: string, value: JobRetryDuration): number {
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function validateJobUniqueOptions(options: JobUniqueOptions): JobUniqueOptions {
+  if (!isRecord(options)) {
+    throw new Error("unique must be an object or resolver function");
+  }
+
+  assertNonEmptyString("unique.key", options.key);
+  durationToMs("unique.ttl", options.ttl);
+  return options;
+}
+
+function validateJobUniqueConfig<Payload extends StandardSchema>(
+  config: JobUniqueConfig<Payload> | undefined,
+): JobUniqueConfig<Payload> | undefined {
+  if (config === undefined) return undefined;
+  if (typeof config === "function") return config;
+  return validateJobUniqueOptions(config);
+}
+
+function validateJobTimeout(
+  timeout: JobTimeoutDuration | undefined,
+): JobTimeoutDuration | undefined {
+  if (timeout === undefined) return undefined;
+  durationToMs("timeout", timeout);
+  return timeout;
+}
+
 const VALIDATED_RETRY_OPTIONS = Symbol("beignet.jobs.validatedRetryOptions");
 
 function validateJobRetryOptions(options: JobRetryOptions): JobRetryOptions {
@@ -567,6 +1030,162 @@ export function getJobRetryDelayMs(
   return delayMs;
 }
 
+/**
+ * Return the execution timeout in milliseconds configured by a job.
+ */
+export function getJobTimeoutMs(
+  job: Pick<JobDef, "timeout">,
+): number | undefined {
+  return job.timeout === undefined
+    ? undefined
+    : durationToMs("timeout", job.timeout);
+}
+
+function jobExecutionLeaseLockKey(
+  jobName: string,
+  key: string,
+  keyPrefix = "jobs:lease",
+): string {
+  return `${keyPrefix}:${jobName}:${key}`;
+}
+
+function validateExecutionLeaseKey(key: string): string {
+  assertNonEmptyString("executionLease.key", key);
+  return key;
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new Error("Job execution aborted.");
+}
+
+async function resolveExecutionLeaseLocks<J extends JobDef, Ctx>(
+  locks: JobExecutionLeaseLocksResolver<J, Ctx>,
+  args: JobExecutionLeaseResolverArgs<J, Ctx>,
+): Promise<LocksPort> {
+  return typeof locks === "function" ? await locks(args) : locks;
+}
+
+async function resolveExecutionLeaseMetadata<J extends JobDef, Ctx>(
+  metadata: JobExecutionLeaseMetadataResolver<J, Ctx> | undefined,
+  args: JobExecutionLeaseResolverArgs<J, Ctx>,
+): Promise<LeaseMetadata | undefined> {
+  return typeof metadata === "function" ? await metadata(args) : metadata;
+}
+
+async function releaseExecutionLease(lease: LeaseHandle): Promise<void> {
+  try {
+    await lease.release();
+  } catch {
+    // The lease TTL is the correctness boundary. Release is best effort so a
+    // provider outage after handler side effects does not turn success into a
+    // retry.
+  }
+}
+
+async function handleUnavailableExecutionLease<J extends JobDef, Ctx>(
+  behavior: JobExecutionLeaseUnavailableBehavior<J, Ctx> | undefined,
+  args: JobExecutionLeaseUnavailableArgs<J, Ctx>,
+): Promise<void> {
+  if (behavior === undefined || behavior === "skip") return;
+
+  if (behavior === "throw") {
+    throw new JobExecutionLeaseUnavailableError({
+      jobName: args.job.name,
+      key: args.key,
+      lockKey: args.lockKey,
+      reason: args.reason,
+    });
+  }
+
+  await behavior(args);
+}
+
+/**
+ * Create a job hook that prevents overlapping handler attempts for the same
+ * logical execution key.
+ *
+ * The hook uses one bounded `LocksPort.acquire(...)` call and never starts
+ * renewal loops, so it can run in serverless entrypoints as long as `locks`
+ * points at shared storage. `ttl` is the real safety boundary when a runtime
+ * terminates before best-effort release runs.
+ */
+export function createJobExecutionLeaseHook<
+  J extends JobDef = JobDef,
+  Ctx = unknown,
+>(options: JobExecutionLeaseHookOptions<J, Ctx>): JobHook<J, Ctx> {
+  const ttlMs = durationToMs("executionLease.ttl", options.ttl);
+  const waitMs =
+    options.wait === undefined
+      ? undefined
+      : durationToMs("executionLease.wait", options.wait);
+  const retryDelayMs =
+    options.retryDelay === undefined
+      ? undefined
+      : durationToMs("executionLease.retryDelay", options.retryDelay);
+  const keyPrefix = options.keyPrefix ?? "jobs:lease";
+  assertNonEmptyString("executionLease.keyPrefix", keyPrefix);
+
+  if (typeof options.key === "string") {
+    validateExecutionLeaseKey(options.key);
+  }
+
+  return async (args, next) => {
+    if (args.signal.aborted) throw abortReason(args.signal);
+
+    const key = validateExecutionLeaseKey(
+      typeof options.key === "function" ? await options.key(args) : options.key,
+    );
+    if (args.signal.aborted) throw abortReason(args.signal);
+
+    const lockKey = jobExecutionLeaseLockKey(args.job.name, key, keyPrefix);
+    const locks = await resolveExecutionLeaseLocks(options.locks, args);
+    if (args.signal.aborted) throw abortReason(args.signal);
+
+    const metadata = await resolveExecutionLeaseMetadata(
+      options.metadata,
+      args,
+    );
+    if (args.signal.aborted) throw abortReason(args.signal);
+
+    const result = await locks.acquire(lockKey, {
+      ttlMs,
+      ...(waitMs === undefined ? {} : { waitMs }),
+      ...(retryDelayMs === undefined ? {} : { retryDelayMs }),
+      metadata: {
+        ...(metadata ?? {}),
+        capability: "jobs",
+        jobName: args.job.name,
+        leaseKey: key,
+        attempt: args.attempt ?? null,
+        maxAttempts: args.maxAttempts ?? null,
+      },
+    });
+
+    if (!result.acquired) {
+      if (args.signal.aborted) throw abortReason(args.signal);
+
+      await handleUnavailableExecutionLease(options.onUnavailable, {
+        ...args,
+        key,
+        lockKey,
+        reason: result.reason,
+      });
+      return;
+    }
+
+    if (args.signal.aborted) {
+      await releaseExecutionLease(result.lease);
+      throw abortReason(args.signal);
+    }
+
+    try {
+      await next();
+    } finally {
+      await releaseExecutionLease(result.lease);
+    }
+  };
+}
+
 async function parsePayload<Schema extends StandardSchemaV1>(
   schema: Schema,
   input: unknown,
@@ -609,6 +1228,8 @@ function defineJobImpl<
   const retryOptions = options.retry
     ? validateJobRetryOptions(options.retry)
     : undefined;
+  const uniqueOptions = validateJobUniqueConfig(options.unique);
+  const timeout = validateJobTimeout(options.timeout);
 
   return {
     kind: "job",
@@ -616,6 +1237,9 @@ function defineJobImpl<
     payload: options.payload,
     description: options.description,
     retry: retryOptions,
+    unique: uniqueOptions,
+    timeout,
+    hooks: options.hooks,
     handle: options.handle as JobDef<Name, Payload, Ctx>["handle"],
   };
 }
@@ -632,6 +1256,183 @@ export async function parseJobPayload<J extends JobDef>(
   })) as InferJobPayload<J>;
 }
 
+/**
+ * Options for running one parsed job handler attempt.
+ */
+export interface RunJobHandlerOptions<
+  J extends JobDef<string, StandardSchema, Ctx>,
+  Ctx,
+> {
+  /**
+   * Job definition to execute.
+   */
+  job: J;
+  /**
+   * Parsed job payload.
+   */
+  payload: InferJobPayload<J>;
+  /** Handler context or factory resolved inside the job span. */
+  ctx: Ctx | (() => MaybePromise<Ctx>);
+  /** Runtime tracing port used before a lazy context factory runs. */
+  tracing?: TracingPort;
+  /**
+   * Runner-level hooks. These wrap job-local hooks.
+   */
+  hooks?: readonly JobHook<JobDef<string, StandardSchema, Ctx>, Ctx>[];
+  /**
+   * One-based execution attempt when the runner can report it.
+   */
+  attempt?: number;
+  /**
+   * Maximum execution attempts when the runner can report it.
+   */
+  maxAttempts?: number;
+}
+
+function normalizeJobHooks<Ctx>(
+  job: JobDef<string, StandardSchema, Ctx>,
+  hooks: readonly JobHook<JobDef<string, StandardSchema, Ctx>, Ctx>[] = [],
+): readonly JobHook<JobDef<string, StandardSchema, Ctx>, Ctx>[] {
+  return [
+    ...hooks,
+    ...((job.hooks ?? []) as readonly JobHook<
+      JobDef<string, StandardSchema, Ctx>,
+      Ctx
+    >[]),
+  ];
+}
+
+/**
+ * Run a parsed job handler once, enforcing hooks and the job's declared
+ * timeout.
+ */
+export async function runJobHandler<
+  J extends JobDef<string, StandardSchema, Ctx>,
+  Ctx,
+>(args: RunJobHandlerOptions<J, Ctx>): Promise<void> {
+  const traceAttributes = {
+    "beignet.job.name": args.job.name,
+    ...(args.attempt === undefined
+      ? {}
+      : { "beignet.job.attempt": args.attempt }),
+    ...(args.maxAttempts === undefined
+      ? {}
+      : { "beignet.job.max_attempts": args.maxAttempts }),
+  } as const;
+
+  await runWithResolvedTracingContext({
+    tracing: args.tracing,
+    ctx: args.ctx,
+    operation: {
+      name: `beignet.job ${args.job.name}`,
+      type: "job",
+      kind: "consumer",
+      attributes: traceAttributes,
+      metricAttributes: traceAttributes,
+    },
+    run: async (ctx) => {
+      const timeoutMs = getJobTimeoutMs(args.job);
+      const controller = new AbortController();
+      const hooks = normalizeJobHooks(args.job, args.hooks);
+      const hookArgs = {
+        job: args.job,
+        payload: args.payload,
+        ctx,
+        signal: controller.signal,
+        attempt: args.attempt,
+        maxAttempts: args.maxAttempts,
+      } satisfies JobHookArgs<J, Ctx>;
+
+      const run = Promise.resolve().then(async () => {
+        let index = -1;
+        const dispatch = async (nextIndex: number): Promise<void> => {
+          if (nextIndex <= index) {
+            throw new Error(
+              `Job "${args.job.name}" hook called next() multiple times.`,
+            );
+          }
+          index = nextIndex;
+
+          const hook = hooks[nextIndex];
+          if (!hook) {
+            await args.job.handle({
+              job: args.job,
+              payload: args.payload,
+              ctx,
+              signal: controller.signal,
+            });
+            return;
+          }
+
+          await hook(hookArgs, () => dispatch(nextIndex + 1));
+        };
+
+        await dispatch(0);
+      });
+
+      if (timeoutMs === undefined) {
+        await run;
+        return;
+      }
+
+      const timeoutError = new JobTimeoutError({
+        jobName: args.job.name,
+        timeoutMs,
+      });
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+
+      try {
+        await Promise.race([
+          run,
+          new Promise<void>((_, reject) => {
+            timeout = setTimeout(() => {
+              controller.abort(timeoutError);
+              reject(timeoutError);
+            }, timeoutMs);
+          }),
+        ]);
+      } finally {
+        if (timeout !== undefined) {
+          clearTimeout(timeout);
+        }
+      }
+    },
+  });
+}
+
+function jobUniqueLockKey(
+  jobName: string,
+  key: string,
+  keyPrefix = "jobs:unique",
+): string {
+  return `${keyPrefix}:${jobName}:${key}`;
+}
+
+/**
+ * Resolve a job's dispatch-time uniqueness metadata for a parsed payload.
+ */
+export async function resolveJobUnique<J extends JobDef>(
+  job: J,
+  payload: InferJobPayload<J>,
+  options: { keyPrefix?: string } = {},
+): Promise<ResolvedJobUniqueOptions | undefined> {
+  const config = job.unique;
+  if (!config) return undefined;
+
+  const unique =
+    typeof config === "function"
+      ? await config({ jobName: job.name, payload })
+      : config;
+  if (unique == null) return undefined;
+
+  const validated = validateJobUniqueOptions(unique);
+  return {
+    key: validated.key,
+    lockKey: jobUniqueLockKey(job.name, validated.key, options.keyPrefix),
+    ttlMs: durationToMs("unique.ttl", validated.ttl),
+  };
+}
+
 /**
  * Create a local/test dispatcher that runs job handlers inline.
  *
@@ -650,6 +1451,7 @@ export function createInlineJobDispatcher<Ctx>(
     job: J,
     payload: InferJobPayload<J>,
     retryEnabled: boolean,
+    dispatchOptions: SingleAttemptJobDispatchOptions = {},
   ): Promise<void> {
     const fail = (error: unknown): void => {
       options.onError?.(error, job);
@@ -673,10 +1475,13 @@ export function createInlineJobDispatcher<Ctx>(
 
     for (let attempt = 1; ; attempt += 1) {
       try {
-        await job.handle({
+        await runJobHandler({
           job,
           payload: parsed,
           ctx,
+          hooks: options.hooks,
+          attempt: dispatchOptions.attempt ?? attempt,
+          maxAttempts: dispatchOptions.maxAttempts ?? maxAttempts,
         });
         return;
       } catch (error) {
@@ -716,13 +1521,96 @@ export function createInlineJobDispatcher<Ctx>(
     value: <J extends JobDef<string, StandardSchema, Ctx>>(
       job: J,
       payload: InferJobPayload<J>,
-    ) => run(job, payload, false),
+      dispatchOptions?: SingleAttemptJobDispatchOptions,
+    ) => run(job, payload, false, dispatchOptions),
     enumerable: false,
   });
 
   return dispatcher;
 }
 
+/**
+ * Wrap any job dispatcher with dispatch-time unique job suppression.
+ *
+ * When a job has no `unique` declaration, dispatch passes through unchanged.
+ * When it does, the wrapper validates the payload, resolves the unique key,
+ * acquires the matching lease, and calls the underlying dispatcher only when
+ * the lease is acquired. Successful dispatches intentionally keep the lease
+ * until its TTL expires; failed dispatches release it so callers can retry.
+ */
+export function createUniqueJobDispatcher(
+  options: UniqueJobDispatcherOptions,
+): JobDispatcher {
+  const dispatcher: JobDispatcher = {
+    async dispatch<J extends JobDef>(
+      job: J,
+      payload: InferJobPayload<J>,
+    ): Promise<void> {
+      if (!job.unique) {
+        await options.jobs.dispatch(job, payload);
+        return;
+      }
+
+      const parsed = await parseJobPayload(job, payload);
+      const unique = await resolveJobUnique(job, parsed, {
+        keyPrefix: options.keyPrefix,
+      });
+      if (!unique) {
+        await options.jobs.dispatch(job, parsed);
+        return;
+      }
+
+      const result = await options.locks.acquire(unique.lockKey, {
+        ttlMs: unique.ttlMs,
+        waitMs: 0,
+        metadata: {
+          capability: "jobs",
+          jobName: job.name,
+          uniqueKey: unique.key,
+        },
+      });
+      if (!result.acquired) {
+        await options.onDuplicate?.({
+          job,
+          payload: parsed,
+          key: unique.key,
+          lockKey: unique.lockKey,
+          ttlMs: unique.ttlMs,
+          reason: result.reason,
+        });
+        return;
+      }
+
+      try {
+        await options.jobs.dispatch(job, parsed);
+      } catch (error) {
+        try {
+          await result.lease.release();
+        } catch {
+          // Preserve the dispatch failure; lease release is best effort and
+          // the TTL still bounds duplicate suppression if release fails.
+        }
+        throw error;
+      }
+    },
+  };
+
+  const singleAttempt = (
+    options.jobs as {
+      [SINGLE_ATTEMPT_DISPATCH]?: SingleAttemptJobDispatch;
+    }
+  )[SINGLE_ATTEMPT_DISPATCH];
+
+  if (singleAttempt) {
+    Object.defineProperty(dispatcher, SINGLE_ATTEMPT_DISPATCH, {
+      value: singleAttempt,
+      enumerable: false,
+    });
+  }
+
+  return dispatcher;
+}
+
 /**
  * Create job helper methods bound to an application context type.
  *