@igniter-js/jobs 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -1,1107 +1,634 @@
+import { p as IgniterJobsQueue, I as IgniterJobsAdapter, q as IgniterJobsScopeDefinition, c as IgniterJobDefinition, m as IgniterJobsWorkerBuilderConfig, r as IgniterJobsTelemetry, s as IgniterJobsInferSchemaInput, d as IgniterCronDefinition, g as IgniterJobSearchResult, h as IgniterJobStatus, t as IgniterJobsDispatchParams, u as IgniterJobsScheduleParams, n as IgniterJobsEventHandler, j as IgniterJobsQueueInfo, k as IgniterJobsQueueCleanOptions, v as IgniterJobsLimiter, w as IgniterJobsWorkerHandlers, l as IgniterJobsWorkerHandle, x as IgniterJobsScopeOptions, y as IgniterJobsSchema } from './adapter-PiDCQWQd.mjs';
+export { o as IgniterJobCounts, e as IgniterJobsAdapterDispatchParams, f as IgniterJobsAdapterScheduleParams, b as IgniterJobsBullMQAdapterOptions, z as IgniterJobsEvent, B as IgniterJobsExecutionContext, F as IgniterJobsFailureHook, C as IgniterJobsHookContext, L as IgniterJobsInferSchemaOutput, A as IgniterJobsInvokeOptions, i as IgniterJobsJobLog, G as IgniterJobsProgressHook, a as IgniterJobsQueueManager, J as IgniterJobsScheduleOptions, H as IgniterJobsScopeEntry, D as IgniterJobsStartHook, E as IgniterJobsSuccessHook, K as IgniterJobsWorkerMetrics } from './adapter-PiDCQWQd.mjs';
 import { IgniterLogger, IgniterError } from '@igniter-js/core';
-import { IgniterTelemetry } from '@igniter-js/telemetry';
-import { n as IgniterJobDefinition, o as IgniterCronDefinition, p as IgniterQueueConfig, I as IgniterJobsAdapter, q as IgniterJobScopeOptions, r as IgniterJobActorOptions, l as AdapterJobHandler } from './adapter-CcQCatSa.mjs';
-export { A as AdapterDispatchParams, a as AdapterScheduleParams, k as AdapterWorkerConfig, m as AdapterWorkerHandle, y as IgniterCronFailureHook, u as IgniterCronHandler, v as IgniterCronHandlerContext, Q as IgniterJobActorEntry, z as IgniterJobBackoff, x as IgniterJobCompleteHook, M as IgniterJobCompletedPayload, g as IgniterJobCounts, J as IgniterJobEnqueuedPayload, G as IgniterJobEventContext, i as IgniterJobEventHandler, H as IgniterJobEventPayload, F as IgniterJobEventType, N as IgniterJobFailedPayload, w as IgniterJobFailureHook, s as IgniterJobHandler, t as IgniterJobHandlerContext, b as IgniterJobInfo, B as IgniterJobLimiter, d as IgniterJobLog, L as IgniterJobProgressPayload, O as IgniterJobRetryingPayload, P as IgniterJobScopeEntry, h as IgniterJobSearchResult, K as IgniterJobStartedPayload, c as IgniterJobStatus, j as IgniterJobUnsubscribeFn, D as IgniterJobsSearchFilter, f as IgniterQueueCleanOptions, e as IgniterQueueInfo, C as IgniterQueuesSearchFilter, E as IgniterWorkersSearchFilter } from './adapter-CcQCatSa.mjs';
+export { IgniterJobsBullMQAdapter } from './adapters/bullmq.adapter.mjs';
+export { IgniterJobsMemoryAdapter } from './adapters/memory.adapter.mjs';
+import 'ioredis';
 
 /**
- * @fileoverview Configuration types for @igniter-js/jobs
- * @module @igniter-js/jobs/types/config
+ * Configuration used to build the jobs runtime.
  */
-
-/**
- * Full configuration for IgniterJobs.
- *
- * @typeParam TContext - Application context type
- * @typeParam TQueues - Map of queue names to queue configs
- * @typeParam TScope - Scope key (only one allowed)
- * @typeParam TActor - Actor key (only one allowed)
- */
-interface IgniterJobsConfig<TContext = unknown, TQueues extends Record<string, IgniterQueueConfig<TContext, any, any>> = Record<string, never>, TScope extends string = never, TActor extends string = never> {
-    /**
-     * Queue adapter (required).
-     */
+interface IgniterJobsConfig<TContext = unknown, TQueues extends Record<string, IgniterJobsQueue<TContext, any, any>> = {}, TScope extends string = never> {
     adapter: IgniterJobsAdapter;
-    /**
-     * Application context provider (required).
-     * Called for each job to get the context.
-     */
-    context: () => TContext | Promise<TContext>;
-    /**
-     * Queue configurations.
-     */
+    service: string;
+    environment: string;
+    contextFactory: () => TContext | Promise<TContext>;
     queues: TQueues;
-    /**
-     * Scope definition (only one allowed).
-     * Used for multi-tenancy.
-     */
-    scope?: TScope extends never ? never : {
-        key: TScope;
-        options?: IgniterJobScopeOptions;
-    };
-    /**
-     * Actor definition (only one allowed).
-     * Used for auditing.
-     */
-    actor?: TActor extends never ? never : {
-        key: TActor;
-        options?: IgniterJobActorOptions;
+    scopeDefinition?: IgniterJobsScopeDefinition<TScope>;
+    queueDefaults?: Partial<IgniterJobDefinition<TContext, any, any>>;
+    workerDefaults?: Partial<IgniterJobsWorkerBuilderConfig>;
+    autoStartWorker?: {
+        queues: (keyof TQueues)[];
+        concurrency?: number;
+        limiter?: IgniterJobsWorkerBuilderConfig['limiter'];
     };
-    /**
-     * Telemetry instance for observability.
-     */
-    telemetry?: IgniterTelemetry;
-    /**
-     * Custom logger.
-     */
     logger?: IgniterLogger;
-    /**
-     * Default job options applied to all jobs.
-     */
-    defaults?: {
-        /**
-         * Default retry configuration.
-         */
-        retry?: {
-            attempts?: number;
-            backoff?: {
-                type: 'exponential' | 'fixed' | 'linear';
-                delay: number;
-                maxDelay?: number;
-            };
-        };
-        /**
-         * Default timeout in milliseconds.
-         */
-        timeout?: number;
-        /**
-         * Default remove on complete config.
-         */
-        removeOnComplete?: boolean | {
-            count?: number;
-            age?: number;
-        };
-        /**
-         * Default remove on fail config.
-         */
-        removeOnFail?: boolean | {
-            count?: number;
-            age?: number;
-        };
-    };
+    telemetry?: IgniterJobsTelemetry;
 }
 /**
- * Builder state for IgniterJobs configuration.
- *
- * @typeParam TContext - Application context type
- * @typeParam TQueues - Map of queue names to queue configs
- * @typeParam TScope - Scope key
- * @typeParam TActor - Actor key
+ * Builder interface placeholder to help fluent APIs type-infer.
  */
-interface IgniterJobsBuilderState<TContext = unknown, TQueues extends Record<string, IgniterQueueConfig<TContext, any, any>> = Record<string, never>, TScope extends string = never, TActor extends string = never> {
+interface IgniterJobsBuilderState<TContext, TQueues extends Record<string, IgniterJobsQueue<TContext, any, any>>, TScope extends string> {
     adapter?: IgniterJobsAdapter;
-    context?: () => TContext | Promise<TContext>;
+    service?: string;
+    environment?: string;
+    contextFactory?: () => TContext | Promise<TContext>;
     queues: TQueues;
-    scope?: {
-        key: TScope;
-        options?: IgniterJobScopeOptions;
-    };
-    actor?: {
-        key: TActor;
-        options?: IgniterJobActorOptions;
+    scopeDefinition?: IgniterJobsScopeDefinition<TScope>;
+    queueDefaults?: Partial<IgniterJobDefinition<TContext, any, any>>;
+    workerDefaults?: Partial<IgniterJobsWorkerBuilderConfig>;
+    autoStartWorker?: {
+        queues: (keyof TQueues)[];
+        concurrency?: number;
+        limiter?: IgniterJobsWorkerBuilderConfig['limiter'];
     };
-    telemetry?: IgniterTelemetry;
-    logger?: IgniterLogger;
-    defaults?: IgniterJobsConfig<TContext>['defaults'];
-}
-/**
- * Builder state for IgniterQueue configuration.
- *
- * @typeParam TContext - Application context type
- * @typeParam TJobs - Map of job names to definitions
- * @typeParam TCrons - Map of cron names to definitions
- */
-interface IgniterQueueBuilderState<TContext = unknown, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>> = Record<string, never>, TCrons extends Record<string, IgniterCronDefinition<TContext, any>> = Record<string, never>> {
-    name: string;
-    jobs: TJobs;
-    crons: TCrons;
 }
 
 /**
- * @fileoverview Worker types for @igniter-js/jobs
- * @module @igniter-js/jobs/types/worker
+ * @fileoverview Runtime surface types for @igniter-js/jobs
+ * @module @igniter-js/jobs/types/runtime
  */
-/**
- * Worker handle returned from worker.start().
- */
-interface IgniterWorkerHandle {
-    /**
-     * Unique worker ID.
-     */
-    readonly id: string;
-    /**
-     * Pause the worker (stops processing new jobs).
-     */
+
+type IgniterJobsInferInput<TInput> = IgniterJobsInferSchemaInput<TInput>;
+type IgniterJobsInferJobInput<TDef> = TDef extends IgniterJobDefinition<any, infer TInput, any> ? IgniterJobsInferInput<TInput> : unknown;
+type IgniterJobsInferCronResult<TDef> = TDef extends IgniterCronDefinition<any, infer TResult> ? TResult : unknown;
+interface IgniterJobsJobInstanceAccessor {
+    retrieve(): Promise<IgniterJobSearchResult | null>;
+    retry(): Promise<void>;
+    remove(): Promise<void>;
+    promote(): Promise<void>;
+    move(state: 'failed', reason: string): Promise<void>;
+    state(): Promise<IgniterJobStatus | null>;
+    progress(): Promise<number>;
+    logs(): Promise<{
+        timestamp: Date;
+        message: string;
+        level: 'info' | 'warn' | 'error';
+    }[]>;
+}
+interface IgniterJobsJobManyAccessor {
+    retry(): Promise<void>;
+    remove(): Promise<void>;
+}
+interface IgniterJobsJobAccessor<TInput = unknown, TResult = unknown> {
+    dispatch(params: IgniterJobsDispatchParams<TInput>): Promise<string>;
+    schedule(params: IgniterJobsScheduleParams<TInput>): Promise<string>;
+    get(id: string): IgniterJobsJobInstanceAccessor;
+    many(ids: string[]): IgniterJobsJobManyAccessor;
     pause(): Promise<void>;
-    /**
-     * Resume the worker.
-     */
     resume(): Promise<void>;
-    /**
-     * Close the worker gracefully.
-     */
-    close(): Promise<void>;
-    /**
-     * Check if worker is currently running.
-     */
-    isRunning(): boolean;
-    /**
-     * Check if worker is paused.
-     */
-    isPaused(): boolean;
-    /**
-     * Get worker metrics.
-     */
-    getMetrics(): Promise<IgniterWorkerMetrics>;
+    subscribe(handler: IgniterJobsEventHandler): Promise<() => Promise<void>>;
 }
-/**
- * Worker metrics.
- */
-interface IgniterWorkerMetrics {
-    /**
-     * Total jobs processed.
-     */
-    processed: number;
-    /**
-     * Total jobs failed.
-     */
-    failed: number;
-    /**
-     * Total jobs completed successfully.
-     */
-    completed: number;
-    /**
-     * Currently active jobs.
-     */
-    active: number;
-    /**
-     * Worker uptime in milliseconds.
-     */
-    uptime: number;
+interface IgniterJobsQueueManagerAccessor {
+    retrieve(): Promise<IgniterJobsQueueInfo | null>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    drain(): Promise<number>;
+    clean(options: IgniterJobsQueueCleanOptions): Promise<number>;
+    obliterate(options?: {
+        force?: boolean;
+    }): Promise<void>;
+    retryAll(): Promise<number>;
 }
-/**
- * Worker builder state.
- */
-interface IgniterWorkerBuilderState {
-    /**
-     * Queue names to process.
-     */
-    queues: string[];
-    /**
-     * Concurrency per queue.
-     */
-    concurrency: number;
-    /**
-     * Lock duration in milliseconds.
-     */
-    lockDuration?: number;
-    /**
-     * Rate limiter configuration.
-     */
-    limiter?: {
-        max: number;
-        duration: number;
+type IgniterJobsQueueAccessor<TJobs extends Record<string, IgniterJobDefinition<any, any, any>> = {}> = {
+    get(): IgniterJobsQueueManagerAccessor;
+    list(filter?: {
+        status?: IgniterJobStatus[];
+        limit?: number;
+        offset?: number;
+    }): Promise<IgniterJobSearchResult[]>;
+    subscribe(handler: IgniterJobsEventHandler): Promise<() => Promise<void>>;
+    readonly jobs: {
+        [K in keyof TJobs]: IgniterJobsJobAccessor<IgniterJobsInferJobInput<TJobs[K]>, any>;
     };
-    /**
-     * Callback when worker becomes idle.
-     */
-    onIdle?: () => void;
+} & {
+    [K in keyof TJobs]: IgniterJobsJobAccessor<IgniterJobsInferJobInput<TJobs[K]>, any>;
+};
+interface IgniterJobsWorkerBuilderAccessor<TQueueNames extends string> {
+    create(): IgniterJobsWorkerFluentBuilder<TQueueNames>;
 }
+interface IgniterJobsWorkerFluentBuilder<TQueueNames extends string> {
+    addQueue(queue: TQueueNames): IgniterJobsWorkerFluentBuilder<TQueueNames>;
+    withConcurrency(concurrency: number): IgniterJobsWorkerFluentBuilder<TQueueNames>;
+    withLimiter(limiter: IgniterJobsLimiter): IgniterJobsWorkerFluentBuilder<TQueueNames>;
+    onActive(handler: NonNullable<IgniterJobsWorkerHandlers['onActive']>): IgniterJobsWorkerFluentBuilder<TQueueNames>;
+    onSuccess(handler: NonNullable<IgniterJobsWorkerHandlers['onSuccess']>): IgniterJobsWorkerFluentBuilder<TQueueNames>;
+    onFailure(handler: NonNullable<IgniterJobsWorkerHandlers['onFailure']>): IgniterJobsWorkerFluentBuilder<TQueueNames>;
+    onIdle(handler: NonNullable<IgniterJobsWorkerHandlers['onIdle']>): IgniterJobsWorkerFluentBuilder<TQueueNames>;
+    start(): Promise<IgniterJobsWorkerHandle>;
+}
+interface IgniterJobsBaseRuntime<TConfig extends IgniterJobsConfig<any, any, any> = IgniterJobsConfig<any, any, any>> {
+    readonly config: TConfig;
+    subscribe(handler: IgniterJobsEventHandler): Promise<() => Promise<void>>;
+    search(target: 'jobs', filter: Record<string, unknown>): Promise<IgniterJobSearchResult[]>;
+    search(target: 'queues', filter: Record<string, unknown>): Promise<IgniterJobsQueueInfo[]>;
+    search(target: 'workers', filter: Record<string, unknown>): Promise<IgniterJobsWorkerHandle[]>;
+    shutdown(): Promise<void>;
+    readonly worker: IgniterJobsWorkerBuilderAccessor<keyof TConfig['queues'] & string>;
+    scope: TConfig extends IgniterJobsConfig<any, any, infer TScope> ? (TScope extends string ? (type: TScope, id: string | number, tags?: Record<string, unknown>) => IgniterJobsRuntime<TConfig> : never) : never;
+}
+type IgniterJobsRuntime<TConfig extends IgniterJobsConfig<any, any, any> = IgniterJobsConfig<any, any, any>> = IgniterJobsBaseRuntime<TConfig> & {
+    [Q in keyof TConfig['queues']]: TConfig['queues'][Q] extends {
+        jobs: infer TJobs extends Record<string, IgniterJobDefinition<any, any, any>>;
+    } ? IgniterJobsQueueAccessor<TJobs> : IgniterJobsQueueAccessor;
+};
 
 /**
- * @fileoverview Builder for creating IgniterJobs instances
- * @module @igniter-js/jobs/builders/igniter-jobs
- *
- * @description
- * Provides a fluent builder API for configuring and creating IgniterJobs instances.
- * Supports adapter configuration, context provider, queues, scopes, actors, and telemetry.
+ * Canonical error codes for `@igniter-js/jobs`.
+ */
+declare const IGNITER_JOBS_ERROR_CODES: {
+    readonly JOBS_ADAPTER_REQUIRED: "JOBS_ADAPTER_REQUIRED";
+    readonly JOBS_SERVICE_REQUIRED: "JOBS_SERVICE_REQUIRED";
+    readonly JOBS_CONTEXT_REQUIRED: "JOBS_CONTEXT_REQUIRED";
+    readonly JOBS_CONFIGURATION_INVALID: "JOBS_CONFIGURATION_INVALID";
+    readonly JOBS_QUEUE_NOT_FOUND: "JOBS_QUEUE_NOT_FOUND";
+    readonly JOBS_QUEUE_DUPLICATE: "JOBS_QUEUE_DUPLICATE";
+    readonly JOBS_QUEUE_OPERATION_FAILED: "JOBS_QUEUE_OPERATION_FAILED";
+    readonly JOBS_INVALID_DEFINITION: "JOBS_INVALID_DEFINITION";
+    readonly JOBS_HANDLER_REQUIRED: "JOBS_HANDLER_REQUIRED";
+    readonly JOBS_DUPLICATE_JOB: "JOBS_DUPLICATE_JOB";
+    readonly JOBS_NOT_FOUND: "JOBS_NOT_FOUND";
+    readonly JOBS_NOT_REGISTERED: "JOBS_NOT_REGISTERED";
+    readonly JOBS_EXECUTION_FAILED: "JOBS_EXECUTION_FAILED";
+    readonly JOBS_TIMEOUT: "JOBS_TIMEOUT";
+    readonly JOBS_CONTEXT_FACTORY_FAILED: "JOBS_CONTEXT_FACTORY_FAILED";
+    readonly JOBS_VALIDATION_FAILED: "JOBS_VALIDATION_FAILED";
+    readonly JOBS_INVALID_INPUT: "JOBS_INVALID_INPUT";
+    readonly JOBS_INVALID_CRON: "JOBS_INVALID_CRON";
+    readonly JOBS_INVALID_SCHEDULE: "JOBS_INVALID_SCHEDULE";
+    readonly JOBS_SCOPE_ALREADY_DEFINED: "JOBS_SCOPE_ALREADY_DEFINED";
+    readonly JOBS_WORKER_FAILED: "JOBS_WORKER_FAILED";
+    readonly JOBS_ADAPTER_ERROR: "JOBS_ADAPTER_ERROR";
+    readonly JOBS_ADAPTER_CONNECTION_FAILED: "JOBS_ADAPTER_CONNECTION_FAILED";
+    readonly JOBS_SUBSCRIBE_FAILED: "JOBS_SUBSCRIBE_FAILED";
+};
+type IgniterJobsErrorCode = keyof typeof IGNITER_JOBS_ERROR_CODES;
+interface IgniterJobsErrorOptions {
+    /** Error code scoped to Igniter Jobs. */
+    code: IgniterJobsErrorCode;
+    /** Human-readable message. */
+    message: string;
+    /** HTTP-like status code hint (default: 500). */
+    statusCode?: number;
+    /** Optional structured details for debugging and clients. */
+    details?: unknown;
+    /** Optional metadata for logs and tracing. */
+    metadata?: Record<string, unknown>;
+    /** Optional causer tag used by some Igniter tooling. */
+    causer?: string;
+    /** Underlying cause for debugging (optional). */
+    cause?: Error;
+    /** Optional logger passthrough to align with other Igniter errors. */
+    logger?: any;
+}
+/**
+ * Typed error class for the Jobs package.
  *
  * @example
  * ```typescript
- * import { IgniterJobs, IgniterQueue } from '@igniter-js/jobs'
- * import { BullMQAdapter } from '@igniter-js/jobs/adapters'
- * import Redis from 'ioredis'
- *
- * const redis = new Redis()
- *
- * const emailQueue = IgniterQueue.create<AppContext>('email')
- *   .addJob('sendWelcome', { ... })
- *   .build()
- *
- * const jobs = IgniterJobs.create<AppContext>()
- *   .withAdapter(BullMQAdapter.create({ redis }))
- *   .withContext(() => ({ db, mailer }))
- *   .addQueue(emailQueue)
- *   .addScope('organization')
- *   .addActor('user')
- *   .build()
+ * throw new IgniterJobsError({
+ *   code: 'JOBS_INVALID_INPUT',
+ *   message: 'Input payload failed validation',
+ * })
  * ```
  */
+declare class IgniterJobsError extends IgniterError {
+    constructor(options: IgniterJobsErrorOptions);
+}
 
 /**
- * Builder for creating IgniterJobs instances.
+ * Fluent builder responsible for configuring and constructing an `IgniterJobs` instance.
  *
- * @typeParam TContext - Application context type
- * @typeParam TQueues - Map of queue names to queue configs
- * @typeParam TScope - Scope key (only one allowed)
- * @typeParam TActor - Actor key (only one allowed)
+ * The builder follows the immutable pattern used across Igniter packages: each
+ * method returns a new builder with refined types. Only a single scope is
+ * supported per the current specification (no actor support).
  */
-declare class IgniterJobsBuilder<TContext = unknown, TQueues extends Record<string, IgniterQueueBuilderState<TContext, any, any>> = Record<string, never>, TScope extends string = never, TActor extends string = never> {
+declare class IgniterJobsBuilder<TContext, TQueues extends Record<string, IgniterJobsQueue<TContext, any, any>> = {}, TScope extends string = never> {
     private readonly state;
     private constructor();
     /**
-     * Create a new IgniterJobs builder.
-     *
-     * @returns A new IgniterJobsBuilder instance
-     *
-     * @example
-     * ```typescript
-     * const jobs = IgniterJobs.create<AppContext>()
-     *   .withAdapter(...)
-     *   .build()
-     * ```
+     * Creates the initial builder with no configuration.
      */
-    static create<TContext = unknown>(): IgniterJobsBuilder<TContext>;
+    static create<TContext>(): IgniterJobsBuilder<TContext>;
     /**
-     * Configure the queue adapter (required).
-     *
-     * @param adapter - The queue adapter (e.g., BullMQAdapter)
-     * @returns The builder with adapter configured
-     *
-     * @example
-     * ```typescript
-     * .withAdapter(BullMQAdapter.create({ redis }))
-     * ```
+     * Returns a new builder with updated state while preserving generics.
      */
-    withAdapter(adapter: IgniterJobsAdapter): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    private clone;
     /**
-     * Configure the application context provider (required).
-     * This function is called for each job to provide the application context.
-     *
-     * @param contextFn - Function that returns the application context
-     * @returns The builder with context configured
+     * Attaches the jobs adapter.
      *
-     * @example
-     * ```typescript
-     * .withContext(() => ({
-     *   db: prisma,
-     *   mailer: mailerService,
-     *   cache: redis,
-     * }))
-     * ```
+     * @param adapter - Backend adapter implementation (BullMQ, memory, etc.).
      */
-    withContext(contextFn: () => TContext | Promise<TContext>): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    withAdapter(adapter: IgniterJobsAdapter): IgniterJobsBuilder<TContext, TQueues, TScope>;
     /**
-     * Add a queue to the jobs instance.
-     *
-     * @param queue - Queue configuration from IgniterQueue.create().build()
-     * @returns The builder with the queue added
-     *
-     * @example
-     * ```typescript
-     * const emailQueue = IgniterQueue.create<AppContext>('email')
-     *   .addJob('sendWelcome', { ... })
-     *   .build()
+     * Sets the service identifier for telemetry and metrics.
      *
-     * const jobs = IgniterJobs.create<AppContext>()
-     *   .addQueue(emailQueue)
-     *   .build()
-     * ```
+     * @param service - Service name (e.g., "my-api").
      */
-    addQueue<TQueueState extends IgniterQueueBuilderState<TContext, any, any>>(queue: TQueueState): IgniterJobsBuilder<TContext, TQueues & {
-        [K in TQueueState['name']]: TQueueState;
-    }, TScope, TActor>;
+    withService(service: string): IgniterJobsBuilder<TContext, TQueues, TScope>;
     /**
-     * Add a scope for multi-tenancy (only one scope allowed).
-     * Scopes are used to isolate jobs by organization, tenant, etc.
-     *
-     * @param key - Scope key (e.g., 'organization', 'tenant')
-     * @param options - Optional scope configuration
-     * @returns The builder with scope configured
-     *
-     * @example
-     * ```typescript
-     * .addScope('organization', { required: true })
-     * ```
+     * Sets the environment name (e.g., development, staging, production).
      */
-    addScope<TScopeKey extends string>(key: TScope extends never ? TScopeKey : never, options?: IgniterJobScopeOptions): IgniterJobsBuilder<TContext, TQueues, TScopeKey, TActor>;
+    withEnvironment(environment: string): IgniterJobsBuilder<TContext, TQueues, TScope>;
     /**
-     * Add an actor for auditing (only one actor type allowed).
-     * Actors are used to track who initiated jobs.
-     *
-     * @param key - Actor key (e.g., 'user', 'system')
-     * @param options - Optional actor configuration
-     * @returns The builder with actor configured
-     *
-     * @example
-     * ```typescript
-     * .addActor('user', { description: 'The user who initiated the job' })
-     * ```
+     * Provides a context factory used when executing jobs.
      */
-    addActor<TActorKey extends string>(key: TActor extends never ? TActorKey : never, options?: IgniterJobActorOptions): IgniterJobsBuilder<TContext, TQueues, TScope, TActorKey>;
+    withContext(factory: () => TContext | Promise<TContext>): IgniterJobsBuilder<TContext, TQueues, TScope>;
     /**
-     * Configure telemetry for observability (optional).
-     *
-     * @param telemetry - IgniterTelemetry instance
-     * @returns The builder with telemetry configured
-     *
-     * @example
-     * ```typescript
-     * .withTelemetry(telemetry)
-     * ```
+     * Adds a scope definition (single scope supported).
      */
-    withTelemetry(telemetry: IgniterTelemetry): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    addScope<TNewScope extends string>(name: TNewScope, options?: IgniterJobsScopeOptions): IgniterJobsBuilder<TContext, TQueues, TScope | TNewScope>;
     /**
-     * Configure a custom logger (optional).
-     *
-     * @param logger - Logger instance
-     * @returns The builder with logger configured
-     *
-     * @example
-     * ```typescript
-     * .withLogger(customLogger)
-     * ```
+     * Registers a queue definition on the builder.
      */
-    withLogger(logger: IgniterLogger): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    addQueue<TName extends string, TQueue extends IgniterJobsQueue<TContext, any, any>>(queue: TQueue & {
+        name: TName;
+    }): IgniterJobsBuilder<TContext, TQueues & Record<TName, TQueue>, TScope>;
     /**
-     * Configure default job options applied to all jobs.
-     *
-     * @param defaults - Default job configuration
-     * @returns The builder with defaults configured
-     *
-     * @example
-     * ```typescript
-     * .withDefaults({
-     *   retry: { attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
-     *   timeout: 30000,
-     *   removeOnComplete: { count: 1000 },
-     * })
-     * ```
+     * Applies default job options to all queues.
      */
-    withDefaults(defaults: {
-        retry?: {
-            attempts?: number;
-            backoff?: {
-                type: 'exponential' | 'fixed' | 'linear';
-                delay: number;
-                maxDelay?: number;
-            };
-        };
-        timeout?: number;
-        removeOnComplete?: boolean | {
-            count?: number;
-            age?: number;
-        };
-        removeOnFail?: boolean | {
-            count?: number;
-            age?: number;
-        };
-    }): IgniterJobsBuilder<TContext, TQueues, TScope, TActor>;
+    withQueueDefaults(defaults: Partial<IgniterJobDefinition<TContext, any, any>>): IgniterJobsBuilder<TContext, TQueues, TScope>;
     /**
-     * Build the IgniterJobs instance.
-     * Validates configuration and returns a fully typed jobs instance.
-     *
-     * @returns The IgniterJobs instance with proxy for typed access
-     *
-     * @throws {IgniterJobsError} If adapter is not configured
-     * @throws {IgniterJobsError} If context is not configured
-     * @throws {IgniterJobsError} If no queues are defined
-     *
-     * @example
-     * ```typescript
-     * const jobs = IgniterJobs.create<AppContext>()
-     *   .withAdapter(adapter)
-     *   .withContext(() => context)
-     *   .addQueue(emailQueue)
-     *   .build()
-     *
-     * // Now use with full type safety
-     * await jobs.email.sendWelcome.dispatch({ userId: '123' })
-     * ```
+     * Applies default worker options.
      */
-    build(): IgniterJobsInstance<TContext, TQueues, TScope, TActor>;
-}
-/**
- * Type for the built IgniterJobs instance.
- * Provides typed access to queues, jobs, and management APIs.
- */
-type IgniterJobsInstance<TContext, TQueues extends Record<string, IgniterQueueBuilderState<TContext, any, any>>, TScope extends string, TActor extends string> = {
-    [QueueName in keyof TQueues]: IgniterQueueProxy<TContext, TQueues[QueueName]['jobs'], TQueues[QueueName]['crons'], TScope, TActor>;
-} & {
-    subscribe: IgniterJobsGlobalSubscribe;
-    search: IgniterJobsSearch;
-    worker: IgniterJobsWorkerBuilder<TQueues>;
-    shutdown: () => Promise<void>;
-};
-/**
- * Queue proxy type providing access to jobs and queue management.
- */
-type IgniterQueueProxy<TContext, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>>, TCrons extends Record<string, IgniterCronDefinition<TContext, any>>, TScope extends string, TActor extends string> = {
-    [JobName in keyof TJobs]: IgniterJobProxy<TContext, TJobs[JobName] extends IgniterJobDefinition<TContext, infer TInput, infer TOutput> ? TInput : unknown, TJobs[JobName] extends IgniterJobDefinition<TContext, infer TInput, infer TOutput> ? TOutput : unknown, TScope, TActor>;
-} & {
-    subscribe: (handler: (event: any) => void | Promise<void>) => Promise<() => Promise<void>>;
-    list: (options?: {
-        status?: string[];
-        limit?: number;
-    }) => Promise<any[]>;
-    get: () => IgniterQueueManagement;
-};
-/**
- * Job proxy type providing dispatch, schedule, and job management.
- */
-interface IgniterJobProxy<TContext, TInput, TOutput, TScope extends string, TActor extends string> {
-    dispatch: IgniterJobDispatch<TInput, TScope, TActor>;
-    schedule: IgniterJobSchedule<TInput, TScope, TActor>;
-    get: (jobId: string) => IgniterJobManagement;
-    many: (jobIds: string[]) => IgniterJobBatchManagement;
-    pause: () => Promise<void>;
-    resume: () => Promise<void>;
-    subscribe: (handler: (event: any) => void | Promise<void>) => Promise<() => Promise<void>>;
-}
-/**
- * Job dispatch function type.
- */
-type IgniterJobDispatch<TInput, TScope extends string, TActor extends string> = (input: TInput, options?: IgniterJobDispatchOptions<TScope, TActor>) => Promise<string>;
-/**
- * Job dispatch options.
- */
-interface IgniterJobDispatchOptions<TScope extends string, TActor extends string> {
-    jobId?: string;
-    delay?: number;
-    priority?: number;
-    scope?: TScope extends never ? never : {
-        id: string;
-        tags?: Record<string, string | number | boolean>;
-    };
-    actor?: TActor extends never ? never : {
-        id?: string;
-        tags?: Record<string, string | number | boolean>;
-    };
-}
-/**
- * Job schedule function type.
- */
-type IgniterJobSchedule<TInput, TScope extends string, TActor extends string> = (params: {
-    input: TInput;
-    at?: Date;
-    cron?: string;
-    every?: number;
-    timezone?: string;
-    jobId?: string;
-    scope?: TScope extends never ? never : {
-        id: string;
-        tags?: Record<string, string | number | boolean>;
-    };
-    actor?: TActor extends never ? never : {
-        id?: string;
-        tags?: Record<string, string | number | boolean>;
-    };
-}) => Promise<string>;
-/**
- * Single job management operations.
- */
-interface IgniterJobManagement {
-    retrieve: () => Promise<any>;
-    retry: () => Promise<void>;
-    remove: () => Promise<void>;
-    state: () => Promise<string | null>;
-    progress: () => Promise<number>;
-    logs: () => Promise<any[]>;
-    promote: () => Promise<void>;
-    move: (state: 'failed' | 'completed', reason?: string) => Promise<void>;
-}
-/**
- * Batch job management operations.
- */
-interface IgniterJobBatchManagement {
-    retry: () => Promise<void>;
-    remove: () => Promise<void>;
-}
-/**
- * Queue management operations.
- */
-interface IgniterQueueManagement {
-    retrieve: () => Promise<any>;
-    pause: () => Promise<void>;
-    resume: () => Promise<void>;
-    drain: () => Promise<number>;
-    clean: (options: {
-        status: string | string[];
-        olderThan?: number;
-        limit?: number;
-    }) => Promise<number>;
-    obliterate: (options?: {
-        force?: boolean;
-    }) => Promise<void>;
-    retryAll: () => Promise<number>;
-}
-/**
- * Global subscribe function.
- */
-type IgniterJobsGlobalSubscribe = (handler: (event: any) => void | Promise<void>) => Promise<() => Promise<void>>;
-/**
- * Search function.
- */
-interface IgniterJobsSearch {
-    (target: 'queues', filter?: any): Promise<any[]>;
-    (target: 'jobs', filter?: any): Promise<any[]>;
-    (target: 'workers', filter?: any): Promise<any[]>;
-}
-/**
- * Worker builder interface.
- */
-interface IgniterJobsWorkerBuilder<TQueues> {
-    create: () => IgniterJobsWorkerConfig<TQueues>;
-}
-/**
- * Worker configuration builder.
- */
-interface IgniterJobsWorkerConfig<TQueues> {
-    forQueues: (...queues: (keyof TQueues)[]) => IgniterJobsWorkerConfig<TQueues>;
-    withConcurrency: (concurrency: number) => IgniterJobsWorkerConfig<TQueues>;
-    withLockDuration: (duration: number) => IgniterJobsWorkerConfig<TQueues>;
-    withLimiter: (config: {
-        max: number;
-        duration: number;
-    }) => IgniterJobsWorkerConfig<TQueues>;
-    onIdle: (callback: () => void) => IgniterJobsWorkerConfig<TQueues>;
-    start: () => Promise<any>;
+    withWorkerDefaults(defaults: Partial<IgniterJobsWorkerBuilderConfig>): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Configures automatic worker startup.
+     */
+    withAutoStartWorker(config: {
+        queues: (keyof TQueues)[];
+        concurrency?: number;
+        limiter?: IgniterJobsLimiter;
+    }): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Attaches telemetry support.
+     */
+    withTelemetry(telemetry: IgniterJobsTelemetry): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Attaches a custom logger.
+     */
+    withLogger(logger: IgniterLogger): IgniterJobsBuilder<TContext, TQueues, TScope>;
+    /**
+     * Finalizes the configuration and returns the runtime instance.
+     */
+    build(): IgniterJobsRuntime<IgniterJobsConfig<TContext, TQueues, TScope>>;
 }
+
 /**
- * Convenience alias for IgniterJobsBuilder.create().
- *
- * @example
- * ```typescript
- * import { IgniterJobs } from '@igniter-js/jobs'
- *
- * const jobs = IgniterJobs.create<AppContext>()
- *   .withAdapter(adapter)
- *   .withContext(() => context)
- *   .addQueue(emailQueue)
- *   .build()
- * ```
+ * @fileoverview Queue builder for @igniter-js/jobs
+ * @module @igniter-js/jobs/builders/igniter-queue
  */
-declare const IgniterJobs: {
-    create: typeof IgniterJobsBuilder.create;
-};
 
 /**
- * @fileoverview Builder for creating IgniterQueue instances
- * @module @igniter-js/jobs/builders/igniter-queue
- *
- * @description
- * Provides a fluent builder API for defining queues with jobs and cron jobs.
- * Queues group related jobs together and provide type-safe job definitions.
+ * Builder for defining queues, jobs, and cron tasks.
  *
  * @example
  * ```typescript
  * import { IgniterQueue } from '@igniter-js/jobs'
  * import { z } from 'zod'
  *
- * const emailQueue = IgniterQueue.create<AppContext>('email')
+ * const emailQueue = IgniterQueue.create('email')
+ *   .withContext<{ mailer: Mailer }>()
  *   .addJob('sendWelcome', {
- *     input: z.object({
- *       userId: z.string(),
- *       email: z.string().email(),
- *     }),
- *     retry: { attempts: 3 },
- *     handler: async (ctx) => {
- *       await ctx.context.mailer.send({
- *         to: ctx.input.email,
- *         template: 'welcome',
- *       })
+ *     input: z.object({ email: z.string().email() }),
+ *     handler: async ({ input, context }) => {
+ *       await context.mailer.send(input)
  *     },
  *   })
- *   .addCron('cleanupExpired', {
- *     expression: '0 0 * * *',
- *     handler: async (ctx) => {
- *       await ctx.context.db.cleanup.expiredSessions()
+ *   .addCron('cleanup', {
+ *     cron: '0 2 * * *',
+ *     handler: async ({ context }) => {
+ *       await context.mailer.cleanup()
  *     },
  *   })
  *   .build()
  * ```
  */
-
-/**
- * Builder for creating queue configurations.
- *
- * @typeParam TContext - Application context type
- * @typeParam TJobs - Map of job names to definitions
- * @typeParam TCrons - Map of cron names to definitions
- */
-declare class IgniterQueueBuilder<TContext = unknown, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>> = Record<string, never>, TCrons extends Record<string, IgniterCronDefinition<TContext, any>> = Record<string, never>> {
+declare class IgniterQueueBuilder<TContext, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>> = {}, TCron extends Record<string, IgniterCronDefinition<TContext, any>> = {}, TName extends string = string> {
     private readonly state;
     private constructor();
     /**
-     * Create a new queue builder.
-     *
-     * @param name - Queue name (kebab-case, e.g., 'email', 'payment-processing')
-     * @returns A new IgniterQueueBuilder instance
-     *
-     * @example
-     * ```typescript
-     * const emailQueue = IgniterQueue.create<AppContext>('email')
-     * ```
+     * Creates a new queue builder for the given queue name.
      */
-    static create<TContext = unknown>(name: string): IgniterQueueBuilder<TContext>;
+    static create<const TName extends string>(name: TName): IgniterQueueBuilder<unknown, {}, {}, TName>;
     /**
-     * Add a job definition to the queue.
+     * Re-types this builder with the application context type.
      *
-     * @param name - Job name (camelCase, e.g., 'sendWelcome', 'processPayment')
-     * @param definition - Job definition with input schema, handler, retry config, etc.
-     * @returns The builder with the new job added
+     * This is a type-level helper; it does not mutate runtime state.
      *
      * @example
      * ```typescript
-     * .addJob('sendWelcome', {
-     *   input: z.object({
-     *     userId: z.string(),
-     *     email: z.string().email(),
-     *   }),
-     *   retry: { attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
-     *   handler: async (ctx) => {
-     *     await ctx.context.mailer.send({
-     *       to: ctx.input.email,
-     *       template: 'welcome',
-     *     })
-     *   },
-     * })
+     * const queue = IgniterQueue.create('email')
+     *   .withContext<AppContext>()
+     *   .addJob('send', { handler: async ({ context }) => context.mailer.send() })
      * ```
      */
-    addJob<TName extends string, TInput, TOutput = void>(name: TName extends keyof TJobs ? never : TName, definition: IgniterJobDefinition<TContext, TInput, TOutput>): IgniterQueueBuilder<TContext, TJobs & {
-        [K in TName]: IgniterJobDefinition<TContext, TInput, TOutput>;
-    }, TCrons>;
+    withContext<TNewContext>(this: IgniterQueueBuilder<unknown, {}, {}, TName>): IgniterQueueBuilder<TNewContext, {}, {}, TName>;
+    private clone;
     /**
-     * Add a cron job definition to the queue.
+     * Registers a job on the queue.
      *
-     * @param name - Cron job name (camelCase)
-     * @param definition - Cron definition with expression, handler, etc.
-     * @returns The builder with the new cron added
-     *
-     * @example
-     * ```typescript
-     * .addCron('cleanupExpired', {
-     *   expression: '0 0 * * *', // Every day at midnight
-     *   timezone: 'America/New_York',
-     *   handler: async (ctx) => {
-     *     await ctx.context.db.cleanup.expiredSessions()
-     *   },
-     * })
-     * ```
+     * @param jobName - Unique name of the job inside the queue.
+     * @param definition - Job definition (handler, schemas, options, hooks).
      */
-    addCron<TName extends string, TOutput = void>(name: TName extends keyof TCrons ? never : TName, definition: IgniterCronDefinition<TContext, TOutput>): IgniterQueueBuilder<TContext, TJobs, TCrons & {
-        [K in TName]: IgniterCronDefinition<TContext, TOutput>;
-    }>;
+    addJob<TJobName extends string, TInput extends IgniterJobsSchema | unknown, TResult = unknown>(jobName: TJobName, definition: IgniterJobDefinition<TContext, TInput, TResult>): IgniterQueueBuilder<TContext, TJobs & Record<TJobName, IgniterJobDefinition<TContext, TInput, TResult>>, TCron, TName>;
     /**
-     * Build the queue configuration.
-     *
-     * @returns The queue configuration ready to be registered with IgniterJobs
+     * Registers a cron task on the queue.
      *
-     * @example
-     * ```typescript
-     * const emailQueue = IgniterQueue.create<AppContext>('email')
-     *   .addJob('sendWelcome', { ... })
-     *   .build()
-     * ```
+     * @param cronName - Unique name of the cron task inside the queue.
+     * @param definition - Cron definition (cron string, tz, handler, options).
+     */
+    addCron<TCronName extends string, TResult = unknown>(cronName: TCronName, definition: IgniterCronDefinition<TContext, TResult>): IgniterQueueBuilder<TContext, TJobs, TCron & Record<TCronName, IgniterCronDefinition<TContext, TResult>>, TName>;
+    /**
+     * Finalizes the queue definition.
      */
-    build(): IgniterQueueBuilderState<TContext, TJobs, TCrons>;
+    build(): IgniterJobsQueue<TContext, TJobs, TCron> & {
+        name: TName;
+    };
 }
-/**
- * Convenience alias for IgniterQueueBuilder.create().
- * Use this to create queue configurations with a fluent API.
- *
- * @example
- * ```typescript
- * import { IgniterQueue } from '@igniter-js/jobs'
- *
- * const emailQueue = IgniterQueue.create<AppContext>('email')
- *   .addJob('sendWelcome', { ... })
- *   .build()
- * ```
- */
-declare const IgniterQueue: {
-    create: typeof IgniterQueueBuilder.create;
-};
 
 /**
- * @fileoverview Builder for creating workers
+ * @fileoverview Worker builder for @igniter-js/jobs
  * @module @igniter-js/jobs/builders/igniter-worker
  */
 
+type IgniterJobsWorkerBuilderState<TAllowedQueues extends string> = {
+    queues: TAllowedQueues[];
+    concurrency?: number;
+    limiter?: IgniterJobsLimiter;
+    handlers: IgniterJobsWorkerHandlers;
+};
 /**
- * Builder for configuring and starting workers.
+ * Fluent builder for creating workers tied to registered queues.
  *
- * @example
- * ```typescript
- * const worker = await jobs.worker
- *   .create()
- *   .forQueues('email', 'payment')
- *   .withConcurrency(10)
- *   .withLimiter({ max: 100, duration: 60000 })
- *   .start()
- * ```
+ * Instances of this builder are created by `jobs.worker.create()` so it can be
+ * automatically scoped to registered queue names.
  */
-declare class IgniterWorkerBuilder {
-    private state;
-    private adapter;
-    private jobHandler;
-    private availableQueues;
-    constructor(adapter: IgniterJobsAdapter, jobHandler: AdapterJobHandler, availableQueues: string[]);
+declare class IgniterWorkerBuilder<TAllowedQueues extends string> {
+    private readonly adapter;
+    private readonly allowedQueues;
+    private readonly state;
+    constructor(params: {
+        adapter: IgniterJobsAdapter;
+        allowedQueues: readonly TAllowedQueues[];
+        state?: Partial<IgniterJobsWorkerBuilderState<TAllowedQueues>>;
+    });
+    private clone;
     /**
-     * Specify which queues this worker should process.
-     * If not called, worker processes all queues.
-     *
-     * @param queues - Queue names to process
-     * @returns The builder for chaining
+     * Adds a queue to the worker.
      *
-     * @example
-     * ```typescript
-     * .forQueues('email', 'payment')
-     * ```
+     * @param queue - Queue name registered on the jobs instance.
      */
-    forQueues(...queues: string[]): this;
+    addQueue(queue: TAllowedQueues): IgniterWorkerBuilder<TAllowedQueues>;
     /**
-     * Set the concurrency level (jobs processed in parallel per queue).
-     *
-     * @param concurrency - Number of parallel jobs
-     * @returns The builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withConcurrency(10)
-     * ```
+     * Sets the worker concurrency.
      */
-    withConcurrency(concurrency: number): this;
+    withConcurrency(concurrency: number): IgniterWorkerBuilder<TAllowedQueues>;
     /**
-     * Set the lock duration in milliseconds.
-     * Jobs are locked for this duration while being processed.
-     *
-     * @param duration - Lock duration in milliseconds
-     * @returns The builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withLockDuration(30000) // 30 seconds
-     * ```
+     * Sets a worker-level rate limiter.
      */
-    withLockDuration(duration: number): this;
+    withLimiter(limiter: IgniterJobsLimiter): IgniterWorkerBuilder<TAllowedQueues>;
+    onActive(handler: NonNullable<IgniterJobsWorkerHandlers['onActive']>): IgniterWorkerBuilder<TAllowedQueues>;
+    onSuccess(handler: NonNullable<IgniterJobsWorkerHandlers['onSuccess']>): IgniterWorkerBuilder<TAllowedQueues>;
+    onFailure(handler: NonNullable<IgniterJobsWorkerHandlers['onFailure']>): IgniterWorkerBuilder<TAllowedQueues>;
+    onIdle(handler: NonNullable<IgniterJobsWorkerHandlers['onIdle']>): IgniterWorkerBuilder<TAllowedQueues>;
     /**
-     * Configure rate limiting for the worker.
-     *
-     * @param config - Rate limiter configuration
-     * @returns The builder for chaining
+     * Builds and starts the worker.
      *
-     * @example
-     * ```typescript
-     * .withLimiter({ max: 100, duration: 60000 }) // 100 jobs per minute
-     * ```
+     * If no queues are added explicitly, the adapter should interpret it as "all queues".
      */
-    withLimiter(config: {
-        max: number;
-        duration: number;
-    }): this;
+    start(): Promise<IgniterJobsWorkerHandle>;
+}
+
+/**
+ * @fileoverview Core runtime factory for @igniter-js/jobs
+ * @module @igniter-js/jobs/core/igniter-jobs
+ */
+
+/**
+ * Runtime wrapper produced by `IgniterJobsBuilder`.
+ *
+ * The concrete implementation will expose queue/job proxies, management APIs,
+ * worker builder access, and shutdown handling.
+ */
+declare class IgniterJobs {
     /**
-     * Set a callback to be called when the worker becomes idle.
-     *
-     * @param callback - Idle callback
-     * @returns The builder for chaining
+     * Starts the fluent builder API for jobs.
      *
      * @example
      * ```typescript
-     * .onIdle(() => console.log('Worker is idle'))
+     * const jobs = IgniterJobs.create<AppContext>()
+     *   .withAdapter(IgniterJobsMemoryAdapter.create())
+     *   .withService('my-api')
+     *   .withEnvironment('test')
+     *   .withContext(async () => ({ db }))
+     *   .addQueue(emailQueue)
+     *   .build()
      * ```
      */
-    onIdle(callback: () => void): this;
+    static create<TContext>(): IgniterJobsBuilder<TContext, {}, never>;
     /**
-     * Start the worker.
-     *
-     * @returns Worker handle for management
-     *
-     * @example
-     * ```typescript
-     * const worker = await jobs.worker
-     *   .create()
-     *   .forQueues('email')
-     *   .start()
-     *
-     * // Later
-     * await worker.pause()
-     * await worker.close()
-     * ```
+     * Creates a runtime instance from a validated configuration.
      */
-    start(): Promise<IgniterWorkerHandle>;
+    static fromConfig<TConfig extends IgniterJobsConfig<any, any, any>>(config: TConfig): IgniterJobsRuntime<TConfig>;
 }
 
 /**
- * @fileoverview IgniterJobs runtime class with proxy-based API
- * @module @igniter-js/jobs/core/igniter-jobs
+ * @fileoverview Public queue entry point for @igniter-js/jobs
+ * @module @igniter-js/jobs/core/igniter-queue
  */
 
 /**
- * Configuration passed to IgniterJobsRuntime.
- */
-interface IgniterJobsRuntimeConfig<TContext, TQueues extends Record<string, IgniterQueueBuilderState<TContext, any, any>>, TScope extends string, TActor extends string> {
-    adapter: IgniterJobsAdapter;
-    context: () => TContext | Promise<TContext>;
-    queues: TQueues;
-    scope?: {
-        key: TScope;
-        options?: IgniterJobScopeOptions;
-    };
-    actor?: {
-        key: TActor;
-        options?: IgniterJobActorOptions;
-    };
-    telemetry?: IgniterTelemetry;
-    logger?: IgniterLogger;
-    defaults?: {
-        retry?: {
-            attempts?: number;
-            backoff?: any;
-        };
-        timeout?: number;
-        removeOnComplete?: boolean | {
-            count?: number;
-            age?: number;
-        };
-        removeOnFail?: boolean | {
-            count?: number;
-            age?: number;
-        };
-    };
-}
-/**
- * Main runtime class for IgniterJobs.
- * Creates proxy-based API for type-safe job access.
+ * Queue facade that exposes the fluent queue builder API.
  */
-declare class IgniterJobsRuntime<TContext, TQueues extends Record<string, IgniterQueueBuilderState<TContext, any, any>>, TScope extends string, TActor extends string> {
-    private readonly config;
-    private readonly queueNames;
-    constructor(config: IgniterJobsRuntimeConfig<TContext, TQueues, TScope, TActor>);
-    /**
-     * Create the main proxy that provides queue access and global methods.
-     */
-    private createProxy;
-    /**
-     * Create a proxy for a specific queue.
-     */
-    private createQueueProxy;
-    /**
-     * Create a proxy for a specific job.
-     */
-    private createJobProxy;
-    /**
-     * Dispatch a job.
-     */
-    private dispatchJob;
-    /**
-     * Schedule a job for future execution.
-     */
-    private scheduleJob;
+declare class IgniterQueue {
     /**
-     * Create job management methods.
-     */
-    private createJobManagement;
-    /**
-     * Create batch job management methods.
-     */
-    private createJobBatchManagement;
-    /**
-     * Create queue management methods.
-     */
-    private createQueueManagement;
-    /**
-     * Pause a specific job type.
-     */
-    private pauseJobType;
-    /**
-     * Resume a specific job type.
-     */
-    private resumeJobType;
-    /**
-     * Subscribe to events for a specific job.
-     */
-    private subscribeToJob;
-    /**
-     * Create queue-level subscribe.
-     */
-    private createQueueSubscribe;
-    /**
-     * List jobs in a queue.
-     */
-    private listQueueJobs;
-    /**
-     * Create global subscribe.
-     */
-    private createGlobalSubscribe;
-    /**
-     * Create search function.
-     */
-    private createSearch;
-    /**
-     * Create worker builder.
-     */
-    private createWorkerBuilder;
-    /**
-     * Create the job handler function for workers.
-     */
-    private createJobHandler;
-    /**
-     * Shutdown the jobs instance.
+     * Creates a new queue builder for the given name.
+     *
+     * @example
+     * ```typescript
+     * const queue = IgniterQueue.create('email')
+     *   .withContext<AppContext>()
+     *   .addJob('sendWelcome', { handler: async () => {} })
+     *   .build()
+     * ```
      */
-    private shutdown;
+    static create<const TName extends string>(name: TName): IgniterQueueBuilder<unknown, {}, {}, TName>;
 }
 
 /**
- * @fileoverview Error class and error codes for @igniter-js/jobs
- * @module @igniter-js/jobs/errors
+ * @fileoverview Telemetry event definitions for @igniter-js/jobs
+ * @module @igniter-js/jobs/telemetry/jobs.telemetry
+ *
+ * @description
+ * Defines all telemetry events emitted by the jobs package during job
+ * lifecycle operations. These events can be consumed by any transport
+ * adapter configured on the telemetry instance.
+ *
+ * Events follow the pattern: igniter.jobs.<group>.<event>
+ *
+ * Groups:
+ * - job: Job lifecycle events (enqueued, started, completed, failed, progress, retrying)
+ * - worker: Worker lifecycle events (started, stopped, idle)
+ * - queue: Queue management events (paused, resumed, drained, cleaned)
+ *
+ * @example
+ * ```typescript
+ * import { IgniterTelemetry } from '@igniter-js/telemetry'
+ * import { IgniterJobsTelemetryEvents } from '@igniter-js/jobs'
+ *
+ * const telemetry = IgniterTelemetry.create()
+ *   .withService('my-api')
+ *   .addEvents(IgniterJobsTelemetryEvents)
+ *   .build()
+ * ```
  */
-
 /**
- * All possible error codes for IgniterJobs.
- * Use these codes for programmatic error handling.
+ * Telemetry event definitions for @igniter-js/jobs.
+ *
+ * This descriptor can be passed to `IgniterTelemetry.addEvents()` to register
+ * all job-related telemetry events with proper type inference.
+ *
+ * Event names follow the pattern: `igniter.jobs.<group>.<event>`
  *
  * @example
  * ```typescript
- * try {
- *   await jobs.email.sendWelcome.dispatch(input)
- * } catch (error) {
- *   if (error instanceof IgniterJobsError) {
- *     switch (error.code) {
- *       case 'JOBS_ADAPTER_REQUIRED':
- *         // Handle missing adapter
- *         break
- *       case 'JOBS_DISPATCH_FAILED':
- *         // Handle dispatch failure
- *         break
- *     }
- *   }
- * }
+ * import { IgniterTelemetry } from '@igniter-js/telemetry'
+ * import { IgniterJobsTelemetryEvents } from '@igniter-js/jobs'
+ *
+ * const telemetry = IgniterTelemetry.create()
+ *   .withService('my-api')
+ *   .addEvents(IgniterJobsTelemetryEvents)
+ *   .build()
+ *
+ * // Type-safe emit
+ * telemetry.emit('igniter.jobs.job.completed', {
+ *   attributes: {
+ *     'ctx.job.id': 'job_123',
+ *     'ctx.job.name': 'sendWelcome',
+ *     'ctx.job.queue': 'email',
+ *     'ctx.job.duration': 1500,
+ *   },
+ * })
  * ```
  */
-declare const IGNITER_JOBS_ERROR_CODES: {
-    readonly JOBS_ADAPTER_REQUIRED: "JOBS_ADAPTER_REQUIRED";
-    readonly JOBS_CONTEXT_REQUIRED: "JOBS_CONTEXT_REQUIRED";
-    readonly JOBS_QUEUE_REQUIRED: "JOBS_QUEUE_REQUIRED";
-    readonly JOBS_CONFIGURATION_INVALID: "JOBS_CONFIGURATION_INVALID";
-    readonly JOBS_QUEUE_NOT_FOUND: "JOBS_QUEUE_NOT_FOUND";
-    readonly JOBS_QUEUE_ALREADY_EXISTS: "JOBS_QUEUE_ALREADY_EXISTS";
-    readonly JOBS_QUEUE_NAME_INVALID: "JOBS_QUEUE_NAME_INVALID";
-    readonly JOBS_QUEUE_PAUSE_FAILED: "JOBS_QUEUE_PAUSE_FAILED";
-    readonly JOBS_QUEUE_RESUME_FAILED: "JOBS_QUEUE_RESUME_FAILED";
-    readonly JOBS_QUEUE_DRAIN_FAILED: "JOBS_QUEUE_DRAIN_FAILED";
-    readonly JOBS_QUEUE_CLEAN_FAILED: "JOBS_QUEUE_CLEAN_FAILED";
-    readonly JOBS_QUEUE_OBLITERATE_FAILED: "JOBS_QUEUE_OBLITERATE_FAILED";
-    readonly JOBS_JOB_NOT_FOUND: "JOBS_JOB_NOT_FOUND";
-    readonly JOBS_JOB_ALREADY_EXISTS: "JOBS_JOB_ALREADY_EXISTS";
-    readonly JOBS_JOB_NAME_INVALID: "JOBS_JOB_NAME_INVALID";
-    readonly JOBS_JOB_HANDLER_REQUIRED: "JOBS_JOB_HANDLER_REQUIRED";
-    readonly JOBS_CRON_NOT_FOUND: "JOBS_CRON_NOT_FOUND";
-    readonly JOBS_CRON_ALREADY_EXISTS: "JOBS_CRON_ALREADY_EXISTS";
-    readonly JOBS_CRON_EXPRESSION_INVALID: "JOBS_CRON_EXPRESSION_INVALID";
-    readonly JOBS_CRON_HANDLER_REQUIRED: "JOBS_CRON_HANDLER_REQUIRED";
-    readonly JOBS_DISPATCH_FAILED: "JOBS_DISPATCH_FAILED";
-    readonly JOBS_SCHEDULE_FAILED: "JOBS_SCHEDULE_FAILED";
-    readonly JOBS_INPUT_REQUIRED: "JOBS_INPUT_REQUIRED";
-    readonly JOBS_INPUT_VALIDATION_FAILED: "JOBS_INPUT_VALIDATION_FAILED";
-    readonly JOBS_SCOPE_REQUIRED: "JOBS_SCOPE_REQUIRED";
-    readonly JOBS_SCOPE_ALREADY_DEFINED: "JOBS_SCOPE_ALREADY_DEFINED";
-    readonly JOBS_SCOPE_INVALID: "JOBS_SCOPE_INVALID";
-    readonly JOBS_ACTOR_ALREADY_DEFINED: "JOBS_ACTOR_ALREADY_DEFINED";
-    readonly JOBS_ACTOR_INVALID: "JOBS_ACTOR_INVALID";
-    readonly JOBS_GET_FAILED: "JOBS_GET_FAILED";
-    readonly JOBS_RETRY_FAILED: "JOBS_RETRY_FAILED";
-    readonly JOBS_REMOVE_FAILED: "JOBS_REMOVE_FAILED";
-    readonly JOBS_PROMOTE_FAILED: "JOBS_PROMOTE_FAILED";
-    readonly JOBS_MOVE_FAILED: "JOBS_MOVE_FAILED";
-    readonly JOBS_STATE_FAILED: "JOBS_STATE_FAILED";
-    readonly JOBS_PROGRESS_FAILED: "JOBS_PROGRESS_FAILED";
-    readonly JOBS_LOGS_FAILED: "JOBS_LOGS_FAILED";
-    readonly JOBS_WORKER_CREATE_FAILED: "JOBS_WORKER_CREATE_FAILED";
-    readonly JOBS_WORKER_START_FAILED: "JOBS_WORKER_START_FAILED";
-    readonly JOBS_WORKER_STOP_FAILED: "JOBS_WORKER_STOP_FAILED";
-    readonly JOBS_WORKER_NOT_FOUND: "JOBS_WORKER_NOT_FOUND";
-    readonly JOBS_WORKER_ALREADY_RUNNING: "JOBS_WORKER_ALREADY_RUNNING";
-    readonly JOBS_SUBSCRIBE_FAILED: "JOBS_SUBSCRIBE_FAILED";
-    readonly JOBS_UNSUBSCRIBE_FAILED: "JOBS_UNSUBSCRIBE_FAILED";
-    readonly JOBS_EVENT_EMIT_FAILED: "JOBS_EVENT_EMIT_FAILED";
-    readonly JOBS_SEARCH_FAILED: "JOBS_SEARCH_FAILED";
-    readonly JOBS_SEARCH_INVALID_TARGET: "JOBS_SEARCH_INVALID_TARGET";
-    readonly JOBS_SHUTDOWN_FAILED: "JOBS_SHUTDOWN_FAILED";
-    readonly JOBS_HANDLER_FAILED: "JOBS_HANDLER_FAILED";
-    readonly JOBS_HANDLER_TIMEOUT: "JOBS_HANDLER_TIMEOUT";
+declare const IgniterJobsTelemetryEvents: {
+    readonly namespace: "igniter.jobs";
+    readonly events: {
+        readonly job: {
+            readonly enqueued: {
+                "ctx.job.id": string;
+                "ctx.job.name": string;
+                "ctx.job.queue": string;
+                "ctx.job.priority"?: number;
+                "ctx.job.delay"?: number;
+            };
+            readonly started: {
+                "ctx.job.id": string;
+                "ctx.job.name": string;
+                "ctx.job.queue": string;
+                "ctx.job.attempt": number;
+                "ctx.job.maxAttempts": number;
+            };
+            readonly completed: {
+                "ctx.job.id": string;
+                "ctx.job.name": string;
+                "ctx.job.queue": string;
+                "ctx.job.duration": number;
+            };
+            readonly failed: {
+                "ctx.job.id": string;
+                "ctx.job.name": string;
+                "ctx.job.queue": string;
+                "ctx.job.error.message": string;
+                "ctx.job.error.code"?: string;
+                "ctx.job.attempt": number;
+                "ctx.job.maxAttempts": number;
+                "ctx.job.isFinalAttempt": boolean;
+            };
+            readonly progress: {
+                "ctx.job.id": string;
+                "ctx.job.name": string;
+                "ctx.job.queue": string;
+                "ctx.job.progress": number;
+                "ctx.job.progress.message"?: string;
+            };
+            readonly retrying: {
+                "ctx.job.id": string;
+                "ctx.job.name": string;
+                "ctx.job.queue": string;
+                "ctx.job.attempt": number;
+                "ctx.job.maxAttempts": number;
+                "ctx.job.nextRetryDelay": number;
+            };
+            readonly scheduled: {
+                "ctx.job.id": string;
+                "ctx.job.name": string;
+                "ctx.job.queue": string;
+                "ctx.job.scheduledAt"?: string;
+                "ctx.job.cron"?: string;
+            };
+        };
+        readonly worker: {
+            readonly started: {
+                "ctx.worker.id": string;
+                "ctx.worker.queues": string;
+                "ctx.worker.concurrency": number;
+            };
+            readonly stopped: {
+                "ctx.worker.id": string;
+                "ctx.worker.processed": number;
+                "ctx.worker.failed": number;
+                "ctx.worker.uptime": number;
+            };
+            readonly idle: {
+                "ctx.worker.id": string;
+                "ctx.worker.queues": string;
+            };
+            readonly paused: {
+                "ctx.worker.id": string;
+                "ctx.worker.queues": string;
+            };
+            readonly resumed: {
+                "ctx.worker.id": string;
+                "ctx.worker.queues": string;
+            };
+        };
+        readonly queue: {
+            readonly paused: {
+                "ctx.queue.name": string;
+            };
+            readonly resumed: {
+                "ctx.queue.name": string;
+            };
+            readonly drained: {
+                "ctx.queue.name": string;
+                "ctx.queue.drained.count": number;
+            };
+            readonly cleaned: {
+                "ctx.queue.name": string;
+                "ctx.queue.cleaned.count": number;
+                "ctx.queue.cleaned.status": string;
+            };
+            readonly obliterated: {
+                "ctx.queue.name": string;
+                "ctx.queue.obliterated.force": boolean;
+            };
+        };
+    };
 };
 /**
- * Type for all possible error codes.
- */
-type IgniterJobsErrorCode = keyof typeof IGNITER_JOBS_ERROR_CODES;
-/**
- * Options for creating an IgniterJobsError.
- */
-interface IgniterJobsErrorOptions {
-    /**
-     * Error code from IGNITER_JOBS_ERROR_CODES.
-     */
-    code: IgniterJobsErrorCode;
-    /**
-     * Human-readable error message.
-     */
-    message: string;
-    /**
-     * HTTP status code (for REST API responses).
-     * @default 500
-     */
-    statusCode?: number;
-    /**
-     * Original error that caused this error.
-     */
-    cause?: Error;
-    /**
-     * Additional details for debugging.
-     */
-    details?: Record<string, unknown>;
-    /**
-     * Logger instance for logging the error.
-     */
-    logger?: IgniterLogger;
-}
-/**
- * Custom error class for @igniter-js/jobs.
- * Extends IgniterError for consistent error handling across the Igniter ecosystem.
+ * Union type of all job telemetry event names.
  *
  * @example
  * ```typescript
- * throw new IgniterJobsError({
- *   code: 'JOBS_DISPATCH_FAILED',
- *   message: 'Failed to dispatch job to queue',
- *   statusCode: 500,
- *   details: { queue: 'email', job: 'sendWelcome' },
- * })
+ * import type { IgniterJobsTelemetryEventNames } from '@igniter-js/jobs'
+ *
+ * function handleEvent(name: IgniterJobsTelemetryEventNames) {
+ *   // name is type-safe
+ * }
  * ```
  */
-declare class IgniterJobsError extends IgniterError {
-    /**
-     * Error code for programmatic handling.
-     */
-    readonly code: IgniterJobsErrorCode;
-    /**
-     * Additional error details.
-     */
-    readonly details?: Record<string, unknown>;
-    constructor(options: IgniterJobsErrorOptions);
-    /**
-     * Convert error to a plain object for serialization.
-     */
-    toJSON(): Record<string, unknown>;
-}
+type IgniterJobsTelemetryEventNames = "igniter.jobs.job.enqueued" | "igniter.jobs.job.started" | "igniter.jobs.job.completed" | "igniter.jobs.job.failed" | "igniter.jobs.job.progress" | "igniter.jobs.job.retrying" | "igniter.jobs.job.scheduled" | "igniter.jobs.worker.started" | "igniter.jobs.worker.stopped" | "igniter.jobs.worker.idle" | "igniter.jobs.worker.paused" | "igniter.jobs.worker.resumed" | "igniter.jobs.queue.paused" | "igniter.jobs.queue.resumed" | "igniter.jobs.queue.drained" | "igniter.jobs.queue.cleaned" | "igniter.jobs.queue.obliterated";
 
-export { AdapterJobHandler, IGNITER_JOBS_ERROR_CODES, IgniterCronDefinition, IgniterJobActorOptions, IgniterJobDefinition, IgniterJobScopeOptions, IgniterJobs, IgniterJobsAdapter, IgniterJobsBuilder, type IgniterJobsBuilderState, type IgniterJobsConfig, IgniterJobsError, type IgniterJobsErrorCode, IgniterJobsRuntime, IgniterQueue, IgniterQueueBuilder, type IgniterQueueBuilderState, IgniterQueueConfig, IgniterWorkerBuilder, type IgniterWorkerBuilderState, type IgniterWorkerHandle, type IgniterWorkerMetrics };
+export { IGNITER_JOBS_ERROR_CODES, IgniterCronDefinition, IgniterJobDefinition, IgniterJobSearchResult, IgniterJobStatus, IgniterJobs, IgniterJobsAdapter, type IgniterJobsBaseRuntime, IgniterJobsBuilder, type IgniterJobsBuilderState, type IgniterJobsConfig, IgniterJobsDispatchParams, IgniterJobsError, type IgniterJobsErrorCode, type IgniterJobsErrorOptions, IgniterJobsEventHandler, type IgniterJobsInferCronResult, type IgniterJobsInferInput, type IgniterJobsInferJobInput, IgniterJobsInferSchemaInput, type IgniterJobsJobAccessor, type IgniterJobsJobInstanceAccessor, type IgniterJobsJobManyAccessor, IgniterJobsLimiter, IgniterJobsQueue, type IgniterJobsQueueAccessor, IgniterJobsQueueCleanOptions, IgniterJobsQueueInfo, type IgniterJobsQueueManagerAccessor, type IgniterJobsRuntime, IgniterJobsScheduleParams, IgniterJobsSchema, IgniterJobsScopeDefinition, IgniterJobsScopeOptions, IgniterJobsTelemetry, type IgniterJobsTelemetryEventNames, IgniterJobsTelemetryEvents, type IgniterJobsWorkerBuilderAccessor, IgniterJobsWorkerBuilderConfig, type IgniterJobsWorkerFluentBuilder, IgniterJobsWorkerHandle, IgniterJobsWorkerHandlers, IgniterQueue, IgniterQueueBuilder, IgniterWorkerBuilder };