@cosmicdrift/kumiko-framework 0.324.0 → 0.325.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.324.0",
+  "version": "0.325.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -202,8 +202,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.324.0",
-    "@cosmicdrift/kumiko-types": "0.324.0",
+    "@cosmicdrift/kumiko-http": "0.325.0",
+    "@cosmicdrift/kumiko-types": "0.325.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -219,7 +219,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.324.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.325.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.325.0",
+    "type": "improvement",
+    "title": "JobContext exposes ctx.attempt and ctx.finalAttempt",
+    "detail": "Job handlers can read the 1-based run number and whether the current run is\nthe last one BullMQ will attempt, so a handler can defer writing a\nbusiness-facing failure state until the final attempt instead of writing\nit on every retry.\n\nMigration note: hand-built `JobContext` objects (test doubles, boot\nseeders) must add `attempt` and `finalAttempt` (e.g. `attempt: 1,\nfinalAttempt: true`)."
+  },
   {
     "version": "0.324.0",
     "type": "breaking",

package/src/jobs/__tests__/job-attempt-context.integration.test.ts

@@ -0,0 +1,76 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { defineFeature } from "../../engine";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+const retryRuns: [number, boolean][] = [];
+const singleRuns: [number, boolean][] = [];
+
+const attemptFixtureFeature = defineFeature("attemptfixture", (r) => {
+  r.writeHandler(
+    "trigger-retry",
+    z.object({}),
+    async () => ({ isSuccess: true as const, data: {} }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+  r.job(
+    "retry",
+    { trigger: { on: "attemptfixture:write:trigger-retry" }, retries: 2 },
+    async (_payload, ctx) => {
+      retryRuns.push([ctx.attempt, ctx.finalAttempt]);
+      if (ctx.attempt < 3) throw new Error(`fails on attempt ${ctx.attempt}`);
+    },
+  );
+
+  r.writeHandler(
+    "trigger-single",
+    z.object({}),
+    async () => ({ isSuccess: true as const, data: {} }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+  r.job(
+    "single",
+    { trigger: { on: "attemptfixture:write:trigger-single" } },
+    async (_payload, ctx) => {
+      singleRuns.push([ctx.attempt, ctx.finalAttempt]);
+    },
+  );
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [attemptFixtureFeature],
+    jobs: { consumerLane: "worker" },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  retryRuns.length = 0;
+  singleRuns.length = 0;
+});
+
+describe("JobContext.attempt / finalAttempt", () => {
+  test("increments per retry and marks the last configured attempt final", async () => {
+    await stack.http.writeOk("attemptfixture:write:trigger-retry", {}, TestUsers.admin);
+
+    await stack.drainJobs();
+    expect(retryRuns).toEqual([
+      [1, false],
+      [2, false],
+      [3, true],
+    ]);
+  });
+
+  test("a job without retries starts at attempt 1 and is already final", async () => {
+    await stack.http.writeOk("attemptfixture:write:trigger-single", {}, TestUsers.admin);
+
+    await stack.drainJobs();
+    expect(singleRuns).toEqual([[1, true]]);
+  });
+});

package/src/jobs/job-runner.ts

@@ -745,10 +745,11 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // retry number, so audit queries distinguish fresh from retry runs
     // without peeking at BullMQ internals.
     const rawData = bullJob.data as DbRow;
+    const attempt = bullJob.attemptsMade + 1;
     const meta: JobMeta = {
       triggeredById: rawData["_triggeredById"] as string | undefined, // @cast-boundary dynamic-key
       payload: rawData["_payload"] as string | undefined, // @cast-boundary dynamic-key
-      attempt: bullJob.attemptsMade + 1,
+      attempt,
     };
 
     // Build handler payload (without internal meta fields)
@@ -773,7 +774,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       : null;
     // BullMQ stops retrying once attemptsMade reaches the configured attempts
     // (`retries + 1`), so this is the attempt whose failure is final.
-    const finalAttempt = bullJob.attemptsMade + 1 >= (jobDef.retries ?? 0) + 1;
+    const finalAttempt = attempt >= (jobDef.retries ?? 0) + 1;
     const outcomeMeta = (messageKey: string | null): JobOutcomeMeta => ({
       tenantId,
       finalAttempt,
@@ -898,6 +899,8 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       ...(selfRunner !== undefined && { jobRunner: selfRunner }),
       systemUser: jobSystemUser,
       triggeredBy: triggeredById !== null ? { id: triggeredById, tenantId } : null,
+      attempt,
+      finalAttempt,
       log: createJobLogger(logs),
       ...(triggerName !== undefined && { triggerName }),
       ...(triggerEvent !== undefined && { triggerEvent }),
@@ -1003,7 +1006,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
           attributes: {
             "job.name": jobName,
             "job.id": jobId,
-            "job.attempt": bullJob.attemptsMade + 1,
+            "job.attempt": attempt,
             "kumiko.tenant_id": tenantId,
             // Lane-routing attributes (Welle 2.6). `run_in` is the job's
             // declared lane (explicit or default-"worker"); `consumer_lane`