@pattern-stack/codegen 0.22.0 → 0.23.0

package/dist/runtime/subsystems/jobs/job-worker.d.ts

@@ -1,3 +1,4 @@
+import * as drizzle_orm_node_postgres from 'drizzle-orm/node-postgres';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { OnModuleInit, OnModuleDestroy } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
@@ -6,7 +7,6 @@ import { JobRunRow } from './job-orchestration.schema.js';
 import { I as IJobOrchestrator, R as RetryPolicy } from '../../../job-orchestrator.protocol-ZuJ3ow-O.js';
 import { IJobRunService } from './job-run-service.protocol.js';
 import { IJobStepService } from './job-step-service.protocol.js';
-import 'drizzle-orm/node-postgres';
 import 'drizzle-orm';
 import '../events/event-bus.protocol.js';
 import '../events/event-registry.js';
@@ -26,10 +26,29 @@ interface JobWorkerOptions {
     /** Stale sweep interval in ms. Default 60_000. */
     staleSweeperIntervalMs?: number;
     /**
-     * Threshold beyond which a `running` row is presumed stranded by a
-     * crashed worker. Default 5 min. Must be >= 2× max handler duration.
+     * Threshold beyond which a `running` row whose `claimed_at` has NOT been
+     * renewed is presumed stranded by a crashed worker, and the sweeper resets
+     * it to `pending`. Default 5 min.
+     *
+     * With the claim heartbeat (CLAIM-HB-1) in place this is a *liveness*
+     * threshold — a live worker bumps `claimed_at` every
+     * `claimHeartbeatIntervalMs`, so a long-running-but-alive handler is NEVER
+     * swept; only a row whose worker died (process crash/SIGKILL, no clean
+     * shutdown reset) ages past the threshold. It therefore no longer needs to
+     * be `>= 2× max handler duration` — it just needs to exceed a few missed
+     * heartbeats (default leaves a 3× heartbeat margin).
      */
     staleThresholdMs?: number;
+    /**
+     * CLAIM-HB-1 — interval at which this worker bumps `claimed_at = now()` for
+     * every run it currently holds in flight (one batched UPDATE). This is the
+     * lease renewal that keeps a legitimately long-running handler from being
+     * swept by `sweepStaleClaims`. Default `staleThresholdMs / 3` so a row
+     * survives up to two missed renewals before the sweeper acts. MUST be
+     * comfortably less than `staleThresholdMs` or live runs will be re-queued
+     * mid-flight.
+     */
+    claimHeartbeatIntervalMs?: number;
     /** Max ms to wait for in-flight drain on SIGTERM. Default 30_000. */
     shutdownTimeoutMs?: number;
     /**
@@ -144,6 +163,550 @@ declare function buildStaleSweepQuery(db: DrizzleClient, staleThresholdMs: numbe
         generated: undefined;
     }, {}, {}>;
 }>, "where" | "for">;
+/**
+ * CLAIM-HB-1 — build the heartbeat renewal UPDATE. Bumps `claimed_at = now()`
+ * (and `updated_at`) for the given run IDs, but ONLY rows still `status =
+ * 'running'`: a row this worker thinks it owns may have been swept and
+ * reclaimed by another worker (now running elsewhere), or already moved to a
+ * terminal state — the status guard makes the renewal a safe no-op in both
+ * cases rather than resurrecting a lease the worker no longer holds. Exported so
+ * tests can inspect `.toSQL()` without a live DB.
+ */
+declare function buildClaimRenewQuery(db: DrizzleClient, runIds: string[], now?: Date): Omit<drizzle_orm_pg_core.PgUpdateBase<drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "job_run";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        jobType: drizzle_orm_pg_core.PgColumn<{
+            name: "job_type";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        jobVersion: drizzle_orm_pg_core.PgColumn<{
+            name: "job_version";
+            tableName: "job_run";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        parentRunId: drizzle_orm_pg_core.PgColumn<{
+            name: "parent_run_id";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        rootRunId: drizzle_orm_pg_core.PgColumn<{
+            name: "root_run_id";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        parentClosePolicy: drizzle_orm_pg_core.PgColumn<{
+            name: "parent_close_policy";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "terminate" | "cancel" | "abandon";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["terminate", "cancel", "abandon"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        scopeEntityType: drizzle_orm_pg_core.PgColumn<{
+            name: "scope_entity_type";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        scopeEntityId: drizzle_orm_pg_core.PgColumn<{
+            name: "scope_entity_id";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tenantId: drizzle_orm_pg_core.PgColumn<{
+            name: "tenant_id";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tags: drizzle_orm_pg_core.PgColumn<{
+            name: "tags";
+            tableName: "job_run";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, string>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, string>;
+        }>;
+        pool: drizzle_orm_pg_core.PgColumn<{
+            name: "pool";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        priority: drizzle_orm_pg_core.PgColumn<{
+            name: "priority";
+            tableName: "job_run";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        concurrencyKey: drizzle_orm_pg_core.PgColumn<{
+            name: "concurrency_key";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        dedupeKey: drizzle_orm_pg_core.PgColumn<{
+            name: "dedupe_key";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: drizzle_orm_pg_core.PgColumn<{
+            name: "status";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "pending" | "running" | "waiting" | "completed" | "failed" | "timed_out" | "canceled";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["pending", "running", "waiting", "completed", "failed", "timed_out", "canceled"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        input: drizzle_orm_pg_core.PgColumn<{
+            name: "input";
+            tableName: "job_run";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        output: drizzle_orm_pg_core.PgColumn<{
+            name: "output";
+            tableName: "job_run";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        error: drizzle_orm_pg_core.PgColumn<{
+            name: "error";
+            tableName: "job_run";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: {
+                message: string;
+                stack?: string;
+                retryable: boolean;
+                attempt: number;
+            };
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: {
+                message: string;
+                stack?: string;
+                retryable: boolean;
+                attempt: number;
+            };
+        }>;
+        triggerSource: drizzle_orm_pg_core.PgColumn<{
+            name: "trigger_source";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "manual" | "schedule" | "event" | "parent";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["manual", "schedule", "event", "parent"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        triggerRef: drizzle_orm_pg_core.PgColumn<{
+            name: "trigger_ref";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        runAt: drizzle_orm_pg_core.PgColumn<{
+            name: "run_at";
+            tableName: "job_run";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        startedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "started_at";
+            tableName: "job_run";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        finishedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "finished_at";
+            tableName: "job_run";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        claimedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "claimed_at";
+            tableName: "job_run";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attempts: drizzle_orm_pg_core.PgColumn<{
+            name: "attempts";
+            tableName: "job_run";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        waitKind: drizzle_orm_pg_core.PgColumn<{
+            name: "wait_kind";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "signal";
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["signal"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        resumeToken: drizzle_orm_pg_core.PgColumn<{
+            name: "resume_token";
+            tableName: "job_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        waitDeadline: drizzle_orm_pg_core.PgColumn<{
+            name: "wait_deadline";
+            tableName: "job_run";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "job_run";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "job_run";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>, drizzle_orm_node_postgres.NodePgQueryResultHKT, undefined, undefined, undefined, Record<"job_run", "not-null">, [], false, "where" | "leftJoin" | "rightJoin" | "innerJoin" | "fullJoin">, "where" | "leftJoin" | "rightJoin" | "innerJoin" | "fullJoin">;
 declare class JobWorker implements OnModuleInit, OnModuleDestroy {
     private readonly db;
     private readonly orchestrator;
@@ -154,13 +717,24 @@ declare class JobWorker implements OnModuleInit, OnModuleDestroy {
     private readonly logger;
     private shuttingDown;
     private readonly inFlight;
+    /**
+     * CLAIM-HB-1 — the set of run IDs this worker currently has executing. The
+     * heartbeat renews `claimed_at` for exactly these; a run is added when its
+     * `processRun` is dispatched and removed when its execution settles (success,
+     * failure, retry-release, or concurrency-defer). Kept separate from
+     * `inFlight` (which tracks the wrapper Promises for drain) because the
+     * heartbeat needs the IDs, not the promises.
+     */
+    private readonly inFlightRunIds;
     private pollTimer;
     private sweeperTimer;
+    private heartbeatTimer;
     private sigtermHandled;
     private readonly sigtermHandler;
     private readonly pollIntervalMs;
     private readonly staleSweeperIntervalMs;
     private readonly staleThresholdMs;
+    private readonly claimHeartbeatIntervalMs;
     private readonly shutdownTimeoutMs;
     private readonly listenNotifyEnabled;
     private notifyListener;
@@ -207,6 +781,20 @@ declare class JobWorker implements OnModuleInit, OnModuleDestroy {
      * then update) guarantees each stranded row is only reset once.
      */
     sweepStaleClaims(): Promise<void>;
+    /**
+     * Renew the claim lease on every run this worker currently has in flight by
+     * bumping `claimed_at = now()` in a single UPDATE. This is what keeps
+     * `sweepStaleClaims` from re-queueing a legitimately long-running handler:
+     * the sweeper only resets rows whose `claimed_at` has aged past the threshold,
+     * and a live worker keeps renewing. When the worker process dies, renewal
+     * stops, the row ages out, and the sweeper correctly recovers it — its
+     * documented "stranded by a crashed worker" intent.
+     *
+     * No-ops (no query) when nothing is in flight. The `status = 'running'` guard
+     * inside the UPDATE means a run that was swept-and-reclaimed elsewhere (or has
+     * already settled) is not touched.
+     */
+    renewClaims(): Promise<void>;
     private processRun;
     private markFailed;
     private makeStepFn;
@@ -221,4 +809,4 @@ declare class JobWorker implements OnModuleInit, OnModuleDestroy {
     private nextStepSeq;
 }
 
-export { JOB_WORKER_OPTIONS, JobWorker, type JobWorkerOptions, TERMINAL_STATUSES, buildClaimQuery, buildStaleSweepQuery, classifyError, computeBackoff };
+export { JOB_WORKER_OPTIONS, JobWorker, type JobWorkerOptions, TERMINAL_STATUSES, buildClaimQuery, buildClaimRenewQuery, buildStaleSweepQuery, classifyError, computeBackoff };

package/dist/runtime/subsystems/jobs/job-worker.js

@@ -3,10 +3,11 @@ import {
   JobWorker,
   TERMINAL_STATUSES,
   buildClaimQuery,
+  buildClaimRenewQuery,
   buildStaleSweepQuery,
   classifyError,
   computeBackoff
-} from "../../../chunk-VDL5CJ5C.js";
+} from "../../../chunk-7B7MMDOJ.js";
 import "../../../chunk-Q6LRJ4VI.js";
 import "../../../chunk-7P5ODGLA.js";
 import "../../../chunk-ZPL74UQN.js";
@@ -19,6 +20,7 @@ export {
   JobWorker,
   TERMINAL_STATUSES,
   buildClaimQuery,
+  buildClaimRenewQuery,
   buildStaleSweepQuery,
   classifyError,
   computeBackoff

package/dist/runtime/subsystems/jobs/job-worker.module.js

@@ -2,9 +2,9 @@ import {
   JOB_WORKER_MODULE_OPTIONS,
   JobWorkerModule,
   JobWorkerOrchestrator
-} from "../../../chunk-QXVCRA23.js";
-import "../../../chunk-VDL5CJ5C.js";
-import "../../../chunk-6DQEIXYU.js";
+} from "../../../chunk-SH76CFAY.js";
+import "../../../chunk-7B7MMDOJ.js";
+import "../../../chunk-FIUC6QB5.js";
 import "../../../chunk-VQOAATIG.js";
 import "../../../chunk-3VEVGL74.js";
 import "../../../chunk-CDLWYZVQ.js";