bunqueue-client 0.1.9 → 0.2.0

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

@@ -0,0 +1,39 @@
+/**
+ * Latency Tracker
+ * Centralized latency tracking for all operations
+ */
+import { Histogram } from "../shared/histogram.js";
+/** Operation latency histograms */
+export declare class LatencyTracker {
+    readonly push: Histogram;
+    readonly pull: Histogram;
+    readonly ack: Histogram;
+    /** Generate Prometheus output for all histograms */
+    toPrometheus(): string;
+    /** Get average latencies */
+    getAverages(): {
+        pushMs: number;
+        pullMs: number;
+        ackMs: number;
+    };
+    /** Get percentiles for all operations */
+    getPercentiles(): {
+        push: {
+            p50: number;
+            p95: number;
+            p99: number;
+        };
+        pull: {
+            p50: number;
+            p95: number;
+            p99: number;
+        };
+        ack: {
+            p50: number;
+            p95: number;
+            p99: number;
+        };
+    };
+}
+/** Global singleton */
+export declare const latencyTracker: LatencyTracker;

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

@@ -0,0 +1,15 @@
+/**
+ * Lock Manager - Job lock and client tracking
+ * Handles BullMQ-style lock-based job ownership
+ */
+import type { LockContext } from "./types/index.js";
+export { createLock, verifyLock, renewJobLock, renewJobLockBatch, releaseLock, getLockInfo, } from "./lockOperations.js";
+export { registerClientJob, unregisterClientJob, releaseClientJobs, forceReleaseClientJobs, } from "./clientTracking.js";
+/**
+ * Check and handle expired locks.
+ * Jobs with expired locks are requeued for retry.
+ *
+ * Uses proper locking to prevent race conditions.
+ * Lock hierarchy: shards[N] -> processingShards[N] (per CLAUDE.md)
+ */
+export declare function checkExpiredLocks(ctx: LockContext): Promise<void>;

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

@@ -0,0 +1,38 @@
+/**
+ * Lock Operations - Job lock creation, verification, renewal
+ */
+import type { JobId, JobLock, LockToken } from "../domain/types/job.js";
+import type { LockContext } from "./types/index.js";
+/**
+ * Create a lock for a job when it's pulled for processing.
+ * @returns The lock token, or null if job not in processing
+ */
+export declare function createLock(jobId: JobId, owner: string, ctx: LockContext, ttl?: number): LockToken | null;
+/**
+ * Verify that a token is valid for a job.
+ * @returns true if token matches the active lock
+ */
+export declare function verifyLock(jobId: JobId, token: string, ctx: LockContext): boolean;
+/**
+ * Renew a lock with the given token.
+ * @returns true if renewal succeeded, false if token invalid or lock expired
+ */
+export declare function renewJobLock(jobId: JobId, token: string, ctx: LockContext, newTtl?: number): boolean;
+/**
+ * Renew locks for multiple jobs (batch operation).
+ * @returns Array of jobIds that were successfully renewed
+ */
+export declare function renewJobLockBatch(items: Array<{
+    id: JobId;
+    token: string;
+    ttl?: number;
+}>, ctx: LockContext): string[];
+/**
+ * Release a lock when job is completed or failed.
+ * Should be called by ACK/FAIL operations.
+ */
+export declare function releaseLock(jobId: JobId, ctx: LockContext, token?: string): boolean;
+/**
+ * Get lock info for a job (for debugging/monitoring).
+ */
+export declare function getLockInfo(jobId: JobId, ctx: LockContext): JobLock | null;

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

@@ -0,0 +1,27 @@
+/**
+ * Metrics Exporter
+ * Prometheus metrics generation
+ */
+import type { WorkerManager } from "./workerManager.js";
+import type { WebhookManager } from "./webhookManager.js";
+import type { PerQueueStats } from "./statsManager.js";
+import { type SystemMetrics } from "./prometheusOperationalMetrics.js";
+export type { OperationalMetrics, SystemMetrics } from "./prometheusOperationalMetrics.js";
+/** Stats data structure */
+export interface QueueStats {
+    waiting: number;
+    prioritized: number;
+    delayed: number;
+    active: number;
+    dlq: number;
+    completed: number;
+    totalPushed: bigint;
+    totalPulled: bigint;
+    totalCompleted: bigint;
+    totalFailed: bigint;
+    uptime: number;
+    cronJobs: number;
+    cronPending: number;
+}
+/** Generate Prometheus metrics */
+export declare function generatePrometheusMetrics(stats: QueueStats, workerManager: WorkerManager, webhookManager: WebhookManager, perQueueStats?: Map<string, PerQueueStats>, systemMetrics?: SystemMetrics): string;

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

@@ -0,0 +1,36 @@
+/**
+ * Monitoring Checks - Periodic threshold/state monitoring
+ * Emits dashboard events for queue:idle, queue:threshold,
+ * worker:overloaded, storage:size-warning, server:memory-warning
+ */
+import type { WorkerManager } from "./workerManager.js";
+import type { Shard } from "../domain/queue/shard.js";
+/** Monitoring state — tracked across intervals */
+export interface MonitoringState {
+    /** queue → timestamp when it became idle */
+    queueIdleSince: Map<string, number>;
+    /** queues that already emitted threshold warning */
+    queueThresholdEmitted: Set<string>;
+    /** workerId → timestamp when became overloaded */
+    workerOverloadedSince: Map<string, number>;
+    /** Whether storage warning was already emitted */
+    storageWarningEmitted: boolean;
+    /** Whether memory warning was already emitted */
+    memoryWarningEmitted: boolean;
+}
+export declare function createMonitoringState(): MonitoringState;
+export interface MonitoringContext {
+    queueNamesCache: Set<string>;
+    shards: Shard[];
+    processingShards: Map<unknown, {
+        queue: string;
+    }>[];
+    workerManager: WorkerManager;
+    storage: {
+        getSize(): number;
+    } | null;
+    dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
+    state: MonitoringState;
+}
+/** Check all monitoring conditions — called from cleanup interval (10s) */
+export declare function runMonitoringChecks(ctx: MonitoringContext): void;

package/dist/types/src/application/operations/ack/batch.d.ts

@@ -0,0 +1,8 @@
+import type { JobId } from "../../../domain/types/job.js";
+import type { AckContext, CompletionOptions } from "../../types/ack.js";
+export declare function ackJobBatch(jobIds: JobId[], ctx: AckContext, leaseTokens?: Array<string | undefined>): Promise<boolean[]>;
+export declare function ackJobBatchWithResults(items: Array<{
+    id: JobId;
+    result: unknown;
+    token?: string;
+} & CompletionOptions>, ctx: AckContext): Promise<boolean[]>;

package/dist/types/src/application/operations/ack/completion.d.ts

@@ -0,0 +1,3 @@
+import { type JobId } from "../../../domain/types/job.js";
+import type { AckContext, CompletionOptions } from "../../types/ack.js";
+export declare function ackJob(jobId: JobId, result: unknown, ctx: AckContext, options?: CompletionOptions): Promise<boolean>;

package/dist/types/src/application/operations/ack/failure.d.ts

@@ -0,0 +1,3 @@
+import { type JobId } from "../../../domain/types/job.js";
+import type { AckContext, FailJobOptions } from "../../types/ack.js";
+export declare function failJob(jobId: JobId, error: string | undefined, ctx: AckContext, options?: FailJobOptions): Promise<void>;

package/dist/types/src/application/operations/ack.d.ts

@@ -0,0 +1,5 @@
+/** Stable acknowledgement-operation import surface. */
+export { ackJobBatch, ackJobBatchWithResults } from "./ack/batch.js";
+export { ackJob } from "./ack/completion.js";
+export { failJob } from "./ack/failure.js";
+export type { AckContext } from "../types/ack.js";

package/dist/types/src/application/operations/ackHelpers.d.ts

@@ -0,0 +1,36 @@
+/** Shared batch acknowledgement utilities. */
+import type { Job, JobId } from "../../domain/types/job.js";
+import type { BatchContext, ExtractedJob, FinalizeContext } from "../types/ack.js";
+export type { BatchContext, ExtractedJob, FinalizeContext } from "../types/ack.js";
+/** Group job IDs by processing shard. */
+export declare function groupByProcShard(jobIds: JobId[]): Map<number, JobId[]>;
+/**
+ * Group items by processing shard (with results)
+ */
+export declare function groupItemsByProcShard<T extends {
+    id: JobId;
+}>(items: T[]): Map<number, T[]>;
+/**
+ * Extract jobs from processing shards (one lock per shard)
+ */
+export declare function extractJobs(byProcShard: Map<number, JobId[]>, ctx: BatchContext): Promise<ExtractedJob[]>;
+/**
+ * Extract jobs with results from processing shards
+ */
+export declare function extractJobsWithResults<T>(byProcShard: Map<number, Array<{
+    id: JobId;
+    result: T;
+    removeOnComplete?: boolean;
+}>>, ctx: BatchContext): Promise<Array<ExtractedJob<T>>>;
+/**
+ * Group extracted jobs by queue shard
+ */
+export declare function groupByQueueShard(extractedJobs: ExtractedJob[]): Map<number, Job[]>;
+/**
+ * Release resources for each queue shard (one lock per shard)
+ */
+export declare function releaseResources(byQueueShard: Map<number, Job[]>, ctx: BatchContext): Promise<void>;
+/**
+ * Finalize batch ack - update indexes, metrics, broadcast, notify
+ */
+export declare function finalizeBatchAck<T>(extractedJobs: Array<ExtractedJob<T>>, ctx: FinalizeContext, includeResults: boolean): void;

package/dist/types/src/application/operations/customId.d.ts

@@ -0,0 +1,51 @@
+import type { Shard } from "../../domain/queue/shard.js";
+import { type Job, type JobId, type JobInput } from "../../domain/types/job.js";
+import type { JobLocation } from "../../domain/types/queue.js";
+import type { JobLogEntry } from "../../domain/types/worker.js";
+import type { SqliteStorage } from "../../infrastructure/persistence/sqlite.js";
+import type { MapLike, SetLike } from "../../shared/lru.js";
+import type { DependencyCompletionTracker } from "../dependencyCompletions.js";
+import type { RetiredTimeoutGeneration } from "../types/background.js";
+export interface CustomIdContext {
+    storage: SqliteStorage | null;
+    shards: Shard[];
+    completedJobs: SetLike<JobId>;
+    completedJobsData: MapLike<JobId, Job>;
+    depCompletions?: DependencyCompletionTracker;
+    maxDependencyCompletions: number;
+    timedOutJobs?: MapLike<JobId, RetiredTimeoutGeneration>;
+    retiredTimeoutLeaseTokens?: MapLike<string, RetiredTimeoutGeneration>;
+    retiredCronLeaseTokens?: MapLike<JobId, string>;
+    jobResults: MapLike<JobId, unknown>;
+    jobResultQueues: Map<JobId, string>;
+    jobLogs: MapLike<JobId, JobLogEntry[]>;
+    jobLogQueues: Map<JobId, string>;
+    customIdMap: MapLike<string, JobId>;
+    jobIndex: Map<JobId, JobLocation>;
+}
+export type CustomIdResult = {
+    skip: true;
+    existingJob: Job;
+} | {
+    skip: true;
+    existingId: JobId;
+} | {
+    skip: false;
+    id: JobId;
+    retirement?: CustomIdRetirement;
+};
+export interface CustomIdRetirement {
+    readonly completed: boolean;
+    readonly dlqQueue?: string;
+    readonly dependencyCompletion: boolean;
+}
+/**
+ * Inspect custom-ID idempotency while the caller holds the target shard lock.
+ * Terminal retirement is deliberately deferred until persistence commits, so
+ * a rejected durable generation cannot destroy the previous one.
+ */
+export declare function handleCustomId(input: JobInput, ctx: CustomIdContext, lockedShardIndexes: ReadonlySet<number>): CustomIdResult;
+/** Publish custom-ID ownership after the matching storage admission succeeds. */
+export declare function commitCustomIdAdmission(input: JobInput, decision: Exclude<CustomIdResult, {
+    skip: true;
+}>, ctx: CustomIdContext): void;

package/dist/types/src/application/operations/flowPush.d.ts

@@ -0,0 +1,9 @@
+import type { AtomicFlowBatchInput, AtomicFlowBatchResult } from "../../domain/types/flow.js";
+import { type PushContext } from "./pushContext.js";
+/**
+ * Commit a complete flow graph as one broker-side operation.
+ *
+ * SQLite is committed before the graph is published in memory. Workers acquire
+ * the same shard locks, so the first visible leaf always observes every edge.
+ */
+export declare function pushFlowBatch(batch: AtomicFlowBatchInput, ctx: PushContext): Promise<AtomicFlowBatchResult>;

package/dist/types/src/application/operations/flowTopologyValidation.d.ts

@@ -0,0 +1,3 @@
+import type { AtomicFlowBatchInput } from "../../domain/types/flow.js";
+/** Validate references, symmetric parent edges, metadata, and acyclicity in O(V+E). */
+export declare function validateFlowTopology(batch: AtomicFlowBatchInput, dataById: ReadonlyMap<string, Record<string, unknown>>): void;

package/dist/types/src/application/operations/flowValidation.d.ts

@@ -0,0 +1,3 @@
+import type { AtomicFlowBatchInput } from "../../domain/types/flow.js";
+/** Validate the whole graph before any lock, storage write, or queue mutation. */
+export declare function validateAtomicFlowBatch(batch: AtomicFlowBatchInput): void;

package/dist/types/src/application/operations/jobClaim.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cleanup shared ownership state when a management operation claims an active
+ * job before its worker can ACK or FAIL it.
+ */
+import type { JobId, JobLock } from "../../domain/types/job.js";
+export interface JobClaimContext {
+    jobLocks: Map<JobId, JobLock>;
+    clientJobs: Map<string, Set<JobId>>;
+}
+/**
+ * Release the live lease and detach the job from its TCP client owner.
+ *
+ * Map/Set deletion is intentionally idempotent: management commands can race
+ * with disconnect cleanup, but ownership must be removed exactly once from the
+ * observable state.
+ */
+export declare function releaseClaimedJobOwnership(jobId: JobId, ctx: JobClaimContext): void;

package/dist/types/src/application/operations/jobManagement.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Job Management Operations
+ * Cancel, update progress, change priority, promote, move to delayed, discard
+ */
+import type { Job, JobId, JobLock } 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 { WebhookManager } from "../webhookManager.js";
+import type { EventsManager } from "../eventsManager.js";
+import { type RWLock } from "../../shared/lock.js";
+import type { DependencyResultTracker } from "../dependencyResultTracker.js";
+import { type DependencyCompletionTracker } from "../dependencyCompletions.js";
+export { discardJob, moveJobToDelayed } from "./jobMoveOperations.js";
+/** Context for job management operations */
+export interface JobManagementContext {
+    storage: SqliteStorage | null;
+    shards: Shard[];
+    shardLocks: RWLock[];
+    processingShards: Map<JobId, Job>[];
+    processingLocks: RWLock[];
+    jobIndex: Map<JobId, JobLocation>;
+    jobLocks: Map<JobId, JobLock>;
+    clientJobs: Map<string, Set<JobId>>;
+    webhookManager: WebhookManager;
+    eventsManager: EventsManager;
+    repeatChain?: Map<JobId, JobId>;
+    dependencyResults: DependencyResultTracker;
+    customIdMap: {
+        get(id: string): JobId | undefined;
+        delete(id: string): boolean;
+    };
+    depCompletions?: DependencyCompletionTracker;
+    maxDependencyCompletions: number;
+}
+/** Cancel a job (remove from queue) */
+export declare function cancelJob(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;
+/** Update job progress */
+export declare function updateJobProgress(jobId: JobId, progress: number, ctx: JobManagementContext, message?: string): Promise<boolean>;
+/** Update job data */
+export declare function updateJobData(jobId: JobId, data: unknown, ctx: JobManagementContext): Promise<boolean>;
+/** Change job priority */
+export declare function changeJobPriority(jobId: JobId, priority: number, ctx: JobManagementContext, lifo?: boolean): Promise<boolean>;

package/dist/types/src/application/operations/jobMoveOperations.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Job move operations that claim active jobs for delayed or DLQ state.
+ */
+import type { JobId } from "../../domain/types/job.js";
+import type { JobManagementContext } from "./jobManagement.js";
+/** Move active job back to delayed. */
+export declare function moveJobToDelayed(jobId: JobId, delay: number, ctx: JobManagementContext): Promise<boolean>;
+/** Discard a waiting or active job to the DLQ. */
+export declare function discardJob(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;

package/dist/types/src/application/operations/jobPromotion.d.ts

@@ -0,0 +1,7 @@
+/** Delayed-job promotion operations shared by embedded and server modes. */
+import type { JobId } from "../../domain/types/job.js";
+import type { JobManagementContext } from "./jobManagement.js";
+/** Promote one delayed job and persist the transition before resolving. */
+export declare function promoteJob(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;
+/** Promote the oldest delayed jobs from the live shard, never an eventual SQL listing. */
+export declare function promoteJobs(queueName: string, count: number | undefined, ctx: JobManagementContext): Promise<number>;

package/dist/types/src/application/operations/jobStateTransitions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Job State Transition Operations
+ * BullMQ v5 compatible manual state transitions:
+ * - moveActiveToWait: Active -> Waiting
+ * - changeWaitingDelay: Waiting -> Delayed
+ * - moveToWaitingChildren: Active -> WaitingChildren
+ */
+import { type JobId } from "../../domain/types/job.js";
+import type { JobManagementContext } from "./jobManagement.js";
+/** Move active job back to waiting */
+export declare function moveActiveToWait(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;
+/** Change delay for a waiting/delayed job in queue */
+export declare function changeWaitingDelay(jobId: JobId, delay: number, ctx: JobManagementContext): Promise<boolean>;
+/** Move active job to waiting-children state */
+export declare function moveToWaitingChildren(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;

package/dist/types/src/application/operations/parentLink.d.ts

@@ -0,0 +1,36 @@
+import { type Job, type JobId, type JobInput } from "../../domain/types/job.js";
+import type { Shard } from "../../domain/queue/shard.js";
+import { type DedupResult } from "./pushDeduplication.js";
+import { type AcceptedCustomId } from "./pushAdmission.js";
+import type { PushContext } from "./pushContext.js";
+type ParentMembership = 'queue' | 'waiting-deps' | 'waiting-children';
+export interface ParentLinkPlan {
+    readonly child: Job;
+    readonly parent: Job;
+    readonly linkedChild: Job;
+    readonly linkedParent: Job;
+    readonly parentMembership: ParentMembership;
+    readonly childFinished: boolean;
+}
+/** Validate every parent before a batch mutates its accepted prefix. */
+export declare function validateParentLinkInputs(inputs: readonly JobInput[], ctx: PushContext): void;
+export declare function prepareParentLink(child: Job, ctx: PushContext, childFinished?: boolean, parentIdOverride?: JobId, now?: number): ParentLinkPlan;
+/** Publish a persisted link while the parent and child queue shards are locked. */
+export declare function commitParentLink(plan: ParentLinkPlan, ctx: PushContext): void;
+export declare function parentLinkState(plan: ParentLinkPlan): 'waiting-children' | 'waiting' | 'prioritized' | 'delayed';
+/** Persist and publish a new child and its existing parent as one locked operation. */
+export declare function acceptParentedJob(options: {
+    job: Job;
+    input: JobInput;
+    target: {
+        queue: string;
+        shard: Shard;
+        shardIdx: number;
+    };
+    dedup: Exclude<DedupResult, {
+        skip: true;
+    }>;
+    customId: AcceptedCustomId;
+    ctx: PushContext;
+}): JobId[];
+export {};

package/dist/types/src/application/operations/parentLinkInput.d.ts

@@ -0,0 +1,8 @@
+import type { JobInput } from "../../domain/types/job.js";
+/**
+ * Queue.add parent options carry the parent queue in reserved metadata. A bare
+ * parentId remains the legacy flow forward-reference contract and is linked
+ * later when the parent declares the edge.
+ */
+export declare function parentLinkQueue(input: JobInput): string | null;
+export declare function isParentLinkInput(input: JobInput): boolean;

package/dist/types/src/application/operations/pull.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pull Operations
+ * Job pull logic with timeout support
+ */
+import type { Job } from "../../domain/types/job.js";
+import { type GroupPullOptions } from "../../domain/types/group.js";
+import { type PullContext } from "./pullStateTransition.js";
+export type { PullContext } from "./pullStateTransition.js";
+interface PullRequestOptions {
+    signal?: AbortSignal;
+    group?: GroupPullOptions;
+}
+/**
+ * Pull next job from queue
+ */
+export declare function pullJob(queue: string, timeoutMs: number, ctx: PullContext, signal?: AbortSignal, groupOptions?: GroupPullOptions): Promise<Job | null>;
+/**
+ * Pull multiple jobs from queue
+ */
+export declare function pullJobBatch(queue: string, count: number, timeoutMs: number, ctx: PullContext, options?: PullRequestOptions): Promise<Job[]>;

package/dist/types/src/application/operations/pullFinalization.d.ts

@@ -0,0 +1,6 @@
+import type { Job } from "../../domain/types/job.js";
+import type { PullContext } from "./pullStateTransition.js";
+/** Persist and publish a single processing handoff. */
+export declare function finalizeProcessing(job: Job, queue: string, ctx: PullContext): boolean;
+/** Persist and publish all processing handoffs with one durable state transaction. */
+export declare function finalizeProcessingBatch(jobs: Job[], queue: string, ctx: PullContext): Job[];

package/dist/types/src/application/operations/pullStateTransition.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Atomic queue-state transitions used by single and batch pull orchestration.
+ */
+import type { Shard } from "../../domain/queue/shard.js";
+import { type Job, type JobId } from "../../domain/types/job.js";
+import type { GroupPullOptions } from "../../domain/types/group.js";
+import type { EventType, JobEvent, JobLocation } from "../../domain/types/queue.js";
+import type { SqliteStorage } from "../../infrastructure/persistence/sqlite.js";
+import type { RWLock } from "../../shared/lock.js";
+/** Dependencies shared by the single and batch pull paths. */
+export interface PullContext {
+    storage: SqliteStorage | null;
+    shards: Shard[];
+    shardLocks: RWLock[];
+    processingShards: Map<JobId, Job>[];
+    processingLocks: RWLock[];
+    jobIndex: Map<JobId, JobLocation>;
+    totalPulled: {
+        value: bigint;
+    };
+    broadcast: (event: {
+        eventType: EventType;
+        queue: string;
+        jobId: JobId;
+        timestamp: number;
+    }) => void;
+    broadcastBatch?: (events: readonly JobEvent[]) => void;
+    dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
+}
+export interface DequeueScan {
+    parked: Job[];
+    nextRunAt: number | null;
+    groupOptions?: GroupPullOptions;
+}
+export type DequeueResult = {
+    status: 'job';
+    job: Job;
+} | {
+    status: 'stop';
+};
+export declare function createDequeueScan(groupOptions?: GroupPullOptions): DequeueScan;
+/** Restore physical heap membership without changing logical queue state. */
+export declare function restoreParkedJobs(shard: Shard, queue: string, scan: DequeueScan): void;
+/**
+ * Remove the best eligible job from the shard's secondary group indexes.
+ * A batch reuses the same fixed timestamp and group defaults while its
+ * synchronous shard critical section is held.
+ */
+export declare function tryDequeueNextJob(shard: Shard, queue: string, now: number, ctx: PullContext, scan: DequeueScan): DequeueResult;
+/** Restore a dequeued job when its handoff to the worker cannot complete. */
+export declare function requeueJob(job: Job, queue: string, idx: number, ctx: PullContext): Promise<void>;

package/dist/types/src/application/operations/push.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Push Operations
+ * Single-job push logic and stable batch re-export
+ */
+import { type Job, type JobInput } from "../../domain/types/job.js";
+import type { PushContext } from "./pushContext.js";
+export type { PushContext } from "./pushContext.js";
+export { pushJobBatch } from "./pushBatch.js";
+/**
+ * Push a single job to queue
+ * NOTE: customId check happens INSIDE lock to prevent race conditions
+ */
+export declare function pushJob(queue: string, input: JobInput, ctx: PushContext): Promise<Job>;

package/dist/types/src/application/operations/pushAdmission.d.ts

@@ -0,0 +1,36 @@
+import type { Job, JobInput } from "../../domain/types/job.js";
+import type { Shard } from "../../domain/queue/shard.js";
+import type { DurableAdmissionMetadata } from "../../infrastructure/persistence/sqlite.js";
+import { type CustomIdResult } from "./customId.js";
+import type { PushContext } from "./pushContext.js";
+import { type PreparedJobInsertion } from "./pushInsert.js";
+export type AcceptedCustomId = Exclude<CustomIdResult, {
+    skip: true;
+}>;
+export interface PushTarget {
+    queue: string;
+    shard: Shard;
+    shardIdx: number;
+}
+export interface CapturedPushError {
+    readonly value: unknown;
+}
+export declare function capturePushError(value: unknown): CapturedPushError;
+interface PublishPreparedJobOptions {
+    job: Job;
+    input: JobInput;
+    target: PushTarget;
+    customId: AcceptedCustomId;
+    prepared: PreparedJobInsertion;
+    ctx: PushContext;
+    registerDedupKey?: boolean;
+}
+export declare function admissionMetadata(customId: AcceptedCustomId, prepared: PreparedJobInsertion): DurableAdmissionMetadata | undefined;
+/** Publish only non-throwing RAM ownership after the storage admission commits. */
+export declare function publishPreparedJob(options: PublishPreparedJobOptions): void;
+/** Persist or buffer every storage-backed admission before exposing it in RAM. */
+export declare function acceptStandardJob(job: Job, input: JobInput, target: PushTarget, customId: AcceptedCustomId, ctx: PushContext): {
+    storageHandled: boolean;
+};
+export declare function throwPushErrors(errors: Array<CapturedPushError | undefined>, message: string): void;
+export {};

package/dist/types/src/application/operations/pushBatch.d.ts

@@ -0,0 +1,4 @@
+import { type JobId, type JobInput } from "../../domain/types/job.js";
+import type { PushContext } from "./pushContext.js";
+/** Push an ordered batch while preserving its accepted-prefix contract. */
+export declare function pushJobBatch(queue: string, inputs: JobInput[], ctx: PushContext): Promise<JobId[]>;

package/dist/types/src/application/operations/pushContext.d.ts

@@ -0,0 +1,48 @@
+import type { Shard } from "../../domain/queue/shard.js";
+import type { Job, JobId } from "../../domain/types/job.js";
+import type { JobLocation } from "../../domain/types/queue.js";
+import type { JobLogEntry } from "../../domain/types/worker.js";
+import { type EventType, type JobEvent } from "../../domain/types/queue.js";
+import type { SqliteStorage } from "../../infrastructure/persistence/sqlite.js";
+import type { RWLock } from "../../shared/lock.js";
+import type { MapLike, SetLike } from "../../shared/lru.js";
+import type { DependencyCompletionTracker } from "../dependencyCompletions.js";
+import type { DependencyResultTracker } from "../dependencyResultTracker.js";
+import type { RetiredTimeoutGeneration } from "../types/background.js";
+/** Shared mutable state required by queue and flow insertion operations. */
+export interface PushContext {
+    storage: SqliteStorage | null;
+    shards: Shard[];
+    shardLocks: RWLock[];
+    customIdLock: RWLock;
+    completedJobs: SetLike<JobId>;
+    completedJobsData: MapLike<JobId, Job>;
+    depCompletions?: DependencyCompletionTracker;
+    maxDependencyCompletions: number;
+    timedOutJobs?: MapLike<JobId, RetiredTimeoutGeneration>;
+    retiredTimeoutLeaseTokens?: MapLike<string, RetiredTimeoutGeneration>;
+    retiredCronLeaseTokens?: MapLike<JobId, string>;
+    jobResults: MapLike<JobId, unknown>;
+    jobResultQueues: Map<JobId, string>;
+    jobLogs: MapLike<JobId, JobLogEntry[]>;
+    jobLogQueues: Map<JobId, string>;
+    dependencyResults: DependencyResultTracker;
+    customIdMap: MapLike<string, JobId>;
+    jobIndex: Map<JobId, JobLocation>;
+    pendingQueueAdmissions: Map<string, number>;
+    totalPushed: {
+        value: bigint;
+    };
+    broadcast: (event: {
+        eventType: EventType;
+        queue: string;
+        jobId: JobId;
+        timestamp: number;
+    }) => void;
+    broadcastBatch?: (events: readonly JobEvent[]) => void;
+    dashboardEmit?: (event: string, data: Record<string, unknown>) => void;
+    registerQueueName?: (queue: string) => void;
+    onQueueAdmissionsDrained?: (queue: string) => void;
+}
+/** Keep every target queue owned while an asynchronous admission is in flight. */
+export declare function withPendingQueueAdmissions<T>(queues: Iterable<string>, ctx: Pick<PushContext, 'pendingQueueAdmissions' | 'registerQueueName' | 'onQueueAdmissionsDrained'>, operation: () => Promise<T>): Promise<T>;