bunqueue 2.8.53 → 2.8.56

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

@@ -1,24 +1,7 @@
 /** Shared batch acknowledgement utilities. */
 import type { Job, JobId } from '../../domain/types/job';
-import type { JobLocation, EventType } from '../../domain/types/queue';
-import type { Shard } from '../../domain/queue/shard';
-import type { RWLock } from '../../shared/lock';
-import type { SetLike, MapLike } from '../../shared/lru';
-import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
-import type { DependencyResultTracker } from '../dependencyResultTracker';
-import { type DependencyCompletionTracker } from '../dependencyCompletions';
-export interface ExtractedJob<T = unknown> {
-    id: JobId;
-    job: Job;
-    result?: T;
-}
-/** Context for batch operations */
-export interface BatchContext {
-    processingShards: Map<JobId, Job>[];
-    processingLocks: RWLock[];
-    shards: Shard[];
-    shardLocks: RWLock[];
-}
+import type { BatchContext, ExtractedJob, FinalizeContext } from '../types/ack';
+export type { BatchContext, ExtractedJob, FinalizeContext } from '../types/ack';
 /**
  * Group job IDs by processing shard
  * Returns Map<shardIndex, jobIds[]>
@@ -40,6 +23,7 @@ export declare function extractJobs(byProcShard: Map<number, JobId[]>, ctx: Batc
 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
@@ -49,39 +33,6 @@ export declare function groupByQueueShard(extractedJobs: ExtractedJob[]): Map<nu
  * Release resources for each queue shard (one lock per shard)
  */
 export declare function releaseResources(byQueueShard: Map<number, Job[]>, ctx: BatchContext): Promise<void>;
-/** Context for finalize operations */
-export interface FinalizeContext {
-    storage: SqliteStorage | null;
-    shards: Shard[];
-    completedJobs: SetLike<JobId>;
-    completedJobsData: MapLike<JobId, Job>;
-    /** Bare completion ids for removeOnComplete jobs so dependents can unblock */
-    depCompletions?: DependencyCompletionTracker;
-    maxDependencyCompletions: number;
-    jobResults: MapLike<JobId, unknown>;
-    dependencyResults?: DependencyResultTracker;
-    jobIndex: Map<JobId, JobLocation>;
-    customIdMap?: MapLike<string, JobId>;
-    totalCompleted: {
-        value: bigint;
-    };
-    perQueueMetrics?: MapLike<string, {
-        totalCompleted: bigint;
-        totalFailed: bigint;
-    }>;
-    broadcast: (event: {
-        eventType: EventType;
-        queue: string;
-        jobId: JobId;
-        timestamp: number;
-        data?: unknown;
-    }) => void;
-    onJobCompleted: (jobId: JobId) => void;
-    onJobsCompleted?: (jobIds: JobId[]) => void;
-    needsBroadcast?: () => boolean;
-    hasPendingDeps?: () => boolean;
-    onRepeat?: (job: Job) => void;
-}
 /**
  * Finalize batch ack - update indexes, metrics, broadcast, notify
  */

package/dist/application/operations/ackHelpers.js

@@ -1,8 +1,9 @@
 import { MAX_TIMELINE_ENTRIES } from '../../domain/types/job';
+import { setDlqRetryState } from '../../domain/types/dlq';
 import { withWriteLock } from '../../shared/lock';
 import { shardIndex, processingShardIndex } from '../../shared/hash';
 import { throughputTracker } from '../throughputTracker';
-import { commitRemovedCompletion, } from '../dependencyCompletions';
+import { commitRemovedCompletion } from '../dependencyCompletions';
 /**
  * Group job IDs by processing shard
  * Returns Map<shardIndex, jobIds[]>
@@ -65,7 +66,12 @@ export async function extractJobsWithResults(byProcShard, ctx) {
                 const job = ctx.processingShards[procIdx].get(item.id);
                 if (job) {
                     ctx.processingShards[procIdx].delete(item.id);
-                    extractedJobs.push({ id: item.id, job, result: item.result });
+                    extractedJobs.push({
+                        id: item.id,
+                        job,
+                        result: item.result,
+                        removeOnComplete: item.removeOnComplete,
+                    });
                 }
             }
         });
@@ -97,7 +103,7 @@ export async function releaseResources(byQueueShard, ctx) {
         await withWriteLock(ctx.shardLocks[idx], () => {
             const shard = ctx.shards[idx];
             for (const job of jobs) {
-                shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
+                shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId, job.id);
             }
         });
     }));
@@ -134,11 +140,12 @@ export function finalizeBatchAck(extractedJobs, ctx, includeResults) {
     // checking completedJobs.has(jobId) will always find the result available.
     for (let i = 0; i < jobCount; i++) {
         const { id: jobId, job, result } = extractedJobs[i];
+        setDlqRetryState(job, null);
         // Release customId so it can be reused
         if (job.customId && ctx.customIdMap) {
             ctx.customIdMap.delete(job.customId);
         }
-        if (!job.removeOnComplete) {
+        if (!(job.removeOnComplete || extractedJobs[i].removeOnComplete === true)) {
             // Mark completion timestamp + timeline
             job.completedAt = now;
             if (job.timeline.length < MAX_TIMELINE_ENTRIES) {

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

@@ -3,7 +3,8 @@ import { type Job, type JobId, type JobInput } from '../../domain/types/job';
 import type { JobLocation } from '../../domain/types/queue';
 import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
 import type { MapLike, SetLike } from '../../shared/lru';
-import { type DependencyCompletionTracker } from '../dependencyCompletions';
+import type { DependencyCompletionTracker } from '../dependencyCompletions';
+import type { RetiredTimeoutGeneration } from '../types/background';
 export interface CustomIdContext {
     storage: SqliteStorage | null;
     shards: Shard[];
@@ -11,7 +12,9 @@ export interface CustomIdContext {
     completedJobsData: MapLike<JobId, Job>;
     depCompletions?: DependencyCompletionTracker;
     maxDependencyCompletions: number;
-    timedOutJobs?: SetLike<JobId>;
+    timedOutJobs?: MapLike<JobId, RetiredTimeoutGeneration>;
+    retiredTimeoutLeaseTokens?: MapLike<string, RetiredTimeoutGeneration>;
+    retiredCronLeaseTokens?: MapLike<JobId, string>;
     jobResults: MapLike<JobId, unknown>;
     customIdMap: MapLike<string, JobId>;
     jobIndex: Map<JobId, JobLocation>;
@@ -25,10 +28,20 @@ export type CustomIdResult = {
 } | {
     skip: false;
     id: JobId;
+    retirement?: CustomIdRetirement;
 };
+export interface CustomIdRetirement {
+    readonly completed: boolean;
+    readonly dlqQueue?: string;
+    readonly dependencyCompletion: boolean;
+}
 /**
- * Enforce custom-ID idempotency while the caller holds the target shard lock.
- * Live generations are returned unchanged; terminal generations are retired
- * before the deterministic ID is admitted again.
+ * 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/application/operations/customId.js

@@ -1,10 +1,9 @@
 import { generateJobId, jobId } from '../../domain/types/job';
 import { shardIndex } from '../../shared/hash';
-import { releaseDependencyCompletionPins, } from '../dependencyCompletions';
 /**
- * Enforce custom-ID idempotency while the caller holds the target shard lock.
- * Live generations are returned unchanged; terminal generations are retired
- * before the deterministic ID is admitted again.
+ * 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 function handleCustomId(input, ctx, lockedShardIndexes) {
     if (!input.customId) {
@@ -31,39 +30,51 @@ export function handleCustomId(input, ctx, lockedShardIndexes) {
             return { skip: true, existingId: id };
         }
     }
-    if (ctx.completedJobs.has(id)) {
-        ctx.completedJobs.delete(id);
-        ctx.completedJobsData.delete(id);
-        ctx.jobResults.delete(id);
-        ctx.jobIndex.delete(id);
-        ctx.storage?.deleteJob(id);
-    }
+    const completed = ctx.completedJobs.has(id);
     const terminalLocation = ctx.jobIndex.get(id);
+    let dlqQueue;
     if (terminalLocation?.type === 'dlq') {
         const terminalShardIdx = shardIndex(terminalLocation.queueName);
         if (!lockedShardIndexes.has(terminalShardIdx)) {
             throw new Error('Terminal custom ID shard must be locked before reuse');
         }
-        const terminalShard = ctx.shards[terminalShardIdx];
-        terminalShard.removeFromDlq(terminalLocation.queueName, id);
-        ctx.jobIndex.delete(id);
-        // deleteDlqEntry removes every persisted generation for this deterministic
-        // id. The fresh jobs row is inserted only after this retirement completes.
-        ctx.storage?.deleteDlqEntry(id);
+        dlqQueue = terminalLocation.queueName;
     }
+    let dependencyCompletion = false;
     if (ctx.depCompletions?.has(id)) {
         const hasUnresolvedConsumers = ctx.shards.some((shard) => (shard.getJobsWaitingFor(id)?.size ?? 0) > 0);
         if (hasUnresolvedConsumers) {
             throw new Error(`Custom ID ${String(id)} still has unresolved dependency consumers`);
         }
-        releaseDependencyCompletionPins([id], ctx);
-        ctx.storage?.deleteDependencyCompletion(id);
-        ctx.depCompletions.delete(id);
+        dependencyCompletion = true;
+    }
+    const retirement = completed || dlqQueue || dependencyCompletion
+        ? { completed, dlqQueue, dependencyCompletion }
+        : undefined;
+    return { skip: false, id, retirement };
+}
+/** Publish custom-ID ownership after the matching storage admission succeeds. */
+export function commitCustomIdAdmission(input, decision, ctx) {
+    const { id, retirement } = decision;
+    if (retirement?.completed) {
+        ctx.completedJobs.delete(id);
+        ctx.completedJobsData.delete(id);
+        ctx.jobResults.delete(id);
+        ctx.jobIndex.delete(id);
+    }
+    if (retirement?.dlqQueue) {
+        const terminalShard = ctx.shards[shardIndex(retirement.dlqQueue)];
+        terminalShard.removeFromDlq(retirement.dlqQueue, id);
+        ctx.jobIndex.delete(id);
     }
-    // A durable jobs row may outlive its in-memory tracking after an interrupted
-    // cleanup. The storage insert upserts that orphan without adding a DELETE to
-    // every custom-ID push.
+    if (retirement?.dependencyCompletion)
+        ctx.depCompletions?.delete(id);
+    // A recycled deterministic ID starts with no timeout or retired-lease state.
+    const timedOutGeneration = ctx.timedOutJobs?.get(id);
     ctx.timedOutJobs?.delete(id);
-    ctx.customIdMap.set(input.customId, id);
-    return { skip: false, id };
+    if (timedOutGeneration?.token)
+        ctx.retiredTimeoutLeaseTokens?.delete(timedOutGeneration.token);
+    ctx.retiredCronLeaseTokens?.delete(id);
+    if (input.customId)
+        ctx.customIdMap.set(input.customId, id);
 }

package/dist/application/operations/flowValidation.js

@@ -1,3 +1,4 @@
+import { normalizeJobPayload } from '../../domain/types/job';
 import { validateFlowTopology } from './flowTopologyValidation';
 const MAX_FLOW_JOBS = 10_000;
 const MAX_JOB_DATA_BYTES = 10 * 1024 * 1024;
@@ -99,11 +100,13 @@ function validateData(data) {
         throw new Error('Job data too large (max 10MB)');
     }
     const value = data;
-    if (typeof value.name !== 'string' || value.name.length === 0 || value.name.length > 256) {
-        throw new Error('flow job data.name must be a non-empty string of at most 256 characters');
-    }
     return { encodedLength: encoded.length, value };
 }
+function validateName(name) {
+    if (name.length === 0 || name.length > 256) {
+        throw new Error('flow job name must be a non-empty string of at most 256 characters');
+    }
+}
 function validateIdList(value, name) {
     if (value !== undefined &&
         (!Array.isArray(value) ||
@@ -154,7 +157,9 @@ export function validateAtomicFlowBatch(batch) {
         }
         validateIdList(job.input.dependsOn, 'dependsOn');
         validateIdList(job.input.childrenIds, 'childrenIds');
-        const validatedData = validateData(job.input.data);
+        const payload = normalizeJobPayload(job.input);
+        validateName(payload.name);
+        const validatedData = validateData(payload.data);
         totalDataBytes += validatedData.encodedLength;
         if (totalDataBytes > MAX_FLOW_DATA_BYTES) {
             throw new Error('flow data is too large (max 64MB per atomic batch)');

package/dist/application/operations/jobManagement.js

@@ -7,6 +7,38 @@ import { webhookLog } from '../../shared/logger';
 import { withWriteLock } from '../../shared/lock';
 import { releaseDependencyCompletionPins, } from '../dependencyCompletions';
 export { discardJob, moveJobToDelayed } from './jobMoveOperations';
+const FLOW_METADATA_KEYS = [
+    '__parentId',
+    '__parentQueue',
+    '__childrenIds',
+    '__flowParentId',
+    '__flowParentIds',
+];
+function dataRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Merge caller data without allowing it to erase or forge broker-owned flow metadata. */
+function updatedJobData(job, userData) {
+    const current = dataRecord(job.data);
+    const metadata = current
+        ? Object.fromEntries(FLOW_METADATA_KEYS.filter((key) => Object.hasOwn(current, key)).map((key) => [
+            key,
+            current[key],
+        ]))
+        : {};
+    if (Object.keys(metadata).length === 0)
+        return userData;
+    const next = dataRecord(userData);
+    if (!next)
+        throw new Error('flow job data must be an object');
+    for (const key of Object.keys(next)) {
+        if (key.startsWith('__'))
+            throw new Error(`flow job data key is reserved: ${key}`);
+    }
+    return { ...next, ...metadata };
+}
 /** Cancel a job (remove from queue) */
 export async function cancelJob(jobId, ctx) {
     const location = ctx.jobIndex.get(jobId);
@@ -19,8 +51,9 @@ export async function cancelJob(jobId, ctx) {
             if (job) {
                 // Update running counters for O(1) stats
                 shard.decrementQueued(jobId);
-                if (job.uniqueKey)
-                    shard.releaseUniqueKey(location.queueName, job.uniqueKey);
+                if (job.uniqueKey) {
+                    shard.releaseUniqueKeyIfOwned(location.queueName, job.uniqueKey, job.id);
+                }
                 ctx.jobIndex.delete(jobId);
                 ctx.storage?.deleteJob(jobId);
                 ctx.dependencyResults.releaseConsumer(jobId);
@@ -46,8 +79,9 @@ export async function cancelJob(jobId, ctx) {
             if (waiting) {
                 shard.waitingDeps.delete(jobId);
                 shard.unregisterDependencies(jobId, waiting.dependsOn);
-                if (waiting.uniqueKey)
-                    shard.releaseUniqueKey(location.queueName, waiting.uniqueKey);
+                if (waiting.uniqueKey) {
+                    shard.releaseUniqueKeyIfOwned(location.queueName, waiting.uniqueKey, waiting.id);
+                }
                 ctx.jobIndex.delete(jobId);
                 ctx.storage?.deleteJob(jobId);
                 ctx.dependencyResults.releaseConsumer(jobId);
@@ -118,10 +152,13 @@ export async function updateJobData(jobId, data, ctx) {
     if (location?.type === 'queue') {
         return withWriteLock(ctx.shardLocks[location.shardIdx], () => {
             const shard = ctx.shards[location.shardIdx];
-            const job = shard.getQueue(location.queueName).find(jobId) ?? shard.waitingDeps.get(jobId);
+            const job = shard.getQueue(location.queueName).find(jobId) ??
+                shard.waitingDeps.get(jobId) ??
+                shard.waitingChildren.get(jobId);
             if (job) {
-                job.data = data;
-                ctx.storage?.updateJobData(jobId, data);
+                const updated = updatedJobData(job, data);
+                ctx.storage?.updateJobData(jobId, updated);
+                job.data = updated;
                 return true;
             }
             return false;
@@ -132,8 +169,9 @@ export async function updateJobData(jobId, data, ctx) {
         return withWriteLock(ctx.processingLocks[procIdx], () => {
             const job = ctx.processingShards[procIdx].get(jobId);
             if (job) {
-                job.data = data;
-                ctx.storage?.updateJobData(jobId, data);
+                const updated = updatedJobData(job, data);
+                ctx.storage?.updateJobData(jobId, updated);
+                job.data = updated;
                 return true;
             }
             return false;
@@ -161,8 +199,9 @@ async function updateRepeatSuccessor(originalId, data, ctx) {
             .getQueue(successorLoc.queueName)
             .find(successorId);
         if (job) {
-            job.data = data;
-            ctx.storage?.updateJobData(successorId, data);
+            const updated = updatedJobData(job, data);
+            ctx.storage?.updateJobData(successorId, updated);
+            job.data = updated;
             return true;
         }
         return false;

package/dist/application/operations/jobMoveOperations.js

@@ -27,7 +27,7 @@ export async function moveJobToDelayed(jobId, delay, ctx) {
     const queueName = job.queue;
     await withWriteLock(ctx.shardLocks[idx], () => {
         const shard = ctx.shards[idx];
-        shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
+        shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId, job.id);
         shard.getQueue(job.queue).push(job);
         const isDelayed = job.runAt > now;
         shard.incrementQueued(jobId, isDelayed, job.createdAt, job.queue, job.runAt);
@@ -78,11 +78,11 @@ export async function discardJob(jobId, ctx) {
     const entry = await withWriteLock(ctx.shardLocks[idx], () => {
         const shard = ctx.shards[idx];
         if (fromProcessing) {
-            shard.releaseJobResources(validJob.queue, validJob.uniqueKey, validJob.groupId);
+            shard.releaseJobResources(validJob.queue, validJob.uniqueKey, validJob.groupId, validJob.id);
             shard.notify(validJob.queue);
         }
         else if (validJob.uniqueKey) {
-            shard.releaseUniqueKey(validJob.queue, validJob.uniqueKey);
+            shard.releaseUniqueKeyIfOwned(validJob.queue, validJob.uniqueKey, validJob.id);
         }
         const dlqEntry = shard.addToDlq(validJob);
         ctx.jobIndex.set(jobId, { type: 'dlq', queueName: validJob.queue });

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

@@ -5,7 +5,7 @@
  * - changeWaitingDelay: Waiting -> Delayed
  * - moveToWaitingChildren: Active -> WaitingChildren
  */
-import type { JobId } from '../../domain/types/job';
+import { type JobId } from '../../domain/types/job';
 import type { JobManagementContext } from './jobManagement';
 /** Move active job back to waiting */
 export declare function moveActiveToWait(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;

package/dist/application/operations/jobStateTransitions.js

@@ -5,6 +5,7 @@
  * - changeWaitingDelay: Waiting -> Delayed
  * - moveToWaitingChildren: Active -> WaitingChildren
  */
+import { MAX_TIMELINE_ENTRIES } from '../../domain/types/job';
 import { shardIndex, processingShardIndex } from '../../shared/hash';
 import { withWriteLock } from '../../shared/lock';
 import { releaseClaimedJobOwnership } from './jobClaim';
@@ -31,7 +32,7 @@ export async function moveActiveToWait(jobId, ctx) {
     await withWriteLock(ctx.shardLocks[idx], () => {
         const shard = ctx.shards[idx];
         // Release concurrency/uniqueKey/group slots before re-queueing
-        shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
+        shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId, job.id);
         shard.getQueue(job.queue).push(job);
         shard.incrementQueued(jobId, false, job.createdAt, job.queue, job.runAt);
         ctx.jobIndex.set(jobId, { type: 'queue', shardIdx: idx, queueName: job.queue });
@@ -82,13 +83,26 @@ export async function moveToWaitingChildren(jobId, ctx) {
     });
     if (!job)
         return false;
+    const now = Date.now();
+    job.startedAt = null;
+    if (job.timeline.length < MAX_TIMELINE_ENTRIES) {
+        job.timeline.push({ state: 'waiting-children', timestamp: now });
+    }
     const idx = shardIndex(job.queue);
     await withWriteLock(ctx.shardLocks[idx], () => {
         const shard = ctx.shards[idx];
         // Release concurrency/uniqueKey/group slots before moving to waitingChildren
-        shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
+        shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId, job.id);
         shard.waitingChildren.set(jobId, job);
         ctx.jobIndex.set(jobId, { type: 'queue', shardIdx: idx, queueName: job.queue });
     });
+    ctx.storage?.markWaitingChildren(jobId, job.timeline);
+    ctx.eventsManager.broadcast({
+        eventType: "waiting-children" /* EventType.WaitingChildren */,
+        jobId,
+        queue: job.queue,
+        timestamp: now,
+        prev: 'active',
+    });
     return true;
 }

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

@@ -0,0 +1,36 @@
+import { type Job, type JobId, type JobInput } from '../../domain/types/job';
+import type { Shard } from '../../domain/queue/shard';
+import { type DedupResult } from './pushDeduplication';
+import { type AcceptedCustomId } from './pushAdmission';
+import type { PushContext } from './pushContext';
+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/application/operations/parentLink.js

@@ -0,0 +1,153 @@
+import { MAX_TIMELINE_ENTRIES } from '../../domain/types/job';
+import { shardIndex } from '../../shared/hash';
+import { replaceActiveDedupJob, replacePendingDedupJob, } from './pushDeduplication';
+import { admissionMetadata, publishPreparedJob } from './pushAdmission';
+import { prepareJobInsertion } from './pushInsert';
+import { parentLinkQueue } from './parentLinkInput';
+function recordData(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function locateParent(parentId, ctx) {
+    const location = ctx.jobIndex.get(parentId);
+    if (!location)
+        throw new Error(`Parent job not found: ${String(parentId)}`);
+    if (location.type !== 'queue') {
+        throw new Error(`Parent job ${String(parentId)} is not linkable`);
+    }
+    const shard = ctx.shards[location.shardIdx];
+    const queued = shard.getQueue(location.queueName).find(parentId);
+    if (queued)
+        return { job: queued, membership: 'queue' };
+    const waiting = shard.waitingDeps.get(parentId);
+    if (waiting)
+        return { job: waiting, membership: 'waiting-deps' };
+    const waitingChildren = shard.waitingChildren.get(parentId);
+    if (waitingChildren)
+        return { job: waitingChildren, membership: 'waiting-children' };
+    throw new Error(`Parent job ${String(parentId)} changed state while linking`);
+}
+/** Validate every parent before a batch mutates its accepted prefix. */
+export function validateParentLinkInputs(inputs, ctx) {
+    for (const input of inputs) {
+        const expectedQueue = parentLinkQueue(input);
+        if (!input.parentId || !expectedQueue)
+            continue;
+        if (input.customId && String(input.parentId) === input.customId) {
+            throw new Error('A job cannot be its own parent');
+        }
+        const { job: parent } = locateParent(input.parentId, ctx);
+        if (parent.queue !== expectedQueue) {
+            throw new Error(`Parent job ${String(input.parentId)} belongs to queue ${parent.queue}, not ${expectedQueue}`);
+        }
+    }
+}
+export function prepareParentLink(child, ctx, childFinished = false, parentIdOverride, now = Date.now()) {
+    const parentId = parentIdOverride ?? child.parentId;
+    if (!parentId)
+        throw new Error(`Job ${String(child.id)} has no parent`);
+    if (child.id === parentId)
+        throw new Error('A job cannot be its own parent');
+    const { job: parent, membership } = locateParent(parentId, ctx);
+    const childrenIds = parent.childrenIds.includes(child.id)
+        ? [...parent.childrenIds]
+        : [...parent.childrenIds, child.id];
+    const dependsOn = parent.dependsOn.includes(child.id)
+        ? [...parent.dependsOn]
+        : [...parent.dependsOn, child.id];
+    const childData = {
+        ...recordData(child.data),
+        __parentId: String(parent.id),
+        __parentQueue: parent.queue,
+    };
+    const parentData = { ...recordData(parent.data), __childrenIds: childrenIds.map(String) };
+    const timeline = [...parent.timeline];
+    if (!childFinished &&
+        timeline.at(-1)?.state !== 'waiting-children' &&
+        timeline.length < MAX_TIMELINE_ENTRIES) {
+        timeline.push({ state: 'waiting-children', timestamp: now });
+    }
+    return {
+        child,
+        parent,
+        linkedChild: { ...child, parentId: parent.id, data: childData },
+        linkedParent: { ...parent, childrenIds, dependsOn, data: parentData, timeline },
+        parentMembership: membership,
+        childFinished,
+    };
+}
+/** Publish a persisted link while the parent and child queue shards are locked. */
+export function commitParentLink(plan, ctx) {
+    const { child, parent, linkedChild, linkedParent } = plan;
+    child.parentId = linkedChild.parentId;
+    child.data = linkedChild.data;
+    parent.childrenIds = linkedParent.childrenIds;
+    parent.dependsOn = linkedParent.dependsOn;
+    parent.data = linkedParent.data;
+    parent.timeline = linkedParent.timeline;
+    if (!plan.childFinished) {
+        const parentShard = ctx.shards[shardIndex(parent.queue)];
+        if (plan.parentMembership === 'queue') {
+            if (parentShard.getQueue(parent.queue).remove(parent.id)) {
+                parentShard.decrementQueued(parent.id);
+                parentShard.removeFromTemporalIndex(parent.id);
+            }
+            parentShard.waitingDeps.set(parent.id, parent);
+        }
+        else if (plan.parentMembership === 'waiting-children') {
+            parentShard.waitingChildren.delete(parent.id);
+            parentShard.waitingDeps.set(parent.id, parent);
+        }
+        parentShard.registerDependencies(parent.id, linkedParent.dependsOn);
+    }
+    ctx.dependencyResults.registerConsumer(parent.id, linkedParent.dependsOn);
+    for (const dependencyId of linkedParent.dependsOn) {
+        if (ctx.jobResults.has(dependencyId)) {
+            ctx.dependencyResults.retain(dependencyId, ctx.jobResults.get(dependencyId));
+        }
+    }
+}
+export function parentLinkState(plan) {
+    if (!plan.childFinished)
+        return 'waiting-children';
+    if (plan.parent.runAt > Date.now())
+        return 'delayed';
+    return plan.parent.priority > 0 ? 'prioritized' : 'waiting';
+}
+function persistLink(plan, ctx, mode, admission) {
+    ctx.storage?.commitFlowLink(plan.linkedChild, plan.linkedParent, parentLinkState(plan), mode, admission);
+}
+/** Persist and publish a new child and its existing parent as one locked operation. */
+export function acceptParentedJob(options) {
+    const { job, input, target, dedup, customId, ctx } = options;
+    const plan = prepareParentLink(job, ctx);
+    let released = [];
+    if (dedup.replacement) {
+        const replacement = dedup.replacement;
+        released = replacePendingDedupJob(replacement, job, input, target, {
+            ctx,
+            customId,
+            persist: (admission) => {
+                persistLink(plan, ctx, { type: 'replace', previousJobId: replacement.job.id }, admission);
+            },
+        });
+    }
+    else if (dedup.activeOwnerId) {
+        const activeOwnerId = dedup.activeOwnerId;
+        replaceActiveDedupJob(activeOwnerId, job, input, target, {
+            ctx,
+            customId,
+            persist: (admission) => {
+                persistLink(plan, ctx, { type: 'transfer-active', previousJobId: activeOwnerId }, admission);
+            },
+        });
+    }
+    else {
+        const prepared = prepareJobInsertion(job, ctx);
+        persistLink(plan, ctx, { type: 'insert' }, admissionMetadata(customId, prepared));
+        publishPreparedJob({ job, input, target, customId, prepared, ctx });
+    }
+    commitParentLink(plan, ctx);
+    return released;
+}