@shipfox/api-runners 2.0.0

package/src/core/index.ts

@@ -0,0 +1,56 @@
+export type {EphemeralRegistrationToken} from './entities/ephemeral-registration-token.js';
+export type {ManualRegistrationToken} from './entities/manual-registration-token.js';
+export type {
+  ProvisionedRunner,
+  ProvisionedRunnerState,
+} from './entities/provisioned-runner.js';
+export type {ActiveProvisionerToken, ProvisionerToken} from './entities/provisioner-token.js';
+export type {RunnerSession} from './entities/runner-session.js';
+export {
+  type MintEphemeralRegistrationTokenParams,
+  type MintEphemeralRegistrationTokenResult,
+  mintEphemeralRegistrationToken,
+} from './ephemeral-registration-tokens.js';
+export {
+  EmptyRunnerLabelsError,
+  ManualRegistrationTokenNotFoundError,
+  ProvisionerTokenNotFoundError,
+  RegistrationTokenConsumedError,
+  RegistrationTokenExpiredError,
+  RunnerSessionExhaustedError,
+  RunningJobExecutionNotFoundError,
+} from './errors.js';
+export {type ClaimJobExecutionResult, claimJobExecution} from './job-executions.js';
+export {
+  createWorkspaceManualRegistrationToken,
+  listUsableManualRegistrationTokens,
+  revokeWorkspaceManualRegistrationToken,
+} from './manual-registration-tokens.js';
+export {
+  type ActiveRunner,
+  listActiveRunners,
+  type ReconcileDesiredIntent,
+  type ReconciledBoundJobExecution,
+  type ReconciledProvisionedRunner,
+  type ReconcileProvisionedRunnersParams,
+  type ReconcileProvisionedRunnersResult,
+  type ReportProvisionedRunnersParams,
+  type ReportProvisionedRunnersResult,
+  reconcileProvisionedRunners,
+  reportProvisionedRunners,
+} from './provisioned-runners.js';
+export {
+  createWorkspaceProvisionerToken,
+  listActiveProvisioners,
+  listUsableProvisionerTokens,
+  revokeWorkspaceProvisionerToken,
+} from './provisioner-tokens.js';
+export {
+  type RegisterRunnerSessionResult,
+  type RunnerRegistrationCredential,
+  registerRunnerSession,
+} from './runner-sessions.js';
+export {
+  EMPTY_RUNNER_TOOL_CAPABILITIES,
+  effectiveRunnerToolCapabilities,
+} from './runner-tool-capabilities.js';

package/src/core/job-executions.ts

@@ -0,0 +1,47 @@
+import {issueJobLeaseToken} from '@shipfox/api-auth';
+import {claimPendingJobExecution} from '#db/job-executions.js';
+import {jobExecutionClaimedCount} from '#metrics/instance.js';
+import {config} from '../config.js';
+
+export interface ClaimJobExecutionResult {
+  workflowRunId: string;
+  workflowRunAttemptId: string;
+  jobId: string;
+  jobExecutionId: string;
+  leaseToken: string;
+}
+
+export async function claimJobExecution(params: {
+  workspaceId: string;
+  runnerSessionId: string;
+  sessionLabels: string[];
+  maxClaims: number | null;
+}): Promise<ClaimJobExecutionResult | null> {
+  const claimed = await claimPendingJobExecution({
+    ...params,
+    runnerSessionLivenessThrottleSeconds: config.RUNNER_SESSION_LIVENESS_THROTTLE_SECONDS,
+  });
+  if (!claimed) {
+    jobExecutionClaimedCount.add(1, {outcome: 'empty'});
+    return null;
+  }
+  jobExecutionClaimedCount.add(1, {outcome: 'claimed'});
+
+  const leaseToken = await issueJobLeaseToken({
+    workflowRunId: claimed.workflowRunId,
+    workflowRunAttemptId: claimed.workflowRunAttemptId,
+    jobId: claimed.jobId,
+    jobExecutionId: claimed.jobExecutionId,
+    projectId: claimed.projectId,
+    workspaceId: params.workspaceId,
+    runnerSessionId: params.runnerSessionId,
+  });
+
+  return {
+    workflowRunId: claimed.workflowRunId,
+    workflowRunAttemptId: claimed.workflowRunAttemptId,
+    jobId: claimed.jobId,
+    jobExecutionId: claimed.jobExecutionId,
+    leaseToken,
+  };
+}

package/src/core/maintenance-policy.ts

@@ -0,0 +1 @@
+export const STUCK_JOB_THRESHOLD_SECONDS = 180;

package/src/core/maintenance.test.ts

@@ -0,0 +1,251 @@
+import {vi} from '@shipfox/vitest/vi';
+import {eq} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {ephemeralRegistrationTokens} from '#db/schema/ephemeral-registration-tokens.js';
+import {provisionedRunners} from '#db/schema/provisioned-runners.js';
+import {reservations} from '#db/schema/reservations.js';
+import {runnerSessions} from '#db/schema/runner-sessions.js';
+import {provisionedRunnerReapedCount, reservationReleasedCount} from '#metrics/instance.js';
+import {
+  provisionedRunnerFactory,
+  provisionerTokenFactory,
+  reservationFactory,
+} from '#test/index.js';
+import {
+  deleteExpiredEphemeralRegistrationTokens,
+  deleteExpiredRunnerReservations,
+  deleteExpiredRunnerSessions,
+  reapStaleProvisionedRunners,
+} from './maintenance.js';
+
+describe('deleteExpiredRunnerReservations', () => {
+  let workspaceId: string;
+  let provisionerId: string;
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    provisionerId = crypto.randomUUID();
+  });
+
+  it('deletes expired reservations and keeps active reservations', async () => {
+    await reservationFactory.create({
+      workspaceId,
+      provisionerId,
+      requiredLabels: ['linux'],
+      count: 1,
+      expiresAt: new Date(Date.now() - 60_000),
+    });
+    await reservationFactory.create({
+      workspaceId,
+      provisionerId,
+      requiredLabels: ['linux', 'gpu'],
+      count: 1,
+      expiresAt: new Date(Date.now() + 60_000),
+    });
+
+    const result = await deleteExpiredRunnerReservations();
+
+    const remaining = await db()
+      .select()
+      .from(reservations)
+      .where(eq(reservations.workspaceId, workspaceId));
+    expect(result.deleted).toBeGreaterThanOrEqual(1);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0]?.requiredLabels).toEqual(['linux', 'gpu']);
+  });
+});
+
+describe('reapStaleProvisionedRunners', () => {
+  it('returns reaped counts and records maintenance metrics', async () => {
+    const workspaceId = crypto.randomUUID();
+    const provisioner = await provisionerTokenFactory.create({workspaceId});
+    await reservationFactory.create({
+      workspaceId,
+      provisionerId: provisioner.id,
+      requiredLabels: ['linux'],
+      count: 2,
+      expiresAt: new Date(Date.now() + 60_000),
+    });
+    const [reservation] = await db()
+      .select()
+      .from(reservations)
+      .where(eq(reservations.workspaceId, workspaceId));
+    if (!reservation) throw new Error('Expected reservation');
+    const provisionedRunner = await provisionedRunnerFactory.create({
+      workspaceId,
+      provisionerId: provisioner.id,
+      provisionedRunnerId: 'provisioned-runner-1',
+      reservationId: reservation.id,
+      reportedAt: new Date(Date.now() - 120_000),
+    });
+    await db()
+      .update(provisionedRunners)
+      .set({updatedAt: new Date(Date.now() - 120_000)})
+      .where(eq(provisionedRunners.id, provisionedRunner.id));
+    const reapedSpy = vi.spyOn(provisionedRunnerReapedCount, 'add');
+    const releasedSpy = vi.spyOn(reservationReleasedCount, 'add');
+
+    const result = await reapStaleProvisionedRunners({thresholdSeconds: 60, limit: 100});
+
+    expect(result).toEqual({reaped: 1, reservationsReleased: 1});
+    expect(reapedSpy).toHaveBeenCalledWith(1);
+    expect(releasedSpy).toHaveBeenCalledWith(1);
+  });
+});
+
+describe('deleteExpiredRunnerSessions', () => {
+  let workspaceId: string;
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+  });
+
+  it('deletes expired runner sessions using default retention policy', async () => {
+    const manualId = crypto.randomUUID();
+    const ephemeralId = crypto.randomUUID();
+    await db()
+      .insert(runnerSessions)
+      .values([
+        buildRunnerSession({
+          id: manualId,
+          kind: 'manual',
+          createdAt: new Date(Date.now() - 31 * 24 * 60 * 60 * 1000),
+        }),
+        buildRunnerSession({
+          id: ephemeralId,
+          kind: 'ephemeral',
+          createdAt: new Date(Date.now() - 8 * 24 * 60 * 60 * 1000),
+        }),
+      ]);
+
+    const result = await deleteExpiredRunnerSessions();
+
+    const remaining = await db()
+      .select({id: runnerSessions.id})
+      .from(runnerSessions)
+      .where(eq(runnerSessions.workspaceId, workspaceId));
+    expect(result.deleted).toBeGreaterThanOrEqual(2);
+    expect(remaining).toEqual([]);
+  });
+
+  it('passes explicit retention and limit values to the DB cleanup', async () => {
+    const deleteableId = crypto.randomUUID();
+    const keptId = crypto.randomUUID();
+    await db()
+      .insert(runnerSessions)
+      .values([
+        buildRunnerSession({
+          id: deleteableId,
+          kind: 'manual',
+          createdAt: new Date(Date.now() - 3650 * 24 * 60 * 60 * 1000),
+        }),
+        buildRunnerSession({
+          id: keptId,
+          kind: 'manual',
+          createdAt: new Date(Date.now() - 4 * 24 * 60 * 60 * 1000),
+        }),
+      ]);
+
+    const result = await deleteExpiredRunnerSessions({
+      manualRetentionDays: 5,
+      ephemeralRetentionDays: 7,
+      limit: 1,
+    });
+
+    const remaining = await db()
+      .select({id: runnerSessions.id})
+      .from(runnerSessions)
+      .where(eq(runnerSessions.workspaceId, workspaceId));
+    expect(result.deleted).toBe(1);
+    expect(remaining.map((row) => row.id)).toEqual([keptId]);
+  });
+
+  function buildRunnerSession(params: {
+    id: string;
+    kind: 'manual' | 'ephemeral';
+    createdAt: Date;
+  }): typeof runnerSessions.$inferInsert {
+    const provisionerId = params.kind === 'ephemeral' ? crypto.randomUUID() : null;
+    return {
+      id: params.id,
+      workspaceId,
+      scope: 'workspace',
+      registrationTokenId: crypto.randomUUID(),
+      registrationTokenKind: params.kind,
+      provisionerId,
+      provisionedRunnerId: params.kind === 'ephemeral' ? `provisioned-${params.id}` : null,
+      labels: ['linux'],
+      maxClaims: params.kind === 'ephemeral' ? 1 : null,
+      claimsUsed: 0,
+      createdAt: params.createdAt,
+      updatedAt: params.createdAt,
+    };
+  }
+});
+
+describe('deleteExpiredEphemeralRegistrationTokens', () => {
+  const DAY_MS = 24 * 60 * 60 * 1000;
+  let workspaceId: string;
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+  });
+
+  it('deletes expired ephemeral tokens using the default retention policy', async () => {
+    const staleId = crypto.randomUUID();
+    await db()
+      .insert(ephemeralRegistrationTokens)
+      .values(
+        buildEphemeralToken({
+          id: staleId,
+          expiresAt: new Date(Date.now() - 8 * DAY_MS),
+        }),
+      );
+
+    const result = await deleteExpiredEphemeralRegistrationTokens();
+
+    const remaining = await db()
+      .select({id: ephemeralRegistrationTokens.id})
+      .from(ephemeralRegistrationTokens)
+      .where(eq(ephemeralRegistrationTokens.workspaceId, workspaceId));
+    expect(result.deleted).toBeGreaterThanOrEqual(1);
+    expect(remaining).toEqual([]);
+  });
+
+  it('passes explicit retention and limit values to the DB cleanup', async () => {
+    const deletableId = crypto.randomUUID();
+    const keptId = crypto.randomUUID();
+    await db()
+      .insert(ephemeralRegistrationTokens)
+      .values([
+        buildEphemeralToken({id: deletableId, expiresAt: new Date(Date.now() - 3650 * DAY_MS)}),
+        buildEphemeralToken({id: keptId, expiresAt: new Date(Date.now() - 4 * DAY_MS)}),
+      ]);
+
+    const result = await deleteExpiredEphemeralRegistrationTokens({retentionDays: 5, limit: 1});
+
+    const remaining = await db()
+      .select({id: ephemeralRegistrationTokens.id})
+      .from(ephemeralRegistrationTokens)
+      .where(eq(ephemeralRegistrationTokens.workspaceId, workspaceId));
+    expect(result.deleted).toBe(1);
+    expect(remaining.map((row) => row.id)).toEqual([keptId]);
+  });
+
+  function buildEphemeralToken(params: {
+    id: string;
+    expiresAt: Date;
+  }): typeof ephemeralRegistrationTokens.$inferInsert {
+    return {
+      id: params.id,
+      workspaceId,
+      provisionerId: crypto.randomUUID(),
+      provisionedRunnerId: `provisioned-${params.id}`,
+      hashedToken: crypto.randomUUID(),
+      prefix: 'sfxr_test',
+      expiresAt: params.expiresAt,
+      consumedAt: null,
+      createdAt: params.expiresAt,
+    };
+  }
+});

package/src/core/maintenance.ts

@@ -0,0 +1,74 @@
+import {config} from '#config.js';
+import {deleteExpiredEphemeralRegistrationTokens as deleteExpiredEphemeralRegistrationTokensDb} from '#db/ephemeral-registration-tokens.js';
+import {expireStuckJobExecutions} from '#db/job-executions.js';
+import {reapStaleProvisionedRunners as reapStaleProvisionedRunnersDb} from '#db/provisioned-runners.js';
+import {deleteExpiredReservations} from '#db/reservations.js';
+import {deleteExpiredRunnerSessions as deleteExpiredRunnerSessionsDb} from '#db/runner-sessions.js';
+import {provisionedRunnerReapedCount, reservationReleasedCount} from '#metrics/instance.js';
+import {STUCK_JOB_THRESHOLD_SECONDS} from './maintenance-policy.js';
+
+export interface DetectAndExpireStuckJobsParams {
+  noFirstHeartbeatGraceSeconds?: number;
+  thresholdSeconds?: number;
+}
+
+export async function detectAndExpireStuckJobs(
+  params: DetectAndExpireStuckJobsParams = {},
+): Promise<{expired: number}> {
+  const reaped = await expireStuckJobExecutions({
+    noFirstHeartbeatGraceSeconds:
+      params.noFirstHeartbeatGraceSeconds ?? config.RUNNER_NO_FIRST_HEARTBEAT_GRACE_SECONDS,
+    thresholdSeconds: params.thresholdSeconds ?? STUCK_JOB_THRESHOLD_SECONDS,
+  });
+  return {expired: reaped.length};
+}
+
+export async function deleteExpiredRunnerReservations(params?: {
+  limit?: number;
+}): Promise<{deleted: number}> {
+  const deleted = await deleteExpiredReservations(params);
+  return {deleted};
+}
+
+export async function reapStaleProvisionedRunners(params?: {
+  thresholdSeconds?: number;
+  limit?: number;
+}): Promise<{reaped: number; reservationsReleased: number}> {
+  const result = await reapStaleProvisionedRunnersDb({
+    thresholdSeconds:
+      params?.thresholdSeconds ?? config.RUNNER_STALE_PROVISIONED_RUNNER_THRESHOLD_SECONDS,
+    limit: params?.limit ?? config.RUNNER_STALE_PROVISIONED_RUNNER_REAPER_LIMIT,
+  });
+
+  if (result.reaped > 0) provisionedRunnerReapedCount.add(result.reaped);
+  if (result.reservationsReleased > 0) {
+    reservationReleasedCount.add(result.reservationsReleased);
+  }
+
+  return result;
+}
+
+export async function deleteExpiredRunnerSessions(params?: {
+  manualRetentionDays?: number;
+  ephemeralRetentionDays?: number;
+  limit?: number;
+}): Promise<{deleted: number}> {
+  const deleted = await deleteExpiredRunnerSessionsDb({
+    manualRetentionDays: params?.manualRetentionDays ?? config.RUNNER_SESSION_MANUAL_RETENTION_DAYS,
+    ephemeralRetentionDays:
+      params?.ephemeralRetentionDays ?? config.RUNNER_SESSION_EPHEMERAL_RETENTION_DAYS,
+    limit: params?.limit ?? config.RUNNER_SESSION_GC_BATCH_SIZE,
+  });
+  return {deleted};
+}
+
+export async function deleteExpiredEphemeralRegistrationTokens(params?: {
+  retentionDays?: number;
+  limit?: number;
+}): Promise<{deleted: number}> {
+  const deleted = await deleteExpiredEphemeralRegistrationTokensDb({
+    retentionDays: params?.retentionDays ?? config.RUNNER_EPHEMERAL_TOKEN_RETENTION_DAYS,
+    limit: params?.limit ?? config.RUNNER_EPHEMERAL_TOKEN_GC_BATCH_SIZE,
+  });
+  return {deleted};
+}

package/src/core/manual-registration-tokens.test.ts

@@ -0,0 +1,44 @@
+import {hashOpaqueToken, tokenTypeParts} from '@shipfox/node-tokens';
+import {eq} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {manualRegistrationTokens} from '#db/schema/manual-registration-tokens.js';
+import {manualRegistrationTokenFactory} from '#test/index.js';
+import {
+  createWorkspaceManualRegistrationToken,
+  listUsableManualRegistrationTokens,
+  revokeWorkspaceManualRegistrationToken,
+} from './manual-registration-tokens.js';
+
+describe('manual registration token core', () => {
+  it('creates a workspace manual registration token and stores only the hash', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    const result = await createWorkspaceManualRegistrationToken({
+      workspaceId,
+      name: 'local runner',
+      ttlSeconds: 3600,
+    });
+
+    expect(result.rawToken.startsWith(`sf_${tokenTypeParts.manualRegistrationToken}_`)).toBe(true);
+    expect(result.token.workspaceId).toBe(workspaceId);
+    expect(result.token.prefix).toBe(result.rawToken.slice(0, 12));
+    const rows = await db()
+      .select()
+      .from(manualRegistrationTokens)
+      .where(eq(manualRegistrationTokens.id, result.token.id));
+    expect(rows[0]?.hashedToken).toBe(hashOpaqueToken(result.rawToken));
+    expect(rows[0]?.hashedToken).not.toBe(result.rawToken);
+  });
+
+  it('lists usable tokens and excludes revoked tokens after revoke', async () => {
+    const workspaceId = crypto.randomUUID();
+    const token = await manualRegistrationTokenFactory.create({workspaceId});
+
+    const beforeRevoke = await listUsableManualRegistrationTokens(workspaceId);
+    await revokeWorkspaceManualRegistrationToken({tokenId: token.id, workspaceId});
+    const afterRevoke = await listUsableManualRegistrationTokens(workspaceId);
+
+    expect(beforeRevoke.map((item) => item.id)).toEqual([token.id]);
+    expect(afterRevoke).toEqual([]);
+  });
+});

package/src/core/manual-registration-tokens.ts

@@ -0,0 +1,51 @@
+import {extractDisplayPrefix, generateOpaqueToken, hashOpaqueToken} from '@shipfox/node-tokens';
+import {
+  createManualRegistrationToken,
+  listUsableManualRegistrationTokensByWorkspaceId,
+  revokeManualRegistrationToken,
+} from '#db/manual-registration-tokens.js';
+import type {ManualRegistrationToken} from './entities/manual-registration-token.js';
+import {ManualRegistrationTokenNotFoundError} from './errors.js';
+
+export interface CreateWorkspaceManualRegistrationTokenParams {
+  workspaceId: string;
+  name?: string | undefined;
+  ttlSeconds?: number | undefined;
+}
+
+export interface CreateWorkspaceManualRegistrationTokenResult {
+  token: ManualRegistrationToken;
+  rawToken: string;
+}
+
+export async function createWorkspaceManualRegistrationToken(
+  params: CreateWorkspaceManualRegistrationTokenParams,
+): Promise<CreateWorkspaceManualRegistrationTokenResult> {
+  const rawToken = generateOpaqueToken('manualRegistrationToken');
+  const expiresAt = params.ttlSeconds ? new Date(Date.now() + params.ttlSeconds * 1000) : undefined;
+
+  const token = await createManualRegistrationToken({
+    workspaceId: params.workspaceId,
+    hashedToken: hashOpaqueToken(rawToken),
+    prefix: extractDisplayPrefix(rawToken),
+    name: params.name,
+    expiresAt,
+  });
+
+  return {token, rawToken};
+}
+
+export function listUsableManualRegistrationTokens(
+  workspaceId: string,
+): Promise<ManualRegistrationToken[]> {
+  return listUsableManualRegistrationTokensByWorkspaceId(workspaceId);
+}
+
+export async function revokeWorkspaceManualRegistrationToken(params: {
+  tokenId: string;
+  workspaceId: string;
+}): Promise<ManualRegistrationToken> {
+  const token = await revokeManualRegistrationToken(params);
+  if (!token) throw new ManualRegistrationTokenNotFoundError(params.tokenId);
+  return token;
+}

package/src/core/provisioned-runners.test.ts

@@ -0,0 +1,101 @@
+import {reconcileProvisionedRunnersFromDbResult} from './provisioned-runners.js';
+
+describe('reconcileProvisionedRunnersFromDbResult', () => {
+  it('keeps active provisioned runners', () => {
+    const result = reconcileProvisionedRunnersFromDbResult({
+      observedProvisionedRunnerIds: ['provisioned-runner-1'],
+      observedRows: [provisionedRunner({provisionedRunnerId: 'provisioned-runner-1'})],
+      boundJobExecutionsByProvisionedRunnerId: new Map(),
+    });
+
+    expect(result[0]?.desiredIntent).toBe('keep');
+  });
+
+  it('terminates terminal provisioned runners', () => {
+    const result = reconcileProvisionedRunnersFromDbResult({
+      observedProvisionedRunnerIds: ['provisioned-runner-1'],
+      observedRows: [
+        provisionedRunner({provisionedRunnerId: 'provisioned-runner-1', state: 'terminated'}),
+      ],
+      boundJobExecutionsByProvisionedRunnerId: new Map(),
+    });
+
+    expect(result[0]?.desiredIntent).toBe('terminate');
+  });
+
+  it('keeps orphan observed provisioned runners', () => {
+    const result = reconcileProvisionedRunnersFromDbResult({
+      observedProvisionedRunnerIds: ['provisioned-runner-1'],
+      observedRows: [],
+      boundJobExecutionsByProvisionedRunnerId: new Map(),
+    });
+
+    expect(result[0]).toMatchObject({
+      provisionedRunnerId: 'provisioned-runner-1',
+      state: null,
+      desiredIntent: 'keep',
+    });
+  });
+
+  it('terminates active provisioned runners with a cancelled latest bound job', () => {
+    const result = reconcileProvisionedRunnersFromDbResult({
+      observedProvisionedRunnerIds: ['provisioned-runner-1'],
+      observedRows: [provisionedRunner({provisionedRunnerId: 'provisioned-runner-1'})],
+      boundJobExecutionsByProvisionedRunnerId: new Map([
+        [
+          'provisioned-runner-1',
+          boundJobExecution({
+            provisionedRunnerId: 'provisioned-runner-1',
+            cancellationRequestedAt: new Date('2025-01-01T00:01:00.000Z'),
+          }),
+        ],
+      ]),
+    });
+
+    expect(result[0]?.desiredIntent).toBe('terminate');
+  });
+});
+
+function provisionedRunner(params: {
+  provisionedRunnerId: string;
+  state?: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'terminated';
+}) {
+  return {
+    id: crypto.randomUUID(),
+    workspaceId: crypto.randomUUID(),
+    provisionerId: crypto.randomUUID(),
+    provisionedRunnerId: params.provisionedRunnerId,
+    reservationId: null,
+    templateKey: 'linux',
+    labels: ['linux'],
+    state: params.state ?? 'running',
+    reason: null,
+    runnerSessionId: null,
+    providerKind: 'docker',
+    reportedAt: new Date(),
+    startedAt: null,
+    stoppingAt: null,
+    stoppedAt: null,
+    failedAt: null,
+    terminatedAt: null,
+    reservationReleasedAt: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+function boundJobExecution(params: {
+  provisionedRunnerId: string;
+  cancellationRequestedAt?: Date | null;
+}) {
+  return {
+    workflowRunId: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    jobId: crypto.randomUUID(),
+    jobExecutionId: crypto.randomUUID(),
+    provisionedRunnerId: params.provisionedRunnerId,
+    startedAt: new Date('2025-01-01T00:00:00.000Z'),
+    lastHeartbeatAt: new Date('2025-01-01T00:00:00.000Z'),
+    cancellationRequestedAt: params.cancellationRequestedAt ?? null,
+  };
+}