@vibesdotdev/workers 0.0.0-stage → 1.0.0-rc.3

package/dist/core/flatten-workers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Worker Hierarchy Flattening Utilities
+ *
+ * Converts nested worker hierarchies into flat lists for runtime registration
+ */
+import type { Worker } from './worker.ts';
+/**
+ * Recursively flatten a worker hierarchy into a list of leaf workers
+ *
+ * Module/namespace workers (those with `workers` property) are containers only.
+ * Only leaf workers (those with actual jobs) are returned.
+ *
+ * @example
+ * const aiWorker = new AIWorker(); // has workers: [textGen, imageGen]
+ * const flattened = flattenWorkers(aiWorker);
+ * // Returns: [TextGenerationWorker, ImageGenerationWorker]
+ */
+export declare function flattenWorkers(worker: Worker): Worker[];
+/**
+ * Flatten multiple workers into a single list
+ *
+ * @example
+ * const workers = flattenWorkerList([aiWorker, chatWorker, knowledgeWorker]);
+ */
+export declare function flattenWorkerList(workers: Worker[]): Worker[];
+/**
+ * Get all job IDs from a worker hierarchy
+ *
+ * Useful for validation and discovery
+ */
+export declare function getJobIds(worker: Worker): string[];
+/**
+ * Find a worker by ID in a hierarchy
+ */
+export declare function findWorker(root: Worker, workerId: string): Worker | undefined;
+/**
+ * Validate worker hierarchy
+ *
+ * Ensures:
+ * - No duplicate worker IDs
+ * - No duplicate job IDs
+ * - Job IDs follow naming convention (start with worker ID)
+ */
+/** Outcome of {@link validateWorkerHierarchy}: whether the tree is valid and every problem found. */
+export interface WorkerHierarchyValidation {
+    valid: boolean;
+    errors: string[];
+}
+export declare function validateWorkerHierarchy(worker: Worker): WorkerHierarchyValidation;
+//# sourceMappingURL=flatten-workers.d.ts.map

package/dist/core/flatten-workers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten-workers.d.ts","sourceRoot":"","sources":["../../src/core/flatten-workers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAcvD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQ7D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CASlD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa7E;AAED;;;;;;;GAOG;AACH,qGAAqG;AACrG,MAAM,WAAW,yBAAyB;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,yBAAyB,CA0CjF"}

package/dist/core/flatten-workers.js

@@ -0,0 +1,108 @@
+/**
+ * Worker Hierarchy Flattening Utilities
+ *
+ * Converts nested worker hierarchies into flat lists for runtime registration
+ */
+/**
+ * Recursively flatten a worker hierarchy into a list of leaf workers
+ *
+ * Module/namespace workers (those with `workers` property) are containers only.
+ * Only leaf workers (those with actual jobs) are returned.
+ *
+ * @example
+ * const aiWorker = new AIWorker(); // has workers: [textGen, imageGen]
+ * const flattened = flattenWorkers(aiWorker);
+ * // Returns: [TextGenerationWorker, ImageGenerationWorker]
+ */
+export function flattenWorkers(worker) {
+    const result = [];
+    // If this worker has nested workers, recursively flatten them
+    if (worker.workers && worker.workers.length > 0) {
+        for (const child of worker.workers) {
+            result.push(...flattenWorkers(child));
+        }
+    }
+    else {
+        // Leaf worker with actual jobs - add it to the result
+        result.push(worker);
+    }
+    return result;
+}
+/**
+ * Flatten multiple workers into a single list
+ *
+ * @example
+ * const workers = flattenWorkerList([aiWorker, chatWorker, knowledgeWorker]);
+ */
+export function flattenWorkerList(workers) {
+    const result = [];
+    for (const worker of workers) {
+        result.push(...flattenWorkers(worker));
+    }
+    return result;
+}
+/**
+ * Get all job IDs from a worker hierarchy
+ *
+ * Useful for validation and discovery
+ */
+export function getJobIds(worker) {
+    const workers = flattenWorkers(worker);
+    const jobIds = [];
+    for (const w of workers) {
+        jobIds.push(...w.getHandlerIds());
+    }
+    return jobIds;
+}
+/**
+ * Find a worker by ID in a hierarchy
+ */
+export function findWorker(root, workerId) {
+    if (root.id === workerId) {
+        return root;
+    }
+    if (root.workers) {
+        for (const child of root.workers) {
+            const found = findWorker(child, workerId);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+export function validateWorkerHierarchy(worker) {
+    const errors = [];
+    const workerIds = new Set();
+    const jobIds = new Set();
+    function validate(w, _parentId) {
+        // Check for duplicate worker ID
+        if (workerIds.has(w.id)) {
+            errors.push(`Duplicate worker ID: ${w.id}`);
+        }
+        workerIds.add(w.id);
+        // Check job IDs
+        for (const jobId of w.getHandlerIds()) {
+            // Check for duplicate job ID
+            if (jobIds.has(jobId)) {
+                errors.push(`Duplicate job ID: ${jobId}`);
+            }
+            jobIds.add(jobId);
+            // Check naming convention (job ID should start with worker ID)
+            if (!jobId.startsWith(w.id)) {
+                errors.push(`Job ID "${jobId}" does not start with worker ID "${w.id}" (should be "${w.id}.*")`);
+            }
+        }
+        // Validate children
+        if (w.workers) {
+            for (const child of w.workers) {
+                validate(child, w.id);
+            }
+        }
+    }
+    validate(worker);
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+//# sourceMappingURL=flatten-workers.js.map

package/dist/core/flatten-workers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten-workers.js","sourceRoot":"","sources":["../../src/core/flatten-workers.ts"],"names":[],"mappings":"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"}

package/dist/core/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Core Worker Exports
+ */
+export { Worker } from './worker.ts';
+export type { WorkerConfig } from './worker.ts';
+export { JobHandler } from './job-handler.ts';
+export type { JobHandlerClass, JobHandlerConfig, JobContext, JobType, JobEventEmitter, SubtaskSpawner, SubtaskSpawnOptions, SubtaskEvent, SubtaskEventStream } from './job-handler.ts';
+export { BaseQueueAdapter } from './queue-adapter.ts';
+export type { QueueAdapter, Job, JobStatus, JobState, JobUpdate, QueueMetrics, EnqueueOptions, RepeatOptions, ScheduleInfo, CleanupOptions, CleanupResult, JobEvent } from './queue-adapter.ts';
+export { BaseScheduleManager } from './schedule-manager.ts';
+export type { ScheduleConfig } from './schedule-manager.ts';
+export { createJobEventEmitter, WorkerEventRouter } from './events.ts';
+export { flattenWorkers, flattenWorkerList, getJobIds, findWorker, validateWorkerHierarchy } from './flatten-workers.ts';
+export { SUPERVISED_METADATA_KEY, SupervisedWorkloadSchema, SupervisedWorkloadsSchema, type SupervisedWorkload } from './supervised-workloads.ts';
+export { ADMITTED_BY_METADATA_KEY, ResumeAdmissionSchema, keyedAdmissionFor, keyedEnqueueOptions, keyedJobId, runAsExecutingJob, withExecutingJobPark, type KeyedAdmission, type ResumeAdmission } from './keyed-dispatch.ts';
+export { JobQueueOwnerSchema, ExecutingJobReceiptSchema, executingJobReceipt } from './keyed-dispatch.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EACX,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EACX,YAAY,EACZ,GAAG,EACH,SAAS,EACT,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGvE,OAAO,EACN,cAAc,EACd,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,uBAAuB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAClJ,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,UAAU,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC9N,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,18 @@
+/**
+ * Core Worker Exports
+ */
+// Worker/JobHandler pattern
+export { Worker } from "./worker.js";
+export { JobHandler } from "./job-handler.js";
+// Queue adapter interface
+export { BaseQueueAdapter } from "./queue-adapter.js";
+// Schedule management
+export { BaseScheduleManager } from "./schedule-manager.js";
+// Event support
+export { createJobEventEmitter, WorkerEventRouter } from "./events.js";
+// Worker hierarchy utilities
+export { flattenWorkers, flattenWorkerList, getJobIds, findWorker, validateWorkerHierarchy } from "./flatten-workers.js";
+export { SUPERVISED_METADATA_KEY, SupervisedWorkloadSchema, SupervisedWorkloadsSchema } from "./supervised-workloads.js";
+export { ADMITTED_BY_METADATA_KEY, ResumeAdmissionSchema, keyedAdmissionFor, keyedEnqueueOptions, keyedJobId, runAsExecutingJob, withExecutingJobPark } from "./keyed-dispatch.js";
+export { JobQueueOwnerSchema, ExecutingJobReceiptSchema, executingJobReceipt } from "./keyed-dispatch.js";
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,4BAA4B;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAa9C,0BAA0B;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAgBtD,sBAAsB;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG5D,gBAAgB;AAChB,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEvE,6BAA6B;AAC7B,OAAO,EACN,cAAc,EACd,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,uBAAuB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,yBAAyB,EAA2B,MAAM,2BAA2B,CAAC;AAClJ,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,UAAU,EAAE,iBAAiB,EAAE,oBAAoB,EAA6C,MAAM,qBAAqB,CAAC;AAC9N,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/core/interface.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Worker Manager Interface
+ * Provides job queue and worker lifecycle management
+ */
+export type { WorkersCoreConfig } from './schemas/index.ts';
+//# sourceMappingURL=interface.d.ts.map

package/dist/core/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/core/interface.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/core/interface.js

@@ -0,0 +1,6 @@
+/**
+ * Worker Manager Interface
+ * Provides job queue and worker lifecycle management
+ */
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/core/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/core/interface.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/core/job-event-publisher.d.ts

@@ -0,0 +1,13 @@
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import type { WorkerJobEventPayload } from './worker-job-event.ts';
+import type { RuntimeJobEventBridge } from '../kinds/schemas/job-event-bus.ts';
+/** Publish through the runtime-selected event bus without naming a provider. */
+export declare function publishWorkerJobEvent(event: WorkerJobEventPayload, runtime: RuntimeRef): Promise<void>;
+/**
+ * Job events through the runtime's `workers/job-event-bus`, whichever
+ * provider the host binds. The bus subscription starts with the first handler
+ * and every registered handler receives each event; a handler that throws is
+ * diagnosed without preventing sibling delivery. Detach joins issued handlers and native cleanup.
+ */
+export declare function createRuntimeJobEventBridge(runtime: RuntimeRef, owner: string): RuntimeJobEventBridge;
+//# sourceMappingURL=job-event-publisher.d.ts.map

package/dist/core/job-event-publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-event-publisher.d.ts","sourceRoot":"","sources":["../../src/core/job-event-publisher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAkD,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAW/H,gFAAgF;AAChF,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5G;AAGD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAwFrG"}

package/dist/core/job-event-publisher.js

@@ -0,0 +1,120 @@
+import { settle } from '@vibesdotdev/kernel';
+/** The bus the runtime selects, or `null` when the host composes none (queue-local events). */
+async function resolveJobEventBus(runtime) {
+    if (!runtime.hasKind('workers/job-event-bus'))
+        return null;
+    if (runtime.query('workers/job-event-bus').descriptors().length === 0)
+        return null;
+    return runtime.query('workers/job-event-bus').resolve();
+}
+/** Publish through the runtime-selected event bus without naming a provider. */
+export async function publishWorkerJobEvent(event, runtime) {
+    const bus = await resolveJobEventBus(runtime);
+    if (!bus)
+        return;
+    await bus.publish(event);
+}
+/**
+ * Job events through the runtime's `workers/job-event-bus`, whichever
+ * provider the host binds. The bus subscription starts with the first handler
+ * and every registered handler receives each event; a handler that throws is
+ * diagnosed without preventing sibling delivery. Detach joins issued handlers and native cleanup.
+ */
+export function createRuntimeJobEventBridge(runtime, owner) {
+    const handlers = new Map();
+    const deliveries = new Set();
+    let subscription = null;
+    let closing = null;
+    const dispatch = async (event) => {
+        // Registrations added during delivery do not receive this event.
+        for (const [handler, work] of Array.from(handlers)) {
+            // A detached or replaced registration cannot admit a later callback.
+            if (handlers.get(handler) !== work)
+                continue;
+            const delivery = Promise.resolve().then(async () => {
+                const outcome = await settle(() => handler(event));
+                if (!outcome.ok)
+                    runtime.diagnostics.error('worker-job-event-handler-failed', {
+                        scope: 'workers:events', plugin: owner, error: outcome.cause
+                    });
+            });
+            work.add(delivery);
+            deliveries.add(delivery);
+            try {
+                await delivery;
+            }
+            finally {
+                work.delete(delivery);
+                deliveries.delete(delivery);
+            }
+        }
+    };
+    const subscribe = () => {
+        if (subscription || closing || handlers.size === 0)
+            return;
+        subscription = settle(async () => {
+            const bus = await resolveJobEventBus(runtime);
+            return bus?.subscribe ? await bus.subscribe(dispatch) : null;
+        }).then((outcome) => {
+            if (!outcome.ok) {
+                subscription = null;
+                runtime.diagnostics.error('worker-job-event-subscribe-failed', {
+                    scope: 'workers:events', plugin: owner, error: outcome.cause
+                });
+                return null;
+            }
+            // Absence is not a permanent selection: the kernel may later register a bus.
+            if (!outcome.value)
+                subscription = null;
+            return outcome.value;
+        });
+    };
+    return {
+        prepare: async () => {
+            await resolveJobEventBus(runtime);
+            subscribe();
+            if (subscription)
+                await subscription;
+        },
+        sendJobEvent: async (event) => {
+            const notified = await settle(async () => {
+                const bus = await resolveJobEventBus(runtime);
+                if (bus)
+                    await bus.publish(event);
+            });
+            if (!notified.ok)
+                runtime.diagnostics.error('worker-job-event-publish-failed', {
+                    scope: 'workers:events', plugin: owner, error: notified.cause
+                });
+        },
+        onMessage: (handler) => {
+            const work = handlers.get(handler) ?? new Set();
+            handlers.set(handler, work);
+            subscribe();
+            return async () => {
+                if (handlers.get(handler) === work)
+                    handlers.delete(handler);
+                if (handlers.size > 0) {
+                    await Promise.all(work);
+                    return;
+                }
+                if (!closing) {
+                    const pending = subscription;
+                    closing = (async () => {
+                        const unsubscribe = pending && await pending;
+                        if (unsubscribe)
+                            await unsubscribe();
+                        await Promise.all(deliveries);
+                    })().then(() => {
+                        subscription = null;
+                        closing = null;
+                        // A reattached handler waits for the prior native subscription to retire.
+                        subscribe();
+                    });
+                }
+                await closing;
+            };
+        }
+    };
+}
+//# sourceMappingURL=job-event-publisher.js.map

package/dist/core/job-event-publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-event-publisher.js","sourceRoot":"","sources":["../../src/core/job-event-publisher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAmB,MAAM,qBAAqB,CAAC;AAM9D,+FAA+F;AAC/F,KAAK,UAAU,kBAAkB,CAAC,OAAmB;IACpD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,uBAAuB,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,IAAI,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,WAAW,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnF,OAAO,OAAO,CAAC,KAAK,CAAiD,uBAAuB,CAAC,CAAC,OAAO,EAAE,CAAC;AACzG,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,KAA4B,EAAE,OAAmB;IAC5F,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,MAAM,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAGD;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAmB,EAAE,KAAa;IAC7E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuC,CAAC;IAChE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAiB,CAAC;IAC5C,IAAI,YAAY,GAAwD,IAAI,CAAC;IAC7E,IAAI,OAAO,GAAyB,IAAI,CAAC;IAEzC,MAAM,QAAQ,GAAG,KAAK,EAAE,KAA4B,EAAiB,EAAE;QACtE,iEAAiE;QACjE,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpD,qEAAqE;YACrE,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI;gBAAE,SAAS;YAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;gBAClD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;gBACnD,IAAI,CAAC,OAAO,CAAC,EAAE;oBAAE,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,iCAAiC,EAAE;wBAC7E,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK;qBAC5D,CAAC,CAAC;YACJ,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACnB,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACzB,IAAI,CAAC;gBAAC,MAAM,QAAQ,CAAC;YAAC,CAAC;oBACf,CAAC;gBACR,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACtB,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC;QACF,CAAC;IACF,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,GAAS,EAAE;QAC5B,IAAI,YAAY,IAAI,OAAO,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAC3D,YAAY,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE;YAChC,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC;YAC9C,OAAO,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9D,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;YACnB,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;gBACjB,YAAY,GAAG,IAAI,CAAC;gBACpB,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,mCAAmC,EAAE;oBAC9D,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK;iBAC5D,CAAC,CAAC;gBACH,OAAO,IAAI,CAAC;YACb,CAAC;YACD,6EAA6E;YAC7E,IAAI,CAAC,OAAO,CAAC,KAAK;gBAAE,YAAY,GAAG,IAAI,CAAC;YACxC,OAAO,OAAO,CAAC,KAAK,CAAC;QACtB,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO;QACN,OAAO,EAAE,KAAK,IAAI,EAAE;YACnB,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC;YAClC,SAAS,EAAE,CAAC;YACZ,IAAI,YAAY;gBAAE,MAAM,YAAY,CAAC;QACtC,CAAC;QACD,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAC7B,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,KAAK,IAAI,EAAE;gBACxC,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC;gBAC9C,IAAI,GAAG;oBAAE,MAAM,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,iCAAiC,EAAE;oBAC9E,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK;iBAC7D,CAAC,CAAC;QACJ,CAAC;QACD,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;YACtB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,GAAG,EAAiB,CAAC;YAC/D,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAC5B,SAAS,EAAE,CAAC;YACZ,OAAO,KAAK,IAAI,EAAE;gBACjB,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI;oBAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC7D,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;oBACvB,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBACxB,OAAO;gBACR,CAAC;gBACD,IAAI,CAAC,OAAO,EAAE,CAAC;oBACd,MAAM,OAAO,GAAG,YAAY,CAAC;oBAC7B,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;wBACrB,MAAM,WAAW,GAAG,OAAO,IAAI,MAAM,OAAO,CAAC;wBAC7C,IAAI,WAAW;4BAAE,MAAM,WAAW,EAAE,CAAC;wBACrC,MAAM,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;oBAC/B,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;wBACd,YAAY,GAAG,IAAI,CAAC;wBACpB,OAAO,GAAG,IAAI,CAAC;wBACf,0EAA0E;wBAC1E,SAAS,EAAE,CAAC;oBACb,CAAC,CAAC,CAAC;gBACJ,CAAC;gBACD,MAAM,OAAO,CAAC;YACf,CAAC,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/core/job-handler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Job Handler
+ *
+ * Focused, composable unit for handling a specific job type.
+ * Job handlers are registered with Workers and invoked by the runtime.
+ */
+import type { VibesRuntime } from '@vibesdotdev/kernel';
+import type { SchemaParser, JobType, JobHandlerConfig, WorkerLogger, JobHandlerJobContext } from './schemas/index.ts';
+export type { SchemaParser, JobType, JobContext, JobEventEmitter, SubtaskSpawnOptions, SubtaskEvent, SubtaskEventStream, SubtaskSpawner, IsolationMode, JobHandlerConfig, HandlerResult, WorkerLogger, JobHandlerClass, JobHandlerJobContext } from './schemas/index.ts';
+export declare abstract class JobHandler<TData = unknown, TResult = unknown> {
+    readonly id: string;
+    readonly type: JobType;
+    readonly description?: string;
+    readonly retries?: JobHandlerConfig['retries'];
+    protected schema?: SchemaParser<TData>;
+    protected resultSchema?: SchemaParser<TResult>;
+    protected logger: WorkerLogger;
+    protected readonly runtime: VibesRuntime;
+    constructor(config: JobHandlerConfig<TData, TResult>);
+    abstract handle(context: JobHandlerJobContext<TData>): Promise<TResult>;
+    beforeHandle?(context: JobHandlerJobContext<TData>): Promise<void>;
+    afterHandle?(context: JobHandlerJobContext<TData>, result: TResult): Promise<void>;
+    onError?(context: JobHandlerJobContext<TData>, error: Error): Promise<void>;
+    getConfig(): Readonly<JobHandlerConfig<TData, TResult>>;
+}
+//# sourceMappingURL=job-handler.d.ts.map

package/dist/core/job-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-handler.d.ts","sourceRoot":"","sources":["../../src/core/job-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACX,YAAY,EACZ,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACX,YAAY,EACZ,OAAO,EACP,UAAU,EACV,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,8BAAsB,UAAU,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAE/C,SAAS,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACvC,SAAS,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAC/C,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC;IAC/B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;gBAE7B,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC;IAcpD,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IACjE,YAAY,CAAC,CAAC,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAClE,WAAW,CAAC,CAAC,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAClF,OAAO,CAAC,CAAC,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjF,SAAS,IAAI,QAAQ,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;CAWvD"}

package/dist/core/job-handler.js

@@ -0,0 +1,41 @@
+/**
+ * Job Handler
+ *
+ * Focused, composable unit for handling a specific job type.
+ * Job handlers are registered with Workers and invoked by the runtime.
+ */
+import { getLogger } from '@vibesdotdev/logging';
+export class JobHandler {
+    id;
+    type;
+    description;
+    retries;
+    schema;
+    resultSchema;
+    logger;
+    runtime;
+    constructor(config) {
+        this.runtime = config.runtime;
+        this.id = config.id;
+        this.type = config.type;
+        this.description = config.description;
+        this.retries = config.retries;
+        this.schema = config.schema;
+        this.resultSchema = config.resultSchema;
+        this.logger = getLogger(`job-handler:${config.id}`, config.runtime).withContext({
+            handlerId: config.id
+        });
+    }
+    getConfig() {
+        return {
+            runtime: this.runtime,
+            id: this.id,
+            type: this.type,
+            description: this.description,
+            schema: this.schema,
+            resultSchema: this.resultSchema,
+            retries: this.retries
+        };
+    }
+}
+//# sourceMappingURL=job-handler.js.map

package/dist/core/job-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-handler.js","sourceRoot":"","sources":["../../src/core/job-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AA4BjD,MAAM,OAAgB,UAAU;IACtB,EAAE,CAAS;IACX,IAAI,CAAU;IACd,WAAW,CAAU;IACrB,OAAO,CAA+B;IAErC,MAAM,CAAuB;IAC7B,YAAY,CAAyB;IACrC,MAAM,CAAe;IACZ,OAAO,CAAe;IAEzC,YAAY,MAAwC;QACnD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QAExC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,eAAe,MAAM,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC;YAC/E,SAAS,EAAE,MAAM,CAAC,EAAE;SACpB,CAAC,CAAC;IACJ,CAAC;IAOD,SAAS;QACR,OAAO;YACN,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;SACrB,CAAC;IACH,CAAC;CACD"}

package/dist/core/job-refusal.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A typed refusal keeps its identity across the queue.
+ *
+ * The queue keeps a failed job's message as text. A handler that refuses with
+ * a `CapabilityError` also leaves its value-free facts (code, reason,
+ * retryable, details) under the job's `refusal` metadata, and the consumer flow
+ * rebuilds the same refusal from them. Untyped failures stay plain errors,
+ * retaining the Kernel's bounded failure class and code when recorded.
+ */
+import * as z from 'zod/v4';
+import { type CaughtFailure, type ValueFreeFailure } from '@vibesdotdev/kernel';
+import { type JsonObject } from '@vibesdotdev/kernel/schemas/json';
+import type { JobMetadataRecord } from './schemas/index.ts';
+/** The metadata key a failed job's refusal facts live under. */
+export declare const JOB_REFUSAL_METADATA_KEY: "refusal";
+export declare const JOB_FAILURE_FACTS_METADATA_KEY: "workers.failureFacts";
+export declare const JobRefusalSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        NOT_FOUND: "NOT_FOUND";
+        INVALID_INPUT: "INVALID_INPUT";
+        PERMISSION_DENIED: "PERMISSION_DENIED";
+        AUTH_REQUIRED: "AUTH_REQUIRED";
+        CONFLICT: "CONFLICT";
+        RATE_LIMITED: "RATE_LIMITED";
+        TIMEOUT: "TIMEOUT";
+        UNAVAILABLE: "UNAVAILABLE";
+        CANCELLED: "CANCELLED";
+        INTERNAL: "INTERNAL";
+    }>;
+    reason: z.ZodString;
+    retryable: z.ZodBoolean;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("@vibesdotdev/kernel/bootstrap").JsonValue, import("@vibesdotdev/kernel/bootstrap").JsonValue, z.core.$ZodTypeInternals<import("@vibesdotdev/kernel/bootstrap").JsonValue, import("@vibesdotdev/kernel/bootstrap").JsonValue>>>>;
+}, z.core.$strip>;
+export type JobRefusal = z.infer<typeof JobRefusalSchema>;
+/** The refusal facts of a caught failure, or undefined for an untyped one. Details that are not JSON are dropped. */
+export declare function jobRefusalOf(failure: CaughtFailure): JsonObject | undefined;
+/** Kernel-owned bounded facts only; legacy receipts need not contain them. */
+export declare function jobFailureFacts(metadata: JobMetadataRecord | undefined): ValueFreeFailure | undefined;
+/** The error a waiter throws for a failed job: its refusal rebuilt when one was recorded. */
+export declare function jobFailureError(message: string, metadata: JobMetadataRecord | undefined): Error;
+//# sourceMappingURL=job-refusal.d.ts.map

package/dist/core/job-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-refusal.d.ts","sourceRoot":"","sources":["../../src/core/job-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAA8D,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5I,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,EAAG,SAAkB,CAAC;AAC3D,eAAO,MAAM,8BAA8B,EAAG,sBAA+B,CAAC;AAI9E,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;iBAgB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,qHAAqH;AACrH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,UAAU,GAAG,SAAS,CAM3E;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAGrG;AAED,6FAA6F;AAC7F,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GAAG,KAAK,CAQ/F"}

package/dist/core/job-refusal.js

@@ -0,0 +1,60 @@
+/**
+ * A typed refusal keeps its identity across the queue.
+ *
+ * The queue keeps a failed job's message as text. A handler that refuses with
+ * a `CapabilityError` also leaves its value-free facts (code, reason,
+ * retryable, details) under the job's `refusal` metadata, and the consumer flow
+ * rebuilds the same refusal from them. Untyped failures stay plain errors,
+ * retaining the Kernel's bounded failure class and code when recorded.
+ */
+import * as z from 'zod/v4';
+import { CapabilityError, isCapabilityError, ValueFreeFailureSchema } from '@vibesdotdev/kernel';
+import { JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+/** The metadata key a failed job's refusal facts live under. */
+export const JOB_REFUSAL_METADATA_KEY = 'refusal';
+export const JOB_FAILURE_FACTS_METADATA_KEY = 'workers.failureFacts';
+const RefusalDetailsSchema = z.record(z.string(), JsonValueSchema);
+export const JobRefusalSchema = z.object({
+    code: z.enum([
+        'NOT_FOUND',
+        'INVALID_INPUT',
+        'PERMISSION_DENIED',
+        'AUTH_REQUIRED',
+        'CONFLICT',
+        'RATE_LIMITED',
+        'TIMEOUT',
+        'UNAVAILABLE',
+        'CANCELLED',
+        'INTERNAL'
+    ]),
+    reason: z.string().min(1),
+    retryable: z.boolean(),
+    details: RefusalDetailsSchema.optional()
+});
+/** The refusal facts of a caught failure, or undefined for an untyped one. Details that are not JSON are dropped. */
+export function jobRefusalOf(failure) {
+    if (!isCapabilityError(failure))
+        return undefined;
+    const refusal = { code: failure.code, reason: failure.reason, retryable: failure.retryable };
+    const details = RefusalDetailsSchema.safeParse(failure.details);
+    if (details.success)
+        refusal.details = details.data;
+    return refusal;
+}
+/** Kernel-owned bounded facts only; legacy receipts need not contain them. */
+export function jobFailureFacts(metadata) {
+    const facts = ValueFreeFailureSchema.safeParse(metadata?.[JOB_FAILURE_FACTS_METADATA_KEY]);
+    return facts.success ? facts.data : undefined;
+}
+/** The error a waiter throws for a failed job: its refusal rebuilt when one was recorded. */
+export function jobFailureError(message, metadata) {
+    const refusal = JobRefusalSchema.safeParse(metadata?.[JOB_REFUSAL_METADATA_KEY]);
+    if (!refusal.success) {
+        return Object.assign(new Error(message), jobFailureFacts(metadata));
+    }
+    const { code, reason, retryable, details } = refusal.data;
+    if (details === undefined)
+        return new CapabilityError(message, code, { reason, retryable });
+    return new CapabilityError(message, code, { reason, retryable, details });
+}
+//# sourceMappingURL=job-refusal.js.map

package/dist/core/job-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-refusal.js","sourceRoot":"","sources":["../../src/core/job-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,sBAAsB,EAA6C,MAAM,qBAAqB,CAAC;AAC5I,OAAO,EAAE,eAAe,EAAmB,MAAM,kCAAkC,CAAC;AAGpF,gEAAgE;AAChE,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAkB,CAAC;AAC3D,MAAM,CAAC,MAAM,8BAA8B,GAAG,sBAA+B,CAAC;AAE9E,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC;AAEnE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;QACZ,WAAW;QACX,eAAe;QACf,mBAAmB;QACnB,eAAe;QACf,UAAU;QACV,cAAc;QACd,SAAS;QACT,aAAa;QACb,WAAW;QACX,UAAU;KACV,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;IACtB,OAAO,EAAE,oBAAoB,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAIH,qHAAqH;AACrH,MAAM,UAAU,YAAY,CAAC,OAAsB;IAClD,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAClD,MAAM,OAAO,GAAe,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;IACzG,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,IAAI,OAAO,CAAC,OAAO;QAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IACpD,OAAO,OAAO,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAAC,QAAuC;IACtE,MAAM,KAAK,GAAG,sBAAsB,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,8BAA8B,CAAC,CAAC,CAAC;IAC3F,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,QAAuC;IACvF,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,wBAAwB,CAAC,CAAC,CAAC;IACjF,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1D,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,eAAe,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5F,OAAO,IAAI,eAAe,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;AAC3E,CAAC"}

package/dist/core/keyed-claim.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The keyed-claim rules every queue owner applies in one step (see
+ * `QueueAdapter.claimKeyed`). Pure: the owner reads the job under the key,
+ * asks this what to do, and writes inside the same atomic section.
+ */
+import type { JobExtended, KeyedClaimDecisionExtended } from './schemas/index.ts';
+/** A job's admission generation; a job written before generations reads as 0. */
+export declare function jobGeneration(job: Pick<JobExtended, 'generation'> | null | undefined): number;
+/** The generation a new write under the key carries: one past the job it replaces. */
+export declare function nextGeneration(current: Pick<JobExtended, 'generation'> | null | undefined): number;
+/** What one claim does to the job currently under its key, and whether it writes. */
+export declare function decideKeyedClaim(current: Pick<JobExtended, 'status' | 'generation' | 'executionClaim'> | null | undefined, restartGeneration: number | undefined): KeyedClaimDecisionExtended;
+//# sourceMappingURL=keyed-claim.d.ts.map

package/dist/core/keyed-claim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-claim.d.ts","sourceRoot":"","sources":["../../src/core/keyed-claim.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAElF,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAE7F;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAElG;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,YAAY,GAAG,gBAAgB,CAAC,GAAG,IAAI,GAAG,SAAS,EACzF,iBAAiB,EAAE,MAAM,GAAG,SAAS,GACnC,0BAA0B,CAmB5B"}

package/dist/core/keyed-claim.js

@@ -0,0 +1,36 @@
+/**
+ * The keyed-claim rules every queue owner applies in one step (see
+ * `QueueAdapter.claimKeyed`). Pure: the owner reads the job under the key,
+ * asks this what to do, and writes inside the same atomic section.
+ */
+/** A job's admission generation; a job written before generations reads as 0. */
+export function jobGeneration(job) {
+    return job?.generation ?? 0;
+}
+/** The generation a new write under the key carries: one past the job it replaces. */
+export function nextGeneration(current) {
+    return current ? jobGeneration(current) + 1 : 1;
+}
+/** What one claim does to the job currently under its key, and whether it writes. */
+export function decideKeyedClaim(current, restartGeneration) {
+    if (!current)
+        return { outcome: 'started', write: true };
+    switch (current.status) {
+        case 'completed':
+            return current.executionClaim.state === 'none'
+                ? { outcome: 'started', write: true }
+                : { outcome: 'active', write: false };
+        case 'failed':
+            return current.executionClaim.state === 'none' &&
+                restartGeneration !== undefined && restartGeneration === jobGeneration(current)
+                ? { outcome: 'restarted', write: true }
+                : { outcome: 'failed', write: false };
+        case 'cancelled':
+            return { outcome: 'cancelled', write: false };
+        case 'delayed':
+        case 'pending':
+        case 'processing':
+            return { outcome: 'active', write: false };
+    }
+}
+//# sourceMappingURL=keyed-claim.js.map

package/dist/core/keyed-claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-claim.js","sourceRoot":"","sources":["../../src/core/keyed-claim.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,GAAuD;IACpF,OAAO,GAAG,EAAE,UAAU,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,cAAc,CAAC,OAA2D;IACzF,OAAO,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAC/B,OAAyF,EACzF,iBAAqC;IAErC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzD,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;QACxB,KAAK,WAAW;YACf,OAAO,OAAO,CAAC,cAAc,CAAC,KAAK,KAAK,MAAM;gBAC7C,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE;gBACrC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACxC,KAAK,QAAQ;YACZ,OAAO,OAAO,CAAC,cAAc,CAAC,KAAK,KAAK,MAAM;gBAC7C,iBAAiB,KAAK,SAAS,IAAI,iBAAiB,KAAK,aAAa,CAAC,OAAO,CAAC;gBAC/E,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE;gBACvC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACxC,KAAK,WAAW;YACf,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC/C,KAAK,SAAS,CAAC;QACf,KAAK,SAAS,CAAC;QACf,KAAK,YAAY;YAChB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC7C,CAAC;AACF,CAAC"}