@semiont/jobs 0.5.36 → 0.5.37

package/dist/index.d.ts

@@ -290,7 +290,22 @@ interface JobQueue {
     destroy(): void;
     createJob(job: AnyJob): Promise<void>;
     getJob(jobId: JobId): Promise<AnyJob | null>;
-    updateJob(job: AnyJob, oldStatus?: JobStatus): Promise<void>;
+    /**
+     * Atomically claim the NEXT pending job matching one of `types` — the ONE
+     * transition that makes this a queue rather than a state store
+     * (JOB-QUEUE-DRIVER P0; reshaped claim-by-TYPE in P2, while every worker
+     * is still ours). pending → running, `startedAt` stamped, progress empty.
+     * An announcement is a WAKE-UP, not a reservation: the claimed job may
+     * differ from any announced one, no ordering among matching pending jobs
+     * is promised, and an empty `types` accepts any type. Simultaneous claims
+     * admit one winner PER pending job; a claim that finds nothing is
+     * DECLINED (`none-available`), never an error.
+     */
+    claimNextJob(types: string[]): Promise<{
+        job: AnyJob;
+    } | {
+        declined: 'none-available';
+    }>;
     /** Move a running job to `complete`. Returns false if the job isn't running. */
     completeJob(jobId: JobId, result: Record<string, unknown>): Promise<boolean>;
     /**
@@ -398,10 +413,30 @@ declare class FsJobQueue implements JobQueue {
      * Get a job by ID (searches all status directories)
      */
     getJob(jobId: JobId): Promise<AnyJob | null>;
+    /**
+     * Serializes claims. This driver's atomicity is single-process by design,
+     * but `claimJob`'s contract must hold even against interleaved awaits in
+     * that one process — a read-check-write with await points in it can admit
+     * two winners without this chain (the TOCTOU the operation exists to kill).
+     */
+    private claimChain;
+    claimNextJob(types: string[]): Promise<{
+        job: AnyJob;
+    } | {
+        declined: 'none-available';
+    }>;
+    private doClaimNext;
     /**
      * Update a job (atomic: delete old, write new)
      */
-    updateJob(job: AnyJob, oldStatus?: JobStatus): Promise<void>;
+    /**
+     * Cross-status move (or in-place rewrite): delete old slot, write new.
+     * Private — the interface exposes named transitions only (JOB-QUEUE-DRIVER
+     * P0); a generic public patch is trivial on files and impossible on an
+     * in-flight message, so no driver may offer one. Re-entering `pending`
+     * announces, which is how failJob's retry reaches a listening worker.
+     */
+    private transition;
     /**
      * Move a running job to `complete`. Returns false (and changes
      * nothing) if the job is missing or not running — which also makes
@@ -478,6 +513,136 @@ declare class FsJobQueue implements JobQueue {
     }>;
 }
 
+/**
+ * JetStreamJobQueue — the JetStream driver behind the `JobQueue` interface
+ * (JOB-QUEUE-DRIVER P1, topology ruling M: gateway-mediated).
+ *
+ * Two primitives, one authority each:
+ *
+ *  - **KV bucket `jobs`** is the AUTHORITATIVE operational state: one entry
+ *    per job (`{ job, lastProgressAt }`), every transition a revision-CAS —
+ *    which is what makes `claimJob` atomic: simultaneous claims race on one
+ *    revision and exactly one update wins.
+ *  - **Stream `JOBS`** (subjects `jobs.<category>.<type>`, work-queue
+ *    retention) is the DELIVERY vehicle and redelivery timer. A delivered
+ *    message is the lease this process holds for a job; `working()`
+ *    heartbeats extend it, and a gateway that dies stops heartbeating, so
+ *    `AckWait` redelivers the job to a live instance — gateway-death
+ *    recovery, protocol-native.
+ *
+ * Worker-death recovery is NOT AckWait's job under the mediated topology
+ * (the gateway holding the lease is alive; the worker vanished): it is the
+ * `lastProgressAt` sweep (`recoverStaleRunningJobs`), the same contract the
+ * fs driver's mtime janitor implemented. The redelivery handler checks KV
+ * state, so the two recovery paths can never double-apply.
+ *
+ * Battery ownership (JOB-QUEUE-DRIVER P0): the retry decision belongs to
+ * `will-retry.ts` — `max_deliver` is unlimited and a deterministic failure
+ * is `term()`ed, so the backend's retry engine never becomes a second
+ * authority. The cursor merge belongs to `checkpoint-merge.ts`, shared with
+ * every driver.
+ *
+ * The boundary is the point: no NATS type, subject string, or delivery
+ * handle escapes this file.
+ */
+
+interface JetStreamJobQueueOptions {
+    /** NATS server address(es), e.g. "192.168.64.42:4222". */
+    servers: string | string[];
+    /** Worker presumed dead after this long without progress (default 30 min). */
+    staleRunningMs?: number;
+    /** Lease redelivery window when THIS process stops heartbeating (default 30 s). */
+    ackWaitMs?: number;
+    /** Re-announce + worker-death-sweep cadence (default 30 s; tests shrink it). */
+    tickMs?: number;
+    /** Reconnect on connection loss (default true; tests turn it off). */
+    reconnect?: boolean;
+}
+declare class JetStreamJobQueue implements JobQueue {
+    private readonly options;
+    private readonly logger;
+    private readonly eventBus?;
+    private nc;
+    private js;
+    private jsm;
+    private kv;
+    private iter;
+    /** Delivered messages this process holds — the lease, keyed by jobId,
+     *  with the job's type so a by-type claim can walk them without a read. */
+    private readonly held;
+    private heartbeat;
+    private reconciling;
+    private tick;
+    private ticking;
+    private readonly lastProgressWrite;
+    private readonly staleRunningMs;
+    private readonly ackWaitMs;
+    private readonly tickMs;
+    constructor(options: JetStreamJobQueueOptions, logger: Logger, eventBus?: EventBus | undefined);
+    initialize(): Promise<void>;
+    destroy(): void;
+    /**
+     * A delivery is a job arriving at this gateway. What it means depends on
+     * the job's authoritative (KV) state:
+     *  - pending  → hold the lease, announce for a worker to claim;
+     *  - running  → hold silently (a claim raced ahead of the delivery, or a
+     *               redelivery reached a fresh instance after a gateway death);
+     *  - terminal → the work already concluded elsewhere; consume the message;
+     *  - unknown  → not ours to run; terminate it.
+     */
+    private onDelivery;
+    /** Same wire shape as the fs driver: only jobs with a resourceId announce. */
+    private announce;
+    private read;
+    private write;
+    /**
+     * Read-transform-CAS with bounded retries: the transform sees the current
+     * job and returns the replacement (or null to stop). Every state
+     * transition goes through here, which is what makes each one atomic.
+     */
+    private cas;
+    createJob(job: AnyJob): Promise<void>;
+    getJob(jobIdArg: JobId): Promise<AnyJob | null>;
+    claimNextJob(types: string[]): Promise<{
+        job: AnyJob;
+    } | {
+        declined: 'none-available';
+    }>;
+    /** CAS one pending job to running; null when someone else won it. */
+    private tryClaim;
+    completeJob(jobIdArg: JobId, result: Record<string, unknown>): Promise<boolean>;
+    failJob(jobIdArg: JobId, error: string, completedUnits?: string[], failureClass?: 'transient' | 'deterministic', unitCursors?: Record<string, UnitCursor>): Promise<'retried' | 'failed' | null>;
+    checkpointUnits(jobIdArg: JobId, completedUnits: string[], unitCursors?: Record<string, UnitCursor>): Promise<void>;
+    recordProgress(jobIdArg: JobId, progress: Record<string, unknown>): Promise<void>;
+    cancelPendingJobs(category: 'annotation' | 'generation'): Promise<number>;
+    cancelJob(jobIdArg: JobId): Promise<boolean>;
+    getStats(): Promise<{
+        pending: number;
+        running: number;
+        complete: number;
+        failed: number;
+        cancelled: number;
+    }>;
+    /**
+     * Worker-death recovery: the same contract the fs driver's mtime janitor
+     * implemented — a running job with no progress inside the stale window is
+     * retried or failed, checkpoint intact. Gateway-death recovery never comes
+     * through here; that is AckWait redelivery.
+     */
+    recoverStaleRunningJobs(): Promise<number>;
+    /** The heartbeat body — extend live leases, settle concluded ones. */
+    private reconcileHeld;
+    /**
+     * Materialize the KV key list BEFORE touching any entry: interleaving
+     * `get`/`update` with an open `keys()` iterator on the same connection
+     * makes the iterator drop entries (measured: the second pending job
+     * vanished from every sweep until this was split into two passes).
+     */
+    private allKeys;
+    /** Conclude this process's lease on a job, if it holds one. */
+    private settleLease;
+}
+
 /**
  * Citation-token resolver (INLINE-CITATIONS P1).
  *
@@ -865,5 +1030,5 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
  */
 declare const STALL_THRESHOLD_MS: number;
 
-export { AnnotationDetection, FsJobQueue, STALL_THRESHOLD_MS, generateResourceFromTopic, isCancelledJob, isCompleteJob, isFailedJob, isPendingJob, isRunningJob, processAssessmentJob, processCommentJob, processGenerationJob, processHighlightJob, processReferenceJob, processTagJob };
-export type { AnyJob, AssessmentDetectionJob, AssessmentDetectionParams, AssessmentDetectionProgress, CancelledJob, CommentDetectionJob, CommentDetectionParams, CommentDetectionProgress, CompleteJob, DetectionJob, DetectionParams, DetectionProgress, FailedJob, GenerationJob, GenerationResult, HighlightDetectionJob, HighlightDetectionParams, HighlightDetectionProgress, JobMetadata, JobQueryFilters, JobQueue, JobStatus, JobType, OnProgress, PendingJob, ProcessorResult, RunningJob, TagDetectionJob, TagDetectionParams, TagDetectionProgress, YieldProgress };
+export { AnnotationDetection, FsJobQueue, JetStreamJobQueue, STALL_THRESHOLD_MS, generateResourceFromTopic, isCancelledJob, isCompleteJob, isFailedJob, isPendingJob, isRunningJob, processAssessmentJob, processCommentJob, processGenerationJob, processHighlightJob, processReferenceJob, processTagJob };
+export type { AnyJob, AssessmentDetectionJob, AssessmentDetectionParams, AssessmentDetectionProgress, CancelledJob, CommentDetectionJob, CommentDetectionParams, CommentDetectionProgress, CompleteJob, DetectionJob, DetectionParams, DetectionProgress, FailedJob, GenerationJob, GenerationResult, HighlightDetectionJob, HighlightDetectionParams, HighlightDetectionProgress, JetStreamJobQueueOptions, JobMetadata, JobQueryFilters, JobQueue, JobStatus, JobType, OnProgress, PendingJob, ProcessorResult, RunningJob, TagDetectionJob, TagDetectionParams, TagDetectionProgress, YieldProgress };