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

package/dist/nodes/nodes.options.js

@@ -0,0 +1,39 @@
+"use strict";
+// =============================================================================
+// `NodesModule.forRoot()` options (issue #734, PP-8.2)
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODES_OPTIONS = void 0;
+exports.resolveNodesModuleOptions = resolveNodesModuleOptions;
+/**
+ * Injection token of the {@link ResolvedNodesModuleOptions}. Optional to every
+ * consumer: a task built without `forRoot` (a unit test) reads the environment.
+ *
+ * @stability experimental
+ */
+exports.NODES_OPTIONS = Symbol.for('@marinoscar/platform/nodes/OPTIONS');
+/**
+ * Validates the options.
+ *
+ * @param options - the app's options.
+ * @returns the resolved, frozen options.
+ * @throws Error naming the field when an option is invalid.
+ *
+ * @stability experimental
+ */
+function resolveNodesModuleOptions(options = {}) {
+    const tasks = options.tasks ?? {};
+    for (const [key, value] of Object.entries(tasks)) {
+        if (!['staleOffline', 'offlinePrune', 'secretSweep'].includes(key)) {
+            throw new Error(`NodesModule.forRoot: tasks.${key} is not a node task.`);
+        }
+        if (value !== undefined && typeof value !== 'boolean') {
+            throw new Error(`NodesModule.forRoot: tasks.${key} must be a boolean, got ${JSON.stringify(value)}.`);
+        }
+    }
+    return Object.freeze({
+        tasks: Object.freeze({ ...tasks }),
+        imports: Object.freeze([...(options.imports ?? [])]),
+    });
+}
+//# sourceMappingURL=nodes.options.js.map

package/dist/nodes/nodes.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.options.js","sourceRoot":"","sources":["../../src/nodes/nodes.options.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,uDAAuD;AACvD,gFAAgF;;;AAsEhF,8DAcC;AApDD;;;;;GAKG;AACU,QAAA,aAAa,GAAkB,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;AAuB7F;;;;;;;;GAQG;AACH,SAAgB,yBAAyB,CAAC,UAA8B,EAAE;IACxE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;IAClC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC,CAAC,cAAc,EAAE,cAAc,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,sBAAsB,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,2BAA2B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxG,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;QAClC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;KACrD,CAAC,CAAC;AACL,CAAC"}

package/dist/nodes/nodes.permissions.d.ts

@@ -0,0 +1,29 @@
+import type { PermissionDeclaration } from '../core/index';
+/**
+ * One permission this slice declares: core's `PermissionDeclaration`, the
+ * entry type of the permission registry (`registerPermissions`).
+ *
+ * @typeParam Id - the permission string.
+ *
+ * @stability stable
+ */
+export type NodesPermissionDeclaration<Id extends string = string> = PermissionDeclaration<Id>;
+/**
+ * The nodes slice's permissions, keyed by the `PERMISSIONS` constant name the
+ * reference app derives from them. System scope, granted to `admin`. Register
+ * them with the app's permission registry.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(NODES_PERMISSIONS);
+ * ```
+ *
+ * @stability stable
+ */
+export declare const NODES_PERMISSIONS: {
+    /** `nodes:read`: view worker nodes and their health. */
+    readonly NODES_READ: NodesPermissionDeclaration<'nodes:read'>;
+    /** `nodes:write`: register, drain and remove worker nodes. */
+    readonly NODES_WRITE: NodesPermissionDeclaration<'nodes:write'>;
+};
+//# sourceMappingURL=nodes.permissions.d.ts.map

package/dist/nodes/nodes.permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.permissions.d.ts","sourceRoot":"","sources":["../../src/nodes/nodes.permissions.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,0BAA0B,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;AAK/F;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,EAAE;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC,YAAY,CAAC,CAAC;IAC9D,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC,aAAa,CAAC,CAAC;CAyBjE,CAAC"}

package/dist/nodes/nodes.permissions.js

@@ -0,0 +1,55 @@
+"use strict";
+// =============================================================================
+// Worker node permissions (issue #676, PP-1.4)
+// =============================================================================
+//
+// Pure data: this module's permissions and their default role grants. Imports
+// only types and has no side effect; the manifest slice (`registerPlatformPermissions()`)
+// registers it, and `common/constants/roles.constants.ts` derives `PERMISSIONS`
+// from it. After a change, run `npm run catalog:permissions --workspace=api` and
+// commit the regenerated `prisma/catalog/permissions.json`.
+// Recipe: common/permissions/README.md.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODES_PERMISSIONS = void 0;
+// Default grants: ADMIN ONLY, including the read half, for the reason given on
+// `JOBS_PERMISSIONS` in `jobs/jobs.permissions.ts` (#256, epic #254: the queue,
+// the fleet and the backup history are operational surfaces).
+/**
+ * The nodes slice's permissions, keyed by the `PERMISSIONS` constant name the
+ * reference app derives from them. System scope, granted to `admin`. Register
+ * them with the app's permission registry.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(NODES_PERMISSIONS);
+ * ```
+ *
+ * @stability stable
+ */
+exports.NODES_PERMISSIONS = {
+    // Worker nodes — the fleet that executes those jobs (#256, epic #254).
+    //
+    // DELIBERATELY SPLIT FROM `jobs:*`, not folded into it. The Settings UI
+    // Pattern (CLAUDE.md rule 3) requires a card's `permission` to be the exact
+    // string the API controller enforces, so a Workers card gated on `jobs:read`
+    // would be advertising a permission the nodes controller never checks — the
+    // hub would hide or show the card on evidence unrelated to whether the
+    // request behind it will be authorized. The two are also genuinely different
+    // questions: "what work is queued" is operational, "which machines are
+    // attached to this deployment" is closer to infrastructure inventory, and a
+    // deployment may well want to grant one without the other.
+    NODES_READ: {
+        id: 'nodes:read',
+        description: 'View worker nodes and their health',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+    NODES_WRITE: {
+        id: 'nodes:write',
+        description: 'Register, drain and remove worker nodes',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+};
+//# sourceMappingURL=nodes.permissions.js.map

package/dist/nodes/nodes.permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.permissions.js","sourceRoot":"","sources":["../../src/nodes/nodes.permissions.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,+CAA+C;AAC/C,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,0FAA0F;AAC1F,gFAAgF;AAChF,iFAAiF;AACjF,4DAA4D;AAC5D,wCAAwC;AACxC,gFAAgF;;;AAchF,+EAA+E;AAC/E,gFAAgF;AAChF,8DAA8D;AAC9D;;;;;;;;;;;GAWG;AACU,QAAA,iBAAiB,GAK1B;IACF,uEAAuE;IACvE,EAAE;IACF,wEAAwE;IACxE,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;IACvE,6EAA6E;IAC7E,uEAAuE;IACvE,4EAA4E;IAC5E,2DAA2D;IAC3D,UAAU,EAAE;QACV,EAAE,EAAE,YAAY;QAChB,WAAW,EAAE,oCAAoC;QACjD,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;IACD,WAAW,EAAE;QACX,EAAE,EAAE,aAAa;QACjB,WAAW,EAAE,yCAAyC;QACtD,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;CACF,CAAC"}

package/dist/nodes/nodes.service.d.ts

@@ -0,0 +1,482 @@
+import { ConfigService } from '@nestjs/config';
+import { type Job, type JobsPrisma, type WorkerNode } from '../jobs/index';
+import { JobClaimService } from '../jobs/index';
+import { JobHandlerRegistry } from '../jobs/index';
+import { NodeOffloadService } from '../jobs/index';
+import { JobLeaseService } from '../jobs/index';
+import { JobSettleOutcome, JobTerminalService } from '../jobs/index';
+import { ClaimJobsDto, HeartbeatNodeDto, NodeJobFailureDto, NodeJobResultDto, RegisterNodeDto } from './dto/node-control-plane.dto';
+import { NodeSettlementLedger } from './node-settlement-ledger';
+/**
+ * What `register` reports back: the row, and whether it already existed.
+ *
+ * @stability experimental
+ */
+export interface NodeRegistration {
+    /** The node row. */
+    node: WorkerNode;
+    /** `true` when the row already existed (same owner and name). */
+    reattached: boolean;
+}
+/**
+ * One node-eligible job type as `GET /nodes/job-types` publishes it.
+ *
+ * Declared here rather than imported from the DTO file so this service keeps
+ * describing what it KNOWS rather than what a controller happens to render —
+ * the same reason the mappers in `dto/node-response.dto.ts` are the only place
+ * a Prisma row becomes a wire shape.
+  *
+  * @stability experimental
+ */
+export interface NodeEligibleJobType {
+    /** The job type. */
+    type: string;
+    /** Its display label (`jobTypeLabel`). */
+    label: string;
+    /** JSON Schema for the result, or `null` when the schema cannot be published. */
+    resultSchema: Record<string, unknown> | null;
+}
+/**
+ * What a settled job reports back to the node that settled it.
+ *
+ * @stability experimental
+ */
+export interface NodeJobSettlement {
+    /** The settled job. */
+    jobId: string;
+    /**
+     * Never `claim-lost` (#477): that outcome is raised as the 409 a stale read
+     * would have produced, not reported as a settlement, so the wire enum in
+     * `node-response.dto.ts` is unchanged.
+     */
+    outcome: Exclude<JobSettleOutcome, 'claim-lost'>;
+    /**
+     * Whether the job will run again — THE SERVER'S ANSWER. A node may send
+     * `willRetry` on a failure; this is what the attempt budget actually
+     * decided, which is the only version of that question anybody should act
+     * on.
+     */
+    willRetry: boolean;
+}
+/**
+ * The node control plane: register, heartbeat, claim, renew, result and failure, each gated by node ownership and the held claim.
+ *
+ * @stability experimental
+ */
+export declare class NodesService {
+    private readonly prisma;
+    private readonly config;
+    private readonly claims;
+    private readonly terminal;
+    private readonly leases;
+    private readonly registry;
+    private readonly offload;
+    private readonly settlements;
+    private readonly logger;
+    constructor(prisma: JobsPrisma, config: ConfigService, claims: JobClaimService, terminal: JobTerminalService, leases: JobLeaseService, registry: JobHandlerRegistry, offload: NodeOffloadService, settlements?: NodeSettlementLedger);
+    /**
+     * Registers a node, or REATTACHES to the one this owner already has under
+     * this name.
+     *
+     * ⚠ IDEMPOTENT ON `(createdById, name)`, and that is the entire reason the
+     * composite unique index exists. Without it, every restart of a worker
+     * container — a deploy, an OOM kill, a host reboot, a `docker compose up`
+     * after an edit — leaks a new `worker_nodes` row. Within a week the fleet
+     * page is a list of ghosts, `GET /nodes` is unreadable, and the operator
+     * cannot tell which row is the machine currently doing work. Reattaching
+     * makes a restart a non-event: same row, same id, refreshed facts.
+     *
+     * FIND, THEN CREATE, THEN RECOVER FROM P2002. The find covers the ordinary
+     * restart. The `P2002` branch covers the case the find cannot: two API
+     * replicas (or two node processes racing on startup) both find nothing and
+     * both insert, and exactly one of them loses. Losing that race is not an
+     * error — the row it wanted now exists — so it re-reads and reattaches to
+     * it. REJECTED: a `$transaction` with `SERIALIZABLE` isolation to make the
+     * race impossible. It would serialise an endpoint every node in the fleet
+     * calls at startup in order to avoid an outcome that is already correct
+     * when it happens; the unique index is the guarantee, and this is just
+     * reading it.
+     *
+     * A FRESH HEARTBEAT WARNS BUT PROCEEDS. If the existing row heartbeated
+     * seconds ago, two processes may genuinely be claiming the same node
+     * identity — but the overwhelmingly common cause is a container that was
+     * killed and recreated before its last heartbeat aged out, which is exactly
+     * the case this endpoint exists to handle gracefully. Refusing would turn
+     * the NORMAL restart into a hard failure at startup, on a machine with
+     * nobody watching, and the operator's only recovery would be to wait or to
+     * invent a new name (leaking the row we just avoided leaking). So the
+     * documented policy is LAST-WRITER-WINS, with a log line naming both hosts
+     * so a genuine duplicate is visible to whoever goes looking.
+     */
+    register(userId: string, dto: RegisterNodeDto): Promise<NodeRegistration>;
+    /**
+     * Refreshes an existing row from a fresh registration.
+     *
+     * ⚠ `disabled` SURVIVES A REATTACH. Everything else about the row is
+     * overwritten by what the node just reported, and the status goes back to
+     * `online` — except when an operator has disabled this node, in which case
+     * the status is left exactly as it is. `disabled` is the kill switch: it is
+     * how an operator says "this machine must not take work", and a node that
+     * could clear it by restarting would make the switch defeatable with
+     * `docker restart` — by the very process being switched off. The claim
+     * endpoint refuses a disabled node, so preserving the status here is what
+     * makes that refusal permanent rather than one restart long.
+     *
+     * `draining` is NOT preserved, and the asymmetry is deliberate: draining
+     * means "finish what you are holding and take nothing new", which is a
+     * statement about the process that WAS running. A re-register is a new
+     * process that holds nothing, so there is nothing left to drain and keeping
+     * the flag would silently produce a node that heartbeats forever and never
+     * claims.
+     */
+    private reattach;
+    /**
+     * Marks a node offline on a graceful shutdown.
+     *
+     * ⚠ IT DOES NOT TOUCH THE JOBS THE NODE IS HOLDING, and that is the whole
+     * decision in this method. Requeueing them here is the obvious "helpful"
+     * addition and it is wrong: `deregister` is an HTTP call a node makes while
+     * shutting down, and nothing proves the work has actually stopped — a
+     * process handling SIGTERM may still be mid-write, and a node whose
+     * shutdown is interrupted may not stop at all. Requeueing on the node's
+     * say-so would hand a still-running job to a second executor and duplicate
+     * whatever it does.
+     *
+     * The component that is allowed to decide a claim is dead is the lease
+     * reaper (#263), and it decides it the only way that is safe: by the lease
+     * having expired. A deregistered node's jobs therefore come back one lease
+     * later, which is exactly what happens when a node crashes instead of
+     * shutting down politely — one path, tested once, with no way for a
+     * cooperative node to reach a state an uncooperative one cannot.
+     */
+    deregister(userId: string, nodeId: string): Promise<WorkerNode>;
+    /**
+     * Records liveness, and optionally refreshes what the node reports about
+     * itself.
+     *
+     * ⚠ A HEARTBEAT CANNOT CLEAR `disabled` OR `draining`. Those two are
+     * OPERATOR state (see `WorkerNode.status` in `schema.prisma`): a human or
+     * #270's lifecycle cron decided them, and they are decisions ABOUT the node
+     * rather than facts reported BY it. A node whose heartbeat could set
+     * `online` would walk out of its own kill switch on the next tick — five
+     * seconds after an operator disabled it, with the operator watching the
+     * fleet page show `online` and having no idea why. So the reported status
+     * is applied only when the current status is one the node owns.
+     *
+     * `concurrency` IS applied, and applying it here is the entire mechanism
+     * behind "a runtime `set-concurrency` takes effect on the next claim": the
+     * claim endpoint re-reads this row rather than caching anything, so a
+     * heartbeat is all it takes.
+     *
+     * `vitals` (#604), when present, replaces `lastVitals` wholesale and stamps
+     * `lastVitalsAt` with the same server clock as `lastHeartbeatAt`, in this
+     * one update. The row written is ALWAYS the path id after `assertOwnership`
+     * — nothing in the body can name a node, so a node cannot report vitals
+     * onto another node's row.
+     */
+    heartbeat(userId: string, nodeId: string, dto: HeartbeatNodeDto): Promise<WorkerNode>;
+    /** Every node this user registered. */
+    listNodes(userId: string): Promise<WorkerNode[]>;
+    /** One node, if it is this user's. */
+    getNode(userId: string, nodeId: string): Promise<WorkerNode>;
+    /**
+     * Takes up to the node's remaining capacity in runnable jobs, for the types
+     * the node can actually run.
+     *
+     * THREE FILTERS, APPLIED IN THIS ORDER, and each one exists because of a
+     * different way a fleet goes wrong:
+     *
+     *   1. WHAT THE NODE ASKED FOR, intersected with WHAT IT REGISTERED. A node
+     *      can only ever NARROW, never widen: the request says which of its own
+     *      types it currently has slots for, and anything it did not declare is
+     *      dropped rather than honoured. Otherwise a node's claim request — the
+     *      one input a compromised or misconfigured worker fully controls —
+     *      would be enough to pull job types it was never approved for, and
+     *      registration would stop meaning anything.
+     *   2. WHAT A NODE CAN ACTUALLY RUN AT ALL: the types whose handler carries
+     *      both `nodeResultSchema` and `persistNodeResult`. A node that claims a
+     *      server-only type will compute something this server cannot store —
+     *      its result post is refused as "not node-persistable", the row sits
+     *      until its lease expires, the reaper requeues it, and the node claims
+     *      it again. That is an infinite loop that burns an attempt per lap and
+     *      looks, from the queue's side, like a job that keeps failing for no
+     *      reason. Dropping the type here (with a warning naming it) makes the
+     *      misconfiguration visible instead of expensive. REJECTED: letting the
+     *      claim through and discovering it at result time, which is the same
+     *      information one full lease later.
+     *   3. THE CONCURRENCY CLAMP, read LIVE off the row. Never the value
+     *      captured at registration, so `set-concurrency` through a heartbeat
+     *      takes effect on the very next claim, and never the node's requested
+     *      limit if it is larger — a node asking for more than it declared is
+     *      describing slots it does not have.
+     *
+     * STATUS GATES BEFORE ANY OF THAT. `disabled` is 403: an operator has
+     * switched this node off, the answer will not change by polling, and the
+     * node should stop asking. `draining` is an EMPTY LIST rather than an
+     * error, because draining is a normal state with a normal instruction —
+     * "finish what you hold, take nothing new" — and a node that must keep
+     * heartbeating and keep renewing leases while it drains must not be taught
+     * that this endpoint is failing.
+     *
+     * `lastHeartbeatAt` IS NOT STAMPED HERE. Liveness has exactly one writer
+     * (`heartbeat`), so "when did we last hear from this node" stays a question
+     * about a column one route moves. A claim that also stamped it would let a
+     * node that polls but never heartbeats look healthy on the fleet page
+     * through a path that reports nothing about its health.
+     */
+    claimJobs(userId: string, nodeId: string, dto: ClaimJobsDto): Promise<Job[]>;
+    /**
+     * How often a node should renew the lease on a job of `type`, in
+     * milliseconds — the server's answer, derived from the very lease the claim
+     * granted.
+     *
+     * ⚠ THE SERVER DERIVES THIS, NOT THE NODE, for the same reason the server
+     * derives the lease itself (see `claimJobs`): the renewal cadence and the
+     * lease are one arithmetic relationship, and letting the two ends compute
+     * their halves independently is how a node ends up renewing every 30 seconds
+     * against a lease it was never told about — or, worse, less often than the
+     * lease it holds, losing jobs it is actively running while doing everything
+     * right. `resolveRenewIntervalMs` is the one derivation, and it is a third
+     * of the lease so two consecutive missed renewals still cost nothing.
+     *
+     * The practical case that made this worth a wire field (#347): a type
+     * declaring a six-hour `maxRuntimeMs` takes a six-hour lease, and the CLI's
+     * shipped `DEFAULT_LEASE_RENEW_MS` of 30 seconds would spend 720 round trips
+     * on it to no purpose whatsoever.
+     *
+     * ADDITIVE AND BACKWARD-COMPATIBLE on both ends: a node that ignores the
+     * field keeps its own cadence and stays correct, and this method is total —
+     * an unregistered type falls back through `resolveJobProfile`/
+     * `resolveJobLeaseMs` to the deployment-wide lease exactly as the claim
+     * would have.
+     */
+    renewIntervalMsFor(type: string): number;
+    /**
+     * Extends the lease on a job this node is still legitimately holding.
+     *
+     * ⚠ THE WRITE RE-ASSERTS THE GUARD IN ITS OWN `WHERE` CLAUSE rather than
+     * trusting the check that just passed. Between `assertJobHeldByNode`
+     * reading the row and this statement running, the reaper can requeue the
+     * job and another executor can claim it — the window is small and it is
+     * real, and a renewal that landed inside it would extend a lease belonging
+     * to somebody else, keeping the reaper away from a job the ORIGINAL node is
+     * no longer running. `updateMany` with the ownership conditions makes the
+     * check and the write the same statement; a zero count means the state
+     * moved, which is a 409 exactly as a stale read would have been.
+     *
+     * ⚠ THAT GUARD NOW LIVES IN `JobLeaseService.heldLeaseWhere` (#347), NOT
+     * HERE, and moving it there was the point of that issue rather than tidying.
+     * The in-process worker renews too now, and "a lease that has already
+     * expired may not be renewed, because another executor may own the row" is a
+     * claim about the queue's invariants, not about this endpoint. Written twice
+     * it drifts exactly once — somebody relaxes the expiry predicate on one side
+     * to stop a flaky node losing jobs, and from then on that side can resurrect
+     * a lease on a row the reaper has already given away. This is the same
+     * argument `resolveJobLeaseMs` makes about deriving the lease: one function,
+     * one rule, both executors.
+     *
+     * The 409 stays here, because it is the only part that is about HTTP: the
+     * shared service answers `false`, and only a caller who has a remote client
+     * waiting turns that into a status code.
+     */
+    renewLease(userId: string, nodeId: string, jobId: string, claimToken?: string): Promise<{
+        /** The job whose lease was renewed. */
+        jobId: string;
+        /** When the renewed lease runs out. */
+        leaseExpiresAt: Date;
+    }>;
+    /**
+     * Accepts a node-computed result, validates it, persists it, and settles
+     * the job.
+     *
+     * THE ORDER OF THE FIVE STEPS BELOW IS THE CONTRACT, and each step is a
+     * different untrusted claim being checked before anything irreversible
+     * happens. Nothing writes until the last two.
+     *
+     * WHY THE SCHEMA IS PARSED BY HAND HERE INSTEAD OF BY THE GLOBAL PIPE.
+     * `nestjs-zod`'s pipe validates against a schema known at decoration time;
+     * WHICH schema applies here is not known until the job row has been read
+     * and its handler resolved, because it is the handler's `nodeResultSchema`.
+     * There is no decorator that can express "the schema belonging to the type
+     * of the row named in the path", so the parse happens where the information
+     * exists — and its failure is converted into the same clean 400 the pipe
+     * would have produced, with the issue list in `details` (the exception
+     * filter rebuilds bodies from a fixed key allowlist, so a custom field has
+     * nowhere else to go).
+     *
+     * ⚠ A `persistNodeResult` THROW BECOMES A JOB FAILURE, NOT AN API ERROR
+     * THE NODE SHOULD RETRY. This is the subtlest decision in the file. Once
+     * the server has begun persisting, it — not the node — owns the row's
+     * lifecycle: the failure is routed through `completeFailed`, so it enters
+     * the ordinary retry machine (backoff, attempt budget, eventual `failed`
+     * with a readable `lastError`) exactly as an in-process handler's throw
+     * would. The node is then told 500, which means "this is ours, not yours".
+     * REJECTED: returning 4xx and letting the node resubmit. The job is no
+     * longer `running` by then — `completeFailed` has already moved it — so
+     * every resubmission would be refused by `assertJobHeldByNode` anyway, and
+     * a node retrying a persist failure would hammer the endpoint while the
+     * server's own retry was already scheduled. REJECTED equally: swallowing
+     * the throw and returning success, which would leave a job marked
+     * `succeeded` with nothing written.
+     *
+     * ⚠ THE ONE EXCEPTION IS A LOST CLAIM (#477). Every terminal write is
+     * guarded by the claim (`heldClaimWhere`), so if the row was reaped or
+     * re-claimed between step 1 and the settle, the settle writes nothing and
+     * answers `claim-lost`. On either path — the normal settle or the
+     * persist-failure one — that becomes the SAME 409 step 1 raises, because it
+     * is the same fact discovered a moment later, and a 500 claiming "settled by
+     * this server" would be false.
+     */
+    submitResult(userId: string, nodeId: string, jobId: string, dto: NodeJobResultDto): Promise<NodeJobSettlement>;
+    /**
+     * Records a failure a node reports for a job it is holding.
+     *
+     * A PASS-THROUGH BY DESIGN. The flags go straight into `completeFailed`,
+     * which treats `rateLimited` identically to a `RateLimitError` thrown by an
+     * in-process handler — down to tripping this server's own throttle gate, so
+     * a node's 429 backs off sibling jobs running here too. This service
+     * classifies nothing and decides nothing; see the file header on why both
+     * executors must reach their conclusions through the same code.
+     *
+     * `willRetry` ARRIVES AND IS IGNORED. The response tells the node what the
+     * server actually decided, which is the only version of that answer that
+     * governs anything.
+     */
+    reportFailure(userId: string, nodeId: string, jobId: string, dto: NodeJobFailureDto): Promise<NodeJobSettlement>;
+    /**
+     * Every job type a node could run, each with the JSON Schema its results
+     * must satisfy.
+     *
+     * THIS IS THE ONE PLACE THE RESULT CONTRACT CROSSES A PROCESS BOUNDARY, and
+     * it does so as DATA rather than as a shared build artefact. A client — the
+     * CLI is the first — validates a result before posting it, against the
+     * schema this server will actually enforce in `submitResult`, generated from
+     * the very same Zod object. There is no second definition to drift, no
+     * package to publish, and no way for a client on an older release to
+     * validate against a schema this server stopped using.
+     *
+     * REJECTED: a shared `packages/job-contracts` workspace exporting the Zod
+     * schemas to every app. `packages/shared/index.js` already documents, at
+     * length, why a compiled workspace package does not work in this
+     * repository: `apps/api` builds with `rootDir: ./src`, so importing
+     * TypeScript source from outside it widens the root and tsc starts emitting
+     * `dist/src/main.js`, which no longer matches `start:prod`'s
+     * `node dist/main` — a green build and a broken container. Its Jest config has no
+     * `moduleNameMapper` and the default `transformIgnorePatterns`, so a
+     * workspace symlink resolving to `.ts` would be untransformed and every API
+     * suite would die at import time. And CI runs `npm ci` straight into
+     * typecheck, so a package needing compilation would have to add a build step
+     * to several jobs. `packages/shared` escapes all of that by shipping
+     * committed `.js` plus a hand-written `.d.ts` — which is fine for a string
+     * constant and useless for a Zod schema, whose entire value is the runtime
+     * object.
+     *
+     * ⚠ `resultSchema` IS `null` RATHER THAN `{}` WHEN CONVERSION FAILS.
+     * `z.toJSONSchema` throws on a schema with no JSON Schema representation (a
+     * `z.custom()`, a `z.date()`, a transform), and the tempting rescue is to
+     * publish an empty schema. That would be a LIE in the most expensive
+     * direction: `{}` in JSON Schema means "anything is valid", so a client
+     * would confidently validate garbage and be refused by the server it just
+     * agreed with. `null` says "this one cannot be published — submit it and
+     * let the server answer", which is true and actionable. The type is still
+     * listed, because it is still claimable.
+     */
+    listNodeEligibleJobTypes(): Promise<NodeEligibleJobType[]>;
+    /**
+     * `handler.nodeResultSchema` as JSON Schema, or `null` if it cannot be one.
+     *
+     * `io: 'input'` because what is being published is what a client must SEND.
+     * The distinction is invisible for a plain object schema and real the moment
+     * a schema grows a default or a coercion, where the input shape and the
+     * parsed output shape stop agreeing — and publishing the output shape would
+     * tell a client to send a field the server actually supplies for it.
+     */
+    private toPublishableSchema;
+    /**
+     * The node exists AND belongs to this caller — 404 for the first, 403 for
+     * the second.
+     *
+     * ONE QUERY, and it RETURNS THE ROW. Both properties are deliberate: a
+     * caller that had to fetch the node again after the check could act on a
+     * different row than the one that was verified, and the second read would
+     * be a second chance to forget the check entirely.
+     *
+     * See the file header for why this deliberately distinguishes "missing"
+     * from "not yours" where `NodeCredentialService` deliberately does not.
+     */
+    assertOwnership(userId: string, nodeId: string): Promise<WorkerNode>;
+    /**
+     * The job is claimed by THIS node, is `running`, its lease has not expired,
+     * and — when the caller quotes one — it is still THIS CLAIM of it.
+     * Otherwise 409.
+     *
+     * THE CONDITIONS ARE ONE CONDITION, checked together and reported together.
+     * Splitting them into distinct errors would tell a remote caller which of
+     * "wrong node", "already finished" and "lease expired" applied, which is
+     * information about another executor's progress that a node has no use for
+     * and cannot act on differently — its correct response is the same in all
+     * three cases: drop the work.
+     *
+     * ⚠ `claimToken` JOINS THAT SAME 409 RATHER THAN RAISING ONE OF ITS OWN
+     * (#364), and the argument is the paragraph above, unchanged. "You are the
+     * right node but the wrong claim" is a fact about another slot's progress —
+     * a slot of this very node, which makes it no more actionable — and the
+     * correct response to it is identical: drop the work. A distinct error code
+     * would tempt a client to treat it as recoverable and re-fetch, which is the
+     * one thing it must not do.
+     *
+     * ⚠ OPTIONAL, AND ABSENT MEANS THE PRE-#364 CHECK, EXACTLY. A node running
+     * older CLI code does not know the token exists, so it omits it and is
+     * identified by `claimedByNodeId` alone — no 400, no 409, no warning that
+     * would break a fleet halfway through a rolling upgrade. Such a node stays
+     * self-ambiguous (its own stale slot can still speak for a newer claim) until
+     * it is upgraded; nothing this server can do closes that earlier, since the
+     * only thing that can tell those two slots apart is a value only they hold.
+     * Same additive posture as `renewIntervalMs` in #347.
+     *
+     * See the file header for the late-submission scenario this prevents, and
+     * for why the answer is 409 rather than 400.
+     */
+    assertJobHeldByNode(userId: string, nodeId: string, jobId: string, claimToken?: string): Promise<Job>;
+    /**
+     * The one 409 body, built in one place.
+     *
+     * Its call sites — the read guard, the renewal's re-assertion, and (#477)
+     * a settle whose guarded write found the claim gone — are answering the
+     * identical question, so a second hand-written message is a second chance
+     * for them to describe the same state differently.
+     *
+     * ⚠ IT STAYS DELIBERATELY UNSPECIFIC about which condition failed, including
+     * the claim-token one (#364). "Another executor may now own it" covers a
+     * second claim taken by THIS node as honestly as one taken by another
+     * machine, and the instruction the node has to act on — drop the work — is
+     * the same either way.
+     */
+    private notHeldByNode;
+    /** `(createdById, name)` — the register-or-reattach anchor. */
+    private findByName;
+    /**
+     * The registered types a node may claim in THIS deployment, right now.
+     *
+     * ⚠ DELEGATED, AND THE DELEGATION IS THE POINT (#352). This used to be
+     * derived here, and `JobWorker`'s `system` mode derived the OPPOSITE answer
+     * from `registry.serverOnlyTypes()` — two independent derivations of one
+     * question, which agreed only for as long as node eligibility was a purely
+     * static property of a handler. The moment a type's eligibility acquired
+     * runtime gates (a settings switch, a capability probe), the two answers
+     * diverged and `db.backup.run` fell into the gap: no node was allowed to
+     * claim it and the `system` worker no longer claimed it either, so on such a
+     * deployment NOBODY TOOK THE BACKUPS.
+     *
+     * `NodeOffloadService` is now the one function, and the two executors read
+     * it in opposite directions — this one takes the set, the worker takes its
+     * complement — so they partition the queue by construction. Its header
+     * carries the full argument, including why it lives in `jobs/` rather than
+     * here (the nodes module imports the jobs module; the reverse would be a
+     * cycle).
+     */
+    private nodeEligibleTypes;
+    /** Whether a settled outcome means the job is coming back. */
+    private willRetry;
+}
+//# sourceMappingURL=nodes.service.d.ts.map

package/dist/nodes/nodes.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.service.d.ts","sourceRoot":"","sources":["../../src/nodes/nodes.service.ts"],"names":[],"mappings":"AAsIA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,KAAK,GAAG,EAA2B,KAAK,UAAU,EAAc,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAMhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAYhE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB;IACpB,IAAI,EAAE,UAAU,CAAC;IACjB,iEAAiE;IACjE,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAoCD;;;;GAIG;AACH,qBACa,YAAY;IAII,OAAO,CAAC,QAAQ,CAAC,MAAM;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAIzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAOzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAQxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IA1B9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAGZ,MAAM,EAAE,UAAU,EAC3C,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,kBAAkB,EAI5B,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,kBAAkB,EAO5B,OAAO,EAAE,kBAAkB,EAQ3B,WAAW,GAAE,oBAAiD;IAOjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuD/E;;;;;;;;;;;;;;;;;;;OAmBG;YACW,QAAQ;IA4BtB;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAWrE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,SAAS,CACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,UAAU,CAAC;IAsCtB,uCAAuC;IACjC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAOtD,sCAAsC;IAChC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAiElF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAMxC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC;QACT,uCAAuC;QACvC,KAAK,EAAE,MAAM,CAAC;QACd,uCAAuC;QACvC,cAAc,EAAE,IAAI,CAAC;KACtB,CAAC;IA4CF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,iBAAiB,CAAC;IAmG7B;;;;;;;;;;;;;OAaG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,iBAAiB,CAAC;IAgC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,wBAAwB,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAUhE;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IAwB3B;;;;;;;;;;;OAWG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAsB1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,mBAAmB,CACvB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,GAAG,CAAC;IAkCf;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,aAAa;IAUrB,+DAA+D;IAC/D,OAAO,CAAC,UAAU;IAMlB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,iBAAiB;IAIzB,8DAA8D;IAC9D,OAAO,CAAC,SAAS;CAGlB"}