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

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

@@ -0,0 +1,46 @@
+/**
+ * What the queue is allowed to know about time.
+ *
+ * @stability experimental
+ */
+export interface JobClock {
+    /** Milliseconds since the epoch, exactly as `Date.now()` reports it. */
+    now(): number;
+    /**
+     * Resolves after (at least) `ms`.
+     *
+     * Implementations MUST NOT hold the process open — see `systemJobClock`
+     * for why the real one unrefs its timer.
+     */
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * DI token for `JobClock`.
+ *
+ * OPTIONAL everywhere it is injected: nothing provides it in
+ * `JobsModule`, so the application always runs on `systemJobClock` below and
+ * a fork cannot accidentally ship a stubbed clock. Tests construct the
+ * services directly and pass their own.
+  *
+  * @stability experimental
+ */
+export declare const JOB_CLOCK: unique symbol;
+/**
+ * The real clock: wall time, and a timer that CANNOT KEEP THE PROCESS ALIVE.
+ *
+ * `unref()` matters more than it looks. Both sleepers in this area are
+ * "waiting on something that has already gone wrong" — a provider that is
+ * throttling us for the next fifteen minutes, or a database that just refused
+ * a write. A pending 15-minute refed timer would hold a shutting-down worker
+ * open for fifteen minutes after the last request, turning a graceful deploy
+ * into an orchestrator kill. Unref'd, the wait simply never completes if
+ * nothing else is keeping the process alive, which is the correct outcome:
+ * there is nothing left to defer a job on behalf of.
+ *
+ * The `typeof` guard is for environments whose `setTimeout` returns a number
+ * rather than a Node `Timeout` (jsdom, and some fake-timer configurations).
+  *
+  * @stability experimental
+ */
+export declare const systemJobClock: JobClock;
+//# sourceMappingURL=job-clock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"job-clock.d.ts","sourceRoot":"","sources":["../../src/jobs/job-clock.ts"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,GAAG,IAAI,MAAM,CAAC;IAEd;;;;;OAKG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,eAAsB,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,EAAE,QAU5B,CAAC"}

package/dist/jobs/job-clock.js

@@ -0,0 +1,73 @@
+"use strict";
+// =============================================================================
+// The queue's injectable clock (issue #261, epic #254)
+// =============================================================================
+//
+// Two things in the terminal path are time: "what is now" (which decides the
+// `scheduled_for` a deferral writes, and whether a provider cooldown has
+// elapsed) and "wait a moment" (the cooperative throttle gate's hold, and
+// `safeTerminalUpdate`'s single retry pause). Both are behind this one tiny
+// interface so a test can drive them, because the alternative is tests that
+// prove nothing:
+//
+//   - A test that asserts a rate-limit deferral scheduled the job "about
+//     thirty seconds out" against a real `Date.now()` has to assert a RANGE,
+//     and a range assertion passes just as happily for an off-by-a-factor-of
+//     -sixty bug that lands inside it. With `now()` pinned, the expected
+//     `scheduled_for` is a single exact timestamp.
+//   - A test for "the gate makes a sibling job wait" against a real
+//     `setTimeout` either sleeps for the real cooldown (thirty seconds of
+//     wall clock per case, so nobody writes the case) or shrinks the cooldown
+//     until the test proves something other than the shipped behaviour.
+//
+// It is a plain object rather than a class so a test can pass an object
+// literal, and it is injected through an OPTIONAL Nest token so production
+// wiring stays "provide nothing and get the real clock" — no test double can
+// reach a running application by accident.
+//
+// The randomness the retry backoff needs is deliberately NOT here: it is a
+// parameter of `computeBackoffMs` instead (see `backoff.util.ts`), because a
+// pure function that takes its own RNG is testable without any injection at
+// all, and jitter is the one thing in this area that has nothing to do with
+// the passage of time.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemJobClock = exports.JOB_CLOCK = void 0;
+/**
+ * DI token for `JobClock`.
+ *
+ * OPTIONAL everywhere it is injected: nothing provides it in
+ * `JobsModule`, so the application always runs on `systemJobClock` below and
+ * a fork cannot accidentally ship a stubbed clock. Tests construct the
+ * services directly and pass their own.
+  *
+  * @stability experimental
+ */
+exports.JOB_CLOCK = Symbol('JOB_CLOCK');
+/**
+ * The real clock: wall time, and a timer that CANNOT KEEP THE PROCESS ALIVE.
+ *
+ * `unref()` matters more than it looks. Both sleepers in this area are
+ * "waiting on something that has already gone wrong" — a provider that is
+ * throttling us for the next fifteen minutes, or a database that just refused
+ * a write. A pending 15-minute refed timer would hold a shutting-down worker
+ * open for fifteen minutes after the last request, turning a graceful deploy
+ * into an orchestrator kill. Unref'd, the wait simply never completes if
+ * nothing else is keeping the process alive, which is the correct outcome:
+ * there is nothing left to defer a job on behalf of.
+ *
+ * The `typeof` guard is for environments whose `setTimeout` returns a number
+ * rather than a Node `Timeout` (jsdom, and some fake-timer configurations).
+  *
+  * @stability experimental
+ */
+exports.systemJobClock = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    }),
+};
+//# sourceMappingURL=job-clock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"job-clock.js","sourceRoot":"","sources":["../../src/jobs/job-clock.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,uDAAuD;AACvD,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,iBAAiB;AACjB,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,mDAAmD;AACnD,oEAAoE;AACpE,0EAA0E;AAC1E,8EAA8E;AAC9E,wEAAwE;AACxE,EAAE;AACF,wEAAwE;AACxE,2EAA2E;AAC3E,6EAA6E;AAC7E,2CAA2C;AAC3C,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAC5E,4EAA4E;AAC5E,uBAAuB;AACvB,gFAAgF;;;AAoBhF;;;;;;;;;GASG;AACU,QAAA,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,cAAc,GAAa;IACtC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IACrB,KAAK,EAAE,CAAC,EAAU,EAAE,EAAE,CACpB,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5B,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAEtC,IAAI,OAAQ,KAAgC,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACjE,KAA+B,CAAC,KAAK,EAAE,CAAC;QAC3C,CAAC;IACH,CAAC,CAAC;CACL,CAAC"}

package/dist/jobs/job-counts.util.d.ts

@@ -0,0 +1,44 @@
+import { JobStatusCounts } from './dto/job-stats.dto';
+/**
+ * A fresh, fully zero-filled status breakdown.
+ *
+ * EVERY KEY PRESENT, including the zeroes — see `dto/job-stats.dto.ts` for
+ * why: a `GROUP BY` returns no row for a status nothing is in, so the natural
+ * shape of a folded result is one where `failed` is simply absent on a healthy
+ * queue, and a client rendering `byStatus.failed` then shows `undefined`
+ * exactly when everything is fine.
+ */
+export declare function zeroCounts(): JobStatusCounts;
+/** The four counts added up. */
+export declare function sumCounts(counts: JobStatusCounts): number;
+/**
+ * The `_count._all` of a `groupBy` row, defensively.
+ *
+ * Prisma types `_count` as possibly absent because the shape depends on the
+ * argument object, which it cannot always narrow through a service boundary.
+ * A missing count must read as 0 rather than propagate `NaN` through a total.
+ */
+export declare function countOf(row: {
+    _count?: {
+        _all?: number;
+    } | null;
+}): number;
+/**
+ * Folds `groupBy({ by: ['type', 'status'] })` rows into one zero-filled
+ * breakdown per type.
+ *
+ * Returns a `Map` rather than an array so a caller can also LOOK A TYPE UP —
+ * which is what `JobInsightsService` needs for its ETA (`pending + running`
+ * for one type) and what an array would turn into a linear scan per type. The
+ * ordering decision (busiest first, alphabetical tie-break) is deliberately
+ * left to the caller, because `stats` and `insights` publish different rows
+ * from the same fold.
+ */
+export declare function foldTypeCounts(rows: Array<{
+    type: string;
+    status: string;
+    _count?: {
+        _all?: number;
+    } | null;
+}>): Map<string, JobStatusCounts>;
+//# sourceMappingURL=job-counts.util.d.ts.map

package/dist/jobs/job-counts.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-counts.util.d.ts","sourceRoot":"","sources":["../../src/jobs/job-counts.util.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,eAAe,CAE5C;AAED,gCAAgC;AAChC,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE;IAAE,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAAE,GAAG,MAAM,CAI1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAAE,CAAC,GAC/E,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAW9B"}

package/dist/jobs/job-counts.util.js

@@ -0,0 +1,76 @@
+"use strict";
+// =============================================================================
+// Folding a Prisma `groupBy` into a status breakdown (issues #264, #265)
+// =============================================================================
+//
+// Three tiny functions, extracted for one reason: TWO services now fold the
+// same `groupBy(['type', 'status'])` result into the same zero-filled shape.
+// `JobAdminService.stats()` (#264) wrote them first; `JobInsightsService`
+// (#265) needs byte-identical arithmetic, because its `live` block and the
+// dashboard's `stats` block are rendered on the same screen and an operator
+// comparing the two numbers is entitled to find them equal.
+//
+// A second copy would not stay identical. The interesting one is `countOf`:
+// Prisma types `_count` as possibly absent, so the obvious `row._count._all`
+// is a type error that a hurried second implementation "fixes" with a `!` or a
+// `?? 0` in the wrong place — and `NaN` propagating through a `total` renders
+// as "NaN jobs" on a dashboard, which is worse than any number it could have
+// shown. Written once, it is wrong once or not at all.
+//
+// Not a service: none of the three touches the database, injects anything, or
+// has state. They are arithmetic over a value a caller already has.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zeroCounts = zeroCounts;
+exports.sumCounts = sumCounts;
+exports.countOf = countOf;
+exports.foldTypeCounts = foldTypeCounts;
+const job_response_dto_1 = require("./dto/job-response.dto");
+/**
+ * A fresh, fully zero-filled status breakdown.
+ *
+ * EVERY KEY PRESENT, including the zeroes — see `dto/job-stats.dto.ts` for
+ * why: a `GROUP BY` returns no row for a status nothing is in, so the natural
+ * shape of a folded result is one where `failed` is simply absent on a healthy
+ * queue, and a client rendering `byStatus.failed` then shows `undefined`
+ * exactly when everything is fine.
+ */
+function zeroCounts() {
+    return { pending: 0, running: 0, succeeded: 0, failed: 0 };
+}
+/** The four counts added up. */
+function sumCounts(counts) {
+    return job_response_dto_1.JOB_STATUSES.reduce((sum, status) => sum + counts[status], 0);
+}
+/**
+ * The `_count._all` of a `groupBy` row, defensively.
+ *
+ * Prisma types `_count` as possibly absent because the shape depends on the
+ * argument object, which it cannot always narrow through a service boundary.
+ * A missing count must read as 0 rather than propagate `NaN` through a total.
+ */
+function countOf(row) {
+    const count = row._count?._all;
+    return typeof count === 'number' && Number.isFinite(count) ? count : 0;
+}
+/**
+ * Folds `groupBy({ by: ['type', 'status'] })` rows into one zero-filled
+ * breakdown per type.
+ *
+ * Returns a `Map` rather than an array so a caller can also LOOK A TYPE UP —
+ * which is what `JobInsightsService` needs for its ETA (`pending + running`
+ * for one type) and what an array would turn into a linear scan per type. The
+ * ordering decision (busiest first, alphabetical tie-break) is deliberately
+ * left to the caller, because `stats` and `insights` publish different rows
+ * from the same fold.
+ */
+function foldTypeCounts(rows) {
+    const perType = new Map();
+    for (const row of rows) {
+        const counts = perType.get(row.type) ?? zeroCounts();
+        counts[row.status] = countOf(row);
+        perType.set(row.type, counts);
+    }
+    return perType;
+}
+//# sourceMappingURL=job-counts.util.js.map

package/dist/jobs/job-counts.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-counts.util.js","sourceRoot":"","sources":["../../src/jobs/job-counts.util.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,yEAAyE;AACzE,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,0EAA0E;AAC1E,2EAA2E;AAC3E,4EAA4E;AAC5E,4DAA4D;AAC5D,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,uDAAuD;AACvD,EAAE;AACF,8EAA8E;AAC9E,oEAAoE;AACpE,gFAAgF;;AAchF,gCAEC;AAGD,8BAEC;AASD,0BAIC;AAaD,wCAaC;AA1DD,6DAAqE;AAGrE;;;;;;;;GAQG;AACH,SAAgB,UAAU;IACxB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,gCAAgC;AAChC,SAAgB,SAAS,CAAC,MAAuB;IAC/C,OAAO,+BAAY,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,OAAO,CAAC,GAA0C;IAChE,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;IAE/B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,cAAc,CAC5B,IAAgF;IAEhF,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAEnD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,UAAU,EAAE,CAAC;QAErD,MAAM,CAAC,GAAG,CAAC,MAAuB,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/jobs/job-execution-profile.d.ts

@@ -0,0 +1,185 @@
+import { ConfigService } from '@nestjs/config';
+import { JobHandler } from './job-handler.interface';
+import { JobHandlerRegistry } from './job-handler.registry';
+/**
+ * What a job type declares about how it is allowed to run.
+ *
+ * TWO NUMBERS, AND ONLY EVER TWO — see the file header for the full argument,
+ * and `JobHandler.profile` for the one-paragraph version a handler author will
+ * actually read. Do not add a lease, a renewal interval, or anything else that
+ * can disagree with `maxRuntimeMs`.
+  *
+  * @stability experimental
+ */
+export interface JobExecutionProfile {
+    /**
+     * Wall-clock ceiling for ONE attempt, in milliseconds.
+     *
+     * `0` means NO ceiling — the same meaning `JOBS_JOB_TIMEOUT_MS=0` already
+     * has, so a profile can express "this type may run as long as it needs"
+     * without the deployment having to disable timeouts for everything else.
+     * The claim's lease is derived from this number, never declared beside it.
+     */
+    readonly maxRuntimeMs: number;
+    /**
+     * Attempt budget for this type, counted the way `attempts` is counted:
+     * CHARGED AT CLAIM TIME (see `job-claim.service.ts`), so it means "attempts
+     * started", not "failures reported".
+     *
+     * `1` therefore means NEVER AUTOMATICALLY RETRIED — one claim, and whatever
+     * happens next is terminal. That is the reason this number is per-type at
+     * all: a job that mutates something irreversible must not be handed a second
+     * attempt by a deployment-wide default that knows nothing about it.
+     */
+    readonly maxAttempts: number;
+}
+/**
+ * Clears the warn-once latch above.
+ *
+ * FOR TESTS ONLY, exactly as `resetUnknownWorkerModeWarning` is: a latch that
+ * survived between cases would make "warns exactly once" pass for the first
+ * case and vacuously for every case after it. Nothing in the application calls
+ * this.
+  *
+  * @stability experimental
+ */
+export declare function resetJobProfileWarnings(): void;
+/**
+ * The profile `handler` declares, or `undefined` when it declares none — or
+ * declares one this process refuses to act on.
+ *
+ * THE SINGLE VALIDATION POINT. Every consumer of a profile goes through here,
+ * so "is this profile usable" is answered once and identically for the lease,
+ * the timeout and the attempt budget; three separate opinions about a
+ * half-valid profile is how a type ends up with a lease derived from a ceiling
+ * nothing else honours.
+ *
+ * `maxRuntimeMs` must be finite and non-negative (`0` is the legitimate "no
+ * ceiling" value, so the floor is zero, not one); `maxAttempts` must be finite
+ * and at least `1`, because a budget of zero describes a job that may never be
+ * claimed — which is not a retry policy, it is a way to delete work silently.
+ *
+ * Returns `undefined` rather than throwing, for the reason
+ * `JobHandlerRegistry.get` returns `undefined`: the caller is on a claim path
+ * with a job to run, and a fork's typo in a profile must degrade that job to
+ * the deployment defaults, not take the worker down.
+  *
+  * @stability experimental
+ */
+export declare function resolveJobProfile(handler: JobHandler | undefined): JobExecutionProfile | undefined;
+/**
+ * The attempt budget for whatever type `handler` handles: its own, or the
+ * deployment's.
+ *
+ * READ BY BOTH GIVE-UP PATHS, and it has to be, which is the point of it
+ * being a function rather than a field read at either. `JobTerminalService`
+ * decides retry-or-fail for a job that reported back; `JobStuckService`
+ * decides requeue-or-fail for a job whose executor died without reporting
+ * anything. If only the first learned about per-type budgets, a
+ * `maxAttempts: 1` job that the terminal path correctly refused to retry would
+ * be found by the reaper, judged against the global 3, and REQUEUED —
+ * resurrecting the exact automatic retry the profile exists to forbid, on the
+ * one path nobody is watching. Both call this.
+ *
+ * `handler` is `JobHandler | undefined` rather than a type string because both
+ * callers already hold the handler (or the registry lookup that produced
+ * `undefined` for a type this process cannot run), and an unknown type has no
+ * profile to consult — it takes the deployment default, which is what it took
+ * before profiles existed.
+  *
+  * @stability experimental
+ */
+export declare function resolveMaxAttempts(config: ConfigService, handler: JobHandler | undefined): number;
+/**
+ * How often a claimer should extend its lease, derived from the lease itself.
+ *
+ * DERIVED, NEVER DECLARED — the file header explains why a declared interval
+ * is the one number that can be wrong in a way nobody notices until a node
+ * starts losing jobs it is actively running. The clamp keeps both extremes
+ * survivable: a very short lease cannot produce a renewal storm, and a very
+ * long one cannot produce an interval that hides a dead node for an hour.
+ *
+ * Defensive against a nonsense lease for the same reason everything else here
+ * is: this is the divisor of a number that came out of a config read, and a
+ * `NaN` interval becomes a `setInterval(NaN)` firing every tick. An unusable
+ * lease degrades to the FLOOR rather than the ceiling — renewing too often
+ * costs a few requests, renewing too rarely loses the job.
+  *
+  * @stability experimental
+ */
+export declare function resolveRenewIntervalMs(leaseMs: number): number;
+/**
+ * How far into the future a lease may legitimately point, as a duration from
+ * "now": the LONGEST lease any registered handler could ask for, plus one
+ * grace.
+ *
+ * THIS IS THE REAPER'S FOURTH SIGNAL (#347), and it exists because the other
+ * three stopped covering a case they used to cover by accident. Until in-process
+ * renewal existed, `stuckRunningWhere`'s aged-claim clause reaped ANY row that
+ * had been `running` too long, lease or no lease — which caught a corrupt
+ * `lease_expires_at` for free, while also (this is the bug #347 fixes) reaping
+ * jobs that were running perfectly well. Narrowing that clause to unleased rows
+ * fixes the second problem and would silently drop the first: a lease pushed
+ * absurdly far out — a bug in a fork's own claim path, a clock jump on the
+ * writer, a hostile write — would then match NO signal at all and hold its
+ * dedup key forever.
+ *
+ * A lease further out than the longest lease ANY REGISTERED HANDLER COULD
+ * LEGITIMATELY ASK FOR is, by construction, not a live executor's promise.
+ * That is a fact this process can compute from what it already knows, without
+ * a new column, a new setting, or a per-row handler lookup inside the sweep.
+ *
+ * ⚠ THE DEPLOYMENT-WIDE LEASE IS ALWAYS IN THE MAXIMUM, even when the registry
+ * is empty. A `JOBS_WORKER_MODE=off` control plane may register no handlers at
+ * all and must still reap for its fleet; a `jobs` row may name a type this
+ * process does not register, and such a row was claimed on the global lease.
+ * Taking the max over registered handlers ALONE would give an empty registry a
+ * horizon of one grace period and reap every live row on the next sweep — the
+ * exact opposite of what this function is for.
+ *
+ * ⚠ THE TRADE-OFF, STATED HONESTLY: this ceiling MOVES WITH THE PROCESS
+ * READING IT. A deployment that removes a handler (or lowers its
+ * `maxRuntimeMs`, or lowers `JOBS_JOB_TIMEOUT_MS`) shortens the horizon, and
+ * in-flight rows of that type carrying the older, longer lease may be reaped
+ * on the next sweep. That is correct rather than merely acceptable: no process
+ * in that deployment can run those rows to completion any more, so requeueing
+ * them is the only outcome that is not "stuck until a human notices". It is
+ * also why the horizon is computed per sweep rather than cached — see
+ * `JobStuckService.leaseHorizon`.
+  *
+  * @stability experimental
+ */
+export declare function resolveLeaseHorizonMs(config: ConfigService, registry: JobHandlerRegistry): number;
+/**
+ * One job type's lease in a claim: the type and how long its claim is held.
+ *
+ * @stability experimental
+ */
+export interface ClaimLease {
+    /** The job type. */
+    type: string;
+    /** Its lease, in milliseconds, derived from the type's `maxRuntimeMs`. */
+    leaseMs: number;
+}
+/**
+ * One `{ type, leaseMs }` pair per eligible type, for `ClaimOptions.leases`.
+ *
+ * THE REASON `ClaimOptions` TAKES A LIST RATHER THAN A NUMBER. A claim is not
+ * necessarily homogeneous: the in-process worker offers every registered type
+ * and takes whichever row is most urgent, and a worker node claims up to its
+ * concurrency ACROSS SEVERAL TYPES IN ONE STATEMENT. With per-type ceilings
+ * those rows no longer share a lease, and a single batch-wide number would
+ * have to be either the shortest (reaping the long job mid-run) or the longest
+ * (leaving a dead executor's short job held for hours). Neither is a lease;
+ * both are a compromise the caller should not have to make.
+ *
+ * BOTH CLAIMERS CALL THIS, which is the same "one function, one number, both
+ * executors" rule `resolveJobLeaseMs` states for the scalar case. A node and
+ * the API server must derive the SAME lease for the same type, because the
+ * lease is not a private detail of a claimer — it is the contract the reaper
+ * reads to decide a claim is dead.
+  *
+  * @stability experimental
+ */
+export declare function buildClaimLeases(config: ConfigService, registry: JobHandlerRegistry, eligibleTypes: string[]): ClaimLease[];
+//# sourceMappingURL=job-execution-profile.d.ts.map

package/dist/jobs/job-execution-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-execution-profile.d.ts","sourceRoot":"","sources":["../../src/jobs/job-execution-profile.ts"],"names":[],"mappings":"AA8FA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG5D;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AA4CD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAiBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAuBlG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAQjG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAS9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,kBAAkB,GAC3B,MAAM,CAYR;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,kBAAkB,EAC5B,aAAa,EAAE,MAAM,EAAE,GACtB,UAAU,EAAE,CAKd"}