@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.4

package/dist/jobs/job-handler.interface.js

@@ -0,0 +1,191 @@
+"use strict";
+// =============================================================================
+// Job handler contract (issue #259, epic #254)
+// =============================================================================
+//
+// THE EXTENSION POINT OF THE WHOLE QUEUE, and deliberately the smallest thing
+// that can be one. Epic #254's headline promise is that a fork adds a new
+// background job type with ONE class and no queue wiring: no migration (the
+// `jobs` table stores `type` as a plain string precisely so a new handler
+// costs zero schema change — see the `Job` model's own comment in
+// prisma/schema.prisma), no enum arm, no `switch` in a worker, no entry in a
+// central dispatch table. That promise is only true if the worker's entire
+// knowledge of a job type is "ask the registry for a handler with this
+// `type`, call `process`" — which is what the interface below is, and why it
+// has exactly two required members.
+//
+// The same argument `notification-events.ts` makes for notifications and
+// `object-processor.interface.ts` makes for post-upload processing, applied
+// to background work: the framework owns the mechanism, the feature owns one
+// class, and neither has to edit the other.
+//
+// -----------------------------------------------------------------------------
+// `process` THROWS TO FAIL — IT DOES NOT RETURN A RESULT OBJECT
+// -----------------------------------------------------------------------------
+//
+// `Promise<void>` and "throw to fail" rather than
+// `ObjectProcessor`-style `Promise<{ success, error }>`. The two contracts
+// look similar and are answering different questions, so the difference is
+// deliberate:
+//
+//   - An object processor is one of SEVERAL processors run in sequence over
+//     the same upload, and one failing must not abort the others. It needs to
+//     report a per-processor outcome that the pipeline aggregates into
+//     metadata, so a result object is right there.
+//   - A job handler IS the job. There is nothing to aggregate: the job either
+//     completed or it did not, and "did not" must be visible to the retry
+//     machinery (#263) as `attempts`, `lastError` and a `failed` status.
+//
+// A returned `{ success: false }` would have to be converted into a throw
+// somewhere anyway, and a handler that forgot to check an inner promise would
+// return `{ success: true }` for work that never happened. Throwing is the
+// default failure mode of every async call a handler makes — an unawaited-but-
+// awaited rejection, a database error, a fetch timeout — so "throw to fail"
+// means a handler gets correct failure behaviour by writing NO error handling
+// at all. Swallowing an error is then the visible, deliberate act (a
+// `try/catch` in the handler that does not rethrow), which is the right way
+// round: a job that silently reports success is far worse than one that
+// retries something it did not need to.
+//
+// The message on the thrown error is what lands in `Job.lastError`, so throw
+// something a human reading the admin job list can act on.
+//
+// -----------------------------------------------------------------------------
+// NODE ELIGIBILITY: THE OPTIONAL PAIR *IS* THE MECHANISM
+// -----------------------------------------------------------------------------
+//
+// Later in this epic, work can be computed on a remote worker node instead of
+// on the API server: the node receives a claimed job, does the expensive part
+// with no database access of its own, and POSTs a result back for the server
+// to persist. Not every job type can work that way — a handler that reads
+// three tables mid-computation, or that streams a file out of object storage,
+// or that writes as it goes, is server-only by nature.
+//
+// The system's ONE source of truth for that distinction is the presence of
+// the two optional members below:
+//
+//   - A handler carrying BOTH `nodeResultSchema` and `persistNodeResult` is
+//     NODE-ELIGIBLE: its work can be computed remotely (the schema is how the
+//     server validates the untrusted payload a node posts back) and its
+//     result can then be written down (that is what `persistNodeResult` does).
+//   - A handler carrying NEITHER is SERVER-ONLY. This is the default, and it
+//     is what every handler is until someone deliberately adds both members.
+//   - A handler carrying exactly ONE of the two is SERVER-ONLY, not a
+//     half-eligible special case. A schema with no persist function describes
+//     a payload nobody can store; a persist function with no schema would have
+//     to trust an unvalidated body from a remote machine. Neither is a state
+//     the node plane can safely act on, so both collapse to the safe answer.
+//     `JobHandlerRegistry.serverOnlyTypes()` derives exactly this, and it is
+//     what makes the later `system` worker mode ("run everything that CANNOT
+//     go to a node") possible with no second list to maintain.
+//
+// REJECTED: a `readonly nodeEligible: boolean` flag alongside the members.
+// A flag is a second statement of a fact the members already state, so it can
+// disagree with them — `nodeEligible: true` on a handler with no
+// `persistNodeResult` is a job dispatched to a node whose result the server
+// then cannot store, and the failure surfaces on a remote machine at runtime
+// rather than in review. Deriving eligibility from the members makes that
+// wrong state unrepresentable: there is nothing to set inconsistently. See
+// docs/specs/job-queue.md for the full argument.
+//
+// -----------------------------------------------------------------------------
+// `persistNodeResult` DOES THE PERSIST HALF AND NOTHING ELSE
+// -----------------------------------------------------------------------------
+//
+// This is a hard rule, not a style preference, and it is what keeps a remote
+// node from needing database access. The split is:
+//
+//     node   →  compute the result  (no DB, no secrets, no app tables)
+//     server →  validate it against `nodeResultSchema`, then
+//               `persistNodeResult` writes it down
+//
+// So `persistNodeResult` MUST NOT recompute the work, re-download the input,
+// call the provider again, or "fix up" a result it dislikes. It takes the
+// already-validated value and writes it. The moment it does any of the other
+// things, the node's computation stops being the source of the result — the
+// server is doing the work twice, the node's answer is decorative, and the
+// whole reason for the node plane (expensive work off the API server) is
+// gone. If a result cannot be persisted without recomputation, the type is
+// not node-eligible: drop both members and let it run server-side.
+//
+// The `result: unknown` parameter type is deliberate: `notify()`'s `data:
+// unknown` makes the same trade. The value arrives from off-machine, so it is
+// untrusted by construction, and `nodeResultSchema` is the only thing that
+// may narrow it. Parse, then use the parse's output type.
+//
+// -----------------------------------------------------------------------------
+// `deriveOutputKey` MOVES THE KEY CHOICE, IT DOES NOT SURRENDER IT (#348, epic #345)
+// -----------------------------------------------------------------------------
+//
+// `NodeDataPlaneService.createUploadTarget` used to hard-code where every
+// node-written output lands: `node-outputs/<jobId>/<uuid>`. That is exactly
+// right for a checksum's scratch output — nothing outside the job ever names
+// it — and exactly wrong for any type whose artifact has a REQUIRED,
+// EXTERNALLY-REFERENCED location. A database backup's key is
+// `buildBackupStorageKey(at, runId)` and its `database_backup_runs` row
+// records `storage_key`/`bucket`/`format` so the archive stays locatable
+// across a bucket rename; the same archive written to `node-outputs/…` is one
+// the retention sweep, the download endpoint and the restore path cannot
+// find. With one constant in the data plane, NO type whose output has a
+// required location could ever be node-eligible.
+//
+// ⚠ THE SERVER STILL CHOOSES THE KEY. This member moves that choice from a
+// constant in the data plane to the handler that OWNS the artifact — both of
+// which are this server. The node's influence stays exactly zero: a
+// caller-supplied `key` is still a 400 (`rejectCallerSuppliedFields`), the
+// chosen key is still returned so the node can name it back in its result,
+// and no `storage_objects` row is created at mint time. Nothing about the
+// data plane's posture changes; only who inside the server answers "where".
+//
+// The consequence for the data plane is that `SAFE_STORAGE_KEY` stops being
+// defensive code about a template it fully controls and becomes the real
+// guard on a value a handler computed — which is why a failure there is a
+// 500, not a 400: the fault is in a handler, not in anything a node sent.
+//
+// -----------------------------------------------------------------------------
+// `nodeSecretBroker` — PRESENCE IS THE DECLARATION, AGAIN (#349, epic #345)
+// -----------------------------------------------------------------------------
+//
+// The node plane's founding constraint is that a node holds NO credentials
+// (`docs/specs/worker-nodes.md` §1), which is why it could only ever run pure
+// compute over presigned bytes. Some work genuinely needs one — a `pg_dump`
+// needs a database connection — so a handler may carry a BROKER: an object
+// that mints a short-lived, job-scoped credential and can destroy it again.
+//
+// It follows the same rule as node eligibility above, and for the same reason.
+// The broker's PRESENCE is the declaration; there is no `requiresSecret:
+// 'postgres'` string and no central switch in the nodes module mapping such a
+// string onto an implementation. That switch is exactly the central dispatch
+// table this file exists to abolish, and it makes an inconsistent state
+// representable — a type naming a secret nobody can mint — which is the same
+// defect a `nodeEligible: boolean` flag has. Hanging the implementation itself
+// off the handler leaves nothing to set inconsistently.
+//
+// `job-secret-broker.ts` carries the full argument, including the three
+// rejected ways of getting a credential onto a node and why the material is
+// never persisted in any form.
+//
+// REJECTED: a `readonly keyPrefix: string` on the handler. It covers a prefix
+// and not the `buildBackupStorageKey(at, runId)` SHAPE, and — the part that
+// kills it — it cannot create the artifact row the key's `runId` comes from.
+// REJECTED: minting the key at claim time and shipping it in the assignment,
+// for the same reason the spec already rejects folding signed URLs into the
+// claim: a node claiming its whole `concurrency` at once would have the last
+// job's key derived long before that job starts.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOB_HANDLER = void 0;
+/**
+ * DI token for job handlers.
+ *
+ * Present for symmetry with `OBJECT_PROCESSOR` and
+ * `NOTIFICATION_CHANNEL_SENDERS`, and so a fork that prefers to collect
+ * handlers with a `multi`-style provider array has a token to collect them
+ * under. Note that the registration path this epic actually uses is
+ * SELF-REGISTRATION from each handler's own `OnModuleInit` — see
+ * `job-handler.registry.ts` for why, and `handlers/README.md` for the recipe.
+  *
+  * @stability experimental
+ */
+exports.JOB_HANDLER = Symbol('JOB_HANDLER');
+//# sourceMappingURL=job-handler.interface.js.map

package/dist/jobs/job-handler.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-handler.interface.js","sourceRoot":"","sources":["../../src/jobs/job-handler.interface.ts"],"names":[],"mappings":"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"}

package/dist/jobs/job-handler.registry.d.ts

@@ -0,0 +1,72 @@
+import { JobHandler } from './job-handler.interface';
+/**
+ * Every job type this process can run, by `type`: handlers register themselves from `onModuleInit`; a duplicate type warns and the last registration wins.
+ *
+ * @stability experimental
+ */
+export declare class JobHandlerRegistry {
+    private readonly logger;
+    private readonly handlers;
+    /**
+     * Adds `handler` under its own `type`, replacing any handler already
+     * registered under that type.
+     *
+     * OVERWRITE, LOUDLY — deliberately not "throw" and not "first one wins".
+     *
+     *   - Throwing would turn a duplicate into a boot failure for the entire
+     *     application. A fork that shadows a framework handler with its own
+     *     implementation of the same type is doing something legitimate (it is
+     *     how you replace framework behaviour without editing framework code),
+     *     and a template should not make that impossible.
+     *   - First-one-wins would make the override depend on module-resolution
+     *     order, which is exactly the kind of invisible coupling the explicit
+     *     registration above exists to avoid — and it would silently ignore the
+     *     handler the author most likely meant to win.
+     *
+     * So the LAST registration wins, and the collision is logged at `warn` so it
+     * is visible in logs whether it was intended or a copy-pasted `type` string
+     * two features apart. `warn` rather than `error`: an intentional override is
+     * not a fault.
+     *
+     * @param handler - the handler; its `type` is the key, its `label` (when
+     *   declared) the type's display label.
+     *
+     * @extensionPoint registry
+     * @stability stable
+     */
+    register(handler: JobHandler): void;
+    /**
+     * The handler for `type`, or `undefined` when nothing is registered.
+     *
+     * RETURNS `undefined` RATHER THAN THROWING, for the same reason
+     * `findEvent()` does in `notification-events.ts`: the caller is holding a
+     * string that came out of the database, and a `jobs` row can legitimately
+     * name a type this process cannot run — a handler that was removed, renamed,
+     * or (once the node plane exists) one that only some deployments register.
+     * The caller decides what an unknown type means; the registry does not
+     * decide it for them by throwing.
+     */
+    get(type: string): JobHandler | undefined;
+    /**
+     * Every registered type, in registration order.
+     *
+     * This is what the admin dashboard lists and what makes a fork's own job
+     * types appear there with no migration and no UI change (see
+     * `job-type-labels.ts` for how an unmapped type still renders).
+     */
+    types(): string[];
+    /**
+     * The registered types that CANNOT be computed on a remote worker node.
+     *
+     * DERIVED, never declared — see `job-handler.interface.ts`'s header for the
+     * full argument. A type is node-eligible only when its handler carries BOTH
+     * `nodeResultSchema` and `persistNodeResult`; anything else, including a
+     * handler carrying exactly one of the two, is server-only. There is no
+     * `nodeEligible` flag anywhere to disagree with this, and no second list of
+     * server-only types to keep in sync — which is what lets the later `system`
+     * worker mode ("claim only what a node could never run") be a single call
+     * to this method.
+     */
+    serverOnlyTypes(): string[];
+}
+//# sourceMappingURL=job-handler.registry.d.ts.map

package/dist/jobs/job-handler.registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-handler.registry.d.ts","sourceRoot":"","sources":["../../src/jobs/job-handler.registry.ts"],"names":[],"mappings":"AAkEA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD;;;;GAIG;AACH,qBACa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAgBnC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIzC;;;;;;OAMG;IACH,KAAK,IAAI,MAAM,EAAE;IAIjB;;;;;;;;;;;OAWG;IACH,eAAe,IAAI,MAAM,EAAE;CAe5B"}

package/dist/jobs/job-handler.registry.js

@@ -0,0 +1,174 @@
+"use strict";
+// =============================================================================
+// Job handler registry (issue #259, epic #254)
+// =============================================================================
+//
+// The one place that knows which job types this process can execute. The
+// worker (#262) holds a reference to this and nothing else: it claims a row,
+// reads `job.type`, calls `get(type)`, and calls `process`. It has no
+// `switch`, no import of any handler, and no reason to change when a handler
+// is added — which is the entire point of epic #254's "one class, no queue
+// wiring" promise.
+//
+// -----------------------------------------------------------------------------
+// EXPLICIT SELF-REGISTRATION, NOT DECORATOR DISCOVERY
+// -----------------------------------------------------------------------------
+//
+// Each handler calls `this.registry.register(this)` from its OWN
+// `OnModuleInit`. Nest can do better-looking things than this: a
+// `@JobHandler()` decorator plus `DiscoveryService` would let a handler
+// register merely by existing, with no lifecycle hook and no injected
+// registry.
+//
+// REJECTED, for the reason `notifications.module.ts` already states about its
+// channel factory ("a channel added by an import side effect is a channel
+// that appears in production without appearing in a diff"):
+//
+//   - It is more magic, not less code. `DiscoveryService` still needs a
+//     registry underneath to hold the scan's results; discovery replaces the
+//     `register` call with a metadata scan and keeps everything else.
+//   - It is harder to trace. "Why is this type running?" has a grep-able
+//     answer today — one `register(this)` line in one file. Under discovery
+//     the answer is "because a decorator you cannot see from here matched a
+//     scan at boot", and a handler that failed to register looks identical to
+//     one that never existed.
+//   - It disagrees with how this repository already does the same job in two
+//     other places: `NOTIFICATION_CHANNEL_SENDERS` is an explicit factory
+//     list, and the storage object processors are explicit `OBJECT_PROCESSOR`
+//     providers. A third mechanism for "collect the implementations of an
+//     interface" would be a third thing to learn.
+//
+// -----------------------------------------------------------------------------
+// ⚠ THE LIFECYCLE CONSEQUENCE THE WORKER (#262) MUST RESPECT
+// -----------------------------------------------------------------------------
+//
+// Because registration happens in each handler's `OnModuleInit`, THE WORKER
+// MUST START FROM `OnApplicationBootstrap`, NOT `OnModuleInit`.
+//
+// Nest runs every `onModuleInit` hook in one phase, in module-resolution
+// order, and only afterwards runs every `onApplicationBootstrap` hook. A
+// worker that started polling from `onModuleInit` would therefore be racing
+// the very registrations it depends on: whether `get(type)` finds a handler
+// would come down to which module Nest happened to initialise first. And the
+// failure is not a retryable blip — a claimed job whose type has no
+// registered handler is an "unknown job type" error, which is a PERMANENT
+// failure for a perfectly good job that would have run fine one second later.
+// Starting at `onApplicationBootstrap` makes the ordering a guarantee rather
+// than luck: every handler has registered before the first claim query runs.
+//
+// `job.worker.ts` satisfies this and says so from its side; the two headers
+// point at each other on purpose, because the file that creates a hazard and
+// the file that must respect it are the two places somebody will be reading
+// when they consider changing either. docs/specs/job-queue.md, "Registration",
+// is the third, and `job.worker.bootstrap.spec.ts` is the test that would fail.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var JobHandlerRegistry_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobHandlerRegistry = void 0;
+const common_1 = require("@nestjs/common");
+const job_type_label_1 = require("./job-type-label");
+/**
+ * Every job type this process can run, by `type`: handlers register themselves from `onModuleInit`; a duplicate type warns and the last registration wins.
+ *
+ * @stability experimental
+ */
+let JobHandlerRegistry = JobHandlerRegistry_1 = class JobHandlerRegistry {
+    logger = new common_1.Logger(JobHandlerRegistry_1.name);
+    handlers = new Map();
+    /**
+     * Adds `handler` under its own `type`, replacing any handler already
+     * registered under that type.
+     *
+     * OVERWRITE, LOUDLY — deliberately not "throw" and not "first one wins".
+     *
+     *   - Throwing would turn a duplicate into a boot failure for the entire
+     *     application. A fork that shadows a framework handler with its own
+     *     implementation of the same type is doing something legitimate (it is
+     *     how you replace framework behaviour without editing framework code),
+     *     and a template should not make that impossible.
+     *   - First-one-wins would make the override depend on module-resolution
+     *     order, which is exactly the kind of invisible coupling the explicit
+     *     registration above exists to avoid — and it would silently ignore the
+     *     handler the author most likely meant to win.
+     *
+     * So the LAST registration wins, and the collision is logged at `warn` so it
+     * is visible in logs whether it was intended or a copy-pasted `type` string
+     * two features apart. `warn` rather than `error`: an intentional override is
+     * not a fault.
+     *
+     * @param handler - the handler; its `type` is the key, its `label` (when
+     *   declared) the type's display label.
+     *
+     * @extensionPoint registry
+     * @stability stable
+     */
+    register(handler) {
+        const existing = this.handlers.get(handler.type);
+        if (existing) {
+            this.logger.warn(`Duplicate job handler for type "${handler.type}": ` +
+                `${existing.constructor.name} is being replaced by ` +
+                `${handler.constructor.name}. The last registration wins.`);
+        }
+        this.handlers.set(handler.type, handler);
+        // The handler's display label, if it declares one (#734; `jobTypeLabel`).
+        (0, job_type_label_1.recordHandlerLabel)(handler.type, handler.label);
+    }
+    /**
+     * The handler for `type`, or `undefined` when nothing is registered.
+     *
+     * RETURNS `undefined` RATHER THAN THROWING, for the same reason
+     * `findEvent()` does in `notification-events.ts`: the caller is holding a
+     * string that came out of the database, and a `jobs` row can legitimately
+     * name a type this process cannot run — a handler that was removed, renamed,
+     * or (once the node plane exists) one that only some deployments register.
+     * The caller decides what an unknown type means; the registry does not
+     * decide it for them by throwing.
+     */
+    get(type) {
+        return this.handlers.get(type);
+    }
+    /**
+     * Every registered type, in registration order.
+     *
+     * This is what the admin dashboard lists and what makes a fork's own job
+     * types appear there with no migration and no UI change (see
+     * `job-type-labels.ts` for how an unmapped type still renders).
+     */
+    types() {
+        return [...this.handlers.keys()];
+    }
+    /**
+     * The registered types that CANNOT be computed on a remote worker node.
+     *
+     * DERIVED, never declared — see `job-handler.interface.ts`'s header for the
+     * full argument. A type is node-eligible only when its handler carries BOTH
+     * `nodeResultSchema` and `persistNodeResult`; anything else, including a
+     * handler carrying exactly one of the two, is server-only. There is no
+     * `nodeEligible` flag anywhere to disagree with this, and no second list of
+     * server-only types to keep in sync — which is what lets the later `system`
+     * worker mode ("claim only what a node could never run") be a single call
+     * to this method.
+     */
+    serverOnlyTypes() {
+        return this.types().filter((type) => {
+            const handler = this.handlers.get(type);
+            if (!handler) {
+                return false;
+            }
+            const nodeEligible = handler.nodeResultSchema !== undefined &&
+                typeof handler.persistNodeResult === 'function';
+            return !nodeEligible;
+        });
+    }
+};
+exports.JobHandlerRegistry = JobHandlerRegistry;
+exports.JobHandlerRegistry = JobHandlerRegistry = JobHandlerRegistry_1 = __decorate([
+    (0, common_1.Injectable)()
+], JobHandlerRegistry);
+//# sourceMappingURL=job-handler.registry.js.map

package/dist/jobs/job-handler.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-handler.registry.js","sourceRoot":"","sources":["../../src/jobs/job-handler.registry.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,152 @@
+import { ConfigService } from '@nestjs/config';
+import { type JobsPrisma } from './data/jobs-db';
+import { JobClock } from './job-clock';
+import { JobInsightsQuery, JobInsightsResult } from './dto/job-insights.dto';
+/**
+ * The per-job duration assumed when NOTHING has ever succeeded.
+ *
+ * Reached only on the `basis: 'none'` branch, which is the response's own
+ * statement that this number is a placeholder and not a measurement — see
+ * `dto/job-insights.dto.ts`. Thirty seconds is chosen to be obviously
+ * order-of-magnitude ("a handful of minutes for a hundred jobs") rather than
+ * flatteringly small: an estimate that starts near zero and then grows as real
+ * samples arrive reads as the queue getting slower, which is the one wrong
+ * impression a first-run dashboard must not give.
+ *
+ * It is deliberately NOT configurable. A knob for the value used when there is
+ * no data is a knob whose correct setting is unknowable, and the honest fix
+ * for a bad `none` estimate is to run some jobs.
+ */
+export declare const FALLBACK_JOB_DURATION_MS = 30000;
+/**
+ * The `/api/admin/jobs/insights` numbers: live counts, windowed duration percentiles, lifetime totals and drain ETAs.
+ *
+ * @stability experimental
+ */
+export declare class JobInsightsService {
+    private readonly prisma;
+    private readonly config;
+    private readonly clock;
+    constructor(prisma: JobsPrisma, config: ConfigService, clock?: JobClock);
+    /**
+     * The whole insights response, from eight parallel `SELECT`s.
+     *
+     * `Promise.all` rather than eight awaits, for a correctness reason as much
+     * as a latency one: the queries are issued together, so the live counts, the
+     * window's percentiles and the lifetime totals describe very nearly the same
+     * instant. Serialised, the last query would run after the first by however
+     * long the middle six took, and on a busy queue the ETA would be computed
+     * from a backlog that had already moved — the same argument `stats()` makes
+     * for summing `total` out of its first aggregate rather than counting it
+     * separately.
+     *
+     * `windowDays` is CLAMPED here as well as bounded by the DTO. The pipe
+     * already rejects an out-of-range query parameter with a 400, so this is
+     * unreachable from HTTP — and that is exactly why it is here: the clamp
+     * belongs to the query's cost, not to one route's validation, and a future
+     * caller reaching this method from a task or a test must not be able to ask
+     * for an unbounded percentile sort.
+     */
+    insights(query: JobInsightsQuery): Promise<JobInsightsResult>;
+    /**
+     * Percentiles, mean, sample count and last-hour throughput over the window,
+     * per type AND overall, in ONE scan.
+     *
+     * `GROUP BY GROUPING SETS ((type), ())` is what makes it one scan rather
+     * than two queries, and the reason is correctness before performance: the
+     * grand total's p50 and p95 CANNOT be derived from the per-type rows (a
+     * percentile is a position in a sorted distribution, and merging sorted
+     * distributions needs the distributions), so the overall figures have to be
+     * their own aggregate. Computed here, they are aggregates over exactly the
+     * rows the per-type figures came from; asked for separately, they would be
+     * taken a moment later over a set that may have grown, and `overall.samples`
+     * would not equal the sum of `byType[].samples` — an inconsistency an
+     * operator checks precisely because it looks checkable.
+     *
+     * `PERCENTILE_CONT`, not `PERCENTILE_DISC`: the continuous form interpolates
+     * between the two bracketing samples, so a slowing job type moves p95
+     * smoothly instead of jumping between two observed durations, and a
+     * two-sample set has a meaningful median instead of an arbitrary one.
+     *
+     * Throughput rides along as a FILTERed count over the last hour rather than
+     * as a ninth query: the hour is always inside the window (the minimum window
+     * is a day), so those rows are already in this scan.
+     *
+     * Every count is cast `::int` at the database. `count(*)` is `bigint`, which
+     * Prisma hands back as a JS `bigint`, which `JSON.stringify` REFUSES to
+     * serialize — the response would not fail to be built, it would fail to be
+     * SENT, which is the same trap the schema's `sumDurationMs` comment warns
+     * about.
+     */
+    private windowedDurations;
+    /**
+     * The LIVE half of the lifetime average: sum and sample count per type over
+     * every succeeded, timed row still in the table.
+     *
+     * Unwindowed on purpose — "lifetime" — and bounded anyway by the retention
+     * the purge enforces, which is the arrangement that lets this be an
+     * index-only aggregate rather than an unbounded scan.
+     *
+     * `finished_at >= started_at` is the sample rule from `foldDeltas`, repeated
+     * so that the live half and the purged half define a duration sample
+     * identically. Without it a clock that stepped backwards would contribute a
+     * negative duration here and nothing at all to the rollup, so a type's
+     * lifetime average would CHANGE the next time a purge ran — a moving number
+     * with no event to explain it.
+     */
+    private lifetimeLiveDurations;
+    /**
+     * One estimate per type with outstanding work.
+     *
+     * `remaining = pending + running`, and `running` is included deliberately: a
+     * job being worked on right now is still work the operator is waiting for.
+     * It makes the estimate very slightly pessimistic (the running jobs are
+     * partway through, and nothing here knows how far), and pessimistic is the
+     * correct direction for a number a human is waiting on.
+     *
+     * The average is resolved in three steps, and `basis` records which one won
+     * — see `dto/job-insights.dto.ts` for why publishing the millisecond figure
+     * alone would be dishonest.
+     *
+     * The divisor is the CONFIGURED worker concurrency, floored at 1. A
+     * deployment running `JOBS_WORKER_CONCURRENCY=0` (or `JOBS_WORKER_MODE=off`)
+     * is not draining this queue at all, so the true ETA is infinite; publishing
+     * `Infinity` — which JSON renders as `null` — or a division by zero would
+     * both be worse than the honest approximation "as long as one worker would
+     * take", with the configured `concurrency` published alongside so a client
+     * can see that it is zero and say so.
+     *
+     * Types with nothing outstanding are OMITTED rather than listed with a zero
+     * estimate: this array is a to-do list, and a queue that has been running a
+     * while accumulates many types with no work in them.
+     */
+    private buildEta;
+    /**
+     * Clears `JobStatsRollup`, and nothing else.
+     *
+     * THE ONE WRITE IN THIS SERVICE, behind its own `jobs:write` route. It is
+     * here rather than in `JobAdminService` because the rollup is only ever
+     * READ by this file, and a "reset the numbers on this page" control that
+     * lived somewhere else would be a second opinion about which numbers the
+     * page shows.
+     *
+     * LIVE ROWS ARE UNTOUCHED, which is the whole safety argument: this deletes
+     * accumulators that summarise jobs that no longer exist, so the worst
+     * outcome is that lifetime totals restart from the rows still in the table.
+     * No job is deleted, no job's state changes, and every live-derived number
+     * in the response — `live`, `history`, `eta`, and the live half of
+     * `lifetime` — is identical before and after.
+     *
+     * It exists because a rollup is the one number in this API that a bad
+     * deployment can corrupt permanently and no other tool can correct: a fork
+     * that double counted during a botched migration, or a staging database
+     * seeded with fictional history, has an all-time average that is simply
+     * wrong forever, since the rows that would prove it wrong were deleted.
+     * Starting the accumulators again is the only available repair.
+     */
+    resetHistory(): Promise<{
+        /** Rollup rows deleted. */
+        reset: number;
+    }>;
+}
+//# sourceMappingURL=job-insights.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"job-insights.service.d.ts","sourceRoot":"","sources":["../../src/jobs/job-insights.service.ts"],"names":[],"mappings":"AAyKA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAIjD,OAAO,EAAa,QAAQ,EAAkB,MAAM,aAAa,CAAC;AAMlE,OAAO,EAGL,gBAAgB,EAChB,iBAAiB,EAGlB,MAAM,wBAAwB,CAAC;AAIhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAoD/C;;;;GAIG;AACH,qBACa,kBAAkB;IAEF,OAAO,CAAC,QAAQ,CAAC,MAAM;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACQ,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAFX,MAAM,EAAE,UAAU,EAC3C,MAAM,EAAE,aAAa,EACU,KAAK,GAAE,QAAyB;IAGlF;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuInE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,qBAAqB;IAa7B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,QAAQ;IA8ChB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,YAAY,IAAI,OAAO,CAAC;QAC5B,2BAA2B;QAC3B,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CAKH"}