@shipfox/api-runners 4.0.0 → 6.0.0

package/src/index.ts

@@ -1,5 +1,6 @@
 import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
+import type {AuthInterModuleClient} from '@shipfox/api-auth-dto/inter-module';
 import {runnersEventSchemas} from '@shipfox/api-runners-dto';
 import {
   WORKFLOWS_JOB_EXECUTION_TIMED_OUT,
@@ -7,13 +8,16 @@ import {
 } from '@shipfox/api-workflows-dto';
 import {type ShipfoxModule, subscriberFactory} from '@shipfox/node-module';
 import {db, migrationsPath, runnersOutbox} from '#db/index.js';
+import type {CreateRunnersModuleOptions} from '#installation-provisioning.js';
 import {registerRunnersServiceMetrics} from '#metrics/index.js';
 import {
   createProvisionerTokenAuthMethod,
+  createRunnerControlSessionAuthMethod,
   createRunnerRegistrationTokenAuthMethod,
+  createRunnerRoutes,
   onWorkflowsJobExecutionTimedOut,
-  routes,
 } from '#presentation/index.js';
+import {createRunnersInterModulePresentation} from '#presentation/inter-module.js';
 import {createRunnersMaintenanceActivities} from '#temporal/activities/index.js';
 import {RUNNERS_MAINTENANCE_TASK_QUEUE} from '#temporal/constants.js';
 
@@ -21,8 +25,8 @@ export {
   type MintEphemeralRegistrationTokenParams,
   type MintEphemeralRegistrationTokenResult,
   type MintEphemeralRegistrationTokensBatchParams,
-  type MintEphemeralRegistrationTokensBatchProvisionedRunner,
   type MintEphemeralRegistrationTokensBatchResult,
+  type MintEphemeralRegistrationTokensBatchRunnerInstance,
   mintEphemeralRegistrationToken,
   mintEphemeralRegistrationTokensBatch,
 } from '#core/ephemeral-registration-tokens.js';
@@ -38,26 +42,42 @@ export {
   isJobLeaseActive,
   releaseJobExecution,
 } from '#db/index.js';
+export type {
+  CreateRunnersModuleOptions,
+  InstallationProvisioningPolicy,
+} from '#installation-provisioning.js';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const workflowsPath = resolve(packageRoot, 'dist/temporal/workflows/index.js');
 
 const subscriber = subscriberFactory<WorkflowsEventMapDto>();
 
-export const runnersModule: ShipfoxModule = {
-  name: 'runners',
-  database: {db, migrationsPath},
-  auth: [createRunnerRegistrationTokenAuthMethod(), createProvisionerTokenAuthMethod()],
-  routes,
-  metrics: registerRunnersServiceMetrics,
-  publishers: [{name: 'runners', table: runnersOutbox, db, eventSchemas: runnersEventSchemas}],
-  subscribers: [subscriber(WORKFLOWS_JOB_EXECUTION_TIMED_OUT, onWorkflowsJobExecutionTimedOut)],
-  workers: [
-    {
-      taskQueue: RUNNERS_MAINTENANCE_TASK_QUEUE,
-      workflowsPath,
-      activities: createRunnersMaintenanceActivities,
-      workflows: [{name: 'stuckJobDetector', id: 'stuck-job-detector', cronSchedule: '* * * * *'}],
-    },
-  ],
-};
+export function createRunnersModule({
+  auth,
+  ...options
+}: CreateRunnersModuleOptions & {auth: AuthInterModuleClient}): ShipfoxModule {
+  return {
+    name: 'runners',
+    database: {db, migrationsPath},
+    auth: [
+      createRunnerRegistrationTokenAuthMethod(),
+      createRunnerControlSessionAuthMethod(),
+      createProvisionerTokenAuthMethod(),
+    ],
+    routes: createRunnerRoutes(auth, options),
+    metrics: registerRunnersServiceMetrics,
+    publishers: [{name: 'runners', table: runnersOutbox, db, eventSchemas: runnersEventSchemas}],
+    subscribers: [subscriber(WORKFLOWS_JOB_EXECUTION_TIMED_OUT, onWorkflowsJobExecutionTimedOut)],
+    workers: [
+      {
+        taskQueue: RUNNERS_MAINTENANCE_TASK_QUEUE,
+        workflowsPath,
+        activities: createRunnersMaintenanceActivities,
+        workflows: [
+          {name: 'stuckJobDetector', id: 'stuck-job-detector', cronSchedule: '* * * * *'},
+        ],
+      },
+    ],
+    interModulePresentations: [createRunnersInterModulePresentation()],
+  };
+}

package/src/installation-provisioning.ts

@@ -0,0 +1,14 @@
+/**
+ * Lets an application host choose which workspaces may receive installation-provisioned capacity.
+ * The runners module passes candidate IDs in batches so host policy can apply its own entitlement
+ * or tenancy rules without exposing those rules from this package.
+ */
+export interface InstallationProvisioningPolicy {
+  filterEligibleWorkspaceIds(workspaceIds: readonly string[]): Promise<ReadonlySet<string>>;
+}
+
+export interface CreateRunnersModuleOptions {
+  installationProvisioning?: {
+    policy: InstallationProvisioningPolicy;
+  };
+}

package/src/metrics/index.ts

@@ -2,11 +2,11 @@ export {
   jobExecutionClaimedCount,
   jobExecutionEnqueuedCount,
   jobExecutionLeaseExpiredCount,
-  provisionedRunnerAbsentTerminatedCount,
-  provisionedRunnerCountDivergenceCount,
-  provisionedRunnerReconcileCallCount,
-  provisionedRunnerTerminateIntentHonoredCount,
-  provisionedRunnerTerminateIntentIssuedCount,
+  providerRunnerAbsentTerminatedCount,
+  providerRunnerCountDivergenceCount,
+  providerRunnerReconcileCallCount,
+  providerRunnerTerminateIntentHonoredCount,
+  providerRunnerTerminateIntentIssuedCount,
   recordRunnersRateLimitCheck,
   recordRunnersRateLimitPruneFailure,
 } from './instance.js';

package/src/metrics/instance.ts

@@ -19,51 +19,62 @@ export const jobExecutionLeaseExpiredCount = meter.createCounter<Record<string,
   {description: 'Job execution leases reaped after passing the heartbeat threshold'},
 );
 
-export const provisionedRunnerReportCount = meter.createCounter<{
+export const providerRunnerReportCount = meter.createCounter<{
   state: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'terminated';
-}>('runners_provisioned_runner_reported', {
+}>('runners_provider_runner_reported', {
   description: 'Provisioned runner lifecycle reports accepted by state',
 });
 
-export const provisionedRunnerReapedCount = meter.createCounter<Record<string, never>>(
-  'runners_provisioned_runner_reaped',
+export const runnerBootstrapExchangeCount = meter.createCounter<{
+  outcome: 'accepted' | 'rejected';
+}>('runners_runner_bootstrap_exchange', {
+  description: 'Runner bootstrap-token exchanges by outcome',
+});
+
+export const runnerControlHeartbeatCount = meter.createCounter<Record<string, never>>(
+  'runners_runner_control_heartbeat',
+  {description: 'Pre-workspace runner-control heartbeats accepted'},
+);
+
+export const providerRunnerReapedCount = meter.createCounter<Record<string, never>>(
+  'runners_provider_runner_reaped',
   {
     description: 'Stale provisioned runners marked failed by backend maintenance',
   },
 );
 
-export const provisionedRunnerCountDivergenceCount = meter.createCounter<{
+export const providerRunnerCountDivergenceCount = meter.createCounter<{
   template_key?: string;
   state: 'starting' | 'running';
   direction: 'backend-higher' | 'advertised-higher';
-}>('runners_provisioned_runner_count_divergence', {
+}>('runners_provider_runner_count_divergence', {
   description:
     'Absolute difference between provisioner-advertised and backend-observed provisioned runner counts',
 });
 
-export const provisionedRunnerReconcileCallCount = meter.createCounter<Record<string, never>>(
-  'runners_provisioned_runner_reconcile_called',
+export const providerRunnerReconcileCallCount = meter.createCounter<Record<string, never>>(
+  'runners_provider_runner_reconcile_called',
   {description: 'Provisioned runner reconcile calls completed successfully'},
 );
 
-export const provisionedRunnerAbsentTerminatedCount = meter.createCounter<Record<string, never>>(
-  'runners_provisioned_runner_absent_terminated',
+export const providerRunnerAbsentTerminatedCount = meter.createCounter<Record<string, never>>(
+  'runners_provider_runner_absent_terminated',
   {
     description:
       'Owned provisioned runners marked terminated because they were absent from reconcile',
   },
 );
 
-export const provisionedRunnerTerminateIntentIssuedCount = meter.createCounter<{
+export const providerRunnerTerminateIntentIssuedCount = meter.createCounter<{
   surface: 'poll-demand' | 'reconcile';
   reason: 'job-cancelled' | 'terminal-state';
-}>('runners_provisioned_runner_terminate_intent_issued', {
+}>('runners_provider_runner_terminate_intent_issued', {
   description: 'Provisioned runner terminate intents returned to provisioners',
 });
 
-export const provisionedRunnerTerminateIntentHonoredCount = meter.createCounter<{
+export const providerRunnerTerminateIntentHonoredCount = meter.createCounter<{
   reason: 'job-cancelled';
-}>('runners_provisioned_runner_terminate_intent_honored', {
+}>('runners_provider_runner_terminate_intent_honored', {
   description: 'Provisioned runner terminate intents honored by first transition to terminated',
 });
 

package/src/presentation/auth/index.ts

@@ -1,4 +1,8 @@
 export {createProvisionerTokenAuthMethod} from './provisioner-token-auth.js';
+export {
+  authenticateRunnerControlSession,
+  createRunnerControlSessionAuthMethod,
+} from './runner-control-session-auth.js';
 export {
   createRunnerRegistrationTokenAuthMethod,
   getRunnerContext,

package/src/presentation/auth/provisioner-token-auth.ts

@@ -48,10 +48,14 @@ export function createProvisionerTokenAuthMethod(): AuthMethod {
         });
       }
 
-      const context: ProvisionerContext = {
-        provisionerTokenId: provisionerToken.id,
-        workspaceId: provisionerToken.workspaceId,
-      };
+      const context: ProvisionerContext =
+        provisionerToken.scope === 'installation'
+          ? {provisionerTokenId: provisionerToken.id, scope: 'installation'}
+          : {
+              provisionerTokenId: provisionerToken.id,
+              scope: 'workspace',
+              workspaceId: provisionerToken.workspaceId,
+            };
 
       await touchProvisionerLastSeen({
         tokenId: provisionerToken.id,

package/src/presentation/auth/runner-control-session-auth.ts

@@ -0,0 +1,31 @@
+import {
+  AUTH_RUNNER_CONTROL_SESSION,
+  setRunnerControlSessionContext,
+} from '@shipfox/api-auth-context';
+import {type AuthMethod, ClientError, extractBearerToken} from '@shipfox/node-fastify';
+import {getTokenType} from '@shipfox/node-tokens';
+import {resolveRunnerControlSession} from '#core/runner-control-sessions.js';
+
+export function createRunnerControlSessionAuthMethod(): AuthMethod {
+  return {
+    name: AUTH_RUNNER_CONTROL_SESSION,
+    authenticate: authenticateRunnerControlSession,
+  };
+}
+
+export async function authenticateRunnerControlSession(
+  request: Parameters<AuthMethod['authenticate']>[0],
+) {
+  const rawToken = extractBearerToken(request.headers.authorization);
+  if (!rawToken || getTokenType(rawToken) !== 'runnerControlSession') {
+    throw new ClientError('Invalid runner control session', 'unauthorized', {status: 401});
+  }
+  const session = await resolveRunnerControlSession(rawToken);
+  if (!session)
+    throw new ClientError('Invalid runner control session', 'unauthorized', {status: 401});
+  setRunnerControlSessionContext(request, {
+    runnerControlSessionId: session.id,
+    runnerInstanceId: session.runnerInstanceId,
+    provisionerId: session.provisionerId,
+  });
+}

package/src/presentation/auth/runner-registration-token-auth.ts

@@ -1,9 +1,14 @@
 import {AUTH_RUNNER_REGISTRATION_TOKEN} from '@shipfox/api-auth-context';
 import {type AuthMethod, ClientError, extractBearerToken} from '@shipfox/node-fastify';
 import {getTokenType, hashOpaqueToken} from '@shipfox/node-tokens';
+import {and, eq, gt, isNull, or, sql} from 'drizzle-orm';
 import type {FastifyRequest} from 'fastify';
+import {db} from '#db/db.js';
 import {resolveEphemeralRegistrationTokenByHash} from '#db/ephemeral-registration-tokens.js';
 import {resolveManualRegistrationTokenByHash} from '#db/manual-registration-tokens.js';
+import {provisionerTokens} from '#db/schema/provisioner-tokens.js';
+import {runnerActivationTokens} from '#db/schema/runner-activation-tokens.js';
+import {providerRunners} from '#db/schema/runner-instances.js';
 
 const RUNNER_CONTEXT_KEY = 'runner';
 
@@ -19,8 +24,9 @@ export type RunnerRegistrationContext =
       workspaceId: string;
       provisionerId: string;
       reservationId: string | null;
-      provisionedRunnerId: string;
-    };
+      providerRunnerId: string;
+    }
+  | {kind: 'activation'; activationTokenId: string; workspaceId: string};
 
 export function getRunnerContext(request: FastifyRequest): RunnerRegistrationContext {
   const context = (request as unknown as Record<string, unknown>)[RUNNER_CONTEXT_KEY] as
@@ -45,6 +51,36 @@ export function createRunnerRegistrationTokenAuthMethod(): AuthMethod {
 
       const tokenType = getTokenType(rawToken);
 
+      if (tokenType === 'runnerActivationToken') {
+        const [activation] = await db()
+          .select({id: runnerActivationTokens.id, workspaceId: providerRunners.workspaceId})
+          .from(runnerActivationTokens)
+          .innerJoin(
+            providerRunners,
+            eq(providerRunners.id, runnerActivationTokens.runnerInstanceId),
+          )
+          .leftJoin(provisionerTokens, eq(provisionerTokens.id, providerRunners.provisionerId))
+          .where(
+            and(
+              eq(runnerActivationTokens.hashedToken, hashOpaqueToken(rawToken)),
+              isNull(runnerActivationTokens.consumedAt),
+              isNull(runnerActivationTokens.revokedAt),
+              gt(runnerActivationTokens.expiresAt, sql`now()`),
+              or(isNull(provisionerTokens.id), isNull(provisionerTokens.revokedAt)),
+              isNull(providerRunners.runnerSessionId),
+            ),
+          )
+          .limit(1);
+        if (!activation?.workspaceId)
+          throw new ClientError('Invalid runner registration token', 'unauthorized', {status: 401});
+        (request as unknown as Record<string, unknown>)[RUNNER_CONTEXT_KEY] = {
+          kind: 'activation',
+          activationTokenId: activation.id,
+          workspaceId: activation.workspaceId,
+        } satisfies RunnerRegistrationContext;
+        return;
+      }
+
       if (tokenType === 'ephemeralRegistrationToken') {
         const ephemeralToken = await resolveEphemeralRegistrationTokenByHash(
           hashOpaqueToken(rawToken),
@@ -68,7 +104,7 @@ export function createRunnerRegistrationTokenAuthMethod(): AuthMethod {
           workspaceId: ephemeralToken.workspaceId,
           provisionerId: ephemeralToken.provisionerId,
           reservationId: ephemeralToken.reservationId,
-          provisionedRunnerId: ephemeralToken.provisionedRunnerId,
+          providerRunnerId: ephemeralToken.providerRunnerId,
         } satisfies RunnerRegistrationContext;
         return;
       }

package/src/presentation/dto/index.ts

@@ -1,13 +1,13 @@
 export {toActiveProvisionerDto} from './active-provisioner.js';
 export {toManualRegistrationTokenDto} from './manual-registration-token.js';
 export {
-  toMintRegistrationTokensProvisionedRunners,
   toMintRegistrationTokensResponseDto,
+  toMintRegistrationTokensRunnerInstances,
 } from './mint-registration-tokens.js';
 export {toPollDemandResponseDto} from './poll-demand.js';
+export {toProvisionerTokenDto} from './provisioner-token.js';
 export {
   toActiveRunnersResponseDto,
-  toReconcileProvisionedRunnersResponseDto,
-  toReportProvisionedRunnersResponseDto,
-} from './provisioned-runners.js';
-export {toProvisionerTokenDto} from './provisioner-token.js';
+  toReconcileRunnerInstancesResponseDto,
+  toReportRunnerInstancesResponseDto,
+} from './runner-instances.js';

package/src/presentation/dto/mint-registration-tokens.ts

@@ -1,34 +1,27 @@
 import type {
   MintedRegistrationTokenDto,
   MintRegistrationTokensBatchResponseDto,
-  MintRegistrationTokensProvisionedRunnerDto,
+  MintRegistrationTokensRunnerInstanceDto,
 } from '@shipfox/api-runners-dto';
-import type {
-  MintEphemeralRegistrationTokensBatchProvisionedRunner,
-  MintEphemeralRegistrationTokensBatchResult,
-} from '#core/ephemeral-registration-tokens.js';
+import type {MintEphemeralRegistrationTokensBatchResult} from '#core/ephemeral-registration-tokens.js';
 
-export function toMintRegistrationTokensProvisionedRunners(
-  provisionedRunners: MintRegistrationTokensProvisionedRunnerDto[],
-): MintEphemeralRegistrationTokensBatchProvisionedRunner[] {
-  return provisionedRunners.map((provisionedRunner) => ({
-    provisionedRunnerId: provisionedRunner.provisioned_runner_id,
-  }));
+export function toMintRegistrationTokensRunnerInstances(
+  providerRunners: MintRegistrationTokensRunnerInstanceDto[],
+) {
+  return providerRunners.map((runner) => ({providerRunnerId: runner.provider_runner_id}));
 }
 
 export function toMintRegistrationTokensResponseDto(
   result: MintEphemeralRegistrationTokensBatchResult[],
 ): MintRegistrationTokensBatchResponseDto {
-  return {
-    tokens: result.map(toMintedRegistrationTokenDto),
-  };
+  return {tokens: result.map(toMintedRegistrationTokenDto)};
 }
 
 function toMintedRegistrationTokenDto(
   result: MintEphemeralRegistrationTokensBatchResult,
 ): MintedRegistrationTokenDto {
   return {
-    provisioned_runner_id: result.provisionedRunnerId,
+    provider_runner_id: result.providerRunnerId,
     registration_token: result.rawToken,
     expires_at: result.token.expiresAt.toISOString(),
   };

package/src/presentation/dto/poll-demand.ts

@@ -4,6 +4,7 @@ import type {PollDemandResult} from '#core/demand.js';
 export function toPollDemandResponseDto(result: PollDemandResult): PollDemandResponseDto {
   return {
     stats: result.stats.map((stat) => ({
+      ...(stat.workspaceId ? {workspace_id: stat.workspaceId} : {}),
       labels: stat.labels,
       queued: stat.queued,
       reserved: stat.reserved,
@@ -11,10 +12,11 @@ export function toPollDemandResponseDto(result: PollDemandResult): PollDemandRes
     })),
     reservations: result.reservations.map((reservation) => ({
       reservation_id: reservation.reservationId,
+      ...(reservation.workspaceId ? {workspace_id: reservation.workspaceId} : {}),
       labels: reservation.labels,
       count: reservation.count,
       expires_at: reservation.expiresAt.toISOString(),
     })),
-    terminate_provisioned_runner_ids: result.terminateProvisionedRunnerIds,
+    terminate_provider_runner_ids: result.terminateRunnerInstanceIds,
   };
 }

package/src/presentation/dto/provisioner-token.ts

@@ -3,6 +3,7 @@ import type {ProvisionerToken} from '#core/entities/provisioner-token.js';
 export function toProvisionerTokenDto(token: ProvisionerToken): {
   id: string;
   workspace_id: string;
+  scope: 'workspace';
   prefix: string;
   name: string | null;
   created_by_user_id: string;
@@ -13,6 +14,9 @@ export function toProvisionerTokenDto(token: ProvisionerToken): {
   created_at: string;
   updated_at: string;
 } {
+  if (token.scope !== 'workspace') {
+    throw new Error('Installation provisioner tokens cannot be returned from workspace routes');
+  }
   return {
     id: token.id,
     workspace_id: token.workspaceId,
@@ -25,5 +29,6 @@ export function toProvisionerTokenDto(token: ProvisionerToken): {
     last_seen_at: token.lastSeenAt?.toISOString() ?? null,
     created_at: token.createdAt.toISOString(),
     updated_at: token.updatedAt.toISOString(),
+    scope: 'workspace',
   };
 }

package/src/presentation/dto/{provisioned-runners.ts → runner-instances.ts}

@@ -1,10 +1,10 @@
 import type {
   ActiveRunner,
-  ReconcileProvisionedRunnersResult,
-  ReportProvisionedRunnersResult,
-} from '#core/provisioned-runners.js';
+  ReconcileRunnerInstancesResult,
+  ReportRunnerInstancesResult,
+} from '#core/runner-instances.js';
 
-export function toReportProvisionedRunnersResponseDto(result: ReportProvisionedRunnersResult): {
+export function toReportRunnerInstancesResponseDto(result: ReportRunnerInstancesResult): {
   accepted: number;
   reservations_released: number;
 } {
@@ -14,12 +14,10 @@ export function toReportProvisionedRunnersResponseDto(result: ReportProvisionedR
   };
 }
 
-export function toReconcileProvisionedRunnersResponseDto(
-  result: ReconcileProvisionedRunnersResult,
-): {
+export function toReconcileRunnerInstancesResponseDto(result: ReconcileRunnerInstancesResult): {
   runners: Array<{
-    provisioned_runner_id: string;
-    state: ReconcileProvisionedRunnersResult['runners'][number]['state'];
+    provider_runner_id: string;
+    state: ReconcileRunnerInstancesResult['runners'][number]['state'];
     reservation_id: string | null;
     runner_session_id: string | null;
     bound_job: {
@@ -28,13 +26,13 @@ export function toReconcileProvisionedRunnersResponseDto(
       last_heartbeat_at: string;
       cancellation_requested_at: string | null;
     } | null;
-    desired_intent: ReconcileProvisionedRunnersResult['runners'][number]['desiredIntent'];
+    desired_intent: ReconcileRunnerInstancesResult['runners'][number]['desiredIntent'];
   }>;
-  terminated_absent_provisioned_runner_ids: string[];
+  terminated_absent_provider_runner_ids: string[];
 } {
   return {
     runners: result.runners.map((runner) => ({
-      provisioned_runner_id: runner.provisionedRunnerId,
+      provider_runner_id: runner.providerRunnerId,
       state: runner.state,
       reservation_id: runner.reservationId,
       runner_session_id: runner.runnerSessionId,
@@ -49,14 +47,14 @@ export function toReconcileProvisionedRunnersResponseDto(
         : null,
       desired_intent: runner.desiredIntent,
     })),
-    terminated_absent_provisioned_runner_ids: result.terminatedAbsentProvisionedRunnerIds,
+    terminated_absent_provider_runner_ids: result.terminatedAbsentRunnerInstanceIds,
   };
 }
 
 export function toActiveRunnersResponseDto(runners: ActiveRunner[]): {
   runners: Array<{
     runner_session_id: string | null;
-    provisioned_runner_id: string | null;
+    provider_runner_id: string | null;
     provisioner_id: string | null;
     state: ActiveRunner['state'];
     labels: string[];
@@ -72,7 +70,7 @@ export function toActiveRunnersResponseDto(runners: ActiveRunner[]): {
   return {
     runners: runners.map((runner) => ({
       runner_session_id: runner.runnerSessionId,
-      provisioned_runner_id: runner.provisionedRunnerId,
+      provider_runner_id: runner.providerRunnerId,
       provisioner_id: runner.provisionerId,
       state: runner.state,
       labels: runner.labels,

package/src/presentation/index.ts

@@ -1,6 +1,7 @@
 export {
   createProvisionerTokenAuthMethod,
+  createRunnerControlSessionAuthMethod,
   createRunnerRegistrationTokenAuthMethod,
 } from './auth/index.js';
-export {runnerRoutes as routes} from './routes/index.js';
+export {createRunnerRoutes, createRunnerRoutes as routes} from './routes/index.js';
 export {onWorkflowsJobExecutionTimedOut} from './subscribers/on-workflows-job-execution-timed-out.js';

package/src/presentation/inter-module.test.ts

@@ -0,0 +1,15 @@
+import {runnersInterModuleContract} from '@shipfox/api-runners-dto/inter-module';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
+import {EmptyRequiredLabelsError} from '#core/errors.js';
+import {toEnqueueJobExecutionKnownError} from './inter-module.js';
+
+describe('Runners inter-module presentation', () => {
+  test('maps empty scheduling labels to the published contract error', () => {
+    const result = toEnqueueJobExecutionKnownError(new EmptyRequiredLabelsError());
+
+    expect(
+      isInterModuleKnownError(runnersInterModuleContract.methods.enqueueJobExecution, result) &&
+        result.code,
+    ).toBe('empty-required-labels');
+  });
+});

package/src/presentation/inter-module.ts

@@ -0,0 +1,53 @@
+import {runnersInterModuleContract} from '@shipfox/api-runners-dto/inter-module';
+import {
+  createInterModuleKnownError,
+  defineInterModulePresentation,
+  type InterModulePresentation,
+} from '@shipfox/inter-module';
+import {EmptyRequiredLabelsError} from '#core/errors.js';
+import {getEffectiveRunnerToolCapabilities} from '#core/runner-tool-capabilities.js';
+import {
+  cancelRunnerJobs,
+  enqueueJobExecution,
+  isJobLeaseActive,
+  releaseJobExecution,
+} from '#db/job-executions.js';
+
+export function createRunnersInterModulePresentation(): InterModulePresentation<
+  typeof runnersInterModuleContract
+> {
+  return defineInterModulePresentation(runnersInterModuleContract, {
+    enqueueJobExecution: async (input) => {
+      try {
+        await enqueueJobExecution(input);
+        return {};
+      } catch (error) {
+        throw toEnqueueJobExecutionKnownError(error);
+      }
+    },
+    releaseJobExecution: async (input) => {
+      await releaseJobExecution(input);
+      return {};
+    },
+    cancelJobs: async (input) => {
+      await cancelRunnerJobs(input);
+      return {};
+    },
+    getLeaseState: async (input) => ({active: await isJobLeaseActive(input)}),
+    getEffectiveRunnerToolCapabilities: async (input) => {
+      const result = await getEffectiveRunnerToolCapabilities(input);
+      return {capabilities: result.capabilities, reportFresh: result.reportFresh};
+    },
+  });
+}
+
+export function toEnqueueJobExecutionKnownError(error: unknown): unknown {
+  if (error instanceof EmptyRequiredLabelsError) {
+    return createInterModuleKnownError(
+      runnersInterModuleContract.methods.enqueueJobExecution,
+      'empty-required-labels',
+      {},
+    );
+  }
+  return error;
+}

package/src/presentation/routes/assign-capacity.ts

@@ -0,0 +1,48 @@
+import {requireProvisionerContext} from '@shipfox/api-auth-context';
+import {
+  assignCapacityBatchBodySchema,
+  assignCapacityBatchResponseSchema,
+} from '@shipfox/api-runners-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {assignCapacityBatch} from '#core/capacity-assignments.js';
+import {
+  CapacityAlreadyAssignedError,
+  CapacityNotAssignableError,
+  ReservationExpiredError,
+  ReservationNotFoundError,
+} from '#core/errors.js';
+
+export const assignCapacityRoute = defineRoute({
+  method: 'POST',
+  path: '/capacity/assignments',
+  description: 'Atomically assign provisioner capacity to a live reservation',
+  schema: {body: assignCapacityBatchBodySchema, response: {200: assignCapacityBatchResponseSchema}},
+  errorHandler: (error) => {
+    if (error instanceof ReservationNotFoundError)
+      throw new ClientError('Reservation not found', 'reservation-not-found', {status: 404});
+    if (error instanceof ReservationExpiredError)
+      throw new ClientError('Reservation has expired', 'reservation-expired', {status: 409});
+    if (
+      error instanceof CapacityAlreadyAssignedError ||
+      error instanceof CapacityNotAssignableError
+    )
+      throw new ClientError('Capacity cannot be assigned', 'capacity-not-assignable', {
+        status: 409,
+      });
+    throw error;
+  },
+  handler: async (request) => {
+    const {provisionerTokenId} = requireProvisionerContext(request);
+    const assignments = await assignCapacityBatch({
+      provisionerId: provisionerTokenId,
+      reservationId: request.body.reservation_id,
+      capacityIds: request.body.capacity_ids,
+    });
+    return {
+      assignments: assignments.map((assignment) => ({
+        capacity_id: assignment.capacityId,
+        assignment_id: assignment.id,
+      })),
+    };
+  },
+});