@pattern-stack/codegen 0.22.0 → 0.24.0

package/runtime/subsystems/events/generated/schemas.ts

@@ -39,6 +39,29 @@ export const dealStageChangedPayloadSchema = z.object({
 	oldStage: z.string(),
 }).strict();
 
+export const messageCreatedPayloadSchema = z.object({
+	changedFields: z.record(z.unknown()).nullable(),
+	entityId: z.string().uuid(),
+	externalId: z.string(),
+	provider: z.string(),
+	source: z.string(),
+}).strict();
+
+export const messageDeletedPayloadSchema = z.object({
+	entityId: z.string().uuid(),
+	externalId: z.string(),
+	provider: z.string(),
+	source: z.string(),
+}).strict();
+
+export const messageEditedPayloadSchema = z.object({
+	changedFields: z.record(z.unknown()).nullable(),
+	entityId: z.string().uuid(),
+	externalId: z.string(),
+	provider: z.string(),
+	source: z.string(),
+}).strict();
+
 export const stripePaymentReceivedPayloadSchema = z.object({
 	amountCents: z.number(),
 	currency: z.string(),
@@ -60,6 +83,9 @@ export const eventPayloadSchemas = {
 	'crm_sync_started': crmSyncStartedPayloadSchema,
 	'deal_created': dealCreatedPayloadSchema,
 	'deal_stage_changed': dealStageChangedPayloadSchema,
+	'message_created': messageCreatedPayloadSchema,
+	'message_deleted': messageDeletedPayloadSchema,
+	'message_edited': messageEditedPayloadSchema,
 	'stripe_payment_received': stripePaymentReceivedPayloadSchema,
 	'webhook_outbound_contact_sync': webhookOutboundContactSyncPayloadSchema,
 } as const satisfies Record<EventTypeName, z.ZodType>;

package/runtime/subsystems/events/generated/types.ts

@@ -64,6 +64,55 @@ export interface DealStageChangedEvent extends DomainEvent {
 	};
 }
 
+export interface MessageCreatedEvent extends DomainEvent {
+	readonly type: 'message_created';
+	readonly aggregateType: 'message';
+	readonly payload: {
+		/** Differ's per-field before/after map (same value as integration_run_items.changed_fields). */
+		changedFields: Record<string, unknown> | null;
+		/** Local aggregate id the sink wrote/soft-deleted. */
+		entityId: string;
+		/** Vendor external id the change keyed on. */
+		externalId: string;
+		/** Provider label (e.g. 'slack', 'google'). */
+		provider: string;
+		/** Provenance marker — always 'integration'. A write-back action reads this to avoid echoing the change back to the vendor. */
+		source: string;
+	};
+}
+
+export interface MessageDeletedEvent extends DomainEvent {
+	readonly type: 'message_deleted';
+	readonly aggregateType: 'message';
+	readonly payload: {
+		/** Local aggregate id the sink wrote/soft-deleted. */
+		entityId: string;
+		/** Vendor external id the change keyed on. */
+		externalId: string;
+		/** Provider label (e.g. 'slack', 'google'). */
+		provider: string;
+		/** Provenance marker — always 'integration'. A write-back action reads this to avoid echoing the change back to the vendor. */
+		source: string;
+	};
+}
+
+export interface MessageEditedEvent extends DomainEvent {
+	readonly type: 'message_edited';
+	readonly aggregateType: 'message';
+	readonly payload: {
+		/** Differ's per-field before/after map (same value as integration_run_items.changed_fields). */
+		changedFields: Record<string, unknown> | null;
+		/** Local aggregate id the sink wrote/soft-deleted. */
+		entityId: string;
+		/** Vendor external id the change keyed on. */
+		externalId: string;
+		/** Provider label (e.g. 'slack', 'google'). */
+		provider: string;
+		/** Provenance marker — always 'integration'. A write-back action reads this to avoid echoing the change back to the vendor. */
+		source: string;
+	};
+}
+
 /** Stripe charge.succeeded webhook, post-signature-verification. */
 export interface StripePaymentReceivedEvent extends DomainEvent {
 	readonly type: 'stripe_payment_received';
@@ -97,6 +146,9 @@ export type AppDomainEvent =
 	| CrmSyncStartedEvent
 	| DealCreatedEvent
 	| DealStageChangedEvent
+	| MessageCreatedEvent
+	| MessageDeletedEvent
+	| MessageEditedEvent
 	| StripePaymentReceivedEvent
 	| WebhookOutboundContactSyncEvent;
 

package/runtime/subsystems/index.ts

@@ -12,6 +12,17 @@ export { EVENT_BUS } from './events';
 // mode reaches it via `@shared/subsystems/events`; both must export it.
 export type { DomainEvent, IEventBus, DrizzleTransaction } from './events';
 export { EventsModule, DrizzleEventBus, MemoryEventBus } from './events';
+// The `TYPED_EVENT_BUS` token is re-exported here so package-mode generated code
+// that publishes events from the single `@pattern-stack/codegen/subsystems`
+// barrel resolves it — notably the EMIT-CHANGES integration change-emitter
+// (`<entity>.change-emitter.ts`), which injects `TYPED_EVENT_BUS`. The emitter
+// types the bus with a local structural `publish` shape (NOT the package's
+// `TypedEventBus`, whose `EventTypeName` union is the package's own events — the
+// consumer's `<entity>_*` events live in the CONSUMER registry), so only the
+// token needs forwarding. The CONSUMER binds their generated `TypedEventBus` to
+// the token via `EventsModule.forRoot()`. Vendored mode reaches it via
+// `@shared/subsystems/events`.
+export { TYPED_EVENT_BUS } from './events';
 
 // Jobs — orchestration schema only (JOB-1). Protocols / modules land in JOB-2 / JOB-5.
 export { jobs, jobRuns, jobSteps } from './jobs';
@@ -131,6 +142,18 @@ export {
 } from './integration';
 export type { IIntegrationSink } from './integration';
 
+// Integration — EMIT-CHANGES seam. The generated per-entity change-emitter
+// (`<entity>.change-emitter.ts`) imports the `INTEGRATION_CHANGE_EMITTER` token
+// + the `IIntegrationChangeEmitter` port + `IntegrationChangeNotification` from
+// `@pattern-stack/codegen/subsystems`. Forwarded here so the emitted opt-in
+// emitter resolves them across the package boundary (package mode).
+export { INTEGRATION_CHANGE_EMITTER } from './integration';
+export type {
+  IIntegrationChangeEmitter,
+  IntegrationChangeAction,
+  IntegrationChangeNotification,
+} from './integration';
+
 // Auth
 export {
   ENCRYPTION_KEY,

package/runtime/subsystems/integration/execute-integration.use-case.ts

@@ -50,8 +50,13 @@ import type { ICursorStore } from './integration-cursor-store.protocol';
 import type { IFieldDiffer, FieldDiff } from './integration-field-diff.protocol';
 import type { IIntegrationSink } from './integration-sink.protocol';
 import type { IIntegrationRunRecorder } from './integration-run-recorder.protocol';
+import type {
+  IIntegrationChangeEmitter,
+  IntegrationChangeAction,
+} from './integration-change-emitter.protocol';
 import { assertTenantId } from './integration-errors';
 import {
+  INTEGRATION_CHANGE_EMITTER,
   INTEGRATION_CHANGE_SOURCE,
   INTEGRATION_CURSOR_STORE,
   INTEGRATION_FIELD_DIFFER,
@@ -118,6 +123,13 @@ export class ExecuteIntegrationUseCase<T extends Record<string, unknown>> {
     @Optional()
     @Inject(INTEGRATION_MULTI_TENANT)
     private readonly multiTenant: boolean = false,
+    // EMIT-CHANGES seam — optional post-upsert domain-event emitter. Bound only
+    // by codegen-emitted assemblies whose entity opts into
+    // `integration.sink.emit_changes: true`. Unbound (the default) ⇒ no events
+    // published, zero behavior change.
+    @Optional()
+    @Inject(INTEGRATION_CHANGE_EMITTER)
+    private readonly emitter: IIntegrationChangeEmitter | null = null,
   ) {}
 
   async execute(input: ExecuteIntegrationInput<T>): Promise<ExecuteIntegrationResult> {
@@ -263,6 +275,12 @@ export class ExecuteIntegrationUseCase<T extends Record<string, unknown>> {
         changedFields: {},
         tenantId: input.tenantId,
       });
+      // EMIT-CHANGES: a real tombstone (a local row existed and was soft-deleted)
+      // is a `<entity>_deleted` event. A delete that hit no local row is a noop —
+      // nothing changed, nothing to emit.
+      if (result) {
+        await this.emitChange(input, change.externalId, result.id, 'deleted');
+      }
       return;
     }
 
@@ -321,15 +339,65 @@ export class ExecuteIntegrationUseCase<T extends Record<string, unknown>> {
       input.provider,
     );
 
+    const action: IntegrationChangeAction =
+      existing === null ? 'created' : 'updated';
+
     await this.recorder.recordItem({
       integrationRunId: runId,
       entityType: input.subscription.domain,
       externalId: change.externalId,
       localId,
-      operation: existing === null ? 'created' : 'updated',
+      operation: action,
       status: 'success',
       changedFields: diff as FieldDiff,
       tenantId: input.tenantId,
     });
+
+    // EMIT-CHANGES: a real create/update (the diff was NOT noop) publishes a
+    // typed `<entity>_created` / `<entity>_edited` event. The noop-reproject path
+    // above intentionally does NOT emit — the canonical state is unchanged.
+    await this.emitChange(
+      input,
+      change.externalId,
+      localId,
+      action,
+      diff as FieldDiff,
+    );
+  }
+
+  /**
+   * Publish one typed data-level change event via the optional emitter
+   * (EMIT-CHANGES seam). No-op when no emitter is bound (the back-compat
+   * default). A failed publish is logged but never aborts the run — the row is
+   * already written; emission is best-effort (the outbox tx, when the generated
+   * adapter rides on one, gives the at-least-once guarantee, not this try/catch).
+   */
+  private async emitChange(
+    input: ExecuteIntegrationInput<T>,
+    externalId: string,
+    entityId: string,
+    action: IntegrationChangeAction,
+    changedFields?: FieldDiff,
+  ): Promise<void> {
+    if (this.emitter === null) return;
+    try {
+      await this.emitter.emitChange({
+        entityId,
+        externalId,
+        provider: input.provider,
+        action,
+        changedFields:
+          action === 'deleted'
+            ? undefined
+            : (changedFields as Record<string, unknown> | undefined),
+        tenantId: input.tenantId,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.logger.warn(
+        `integration change-emit failed: subscription=${input.subscription.id} ` +
+          `externalId=${externalId} action=${action}: ${message}`,
+      );
+    }
   }
 }

package/runtime/subsystems/integration/index.ts

@@ -35,6 +35,11 @@ export {
   FieldDiffValueSchema,
 } from './integration-field-diff.protocol';
 export type { IIntegrationSink } from './integration-sink.protocol';
+export type {
+  IIntegrationChangeEmitter,
+  IntegrationChangeAction,
+  IntegrationChangeNotification,
+} from './integration-change-emitter.protocol';
 export type {
   CompleteRunInput,
   IIntegrationRunRecorder,
@@ -125,6 +130,7 @@ export { buildChangeSource } from './build-change-source';
 // Tokens
 export {
   ENTITY_CHANGE_SOURCE_REGISTRY,
+  INTEGRATION_CHANGE_EMITTER,
   INTEGRATION_CHANGE_SOURCE,
   INTEGRATION_CURSOR_STORE,
   INTEGRATION_FIELD_DIFFER,

package/runtime/subsystems/integration/integration-change-emitter.protocol.ts

@@ -0,0 +1,107 @@
+/**
+ * Integration subsystem — change-emitter protocol (port).
+ *
+ * `IIntegrationChangeEmitter` is the OPT-IN seam through which the generic
+ * orchestrator (`ExecuteIntegrationUseCase`) publishes a typed, data-level
+ * domain event after every sink write/soft-delete. It is the upstream-generalized
+ * form of the per-sink event emission swe-brain hand-built (ADR-0009 Amendment B):
+ * the differ already records `changed_fields` on `integration_run_items`, but
+ * nothing publishes a "this entity changed" domain event for downstream
+ * trigger→action consumers. This port closes that gap.
+ *
+ * ## Why a port (not a direct TypedEventBus call in the orchestrator)
+ *
+ * The orchestrator is strictly provider- AND entity-agnostic: `entityType` is a
+ * bare `string` and the canonical record is generic `T` (see the use-case header
+ * "No CRM bleed"). It therefore cannot know the typed event NAME
+ * (`<entity>_created`) or the typed payload shape at compile time. The typed
+ * knowledge lives at the per-entity assembly wiring (codegen knows the entity
+ * name there). So the orchestrator depends on this thin, untyped port; codegen
+ * binds a per-entity adapter that maps `(operation) → <entity>_<verb>` and calls
+ * the project's generated `TypedEventBus.publish(...)` with the typed payload.
+ *
+ * ## Backwards compatibility
+ *
+ * The port is `@Optional()` on the orchestrator. Entities that do NOT opt in
+ * (`integration.sink.emit_changes` absent/false) bind no emitter, so the
+ * orchestrator's `this.emitter` is `undefined` and NOTHING is published — zero
+ * behavior change. This is the invariant the snapshot fixture (which opts none
+ * in) keeps green.
+ *
+ * ## Provenance — loop-breaking
+ *
+ * Every emitted event carries `source: 'integration'` in its payload. A future
+ * write-back action (the Intervention layer in swe-brain terms) that subscribes
+ * to these events can detect `source === 'integration'` and decline to echo the
+ * change back to the vendor, breaking the inbound→writeback→inbound loop. This
+ * is the data-layer counterpart of the loopback middleware that already guards
+ * the read side (`createLoopbackMiddleware`).
+ *
+ * ## Transactionality
+ *
+ * `emitChange` receives the same `tx` the sink wrote under (when the sink exposes
+ * one — today the sink owns its own transaction internally, so `tx` is reserved
+ * for the future where the orchestrator drives the transaction). The generated
+ * adapter forwards `tx` into `TypedEventBus.publish(type, id, payload, { tx })`,
+ * so the event lands in the outbox iff the row commits (the events subsystem's
+ * outbox guarantee). When `tx` is absent the publish is post-commit best-effort,
+ * matching today's sink-owns-its-own-transaction reality.
+ */
+
+/** The data-level action the orchestrator observed. Maps onto the generated
+ *  event verb: `created → <entity>_created`, `updated → <entity>_edited`
+ *  (per swe-brain ADR-0009 B1 — `_edited`, never `_updated`),
+ *  `deleted → <entity>_deleted` (tombstone soft-delete). `noop` never emits. */
+export type IntegrationChangeAction = 'created' | 'updated' | 'deleted';
+
+/**
+ * The vendor-blind change descriptor the orchestrator hands the emitter. The
+ * generated adapter reshapes this into the typed `<entity>_<verb>` payload
+ * (`{ entityId, externalId, provider, changedFields?, source: 'integration' }`).
+ */
+export interface IntegrationChangeNotification {
+  /** The local row id the sink wrote/soft-deleted (the domain aggregate id —
+   *  becomes `aggregateId` on the published event AND `entityId` in the payload). */
+  readonly entityId: string;
+  /** Vendor-prefixed-or-bare external id the change keyed on (e.g. `slack:123`). */
+  readonly externalId: string;
+  /** Provider label from `ExecuteIntegrationInput.provider` (e.g. `'slack'`). */
+  readonly provider: string;
+  /** The observed action. `created`/`updated` come from the existing-row check;
+   *  `deleted` from the soft-delete path. */
+  readonly action: IntegrationChangeAction;
+  /** The differ's structured per-field before/after map (the same value written
+   *  to `integration_run_items.changed_fields`). Absent on deletes. */
+  readonly changedFields?: Record<string, unknown>;
+  /** Multi-tenant deployments thread the tenant id through to the event metadata. */
+  readonly tenantId?: string | null;
+  /** The transaction the sink wrote under, when the orchestrator drives one.
+   *  Forwarded to `TypedEventBus.publish(..., { tx })` for the outbox guarantee.
+   *  Reserved: today the sink owns its own transaction, so this is usually
+   *  `undefined` and the publish is post-commit. Typed `unknown` here so the
+   *  port stays free of a Drizzle type dependency (the generated adapter narrows). */
+  readonly tx?: unknown;
+}
+
+/**
+ * Post-upsert change-event emission port.
+ *
+ * One implementation per opted-in (entity, provider) assembly — codegen-emitted,
+ * bound to `INTEGRATION_CHANGE_EMITTER` in that assembly module. The orchestrator
+ * injects it `@Optional()`; an unbound token means no emission (back-compat).
+ */
+export interface IIntegrationChangeEmitter {
+  /**
+   * Publish the typed `<entity>_<verb>` domain event for one observed change.
+   *
+   * MUST be called only for real changes — the orchestrator never calls this on
+   * a `noop` diff (canonical state unchanged) or a delete that hit no local row
+   * (no tombstone created). Implementations should treat a call as "this thing
+   * happened" and publish unconditionally.
+   *
+   * Errors are the orchestrator's concern: it wraps the call so a failed publish
+   * does not abort the run (the row is already written; emission is best-effort
+   * unless ridden on the outbox tx). See `ExecuteIntegrationUseCase.processChange`.
+   */
+  emitChange(notification: IntegrationChangeNotification): Promise<void>;
+}

package/runtime/subsystems/integration/integration.tokens.ts

@@ -25,6 +25,17 @@ export const INTEGRATION_CURSOR_STORE = 'INTEGRATION_CURSOR_STORE' as const;
 export const INTEGRATION_FIELD_DIFFER = 'INTEGRATION_FIELD_DIFFER' as const;
 export const INTEGRATION_SINK = 'INTEGRATION_SINK' as const;
 
+/**
+ * Optional post-upsert change-event emitter token (EMIT-CHANGES seam).
+ *
+ * Backed by `IIntegrationChangeEmitter`. Bound ONLY by codegen-emitted assembly
+ * modules whose entity opts in via `integration.sink.emit_changes: true`. The
+ * orchestrator injects it `@Optional()` — an unbound token means no domain
+ * events are published (the back-compat default for non-opted-in entities).
+ * See `integration-change-emitter.protocol.ts`.
+ */
+export const INTEGRATION_CHANGE_EMITTER = 'INTEGRATION_CHANGE_EMITTER' as const;
+
 /**
  * Run-recorder token (SYNC-5). Backed by `IIntegrationRunRecorder`. Drizzle impl
  * lands in SYNC-4; tests provide inline fakes.

package/runtime/subsystems/jobs/job-worker.module.ts

@@ -261,6 +261,11 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
           this.options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS,
         pollIntervalMs: drizzleExt?.pollIntervalMs,
         listenNotify: drizzleExt?.listenNotify,
+        // CLAIM-HB-1 — lease tuning knobs. All optional; the worker defaults
+        // claimHeartbeatIntervalMs to staleThresholdMs/3 when omitted.
+        staleSweeperIntervalMs: drizzleExt?.staleSweeperIntervalMs,
+        staleThresholdMs: drizzleExt?.staleThresholdMs,
+        claimHeartbeatIntervalMs: drizzleExt?.claimHeartbeatIntervalMs,
       };
       const worker = this.options.workerFactory
         ? this.options.workerFactory(workerOptions)

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

@@ -2,11 +2,12 @@
  * JobWorker — backend-agnostic tick loop for the job orchestration domain
  * (ADR-022, JOB-3).
  *
- * One worker instance per active pool. On `onModuleInit` it starts two
- * intervals: the poll loop (claim → process → repeat) and the stale-claim
- * sweeper. On `onModuleDestroy` / SIGTERM it drains in-flight work and
- * releases still-`running` rows back to `pending` so a replacement worker
- * can resume with step memoization intact.
+ * One worker instance per active pool. On `onModuleInit` it starts three
+ * intervals: the poll loop (claim → process → repeat), the claim heartbeat
+ * (CLAIM-HB-1 — renews `claimed_at` for in-flight runs so a long handler isn't
+ * swept), and the stale-claim sweeper. On `onModuleDestroy` / SIGTERM it drains
+ * in-flight work and releases still-`running` rows back to `pending` so a
+ * replacement worker can resume with step memoization intact.
  *
  * The claim query is the beating heart: `SELECT … FOR UPDATE SKIP LOCKED`
  * inside a single transaction. Multiple worker processes share the table
@@ -54,10 +55,29 @@ export 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;
   /**
@@ -78,6 +98,12 @@ const DEFAULT_POLL_INTERVAL_MS = 1_000;
 const DEFAULT_STALE_SWEEPER_INTERVAL_MS = 60_000;
 const DEFAULT_STALE_THRESHOLD_MS = 5 * 60_000;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
+/**
+ * CLAIM-HB-1 — the heartbeat fires at `staleThresholdMs / DIVISOR`, leaving
+ * `DIVISOR - 1` missed-renewal margin before the sweeper presumes the worker
+ * dead. 3 gives two missed beats of slack while keeping the renewal cheap.
+ */
+const CLAIM_HEARTBEAT_DIVISOR = 3;
 
 const TERMINAL_STATUSES: JobRunRow['status'][] = [
   'completed',
@@ -172,6 +198,26 @@ export function buildStaleSweepQuery(
     .for('update', { skipLocked: true });
 }
 
+/**
+ * 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.
+ */
+export function buildClaimRenewQuery(
+  db: DrizzleClient,
+  runIds: string[],
+  now: Date = new Date(),
+) {
+  return db
+    .update(jobRuns)
+    .set({ claimedAt: now, updatedAt: now })
+    .where(and(inArray(jobRuns.id, runIds), eq(jobRuns.status, 'running')));
+}
+
 // ─── Error serialisation ───────────────────────────────────────────────────
 
 function serialiseError(err: unknown, attempt: number, retryable: boolean) {
@@ -191,14 +237,25 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(JobWorker.name);
   private shuttingDown = false;
   private readonly inFlight = new Set<Promise<void>>();
+  /**
+   * 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 = new Set<string>();
   private pollTimer: ReturnType<typeof setInterval> | null = null;
   private sweeperTimer: ReturnType<typeof setInterval> | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   private sigtermHandled = false;
   private readonly sigtermHandler: () => void;
 
   private readonly pollIntervalMs: number;
   private readonly staleSweeperIntervalMs: number;
   private readonly staleThresholdMs: number;
+  private readonly claimHeartbeatIntervalMs: number;
   private readonly shutdownTimeoutMs: number;
 
   // LISTEN-NOTIFY-1 — dedicated listener + debounce state. `null` when
@@ -222,6 +279,12 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
     this.staleSweeperIntervalMs =
       options.staleSweeperIntervalMs ?? DEFAULT_STALE_SWEEPER_INTERVAL_MS;
     this.staleThresholdMs = options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS;
+    // CLAIM-HB-1 — default to a third of the stale threshold so a row tolerates
+    // two missed renewals before the sweeper acts. A consumer-supplied value is
+    // honored verbatim (it's their call if they want it tighter/looser).
+    this.claimHeartbeatIntervalMs =
+      options.claimHeartbeatIntervalMs ??
+      Math.max(1, Math.floor(this.staleThresholdMs / CLAIM_HEARTBEAT_DIVISOR));
     this.shutdownTimeoutMs =
       options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
     this.listenNotifyEnabled = options.listenNotify ?? false;
@@ -245,6 +308,12 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
     this.sweeperTimer = setInterval(() => {
       void this.sweepStaleClaims();
     }, this.staleSweeperIntervalMs);
+    // CLAIM-HB-1 — renew the claim lease on in-flight runs so a legitimately
+    // long-running handler is not swept mid-flight. No-ops cheaply (no UPDATE)
+    // when nothing is in flight.
+    this.heartbeatTimer = setInterval(() => {
+      void this.renewClaims();
+    }, this.claimHeartbeatIntervalMs);
     process.on('SIGTERM', this.sigtermHandler);
 
     // LISTEN-NOTIFY-1 — start the wake listener ALONGSIDE the poll timer (never
@@ -342,6 +411,10 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
       clearInterval(this.sweeperTimer);
       this.sweeperTimer = null;
     }
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
     process.removeListener('SIGTERM', this.sigtermHandler);
 
     await this.drainInFlight();
@@ -406,11 +479,21 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
     if (!claimed) return;
 
     const run = claimed;
-    const promise = this.processRun(run).catch((err) => {
-      this.logger.error(
-        `processRun(${run.id}) unhandled: ${(err as Error).message}`,
-      );
-    });
+    // CLAIM-HB-1 — register the run as in-flight so the heartbeat renews its
+    // lease, and deregister the moment its execution settles (success, failure,
+    // retry-release, concurrency-defer — every path out of processRun). Held in
+    // a `finally` so an unhandled throw can't strand the id in the renew set and
+    // keep bumping `claimed_at` for a run this worker no longer owns.
+    this.inFlightRunIds.add(run.id);
+    const promise = this.processRun(run)
+      .catch((err) => {
+        this.logger.error(
+          `processRun(${run.id}) unhandled: ${(err as Error).message}`,
+        );
+      })
+      .finally(() => {
+        this.inFlightRunIds.delete(run.id);
+      });
     this.inFlight.add(promise);
     promise.finally(() => {
       this.inFlight.delete(promise);
@@ -490,6 +573,37 @@ export class JobWorker implements OnModuleInit, OnModuleDestroy {
     }
   }
 
+  // ============================================================================
+  // Claim heartbeat (CLAIM-HB-1)
+  // ============================================================================
+
+  /**
+   * 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.
+   */
+  async renewClaims(): Promise<void> {
+    if (this.shuttingDown) return;
+    const ids = [...this.inFlightRunIds];
+    if (ids.length === 0) return;
+    try {
+      await buildClaimRenewQuery(this.db, ids, new Date());
+    } catch (err) {
+      // Best-effort: a transient failure just means this beat was missed. The
+      // staleThreshold leaves several beats of slack before the sweeper acts,
+      // and the next beat retries.
+      this.logger.error(`renewClaims failed: ${(err as Error).message}`);
+    }
+  }
+
   // ============================================================================
   // processRun
   // ============================================================================

package/runtime/subsystems/jobs/jobs-domain.module.ts

@@ -59,6 +59,25 @@ export interface DrizzleBackendExtensions {
   listenNotify?: boolean;
   /** Polling interval (ms). Default 1000. */
   pollIntervalMs?: number;
+  /**
+   * CLAIM-HB-1 — stale-claim sweep interval (ms). How often each worker scans
+   * for `running` rows whose lease has expired. Default 60_000.
+   */
+  staleSweeperIntervalMs?: number;
+  /**
+   * CLAIM-HB-1 — stale-claim threshold (ms). A `running` row whose `claimed_at`
+   * has not been renewed within this window is presumed stranded by a dead
+   * worker and reset to `pending`. A LIVE worker renews the lease every
+   * `claimHeartbeatIntervalMs`, so this only catches genuine crashes. Default
+   * 300_000 (5 min).
+   */
+  staleThresholdMs?: number;
+  /**
+   * CLAIM-HB-1 — claim heartbeat interval (ms). How often a worker bumps
+   * `claimed_at` for its in-flight runs to keep them from being swept. Must be
+   * comfortably below `staleThresholdMs`. Default `staleThresholdMs / 3`.
+   */
+  claimHeartbeatIntervalMs?: number;
 }
 
 export interface JobsDomainModuleOptions {