@jarenjs/db 0.34.0 → 0.34.2

package/dist/types/jobs.d.ts

@@ -25,7 +25,10 @@
  *  - **Shutdown is bounded.** Handlers receive an `AbortSignal` and
  *    `stop()` takes a deadline, so a handler that never settles cannot
  *    hold `stop()` — and therefore `store.close()`, and therefore the
- *    database file — open forever.
+ *    database file — open forever. A loop the deadline could not drain
+ *    is CANCELLED, not merely left behind: when its handler finally
+ *    settles it exits without another claim, store write or poll
+ *    timer, and its abandoned job recovers by lease expiry (§5).
  */
 export declare const JOBS_TABLE = "_jaren_jobs";
 export declare const JOB_CHECKPOINTS_TABLE = "_jaren_job_checkpoints";
@@ -117,6 +120,9 @@ export declare function createJobEngine(options: {
          * the loops — but only up to `graceMs`. A handler that ignores its
          * signal cannot hold the process open; the resolved record says so
          * instead, and the lease expiry (§5) lets another worker re-claim.
+         * A loop the grace period could not drain is cancelled outright:
+         * when its handler finally settles it exits without another
+         * claim, store write or poll timer.
          * @param {{ graceMs?: number }} [stopOptions]
          * @returns {Promise<{ drained: boolean, inFlight: number }>}
          */

package/docs/JOBS-FORMAT.md

@@ -125,7 +125,8 @@ stats() }`:
   plainly (§8);
 - `stop({ graceMs })` aborts in-flight handlers and resolves once they
   settle **or** the grace period expires (default 5 s), answering
-  `{ drained, inFlight }` — see §6.1;
+  `{ drained, inFlight }`; a loop the grace period could not drain is
+  **cancelled**, not left running — see §6.1;
 - `stats()` reports claims, completions, failures, wakes, polls and the
   in-flight handler count.
 
@@ -162,6 +163,16 @@ handle really is released. A handler that ignores its signal therefore
 cannot hold the database file open for the life of the process, and the
 lease expiry (§5) lets another worker re-claim its job.
 
+A loop the grace period could not drain is **cancelled**, not merely
+uncounted: when its wedged handler finally settles, the loop exits
+without writing the completion or the failure, without claiming again,
+and without re-arming its poll timer — the store it would touch is the
+one the caller is closing, and the job it abandons recovers by lease
+expiry (§5). A later `start()` builds fresh loops in a new session (and
+re-registers the worker's wake-on-enqueue hook and its place in
+`stopAll`), so a cancelled loop can never be revived as an extra
+claimer.
+
 ## 7. The DAG composition
 
 ```js

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.34.0",
+  "version": "0.34.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -71,9 +71,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.34.0",
-    "@jarenjs/json": "^0.34.0",
-    "@jarenjs/validate": "^0.34.0"
+    "@jarenjs/core": "^0.34.2",
+    "@jarenjs/json": "^0.34.2",
+    "@jarenjs/validate": "^0.34.2"
   },
   "bin": {
     "jaren-db": "./src/cli.js"

package/src/jobs.js

@@ -26,7 +26,10 @@
  *  - **Shutdown is bounded.** Handlers receive an `AbortSignal` and
  *    `stop()` takes a deadline, so a handler that never settles cannot
  *    hold `stop()` — and therefore `store.close()`, and therefore the
- *    database file — open forever.
+ *    database file — open forever. A loop the deadline could not drain
+ *    is CANCELLED, not merely left behind: when its handler finally
+ *    settles it exits without another claim, store write or poll
+ *    timer, and its abandoned job recovers by lease expiry (§5).
  */
 
 import { chain } from './driver.js';
@@ -370,6 +373,17 @@ export function createJobEngine(options) {
 
     /** Aborted when `stop()` is called: the handler's cue to wind up. */
     let shutdown = new AbortController();
+    /**
+     * The per-`start()` loop session. When a `stop()` grace deadline
+     * expires the session is cancelled: a loop that could not be
+     * drained must abandon its job — no completion or failure write,
+     * no further claim, no re-armed poll timer — because the store it
+     * would touch is the one the caller is about to close. The
+     * abandoned lease expires and the next claim re-runs the job (§5).
+     * A later `start()` opens a NEW session, so a cancelled loop can
+     * never be revived.
+     */
+    let session = { cancelled: false };
     /** In-flight handler count, so `stop()` can report what it left. */
     let inFlight = 0;
 
@@ -389,7 +403,8 @@ export function createJobEngine(options) {
       }
     };
 
-    const runOne = async (job) => {
+    /** @param {{ cancelled: boolean }} loopSession */
+    const runOne = async (job, loopSession) => {
       stats.claims += 1;
       inFlight += 1;
       try {
@@ -399,9 +414,13 @@ export function createJobEngine(options) {
             { job, checkpointsFor, signal: shutdown.signal });
         }
         catch (error) {
+          // past cancellation the store is closing: leave the leased
+          // row to expiry-based recovery (§5) instead of racing it
+          if (loopSession.cancelled) return;
           await recordFailure(job, error);
           return;
         }
+        if (loopSession.cancelled) return;
         try {
           // a §7 handler may have completed transactionally already; the
           // guarded update makes this a no-op then
@@ -420,8 +439,9 @@ export function createJobEngine(options) {
       }
     };
 
-    const loop = async () => {
-      while (running) {
+    /** @param {{ cancelled: boolean }} loopSession */
+    const loop = async (loopSession) => {
+      while (running && !loopSession.cancelled) {
         let job;
         try {
           job = await Promise.resolve(claim({
@@ -430,13 +450,13 @@ export function createJobEngine(options) {
         catch {
           job = undefined; // a transient storage failure: back off to the poll
         }
-        if (!running) return;
+        if (!running || loopSession.cancelled) return;
         if (job === undefined) {
           await sleep();
           continue;
         }
         try {
-          await runOne(job);
+          await runOne(job, loopSession);
         }
         catch {
           // `runOne` normalizes every handler outcome, so reaching here
@@ -453,7 +473,12 @@ export function createJobEngine(options) {
         if (running) throw new TypeError('the worker is already started');
         running = true;
         shutdown = new AbortController();
-        loops = Array.from({ length: concurrency }, () => loop());
+        session = { cancelled: false };
+        loops = Array.from({ length: concurrency }, () => loop(session));
+        // a restart re-registers what stop() removed: the
+        // wake-on-enqueue hook and the stopAll membership
+        wakers.add(onWake);
+        workers.add(worker);
         return worker;
       },
       /**
@@ -461,6 +486,9 @@ export function createJobEngine(options) {
        * the loops — but only up to `graceMs`. A handler that ignores its
        * signal cannot hold the process open; the resolved record says so
        * instead, and the lease expiry (§5) lets another worker re-claim.
+       * A loop the grace period could not drain is cancelled outright:
+       * when its handler finally settles it exits without another
+       * claim, store write or poll timer.
        * @param {{ graceMs?: number }} [stopOptions]
        * @returns {Promise<{ drained: boolean, inFlight: number }>}
        */
@@ -478,6 +506,7 @@ export function createJobEngine(options) {
         ]);
         clearTimeout(timer);
         if (drained) loops = [];
+        else session.cancelled = true; // cancel what could not be drained
         wakers.delete(onWake);
         workers.delete(worker);
         return { drained: drained === true, inFlight };