@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/jobs/job-temp.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The prefix for an application name: `'<slug>-job-'`, or `'app-job-'` when
+ * the name slugifies to nothing (or none is given).
+ *
+ * @param appName - the application's display name.
+ * @returns the prefix.
+ *
+ * @stability stable
+ */
+export declare function jobTempPrefixFor(appName: string | undefined): string;
+/**
+ * The prefix EVERY temp file created by a job handler must carry.
+ *
+ * A live binding: `'app-job-'` until the app configures its name
+ * (`JobsModule.forRoot({ appName })`, at import time), then that name's
+ * prefix. Read it where it is used, never copy it into a constant of your own.
+ *
+ * Import this rather than writing your own scratch-file name: a file without
+ * this prefix is a file the janitor will never clean up, and one whose
+ * abandoned copies accumulate for the life of the host.
+ *
+ * @stability stable
+ */
+export declare let JOB_TEMP_PREFIX: string;
+/**
+ * Sets {@link JOB_TEMP_PREFIX} from the application's name. Called by
+ * `JobsModule.forRoot({ appName })`; call it yourself only in a process that
+ * runs handlers without the module (a script).
+ *
+ * @param appName - the application's display name (`APP_NAME`).
+ * @returns the prefix now in effect.
+ *
+ * @stability experimental
+ */
+export declare function configureJobTempPrefix(appName: string): string;
+/**
+ * The directory temp files live in, read on EVERY call rather than captured in
+ * a constant.
+ *
+ * `os.tmpdir()` reads `TMPDIR`/`TEMP` at call time, so a process whose
+ * environment changes is honoured instead of silently ignored, and it is one
+ * `process.env` lookup either way.
+ *
+ * It is also the seam the janitor's suite redirects — by stubbing THIS
+ * function, not the environment: a Jest test file writes to a sandboxed copy
+ * of `process.env`, so setting `TMPDIR` there would silently do nothing and
+ * the suite would sweep the machine's real `/tmp`.
+  *
+  * @stability experimental
+ */
+export declare function jobTempDir(): string;
+/**
+ * An absolute path for a new scratch file, prefixed and collision-free.
+ *
+ * ⚠ IT CREATES NOTHING. It returns a path; the caller writes the file, and the
+ * caller deletes it when the work succeeds. The janitor is the safety net for
+ * the case where the caller never gets the chance — not a substitute for
+ * cleaning up after yourself, because it deliberately leaves anything younger
+ * than six hours alone.
+ *
+ * @param suffix - an optional trailing part (`'.pdf'`, `'-page-2.png'`), for
+ * tools that insist on a real extension.
+  *
+  * @stability experimental
+ */
+export declare function jobTempPath(suffix?: string): string;
+//# sourceMappingURL=job-temp.d.ts.map

package/dist/jobs/job-temp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-temp.d.ts","sourceRoot":"","sources":["../../src/jobs/job-temp.ts"],"names":[],"mappings":"AA+EA;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEpE;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,IAAI,eAAe,QAA8B,CAAC;AAEzD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAK,GAAG,MAAM,CAE/C"}

package/dist/jobs/job-temp.js

@@ -0,0 +1,157 @@
+"use strict";
+// =============================================================================
+// Temp files a job handler creates (issue #263, epic #254)
+// =============================================================================
+//
+// A handler that downloads a file, renders a document, shells out to a
+// converter or streams an object through a transform writes it somewhere
+// first, and `os.tmpdir()` is where. That is fine right up until the worker is
+// SIGKILLed mid-download — an OOM kill, a container replaced by a rolling
+// deploy, a node whose lid closed — at which point NO `finally` block runs,
+// and the partial file stays on disk forever. The next kill leaves another.
+// On a long-lived host with a small `/tmp`, the eventual failure is not "a job
+// failed": it is every write on the machine failing at once, for a reason that
+// looks nothing like the job queue.
+//
+// This file is one half of the fix — the NAMING half. `TempFileJanitorTask` is
+// the other, and it can only work if it can tell OUR abandoned files from
+// everybody else's: `/tmp` is shared with the operating system, the package
+// manager, the language runtime and any other process on the box, and a
+// sweeper that deleted "old files in /tmp" would eventually delete something
+// that mattered to someone else. So every temp file this application creates
+// carries a prefix, and the janitor removes ONLY files that carry it.
+//
+// -----------------------------------------------------------------------------
+// THE PREFIX IS DERIVED FROM THE APP'S NAME, NOT WRITTEN OUT
+// -----------------------------------------------------------------------------
+//
+// This repository is a template: nothing in it may hard-code an application,
+// product or repository name, and `packages/shared`'s `APP_NAME` is the one
+// line a fork edits to rebrand. The package cannot import it (a package never
+// imports an app), so the app passes it: `JobsModule.forRoot({ appName })`
+// calls `configureJobTempPrefix` once, at import time, before any handler or
+// the janitor runs (issue #734). Slugifying it here means the prefix rebrands
+// with everything else, and — the reason that actually matters — two
+// applications built from this template running on the SAME host get DIFFERENT
+// prefixes, so neither janitor can ever delete the other's in-flight temp
+// files. A fixed literal (`app-job-`) would have made that collision silent
+// and data-losing.
+//
+// The one cost is honest and small: renaming the application orphans temp
+// files written under the old name. They are files in `/tmp` with nothing
+// referring to them, left to the operating system's own reaping (systemd's
+// `tmpfiles.d` clears `/tmp` on a schedule and every reboot), and the window
+// is a single deploy. A janitor that also swept "whatever the prefix used to
+// be" would need a list of former names — a second thing to keep in sync, to
+// solve a problem that resolves itself.
+//
+// `slugify` falls back to a NEUTRAL constant rather than to an empty prefix,
+// because an empty prefix would make `startsWith('')` true for every file in
+// `/tmp` and turn the janitor into exactly the indiscriminate sweeper the
+// paragraph above rejects. That fallback is a safety property, not a
+// nicety — see the test.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOB_TEMP_PREFIX = void 0;
+exports.jobTempPrefixFor = jobTempPrefixFor;
+exports.configureJobTempPrefix = configureJobTempPrefix;
+exports.jobTempDir = jobTempDir;
+exports.jobTempPath = jobTempPath;
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * What the prefix degrades to when `APP_NAME` slugifies to nothing (all
+ * punctuation, all non-Latin script, empty).
+ *
+ * Deliberately generic and carrying no product name — it is a description of
+ * WHAT the file is, not of WHOSE it is.
+ */
+const NEUTRAL_PREFIX_SLUG = 'app';
+/**
+ * A display name to a filename-safe slug (`'Some Name'` → `'some-name'`);
+ * anything that reduces to nothing falls back to the neutral slug above.
+ */
+function slugify(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug.length > 0 ? slug : NEUTRAL_PREFIX_SLUG;
+}
+/**
+ * The prefix for an application name: `'<slug>-job-'`, or `'app-job-'` when
+ * the name slugifies to nothing (or none is given).
+ *
+ * @param appName - the application's display name.
+ * @returns the prefix.
+ *
+ * @stability stable
+ */
+function jobTempPrefixFor(appName) {
+    return `${slugify(appName ?? '')}-job-`;
+}
+/**
+ * The prefix EVERY temp file created by a job handler must carry.
+ *
+ * A live binding: `'app-job-'` until the app configures its name
+ * (`JobsModule.forRoot({ appName })`, at import time), then that name's
+ * prefix. Read it where it is used, never copy it into a constant of your own.
+ *
+ * Import this rather than writing your own scratch-file name: a file without
+ * this prefix is a file the janitor will never clean up, and one whose
+ * abandoned copies accumulate for the life of the host.
+ *
+ * @stability stable
+ */
+exports.JOB_TEMP_PREFIX = jobTempPrefixFor(undefined);
+/**
+ * Sets {@link JOB_TEMP_PREFIX} from the application's name. Called by
+ * `JobsModule.forRoot({ appName })`; call it yourself only in a process that
+ * runs handlers without the module (a script).
+ *
+ * @param appName - the application's display name (`APP_NAME`).
+ * @returns the prefix now in effect.
+ *
+ * @stability experimental
+ */
+function configureJobTempPrefix(appName) {
+    exports.JOB_TEMP_PREFIX = jobTempPrefixFor(appName);
+    return exports.JOB_TEMP_PREFIX;
+}
+/**
+ * The directory temp files live in, read on EVERY call rather than captured in
+ * a constant.
+ *
+ * `os.tmpdir()` reads `TMPDIR`/`TEMP` at call time, so a process whose
+ * environment changes is honoured instead of silently ignored, and it is one
+ * `process.env` lookup either way.
+ *
+ * It is also the seam the janitor's suite redirects — by stubbing THIS
+ * function, not the environment: a Jest test file writes to a sandboxed copy
+ * of `process.env`, so setting `TMPDIR` there would silently do nothing and
+ * the suite would sweep the machine's real `/tmp`.
+  *
+  * @stability experimental
+ */
+function jobTempDir() {
+    return (0, node_os_1.tmpdir)();
+}
+/**
+ * An absolute path for a new scratch file, prefixed and collision-free.
+ *
+ * ⚠ IT CREATES NOTHING. It returns a path; the caller writes the file, and the
+ * caller deletes it when the work succeeds. The janitor is the safety net for
+ * the case where the caller never gets the chance — not a substitute for
+ * cleaning up after yourself, because it deliberately leaves anything younger
+ * than six hours alone.
+ *
+ * @param suffix - an optional trailing part (`'.pdf'`, `'-page-2.png'`), for
+ * tools that insist on a real extension.
+  *
+  * @stability experimental
+ */
+function jobTempPath(suffix = '') {
+    return (0, node_path_1.join)(jobTempDir(), `${exports.JOB_TEMP_PREFIX}${(0, node_crypto_1.randomUUID)()}${suffix}`);
+}
+//# sourceMappingURL=job-temp.js.map

package/dist/jobs/job-temp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-temp.js","sourceRoot":"","sources":["../../src/jobs/job-temp.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,2DAA2D;AAC3D,gFAAgF;AAChF,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,+EAA+E;AAC/E,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,+EAA+E;AAC/E,oCAAoC;AACpC,EAAE;AACF,+EAA+E;AAC/E,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,6EAA6E;AAC7E,6EAA6E;AAC7E,sEAAsE;AACtE,EAAE;AACF,gFAAgF;AAChF,6DAA6D;AAC7D,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,2EAA2E;AAC3E,6EAA6E;AAC7E,8EAA8E;AAC9E,qEAAqE;AACrE,+EAA+E;AAC/E,0EAA0E;AAC1E,4EAA4E;AAC5E,mBAAmB;AACnB,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,wCAAwC;AACxC,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,qEAAqE;AACrE,yBAAyB;AACzB,gFAAgF;;;AAqChF,4CAEC;AA2BD,wDAGC;AAiBD,gCAEC;AAgBD,kCAEC;AAxGD,6CAAyC;AACzC,qCAAiC;AACjC,yCAAiC;AAEjC;;;;;;GAMG;AACH,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAElC;;;GAGG;AACH,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,IAAI,GAAG,IAAI;SACd,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE3B,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,gBAAgB,CAAC,OAA2B;IAC1D,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,OAAO,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;GAYG;AACQ,QAAA,eAAe,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAEzD;;;;;;;;;GASG;AACH,SAAgB,sBAAsB,CAAC,OAAe;IACpD,uBAAe,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,uBAAe,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,UAAU;IACxB,OAAO,IAAA,gBAAM,GAAE,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,WAAW,CAAC,MAAM,GAAG,EAAE;IACrC,OAAO,IAAA,gBAAI,EAAC,UAAU,EAAE,EAAE,GAAG,uBAAe,GAAG,IAAA,wBAAU,GAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAC1E,CAAC"}

package/dist/jobs/job-terminal.service.d.ts

@@ -0,0 +1,262 @@
+import { ConfigService } from '@nestjs/config';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { type Job, type JobsPrisma, type JobsUpdateData } from './data/jobs-db';
+import { type JobsMetrics } from './ports';
+import { JobClock } from './job-clock';
+import { JobHandlerRegistry } from './job-handler.registry';
+import { ProviderThrottleService } from './provider-throttle.service';
+/**
+ * What a caller may say about a failure that the thrown value does not carry
+ * on its own. Used by the node control plane, which has an HTTP body rather
+ * than an exception.
+  *
+  * @stability experimental
+ */
+export interface CompleteFailedOptions {
+    /** "This was a provider rate limit" — treated exactly as a thrown `RateLimitError`. */
+    rateLimited?: boolean;
+    /** A provider-requested delay, in milliseconds. A FLOOR on the backoff, not an override. */
+    retryAfterMs?: number;
+    /**
+     * "This job can never succeed, so do not spend attempts discovering that."
+     *
+     * SHORT-CIRCUITS EVERYTHING BELOW — ahead of the rate-limit classification,
+     * not after it — because it is a statement about the job being UNRUNNABLE,
+     * and neither a retry nor a deferral can change an unrunnable job into a
+     * runnable one. A 429 is a "not now"; this is a "not ever".
+     *
+     * The caller that has this knowledge is the executor, not this service: the
+     * in-process worker (#262) sets it when a claimed row names a type no
+     * handler in this process registers, and the node control plane (#268) will
+     * set it for a node reporting an input it can never accept. Retrying either
+     * one re-enters the same process with the same registry, or ships the same
+     * input to the same fleet, and reaches the same conclusion two minutes
+     * later having burnt the budget to learn nothing.
+     *
+     * It is a FLAG INTO THE CHOKEPOINT rather than a licence for the caller to
+     * write its own terminal row — the whole argument in this file's header
+     * applies unchanged: the two executors must reach the same conclusion by
+     * running the same code, including this one.
+     */
+    permanent?: boolean;
+}
+/**
+ * What the terminal path actually did. Returned so a worker can log it and a
+ * test can assert the branch without reverse-engineering it from the written
+ * row.
+ *
+ * `write-failed` is the `safeTerminalUpdate` give-up: the row was NOT
+ * written, and it is still `running` for the lease reaper (#263) to pick up.
+ *
+ * `claim-lost` (#477) means the row was NOT written because it is no longer
+ * held by the claim that is settling it — reaped, re-claimed, or already
+ * settled. Nothing was emitted. Not an error: the caller's conclusion is
+ * stale and belongs to nobody. The node plane maps it to a 409.
+  *
+  * @stability experimental
+ */
+export type JobSettleOutcome = 'succeeded' | 'failed' | 'retry-scheduled' | 'rate-limit-deferred' | 'write-failed' | 'claim-lost';
+/** The data shape a terminal write carries: plain column values only. */
+type TerminalWriteData = JobsUpdateData;
+/**
+ * Does `row` already hold every value `data` would write?
+ *
+ * Used ONLY on the ambiguous path of `safeTerminalUpdate`: the first attempt
+ * threw (so it may or may not have committed) and the guarded retry matched
+ * nothing. If the row now carries exactly what we tried to write, the first
+ * attempt committed and the write is ours; anything else means somebody else
+ * moved the row.
+ *
+ * Why a coincidental match by another writer is not a practical concern: every
+ * terminal payload carries a timestamp from this call's clock
+ * (`finishedAt`, or `scheduledFor` with jitter), which no other writer
+ * reproduces to the millisecond.
+ *
+ * ⚠ THROWS (via `assertPlainTerminalData`) on any value that is not a plain
+ * scalar, `Date` or `null`. The comparison is only meaningful for absolute
+ * values; a Prisma operator such as `{ increment: 1 }` has no "equals the row"
+ * reading at all, and a comparison that silently answered `false` for it would
+ * turn every ambiguous commit into a false `claim-lost`. The un-charge comment
+ * in `deferForRateLimit` explains why no payload here uses operators; this
+ * makes a future one fail loudly.
+  *
+  * @stability experimental
+ */
+export declare function rowMatchesWrite(row: Job, data: TerminalWriteData): boolean;
+/**
+ * The terminal state machine: settles an attempt as succeeded, retried, rate-limited or failed, and emits `job.settled`.
+ *
+ * @stability experimental
+ */
+export declare class JobTerminalService {
+    private readonly prisma;
+    private readonly config;
+    private readonly throttle;
+    private readonly events;
+    private readonly registry;
+    private readonly metrics;
+    private readonly logger;
+    private readonly clock;
+    private readonly rand;
+    constructor(prisma: JobsPrisma, config: ConfigService, throttle: ProviderThrottleService, events: EventEmitter2, registry: JobHandlerRegistry, clock?: JobClock, rand?: () => number, metrics?: JobsMetrics);
+    /**
+     * Records a job that completed its work.
+     *
+     * Order matters: the throttle gate is told about the success FIRST, because
+     * a success is direct evidence the provider's limit has lifted and sibling
+     * slots may be sitting in `acquire()` waiting on a cooldown that is now
+     * stale. Telling them before the (slower) database write shortens their
+     * wait by however long the write takes.
+     *
+     * ⚠ `executor` IS DELIBERATELY NOT CLEARED. `succeeded` is terminal — the
+     * row will never be claimed again — so there is no stale-ownership problem
+     * to solve by nulling it, and WHICH SIDE RAN THE JOB is exactly the kind of
+     * thing you want to still know later ("are node-executed jobs slower?",
+     * "did this succeed before or after we moved this type to nodes?"). The
+     * claim and the lease ARE cleared, because those two are live ownership
+     * assertions and a terminal row must not appear to be held by anybody.
+     *
+     * ⚠ `claimToken` IS NOT COVERED BY THAT EXCEPTION and is cleared with the
+     * rest (#361). `executor` survives because it is AUDIT — it says something
+     * a human can read months later. A random uuid records nothing about what
+     * ran, so keeping it would buy no history at all while leaving a terminal
+     * row carrying a live ownership assertion. Its invariant is "non-null
+     * exactly while the row is claimed"; a settled row is not claimed.
+     */
+    completeSucceeded(job: Job): Promise<JobSettleOutcome>;
+    private settleSucceeded;
+    /**
+     * Records a job that stopped without completing, and decides what happens
+     * to the row: deferred, retried, or permanently failed.
+     *
+     * See the file header for the classification order and for why a node's
+     * `opts` flags are treated identically to a thrown `RateLimitError`.
+     */
+    completeFailed(job: Job, error: unknown, opts?: CompleteFailedOptions): Promise<JobSettleOutcome>;
+    /**
+     * Records one settled executor report as application metrics (#600) and
+     * hands the outcome back unchanged. Duration is claim → settlement
+     * (`startedAt` is stamped by the claim); the metrics service never throws.
+     */
+    private observed;
+    private settleFailed;
+    /**
+     * The RATE-LIMIT branch: back off for minutes, do not charge an attempt,
+     * and give up only against the separate `rateLimitHits` budget.
+     */
+    private deferForRateLimit;
+    /** The ORDINARY branch: retry against `attempts`, or fail permanently. */
+    private retryOrFail;
+    /**
+     * Writes the terminal `failed` row and announces it.
+     *
+     * ONE implementation, reached from the two routes whose written row is
+     * IDENTICAL: the attempt budget running out, and a caller declaring the job
+     * unrunnable. `log` is the only thing that differs, because the row must
+     * not — a `failed` job releases its claim and its lease and keeps its
+     * `executor` whichever route it took, and a second copy of that object is a
+     * second place to forget a field.
+     *
+     * The rate-limit give-up in `deferForRateLimit` deliberately does NOT come
+     * through here: it writes `rateLimitHits` and `rateLimitedAt` as well, and
+     * widening this method with two optional counters to absorb it would make
+     * the shared thing less readable than the duplication it removed.
+     */
+    private failPermanently;
+    /**
+     * Writes the terminal row, retrying ONCE, and then LOGS AND SWALLOWS.
+     *
+     * ⚠ THE SWALLOW IS THE FEATURE. Every caller of this service is a worker
+     * finishing a job and about to free its slot. If a database blip could
+     * throw out of here, that exception would propagate into the worker's
+     * finally-block-shaped cleanup and — depending on where it lands — either
+     * crash the worker or leave the slot accounted for but never released. A
+     * slot lost this way is lost for the life of the process, and losing all of
+     * them silently reduces the queue's throughput to zero with nothing in the
+     * logs but one stack trace from an hour ago.
+     *
+     * So the worst case here is deliberately BOUNDED AND RECOVERABLE: the slot
+     * is freed, and the row is left `running` with an expired lease — which is
+     * precisely the state the lease reaper (#263) exists to find and requeue.
+     * The job is delayed by one lease interval; nothing is lost, and nothing
+     * wedges.
+     *
+     * ONE retry, not zero and not many. Zero would fail the whole terminal
+     * write on a single recycled connection, which is common enough to be
+     * worth covering. Many, with waits between them, would hold the worker slot
+     * open for the duration of an outage — the exact resource this method is
+     * protecting.
+     *
+     * THE WRITE IS GUARDED BY `heldClaimWhere(job)` (#477) — see the file
+     * header. A guarded write that matches nothing is `claim-lost`, and it is
+     * FINAL: it is not retried, because "the row moved" is an answer, not a blip.
+     *
+     * ⚠ THE ONE RULE THE GUARD ADDS TO THE RETRY: the first attempt can COMMIT
+     * AND THEN THROW (the connection drops on the way back). Its retry then
+     * matches nothing — not because somebody else took the row, but because
+     * our own first write already moved it off `running` and cleared the token.
+     * Answering `claim-lost` there would drop the settled event for a settle
+     * that genuinely happened. So:
+     *
+     *   (a) first attempt returns no row, without throwing ⇒ `claim-lost`, final.
+     *   (b) first attempt throws, retry returns no row ⇒ re-read the row by id.
+     *       If it already holds every value `data` writes (`rowMatchesWrite`),
+     *       the first attempt committed and the write is OURS ⇒ `written`, with
+     *       the re-read row (so a terminal branch still emits, exactly once).
+     *       Otherwise ⇒ `claim-lost`. If the re-read itself throws we cannot
+     *       tell which ⇒ `write-failed` (no emit, the conservative answer).
+     *   (c) retry throws ⇒ `write-failed`.
+     *
+     * Returns a `TerminalWrite`; see its declaration.
+     *
+     * WHY `updateManyAndReturn`: it is one `UPDATE … WHERE … RETURNING *`, so the
+     * ownership check and the write are one statement (the same reason
+     * `heldLeaseWhere` lives in a `where` clause) and the row handed to the
+     * settled event is the post-update row, with no second read to race.
+     *
+     * WHY `JobUncheckedUpdateManyInput` AND NOT A CHECKED INPUT. Every one of
+     * this method's five call sites releases the node claim by writing
+     * `claimedByNodeId: null` — a raw foreign-key scalar. Since #267 wired
+     * `Job.claimedByNode` as a real relation, Prisma's *Checked* update input no
+     * longer accepts that scalar; it accepts only the nested relation form
+     * (`claimedByNode: { disconnect: true }`). The *Unchecked* variant is the
+     * one Prisma provides precisely for callers that set foreign keys
+     * themselves, which is what a terminal write is: it clears an ownership
+     * column, it does not navigate a relation.
+     */
+    private safeTerminalUpdate;
+    /**
+     * Best-effort read of a row this settle has just LOST, for the log line
+     * only. A failure to read it changes nothing — the outcome is already
+     * decided — so it is swallowed into `null`.
+     */
+    private peek;
+    /**
+     * Maps a `TerminalWrite` that did NOT land to the outcome a caller returns,
+     * logging `claim-lost` once, here, for all five call sites.
+     *
+     * `claim-lost` is a WARN, not an error: it means an executor came back with
+     * a conclusion about a row that had already moved on (reaped, re-claimed,
+     * settled). Nothing is emitted and nothing throws — see the file header.
+     * `write-failed` was already logged by `safeTerminalUpdate`.
+     */
+    private unwritten;
+    /**
+     * Announces a genuinely settled job. The listener-containment rule (a
+     * listener is a bystander; it must not be able to affect the row or the
+     * slot) lives in `emitJobSettled`, shared with the lease reaper (#468).
+     */
+    private emitSettled;
+    /**
+     * A numeric setting with a defensive fallback.
+     *
+     * The fallback repeats `configuration.ts`'s default rather than trusting
+     * it, because this service is also constructed directly in unit tests with
+     * a stub `ConfigService`, and a missing key must degrade to the shipped
+     * behaviour rather than to `NaN` — which would silently produce
+     * `new Date(NaN)` and an unwritable `scheduled_for`.
+     */
+    private configNumber;
+}
+export {};
+//# sourceMappingURL=job-terminal.service.d.ts.map

package/dist/jobs/job-terminal.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-terminal.service.d.ts","sourceRoot":"","sources":["../../src/jobs/job-terminal.service.ts"],"names":[],"mappings":"AAwGA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhF,OAAO,EAAmC,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE5E,OAAO,EAAE,QAAQ,EAA6B,MAAM,aAAa,CAAC;AAGlE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAGtE;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,uFAAuF;IACvF,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GACxB,WAAW,GACX,QAAQ,GACR,iBAAiB,GACjB,qBAAqB,GACrB,cAAc,GACd,YAAY,CAAC;AAcjB,yEAAyE;AACzE,KAAK,iBAAiB,GAAG,cAAc,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAe1E;AAyED;;;;GAIG;AACH,qBACa,kBAAkB;IAQF,OAAO,CAAC,QAAQ,CAAC,MAAM;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAMvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAOS,OAAO,CAAC,QAAQ,CAAC,OAAO;IAvB5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IAEjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;gBAGQ,MAAM,EAAE,UAAU,EAC3C,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,uBAAuB,EACjC,MAAM,EAAE,aAAa,EAMrB,QAAQ,EAAE,kBAAkB,EAId,KAAK,CAAC,EAAE,QAAQ,EACf,IAAI,CAAC,EAAE,MAAM,MAAM,EAEA,OAAO,GAAE,WAA+B;IAM7F;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAI9C,eAAe;IA0B7B;;;;;;OAMG;IACG,cAAc,CAClB,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE,qBAAqB,GAC3B,OAAO,CAAC,gBAAgB,CAAC;IAI5B;;;;OAIG;IACH,OAAO,CAAC,QAAQ;YAWF,YAAY;IAyD1B;;;OAGG;YACW,iBAAiB;IAgI/B,0EAA0E;YAC5D,WAAW;IAqDzB;;;;;;;;;;;;;;OAcG;YACW,eAAe;IA4B7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4DG;YACW,kBAAkB;IAoEhC;;;;OAIG;YACW,IAAI;IAQlB;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IAsBjB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;CAKrB"}