bunqueue-client 0.1.9 → 0.2.0

package/dist/types/sdk/typescript/src/terminal-outcome.d.ts

@@ -0,0 +1,8 @@
+interface AckEntry {
+    readonly id: string;
+}
+/** Parse structured ACKB evidence while preserving duplicate job-ID positions. */
+export declare function ignoredAckIndices(data: unknown, batch: readonly AckEntry[]): ReadonlySet<number>;
+/** Parse a single ACK/FAIL response; historical applied responses have no data. */
+export declare function terminalOutcomeWasApplied(data: unknown): boolean;
+export {};

package/dist/{types.d.ts → types/sdk/typescript/src/types.d.ts}

@@ -59,8 +59,11 @@ export interface JobOptions {
 }
 /** Map SDK JobOptions to the PUSH/PUSHB wire fields (undefined keys dropped). */
 export declare function wireJobOptions(opts?: JobOptions): Record<string, unknown>;
-/** The job name travels inside `data`, mirroring the official client. */
-export declare function jobPayload(name: string, data: unknown): Record<string, unknown>;
+/** Build the protocol-owned name field without changing user data. */
+export declare function jobPayload(name: string, data: unknown): {
+    name: string;
+    data: unknown;
+};
 export interface JobCounts {
     waiting: number;
     prioritized: number;

package/dist/{worker-base.d.ts → types/sdk/typescript/src/worker-base.d.ts}

@@ -3,8 +3,9 @@
  * dispatch shared by the Worker pull loop (worker.ts).
  */
 import { EventEmitter } from 'node:events';
-import { Connection } from './connection.js';
-import { type WorkerEventMap, type WorkerOptions } from './worker-types.js';
+import { Connection } from "./connection.js";
+import type { Response } from "./connection-types.js";
+import { type WorkerEventMap, type WorkerOptions } from "./worker-types.js";
 export declare class WorkerBase<T = unknown, R = unknown> extends EventEmitter {
     readonly queue: string;
     readonly concurrency: number;
@@ -63,12 +64,11 @@ export declare class WorkerBase<T = unknown, R = unknown> extends EventEmitter {
      * With `force` the wait for in-flight jobs is skipped (parity with the
      * official client's `close(force)`). */
     close(force?: boolean): Promise<void>;
-    /** Dispatch a command, routing failures to 'error'. Returns whether the
-     * command reached the server — callers gate success-only side effects
-     * ('completed'/'failed' emits, counters) on it. */
+    /** Dispatch a command and route failures to 'error'. The optional outcome
+     * parser decides whether a successful response authorizes local effects. */
     protected safeCall(command: Record<string, unknown> & {
         cmd: string;
-    }): Promise<boolean>;
+    }, outcome?: (response: Response) => boolean): Promise<boolean>;
     /** Hook run during close() before draining in-flight jobs (see Worker). */
     protected beforeClose(): Promise<void>;
 }

package/dist/types/sdk/typescript/src/worker-slot-signal.d.ts

@@ -0,0 +1,6 @@
+/** One-shot wake-up used by the pull loop while every worker slot is busy. */
+export declare class SlotSignal {
+    private waiter;
+    wait(timeoutMs: number): Promise<void>;
+    notify(): void;
+}

package/dist/{worker-types.d.ts → types/sdk/typescript/src/worker-types.d.ts}

@@ -1,7 +1,7 @@
 /** Worker option types and shared constants. */
-import type { TlsOption } from './connection.js';
-import type { Job } from './job.js';
-import type { Observability } from './observability.js';
+import type { TlsOption } from "./connection.js";
+import type { Job } from "./job.js";
+import type { Observability } from "./observability.js";
 export type Processor<T = unknown, R = unknown> = (job: Job<T>) => R | Promise<R>;
 /**
  * Typed Worker event map: listeners registered via `on`/`once`/`off` for these

package/dist/{worker.d.ts → types/sdk/typescript/src/worker.d.ts}

@@ -5,11 +5,12 @@
  * live in the bunqueue server — the worker pulls, heartbeats and acks/fails.
  * Lifecycle state and cooperative cancel live in WorkerBase.
  */
-import { WorkerBase } from './worker-base.js';
-import { type Processor, type WorkerOptions } from './worker-types.js';
+import { WorkerBase } from "./worker-base.js";
+import { type Processor, type WorkerOptions } from "./worker-types.js";
 export declare class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
     private readonly processor;
     private readonly ackBatcher;
+    private readonly slotSignal;
     constructor(queue: string, processor: Processor<T, R>, opts?: WorkerOptions);
     /** Flush batched ACKs before the base class drains in-flight jobs. */
     protected beforeClose(): Promise<void>;

package/dist/types/src/application/background/dlq.d.ts

@@ -0,0 +1,2 @@
+import type { BackgroundContext } from "../types/index.js";
+export declare function performDlqMaintenance(ctx: BackgroundContext): void;

package/dist/types/src/application/background/lifecycle.d.ts

@@ -0,0 +1,4 @@
+import type { CronScheduler } from "../../infrastructure/scheduler/cronScheduler.js";
+import type { BackgroundContext, BackgroundTaskHandles } from "../types/index.js";
+export declare function startBackgroundTasks(ctx: BackgroundContext, cronScheduler: CronScheduler): BackgroundTaskHandles;
+export declare function stopBackgroundTasks(handles: BackgroundTaskHandles): void;

package/dist/types/src/application/background/recovery/active.d.ts

@@ -0,0 +1,5 @@
+import { type JobId } from "../../../domain/types/job.js";
+import type { BackgroundContext } from "../../types/index.js";
+export declare function restoreGroupPolicies(ctx: BackgroundContext, groupStates: ReturnType<NonNullable<BackgroundContext['storage']>['loadGroupState']>): void;
+export declare function restoreRecoveryPolicies(ctx: BackgroundContext, queueStates: ReturnType<NonNullable<BackgroundContext['storage']>['loadQueueState']>): void;
+export declare function recoverActiveJobs(ctx: BackgroundContext, dlqJobIds: Set<JobId>, now: number): void;

package/dist/types/src/application/background/recovery/index.d.ts

@@ -0,0 +1,2 @@
+import type { BackgroundContext } from "../../types/index.js";
+export declare function recover(ctx: BackgroundContext): void;

package/dist/types/src/application/background/recovery/pending.d.ts

@@ -0,0 +1,3 @@
+import type { JobId } from "../../../domain/types/job.js";
+import type { BackgroundContext } from "../../types/index.js";
+export declare function recoverPendingJobs(ctx: BackgroundContext, completionProofs: ReadonlySet<JobId>, now: number): void;

package/dist/types/src/application/background/recovery/restore.d.ts

@@ -0,0 +1,5 @@
+import type { BackgroundContext } from "../../types/index.js";
+import { type QueueStateRecord } from "./shared.js";
+export declare function restoreDlq(ctx: BackgroundContext): void;
+export declare function restoreQueueState(ctx: BackgroundContext, queueStates: QueueStateRecord[]): void;
+export declare function recoverCompletedJobs(ctx: BackgroundContext): void;

package/dist/types/src/application/background/recovery/shared.d.ts

@@ -0,0 +1,6 @@
+import type { Job } from "../../../domain/types/job.js";
+import type { BackgroundContext } from "../../types/index.js";
+export declare const RECOVERY_BATCH_SIZE = 10000;
+export type RecoveryStorage = NonNullable<BackgroundContext['storage']>;
+export type QueueStateRecord = ReturnType<RecoveryStorage['loadQueueState']>[number];
+export declare function quarantineCorruptDependsOn(ctx: BackgroundContext, job: Job): void;

package/dist/types/src/application/background/timeouts.d.ts

@@ -0,0 +1,25 @@
+import type { Job, JobId } from "../../domain/types/job.js";
+import type { BackgroundContext } from "../types/index.js";
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+export declare function timeoutTimerDelay(deadline: number, now?: number): number;
+/** Compatibility entry point for explicit timeout checks in tests and tooling. */
+export declare function checkJobTimeouts(ctx: BackgroundContext): Promise<void>;
+/** One timer tracks the earliest active processing deadline. */
+export declare class JobTimeoutScheduler {
+    private readonly active;
+    private readonly deadlines;
+    private timer;
+    private armedDeadline;
+    private stopped;
+    private ctx;
+    get pendingCount(): number;
+    start(ctx: BackgroundContext): void;
+    schedule(job: Job): void;
+    cancel(jobId: JobId): void;
+    stop(): void;
+    private isCurrent;
+    private pruneStaleRoots;
+    private maybeCompact;
+    private armNext;
+    private expireDue;
+}

package/dist/types/src/application/backgroundTasks.d.ts

@@ -0,0 +1,7 @@
+/** Stable background-task import surface. */
+export { startBackgroundTasks, stopBackgroundTasks } from "./background/lifecycle.js";
+export { recover } from "./background/recovery/index.js";
+export { checkJobTimeouts } from "./background/timeouts.js";
+export { processPendingDependencies } from "./dependencyProcessor.js";
+export { getTaskErrorStats } from "./taskErrorTracking.js";
+export type { BackgroundTaskHandles } from "./types/background.js";

package/dist/types/src/application/cleanupTasks.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Cleanup Tasks - Periodic maintenance and garbage collection
+ * Handles orphaned entries, stale data, and memory management
+ */
+import type { BackgroundContext } from "./types/index.js";
+/**
+ * Main cleanup function - called periodically to maintain system health
+ * Cleans orphaned entries, stale data, and manages memory
+ */
+export declare function cleanup(ctx: BackgroundContext): Promise<void>;

package/dist/types/src/application/clientTracking.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Client Tracking - Client-job relationship management
+ * Handles job ownership and release on client disconnect
+ */
+import type { JobId } from "../domain/types/job.js";
+import type { LockContext } from "./types/index.js";
+/**
+ * Register a job as owned by a client (called on PULL).
+ */
+export declare function registerClientJob(clientId: string, jobId: JobId, ctx: LockContext): void;
+/**
+ * Unregister a job from a client (called on ACK/FAIL).
+ */
+export declare function unregisterClientJob(clientId: string | undefined, jobId: JobId, ctx: LockContext): void;
+/**
+ * Release all jobs owned by a client back to queue (called on TCP disconnect).
+ * Returns the number of jobs released.
+ *
+ * Uses proper locking to prevent race conditions.
+ */
+export declare function releaseClientJobs(clientId: string, ctx: LockContext): Promise<number>;
+/**
+ * Force-release client tracking without acquiring queue locks.
+ * Used as a last-resort fallback when releaseClientJobs has exhausted its
+ * retry budget (e.g. persistent lock contention on TCP disconnect). For each
+ * orphaned job:
+ *   - clears `jobLocks` so a stale lock token can't survive the disconnect
+ *     until its TTL expires;
+ *   - expires both `lastHeartbeat` (so stall detection's heartbeat check
+ *     fires) and `startedAt` (so the gracePeriod check passes immediately).
+ *
+ * Recovery latency: stall detection uses two-phase confirmation
+ * (stalledCandidates collected on one tick, acted on the next), so a job is
+ * recovered within ~2 stall-check ticks (≈10s with defaults). This is faster
+ * than the full stallTimeout (30s default) but NOT instant.
+ *
+ * This path runs lock-free: callers must accept that another path (stall
+ * detector, lock expiration) may concurrently mutate or remove the same job
+ * from processingShards. Worst case: our mutation lands on an object that is
+ * no longer in the Map, wasting the write. Never corrupts state.
+ *
+ * Returns the number of jobs whose state was reset.
+ */
+export declare function forceReleaseClientJobs(clientId: string, ctx: LockContext): number;

package/dist/types/src/application/completedCleanup.d.ts

@@ -0,0 +1,34 @@
+import type { Job, JobId } from "../domain/types/job.js";
+import type { SqliteStorage } from "../infrastructure/persistence/sqlite.js";
+import type { DependencyResultTracker } from "./dependencyResultTracker.js";
+export interface CompletedCleanupContext {
+    jobIndex: Map<JobId, {
+        type: string;
+        queueName?: string;
+    }>;
+    completedJobs: {
+        delete(jobId: JobId): boolean;
+    };
+    completedJobsData: {
+        get(jobId: JobId): Job | undefined;
+        delete(jobId: JobId): boolean;
+    };
+    jobResults?: {
+        delete(jobId: JobId): boolean;
+    };
+    jobResultQueues?: {
+        get(jobId: JobId): string | undefined;
+        delete(jobId: JobId): boolean;
+    };
+    jobLogs?: {
+        delete(jobId: JobId): boolean;
+    };
+    jobLogQueues?: {
+        get(jobId: JobId): string | undefined;
+        delete(jobId: JobId): boolean;
+    };
+    dependencyResults: DependencyResultTracker;
+    storage: SqliteStorage | null;
+}
+/** Delete completed rows first, then converge every bounded in-memory projection. */
+export declare function cleanCompletedJobs(queue: string | null, completedBefore: number, limit: number, ctx: CompletedCleanupContext): JobId[];

package/dist/types/src/application/completedRetry.d.ts

@@ -0,0 +1,21 @@
+import { type Job, type JobId } from "../domain/types/job.js";
+import type { DlqContext } from "./dlqManager.js";
+/** Completed-job retry state shared by embedded control surfaces. */
+export interface RetryCompletedContext extends DlqContext {
+    completedJobs: {
+        has(id: JobId): boolean;
+        delete(id: JobId): boolean;
+    } & Iterable<JobId>;
+    completedJobsData: {
+        get(id: JobId): Job | undefined;
+        delete(id: JobId): boolean;
+    };
+    jobResults: {
+        delete(id: JobId): boolean;
+    };
+}
+/** Retry a selected completed generation or an oldest-first bounded set. */
+export declare function retryCompletedJobs(queue: string, ctx: RetryCompletedContext, targetId?: JobId, options?: {
+    limit?: number;
+    timestamp?: number;
+}): number;

package/dist/types/src/application/contextFactory.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ContextFactory - Builds context objects for delegated operations
+ */
+import type { LockContext, BackgroundContext, StatsContext } from "./types/index.js";
+import type { PushContext } from "./operations/push.js";
+import type { PullContext } from "./operations/pull.js";
+import type { AckContext } from "./operations/ack.js";
+import type { JobManagementContext } from "./operations/jobManagement.js";
+import type { QueryContext } from "./operations/queryOperations.js";
+import type { DlqContext, RetryCompletedContext } from "./dlqManager.js";
+import type { ContextCallbacks, ContextDependencies } from "./types/contextFactory.js";
+export type { ContextCallbacks, ContextDependencies } from "./types/contextFactory.js";
+/**
+ * Factory for building context objects
+ */
+export declare class ContextFactory {
+    private readonly deps;
+    private readonly callbacks;
+    constructor(deps: ContextDependencies, callbacks: ContextCallbacks);
+    getLockContext(): LockContext;
+    getBackgroundContext(): BackgroundContext;
+    getStatsContext(): StatsContext;
+    getPushContext(): PushContext;
+    getPullContext(): PullContext;
+    getAckContext(): AckContext;
+    getJobMgmtContext(): JobManagementContext;
+    getQueryContext(): QueryContext;
+    getDlqContext(): DlqContext;
+    getRetryCompletedContext(): RetryCompletedContext;
+    getLogsContext(): {
+        jobIndex: Map<import("../domain/types/job.js").JobId, import("../domain/types/queue.js").JobLocation>;
+        jobLogs: import("../shared/lruMap.js").LRUMap<import("../domain/types/job.js").JobId, import("../domain/types/worker.js").JobLogEntry[]>;
+        jobLogQueues: Map<import("../domain/types/job.js").JobId, string>;
+        maxLogsPerJob: number;
+    };
+    getQueueControlContext(): {
+        shards: import("../domain/queue/shard.js").Shard[];
+        jobIndex: Map<import("../domain/types/job.js").JobId, import("../domain/types/queue.js").JobLocation>;
+        processingShards: Map<import("../domain/types/job.js").JobId, import("../domain/types/job.js").Job>[];
+        completedJobs: import("../shared/boundedSet.js").BoundedSet<import("../domain/types/job.js").JobId>;
+        completedJobsData: import("../shared/boundedMap.js").BoundedMap<import("../domain/types/job.js").JobId, import("../domain/types/job.js").Job>;
+        jobResults: import("../shared/lruMap.js").LRUMap<import("../domain/types/job.js").JobId, unknown>;
+        jobResultQueues: Map<import("../domain/types/job.js").JobId, string>;
+        dependencyResults: import("./dependencyResultTracker.js").DependencyResultTracker;
+        jobLogs: import("../shared/lruMap.js").LRUMap<import("../domain/types/job.js").JobId, import("../domain/types/worker.js").JobLogEntry[]>;
+        jobLogQueues: Map<import("../domain/types/job.js").JobId, string>;
+        storage: import("../infrastructure/persistence/index.js").SqliteStorage | null;
+    };
+}

package/dist/types/src/application/dependencyCompletions.d.ts

@@ -0,0 +1,63 @@
+import type { Job, JobId } from "../domain/types/job.js";
+import type { Shard } from "../domain/queue/shard.js";
+import type { SqliteStorage } from "../infrastructure/persistence/sqlite.js";
+import type { SetLike } from "../shared/lru.js";
+interface CompletionRecord {
+    jobId: JobId;
+    queue: string;
+    pinned: boolean;
+}
+/**
+ * Payload-free completion evidence has two retention classes:
+ * recent IDs are FIFO-bounded, while IDs referenced by live dependency edges
+ * stay pinned until their final consumer is durably resolved or removed.
+ */
+export declare class DependencyCompletionTracker implements SetLike<JobId> {
+    private readonly onRecentEvict?;
+    private readonly recent;
+    private recentOrder;
+    private recentOrderTokens;
+    private readonly recentTokens;
+    private recentOrderHead;
+    private nextRecentToken;
+    private readonly pinned;
+    private readonly owners;
+    private readonly maxRecent;
+    constructor(maxRecent: number, onRecentEvict?: ((jobId: JobId) => void) | undefined);
+    add(jobId: JobId, queue?: string): void;
+    pin(jobId: JobId, queue?: string): void;
+    unpin(jobId: JobId, retainAsRecent: boolean): void;
+    hydrate(records: Iterable<CompletionRecord>): void;
+    pinnedValues(): IterableIterator<JobId>;
+    has(jobId: JobId): boolean;
+    delete(jobId: JobId): boolean;
+    deleteForQueue(queue: string): JobId[];
+    clear(): void;
+    get size(): number;
+    private evictOldestRecent;
+    private compactRecentOrder;
+}
+export interface DependencyCompletionContext {
+    storage: SqliteStorage | null;
+    shards: Shard[];
+    depCompletions?: DependencyCompletionTracker;
+    maxDependencyCompletions: number;
+}
+export declare function hasDependencyWaiters(shards: Shard[], jobId: JobId): boolean;
+/** Persist a removeOnComplete transition before publishing its RAM evidence. */
+export declare function commitRemovedCompletion(job: Pick<Job, 'id' | 'queue'>, ctx: DependencyCompletionContext, completedAt?: number): void;
+/**
+ * Protect recent proofs when a newly accepted parent waits on another
+ * dependency. SQLite is updated first so RAM never advertises a stronger
+ * durability guarantee than the database.
+ */
+export declare function pinReferencedCompletions(dependencyIds: Iterable<JobId>, ctx: Pick<DependencyCompletionContext, 'storage' | 'depCompletions'>): void;
+/**
+ * Unpin candidates only after every shard has released its reverse edge.
+ * Storage returns the complete retained set because pruning can also evict
+ * older recent entries; hydrating from it keeps both RAM tiers exact.
+ */
+export declare function releaseDependencyCompletionPins(dependencyIds: Iterable<JobId>, ctx: DependencyCompletionContext): void;
+/** Rebuild pin ownership from the authoritative reverse dependency indexes. */
+export declare function reconcileDependencyCompletionPins(ctx: DependencyCompletionContext): void;
+export {};

package/dist/types/src/application/dependencyProcessor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Dependency Processor - Job dependency resolution
+ * Uses reverse index for O(m) where m = jobs waiting on completed deps
+ */
+import type { Job } from "../domain/types/job.js";
+import type { BackgroundContext } from "./types/index.js";
+type DependencyReadyState = 'delayed' | 'prioritized' | 'waiting';
+export declare function dependencyReadyState(job: Job, now: number): DependencyReadyState;
+export declare function checkpointDependencyPromotion(job: Job, state: DependencyReadyState, now: number, storage: BackgroundContext['storage']): void;
+/**
+ * Process pending dependency checks
+ * Resolves jobs whose dependencies have been completed
+ */
+export declare function processPendingDependencies(ctx: BackgroundContext): Promise<void>;
+export {};

package/dist/types/src/application/dependencyResultTracker.d.ts

@@ -0,0 +1,18 @@
+import type { JobId } from "../domain/types/job.js";
+/**
+ * Retains results while at least one live dependency consumer may still read
+ * them. Ordinary completed-job results remain governed by the configured LRU.
+ */
+export declare class DependencyResultTracker {
+    private readonly consumersByDependency;
+    private readonly dependenciesByConsumer;
+    private readonly protectedResults;
+    registerConsumer(consumerId: JobId, dependencyIds: readonly JobId[]): void;
+    retain(dependencyId: JobId, result: unknown): void;
+    has(dependencyId: JobId): boolean;
+    get(dependencyId: JobId): unknown;
+    hasConsumers(dependencyId: JobId): boolean;
+    releaseConsumer(consumerId: JobId): void;
+    releaseDependency(consumerId: JobId, dependencyId: JobId): void;
+    clear(): void;
+}

package/dist/types/src/application/dlqManager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Advanced DLQ Manager
+ * Dead Letter Queue operations with auto-retry, metadata, and lifecycle management
+ */
+import type { Job, JobId } from "../domain/types/job.js";
+import type { JobLocation } from "../domain/types/queue.js";
+import type { Shard } from "../domain/queue/shard.js";
+import type { DlqEntry, DlqConfig, DlqFilter, DlqStats } from "../domain/types/dlq.js";
+import type { SqliteStorage } from "../infrastructure/persistence/sqlite.js";
+/** Context for DLQ operations */
+export interface DlqContext {
+    shards: Shard[];
+    jobIndex: Map<JobId, JobLocation>;
+    jobResults: {
+        delete(id: JobId): boolean;
+    };
+    jobResultQueues: Map<JobId, string>;
+    dependencyResults: {
+        releaseConsumer(id: JobId): void;
+    };
+    customIdMap: {
+        get(id: string): JobId | undefined;
+        set(id: string, jobId: JobId): void;
+        delete(id: string): boolean;
+    };
+    jobLogs: {
+        delete(id: JobId): boolean;
+    };
+    jobLogQueues: Map<JobId, string>;
+    storage: SqliteStorage | null;
+}
+export { processAutoRetry, retryDlqByFilter, retryDlqJob, retryDlqJobs } from "./dlqRetry.js";
+export { retryCompletedJobs, type RetryCompletedContext } from "./completedRetry.js";
+/** Get jobs from DLQ (backward compatible) */
+export declare function getDlqJobs(queue: string, ctx: DlqContext, count?: number): Job[];
+/** Get DLQ entries with full metadata */
+export declare function getDlqEntries(queue: string, ctx: DlqContext, filter?: DlqFilter): DlqEntry[];
+/** Get DLQ statistics */
+export declare function getDlqStats(queue: string, ctx: DlqContext): DlqStats;
+/** Purge expired entries from DLQ */
+export declare function purgeExpiredDlq(queue: string, ctx: DlqContext): number;
+/** Purge all jobs from DLQ */
+export declare function purgeDlqJobs(queue: string, ctx: DlqContext): number;
+/** Remove one DLQ entry without re-enqueuing it. */
+export declare function removeDlqJob(queue: string, id: JobId, ctx: DlqContext): boolean;
+/** Configure DLQ for a queue */
+export declare function configureDlq(queue: string, ctx: DlqContext, config: Partial<DlqConfig>): void;
+/** Get DLQ configuration */
+export declare function getDlqConfig(queue: string, ctx: DlqContext): DlqConfig;

package/dist/types/src/application/dlqRetry.d.ts

@@ -0,0 +1,12 @@
+/** DLQ manual and automatic retry transitions. */
+import { type Job, type JobId } from "../domain/types/job.js";
+import type { DlqFilter } from "../domain/types/dlq.js";
+import type { DlqContext } from "./dlqManager.js";
+/** Retry a single job from DLQ and reset the automatic retry generation. */
+export declare function retryDlqJob(queue: string, jobId: JobId, ctx: DlqContext): Job | null;
+/** Retry jobs from DLQ, optionally bounded to the oldest `limit` entries. */
+export declare function retryDlqJobs(queue: string, ctx: DlqContext, jobId?: JobId, limit?: number): number;
+/** Retry all DLQ entries selected by a metadata filter. */
+export declare function retryDlqByFilter(queue: string, ctx: DlqContext, filter: DlqFilter): number;
+/** Dispatch due auto-retries while preserving their bounded retry chain. */
+export declare function processAutoRetry(queue: string, ctx: DlqContext): number;

package/dist/types/src/application/emptyQueueCleanup.d.ts

@@ -0,0 +1,3 @@
+import type { BackgroundContext } from "./types/index.js";
+/** Reconcile registered names with every live or durable queue projection. */
+export declare function cleanEmptyQueues(ctx: BackgroundContext): void;

package/dist/types/src/application/eventsManager.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Events Manager
+ * Job event subscription and broadcasting
+ */
+import type { JobId } from "../domain/types/job.js";
+import { EventType, type JobEvent } from "../domain/types/queue.js";
+import type { WebhookManager } from "./webhookManager.js";
+/** Event subscriber callback */
+export type EventSubscriber = (event: JobEvent) => void;
+export type EventBatchSubscriber = (events: readonly JobEvent[]) => void;
+/** Events manager class */
+export declare class EventsManager {
+    private readonly webhookManager;
+    /** Use Set for O(1) subscribe/unsubscribe instead of indexOf+splice */
+    private readonly subscribers;
+    /** Optional batch path for internal subscribers such as durable telemetry. */
+    private readonly batchSubscribers;
+    /** Waiters for specific job completions - for efficient WaitJob implementation */
+    private readonly completionWaiters;
+    constructor(webhookManager: WebhookManager);
+    /** Number of active event subscribers */
+    get subscriberCount(): number;
+    /** Number of jobs with active completion waiters */
+    get completionWaiterCount(): number;
+    /** Subscribe to job events - O(1) add and remove */
+    subscribe(callback: EventSubscriber, batchCallback?: EventBatchSubscriber): () => void;
+    /** Clear all subscribers (for shutdown) */
+    clear(): void;
+    /**
+     * Wait for a specific job to complete - event-driven, no polling
+     * Returns true if job completed, false if timeout
+     */
+    waitForJobCompletion(jobId: JobId, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    /** Check if broadcast has any listeners - for batch optimizations */
+    needsBroadcast(): boolean;
+    /** Broadcast event to all subscribers - optimized to skip work when no listeners */
+    broadcast(event: Partial<JobEvent> & {
+        eventType: EventType;
+        queue: string;
+        jobId: JobId;
+        timestamp: number;
+        error?: string;
+    }): void;
+    /** Broadcast an ordered batch while allowing internal subscribers to persist once. */
+    broadcastBatch(events: readonly JobEvent[]): void;
+    private notifyCompletionWaiters;
+    private triggerWebhook;
+    /** Map internal event type to webhook event */
+    private mapEventToWebhook;
+}

package/dist/types/src/application/flowFailureRecovery.d.ts

@@ -0,0 +1,20 @@
+import type { JobId } from "../domain/types/job.js";
+import type { JobLocation } from "../domain/types/queue.js";
+import type { Shard } from "../domain/queue/shard.js";
+import type { SqliteStorage } from "../infrastructure/persistence/sqlite.js";
+import type { SetLike } from "../shared/lru.js";
+import type { DependencyResultTracker } from "./dependencyResultTracker.js";
+import { type DependencyCompletionTracker } from "./dependencyCompletions.js";
+export interface FlowFailureRecoveryContext {
+    readonly storage: SqliteStorage;
+    readonly shards: Shard[];
+    readonly jobIndex: Map<JobId, JobLocation>;
+    readonly completedJobs: SetLike<JobId>;
+    readonly depCompletions?: DependencyCompletionTracker;
+    readonly maxDependencyCompletions: number;
+    readonly dependencyResults: DependencyResultTracker;
+    readonly failedChildrenValues: Map<JobId, Record<string, string>>;
+    readonly ignoredChildrenFailures: Map<JobId, Record<string, string>>;
+}
+/** Replay the durable flow-failure outbox before workers can observe recovered jobs. */
+export declare function recoverFlowFailures(ctx: FlowFailureRecoveryContext): void;

package/dist/types/src/application/flowParentBackpatch.d.ts

@@ -0,0 +1,27 @@
+import type { Job, JobId } from "../domain/types/job.js";
+import type { JobLocation } from "../domain/types/queue.js";
+import type { Shard } from "../domain/queue/shard.js";
+import type { SqliteStorage } from "../infrastructure/persistence/sqlite.js";
+import type { RWLock } from "../shared/lock.js";
+import type { MapLike, SetLike } from "../shared/lru.js";
+export interface FlowParentBackpatchContext {
+    readonly storage: SqliteStorage | null;
+    readonly customIdLock: RWLock;
+    readonly shards: Shard[];
+    readonly shardLocks: RWLock[];
+    readonly processingShards: Map<JobId, Job>[];
+    readonly processingLocks: RWLock[];
+    readonly jobIndex: Map<JobId, JobLocation>;
+    readonly completedJobsData: MapLike<JobId, Job>;
+    readonly depCompletions: SetLike<JobId>;
+}
+/** Reject a backpatch that would steal a child from an existing real parent. */
+export declare function assertFlowParentOwnership(child: Job, parentId: JobId): void;
+export declare function isDeclaredFlowChild(parent: Job, childId: JobId): boolean;
+export declare function canAcceptRemovedFlowChild(parent: Job | null, childId: JobId, depCompletions: SetLike<JobId>): boolean;
+export declare function flowChildFailureError(child: Job, shards: Shard[]): string | undefined;
+/**
+ * Replace the legacy `pending` parent marker for an edge already declared by
+ * the parent. This operation never changes parent scheduling or terminal state.
+ */
+export declare function backpatchDeclaredFlowChild(child: Job, parent: Job, ctx: FlowParentBackpatchContext): Promise<Job>;

package/dist/types/src/application/jobLogsManager.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Job Logs Manager
+ * Per-job logging operations
+ */
+import type { JobId } from "../domain/types/job.js";
+import { type JobLogEntry } from "../domain/types/worker.js";
+import type { JobLocation } from "../domain/types/queue.js";
+import type { MapLike } from "../shared/lru.js";
+/** Context for job logs operations */
+export interface JobLogsContext {
+    jobIndex: Map<JobId, JobLocation>;
+    jobLogs: MapLike<JobId, JobLogEntry[]>;
+    jobLogQueues: Map<JobId, string>;
+    maxLogsPerJob: number;
+}
+/** Add log entry to a job */
+export declare function addJobLog(jobId: JobId, message: string, ctx: JobLogsContext, level?: 'info' | 'warn' | 'error'): boolean;
+/** Get logs for a job */
+export declare function getJobLogs(jobId: JobId, ctx: JobLogsContext): JobLogEntry[];
+/** Clear logs for a job, optionally keeping the most recent N entries */
+export declare function clearJobLogs(jobId: JobId, ctx: JobLogsContext, keepLogs?: number): void;