@shipfox/api-runners 4.0.0 → 6.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-runners",
   "license": "MIT",
-  "version": "4.0.0",
+  "version": "6.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -13,43 +13,35 @@
   "types": "dist/index.d.ts",
   "imports": {
     "#test/*": "./test/*",
-    "#*": {
-      "workspace-source": "./src/*",
-      "development": "./src/*",
-      "default": "./dist/*"
-    }
+    "#*": "./dist/*"
   },
   "exports": {
     ".": {
-      "development": {
-        "types": "./src/index.ts",
-        "default": "./src/index.ts"
-      },
-      "default": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "@temporalio/workflow": "1.18.1",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-auth": "4.0.0",
-    "@shipfox/api-auth-context": "3.0.0",
-    "@shipfox/api-runners-dto": "2.0.0",
-    "@shipfox/api-workflows-dto": "2.0.0",
-    "@shipfox/config": "1.2.1",
-    "@shipfox/node-drizzle": "0.3.0",
-    "@shipfox/node-fastify": "0.2.2",
-    "@shipfox/node-module": "0.3.1",
-    "@shipfox/node-opentelemetry": "0.5.1",
-    "@shipfox/node-outbox": "0.2.2",
-    "@shipfox/node-postgres": "0.4.1",
-    "@shipfox/node-rate-limit": "0.2.0",
-    "@shipfox/node-temporal": "0.3.0",
-    "@shipfox/node-tokens": "0.2.0",
-    "@shipfox/runner-labels": "0.1.0"
+    "@shipfox/api-auth-context": "6.0.0",
+    "@shipfox/api-auth-dto": "6.0.0",
+    "@shipfox/api-runners-dto": "6.0.0",
+    "@shipfox/api-workflows-dto": "6.0.0",
+    "@shipfox/config": "1.2.2",
+    "@shipfox/node-drizzle": "0.3.2",
+    "@shipfox/node-auth-root-key": "0.2.0",
+    "@shipfox/node-fastify": "0.2.4",
+    "@shipfox/node-opentelemetry": "0.5.2",
+    "@shipfox/node-outbox": "0.2.4",
+    "@shipfox/inter-module": "0.2.0",
+    "@shipfox/node-module": "0.4.0",
+    "@shipfox/node-postgres": "0.4.2",
+    "@shipfox/node-tokens": "0.3.0",
+    "@shipfox/node-temporal": "0.3.2",
+    "@shipfox/runner-labels": "0.1.1",
+    "@shipfox/node-rate-limit": "0.3.0"
   },
   "devDependencies": {
     "@temporalio/activity": "1.18.1",
@@ -62,18 +54,21 @@
     "fastify": "^5.3.3",
     "fastify-type-provider-zod": "^6.0.0",
     "fishery": "^2.4.0",
-    "@shipfox/api-auth-dto": "2.0.0",
-    "@shipfox/biome": "1.8.1",
-    "@shipfox/node-jwt": "0.2.0",
-    "@shipfox/swc": "1.2.5",
-    "@shipfox/ts-config": "1.3.8",
-    "@shipfox/typescript": "1.1.6",
-    "@shipfox/vitest": "1.2.2"
+    "@shipfox/api-auth": "6.0.0",
+    "@shipfox/api-auth-dto": "6.0.0",
+    "@shipfox/biome": "1.8.2",
+    "@shipfox/depcruise": "1.0.2",
+    "@shipfox/node-jwt": "0.3.0",
+    "@shipfox/swc": "1.2.6",
+    "@shipfox/typescript": "1.1.7",
+    "@shipfox/vitest": "1.2.3",
+    "@shipfox/ts-config": "1.3.8"
   },
   "scripts": {
     "build": "shipfox-swc && shipfox-temporal-bundle dist/temporal/workflows/index.js",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
     "test": "shipfox-vitest-run",
     "test:watch": "shipfox-vitest-watch",
     "type": "shipfox-tsc-check",

package/src/config.test.ts

@@ -27,7 +27,6 @@ describe('EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS validation', () => {
     expect(config.EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS).toBe(3600);
   });
 });
-
 describe('REGISTRATION_TOKEN_BATCH_MAX validation', () => {
   afterEach(() => {
     vi.unstubAllEnvs();
@@ -85,31 +84,6 @@ describe.each([
   });
 });
 
-describe('RATE_LIMIT_IDENTIFIER_SECRET validation', () => {
-  afterEach(() => {
-    vi.unstubAllEnvs();
-    vi.resetModules();
-  });
-
-  it('allows the secret to be omitted', async () => {
-    const previous = process.env.RATE_LIMIT_IDENTIFIER_SECRET;
-    delete process.env.RATE_LIMIT_IDENTIFIER_SECRET;
-    vi.resetModules();
-
-    try {
-      const {config} = await import('#config.js');
-
-      expect(config.RATE_LIMIT_IDENTIFIER_SECRET).toBeUndefined();
-    } finally {
-      if (previous === undefined) {
-        delete process.env.RATE_LIMIT_IDENTIFIER_SECRET;
-      } else {
-        process.env.RATE_LIMIT_IDENTIFIER_SECRET = previous;
-      }
-    }
-  });
-});
-
 describe('RUNNER_NO_FIRST_HEARTBEAT_GRACE_SECONDS validation', () => {
   afterEach(() => {
     vi.unstubAllEnvs();

package/src/config.ts

@@ -1,10 +1,31 @@
 import {REGISTRATION_TOKEN_BATCH_HARD_MAX} from '@shipfox/api-runners-dto';
-import {bool, createConfig, num, str} from '@shipfox/config';
+import {bool, createConfig, num} from '@shipfox/config';
 import {STUCK_JOB_THRESHOLD_SECONDS} from '#core/maintenance-policy.js';
 
 const EPHEMERAL_REGISTRATION_TOKEN_TTL_HARD_MAX_SECONDS = 3600;
+const RUNNER_CONTROL_PLANE_TOKEN_TTL_HARD_MAX_SECONDS = 3600;
 
 export const config = createConfig({
+  RUNNER_BOOTSTRAP_TOKEN_TTL_SECONDS: num({
+    desc: 'Lifetime of a one-use runner bootstrap token in seconds. The token can only create one runner-control session before it expires.',
+    default: 300,
+  }),
+  RUNNER_CONTROL_SESSION_TTL_SECONDS: num({
+    desc: 'Lifetime of a pre-workspace runner-control session in seconds. This session can only enroll, attach its provider identity, and report its own liveness.',
+    default: 3600,
+  }),
+  RUNNER_ACTIVATION_TOKEN_TTL_SECONDS: num({
+    desc: 'Lifetime of a one-use activation token in seconds. The token is issued only to an assigned runner-control session and creates one workspace runner session.',
+    default: 300,
+  }),
+  RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS: num({
+    desc: 'Maximum time the runner assignment poll waits before returning no assignment, in seconds.',
+    default: 30,
+  }),
+  RUNNER_ASSIGNMENT_POLL_INTERVAL_MS: num({
+    desc: 'Delay between durable assignment reads while a runner-control session waits for an assignment, in milliseconds.',
+    default: 1000,
+  }),
   EPHEMERAL_REGISTRATION_TOKEN_TTL_SECONDS: num({
     desc: `Lifetime of a provisioner-minted runner registration token, in seconds. The token can be exchanged once by a runner before this time passes. Set this between 1 and ${EPHEMERAL_REGISTRATION_TOKEN_TTL_HARD_MAX_SECONDS}.`,
     default: 300,
@@ -33,10 +54,6 @@ export const config = createConfig({
     desc: 'Maximum time, in milliseconds, a runners rate-limit storage check may wait before the request fails closed.',
     default: 250,
   }),
-  RATE_LIMIT_IDENTIFIER_SECRET: str({
-    desc: 'Optional secret used to HMAC identifiers before storing rate-limit counters. Leave it unset to derive a stable key from AUTH_JWT_SECRET.',
-    default: undefined,
-  }),
   RESERVATION_TTL_SECONDS: num({
     desc: 'Lifetime of a count-based runner reservation, in seconds. Expired reservations stop counting against queued demand.',
     default: 60,
@@ -110,7 +127,7 @@ export const config = createConfig({
     default: 10,
   }),
   PROVISIONED_RUNNER_COUNT_DIVERGENCE_TEMPLATE_KEY_LABEL_ENABLED: bool({
-    desc: 'Whether runners_provisioned_runner_count_divergence includes template_key as a metric label. Use true or false. Defaults to false because template keys can create high-cardinality metric series. Set true only when template keys are bounded and stable.',
+    desc: 'Whether runners_provider_runner_count_divergence includes template_key as a metric label. Use true or false. Defaults to false because template keys can create high-cardinality metric series. Set true only when template keys are bounded and stable.',
     default: false,
   }),
 });
@@ -126,6 +143,30 @@ if (
   );
 }
 
+for (const [name, value] of [
+  ['RUNNER_BOOTSTRAP_TOKEN_TTL_SECONDS', config.RUNNER_BOOTSTRAP_TOKEN_TTL_SECONDS],
+  ['RUNNER_CONTROL_SESSION_TTL_SECONDS', config.RUNNER_CONTROL_SESSION_TTL_SECONDS],
+  ['RUNNER_ACTIVATION_TOKEN_TTL_SECONDS', config.RUNNER_ACTIVATION_TOKEN_TTL_SECONDS],
+] as const) {
+  if (
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > RUNNER_CONTROL_PLANE_TOKEN_TTL_HARD_MAX_SECONDS
+  ) {
+    throw new Error(
+      `${name} (${value}) must be a whole number of seconds between 1 and ${RUNNER_CONTROL_PLANE_TOKEN_TTL_HARD_MAX_SECONDS}.`,
+    );
+  }
+}
+
+for (const [name, value] of [
+  ['RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS', config.RUNNER_ASSIGNMENT_POLL_MAX_WAIT_SECONDS],
+  ['RUNNER_ASSIGNMENT_POLL_INTERVAL_MS', config.RUNNER_ASSIGNMENT_POLL_INTERVAL_MS],
+] as const) {
+  if (!Number.isInteger(value) || value < 0)
+    throw new Error(`${name} (${value}) must be a whole number >= 0.`);
+}
+
 if (
   !Number.isInteger(config.REGISTRATION_TOKEN_BATCH_MAX) ||
   config.REGISTRATION_TOKEN_BATCH_MAX < 1 ||

package/src/core/capacity-assignments.ts

@@ -0,0 +1,10 @@
+import {assignCapacityBatch as assignCapacityBatchDb} from '#db/capacity-assignments.js';
+import type {CapacityAssignment} from './entities/capacity-assignment.js';
+
+export function assignCapacityBatch(params: {
+  provisionerId: string;
+  reservationId: string;
+  capacityIds: string[];
+}): Promise<CapacityAssignment[]> {
+  return assignCapacityBatchDb(params);
+}

package/src/core/demand.test.ts

@@ -1,12 +1,12 @@
 import {
-  calculateProvisionedRunnerCountDivergences,
+  calculateRunnerInstanceCountDivergences,
   nextBackoffInterval,
   pollDemand,
   shouldReturn,
 } from '#core/demand.js';
 
 describe('shouldReturn', () => {
-  const emptyResult = {stats: [], reservations: [], terminateProvisionedRunnerIds: []};
+  const emptyResult = {stats: [], reservations: [], terminateRunnerInstanceIds: []};
 
   it('returns true for observe-only requests', () => {
     const result = shouldReturn(emptyResult, 0, 1, false);
@@ -27,7 +27,7 @@ describe('shouldReturn', () => {
         reservations: [
           {reservationId: crypto.randomUUID(), labels: ['linux'], count: 1, expiresAt: new Date()},
         ],
-        terminateProvisionedRunnerIds: [],
+        terminateRunnerInstanceIds: [],
       },
       1,
       1,
@@ -39,7 +39,7 @@ describe('shouldReturn', () => {
 
   it('returns true when terminate intents exist', () => {
     const result = shouldReturn(
-      {...emptyResult, terminateProvisionedRunnerIds: ['provisioned-runner-1']},
+      {...emptyResult, terminateRunnerInstanceIds: ['provisioned-runner-1']},
       1,
       1,
       false,
@@ -76,7 +76,7 @@ describe('pollDemand', () => {
       signal: new AbortController().signal,
     });
 
-    expect(result).toEqual({stats: [], reservations: [], terminateProvisionedRunnerIds: []});
+    expect(result).toEqual({stats: [], reservations: [], terminateRunnerInstanceIds: []});
   });
 
   it('returns immediately when terminate intents exist without reservation demand', async () => {
@@ -84,8 +84,8 @@ describe('pollDemand', () => {
     const pollDemandAndReserveTx = vi.fn().mockResolvedValue({stats: [], reservations: []});
     const listProvisionerTerminateIntentRowsTx = vi
       .fn()
-      .mockResolvedValue([{provisionedRunnerId: 'provisioned-runner-1', reason: 'job-cancelled'}]);
-    const listActiveProvisionedRunnerCountsByTemplateTx = vi.fn().mockResolvedValue([]);
+      .mockResolvedValue([{providerRunnerId: 'provisioned-runner-1', reason: 'job-cancelled'}]);
+    const listActiveRunnerInstanceCountsByTemplateTx = vi.fn().mockResolvedValue([]);
     vi.doMock('#db/db.js', () => ({
       db: () => ({transaction: (callback: (tx: unknown) => Promise<unknown>) => callback({})}),
     }));
@@ -93,8 +93,8 @@ describe('pollDemand', () => {
       deleteReservationsByIds: vi.fn(),
       pollDemandAndReserveTx,
     }));
-    vi.doMock('#db/provisioned-runners.js', () => ({
-      listActiveProvisionedRunnerCountsByTemplateTx,
+    vi.doMock('#db/runner-instances.js', () => ({
+      listActiveRunnerInstanceCountsByTemplateTx,
       listProvisionerTerminateIntentRowsTx,
     }));
 
@@ -117,14 +117,14 @@ describe('pollDemand', () => {
       expect(result).toEqual({
         stats: [],
         reservations: [],
-        terminateProvisionedRunnerIds: ['provisioned-runner-1'],
+        terminateRunnerInstanceIds: ['provisioned-runner-1'],
       });
       expect(pollDemandAndReserveTx).toHaveBeenCalledOnce();
       expect(listProvisionerTerminateIntentRowsTx).toHaveBeenCalledOnce();
     } finally {
       vi.doUnmock('#db/db.js');
       vi.doUnmock('#db/reservations.js');
-      vi.doUnmock('#db/provisioned-runners.js');
+      vi.doUnmock('#db/runner-instances.js');
       vi.resetModules();
     }
   });
@@ -137,7 +137,7 @@ describe('pollDemand', () => {
       abortController.abort();
       return [];
     });
-    const listActiveProvisionedRunnerCountsByTemplateTx = vi.fn().mockResolvedValue([]);
+    const listActiveRunnerInstanceCountsByTemplateTx = vi.fn().mockResolvedValue([]);
     vi.doMock('#db/db.js', () => ({
       db: () => ({transaction: (callback: (tx: unknown) => Promise<unknown>) => callback({})}),
     }));
@@ -145,8 +145,8 @@ describe('pollDemand', () => {
       deleteReservationsByIds: vi.fn(),
       pollDemandAndReserveTx,
     }));
-    vi.doMock('#db/provisioned-runners.js', () => ({
-      listActiveProvisionedRunnerCountsByTemplateTx,
+    vi.doMock('#db/runner-instances.js', () => ({
+      listActiveRunnerInstanceCountsByTemplateTx,
       listProvisionerTerminateIntentRowsTx,
     }));
 
@@ -166,12 +166,12 @@ describe('pollDemand', () => {
         signal: abortController.signal,
       });
 
-      expect(result).toEqual({stats: [], reservations: [], terminateProvisionedRunnerIds: []});
-      expect(listActiveProvisionedRunnerCountsByTemplateTx).not.toHaveBeenCalled();
+      expect(result).toEqual({stats: [], reservations: [], terminateRunnerInstanceIds: []});
+      expect(listActiveRunnerInstanceCountsByTemplateTx).not.toHaveBeenCalled();
     } finally {
       vi.doUnmock('#db/db.js');
       vi.doUnmock('#db/reservations.js');
-      vi.doUnmock('#db/provisioned-runners.js');
+      vi.doUnmock('#db/runner-instances.js');
       vi.resetModules();
     }
   });
@@ -182,7 +182,7 @@ describe('pollDemand', () => {
     const divergenceAdd = vi.fn();
     const pollDemandAndReserveTx = vi.fn().mockResolvedValue({stats: [], reservations: []});
     const listProvisionerTerminateIntentRowsTx = vi.fn().mockResolvedValue([]);
-    const listActiveProvisionedRunnerCountsByTemplateTx = vi
+    const listActiveRunnerInstanceCountsByTemplateTx = vi
       .fn()
       .mockResolvedValue([{templateKey: 'linux', state: 'running', count: 2}]);
     vi.doMock('#db/db.js', () => ({
@@ -192,13 +192,13 @@ describe('pollDemand', () => {
       deleteReservationsByIds: vi.fn(),
       pollDemandAndReserveTx,
     }));
-    vi.doMock('#db/provisioned-runners.js', () => ({
-      listActiveProvisionedRunnerCountsByTemplateTx,
+    vi.doMock('#db/runner-instances.js', () => ({
+      listActiveRunnerInstanceCountsByTemplateTx,
       listProvisionerTerminateIntentRowsTx,
     }));
     vi.doMock('#metrics/instance.js', () => ({
-      provisionedRunnerCountDivergenceCount: {add: divergenceAdd},
-      provisionedRunnerTerminateIntentIssuedCount: {add: vi.fn()},
+      providerRunnerCountDivergenceCount: {add: divergenceAdd},
+      providerRunnerTerminateIntentIssuedCount: {add: vi.fn()},
     }));
 
     try {
@@ -217,7 +217,7 @@ describe('pollDemand', () => {
         signal: new AbortController().signal,
       });
 
-      expect(result).toEqual({stats: [], reservations: [], terminateProvisionedRunnerIds: []});
+      expect(result).toEqual({stats: [], reservations: [], terminateRunnerInstanceIds: []});
       expect(divergenceAdd).toHaveBeenCalledWith(1, {
         template_key: 'linux',
         state: 'running',
@@ -227,16 +227,16 @@ describe('pollDemand', () => {
       vi.unstubAllEnvs();
       vi.doUnmock('#db/db.js');
       vi.doUnmock('#db/reservations.js');
-      vi.doUnmock('#db/provisioned-runners.js');
+      vi.doUnmock('#db/runner-instances.js');
       vi.doUnmock('#metrics/instance.js');
       vi.resetModules();
     }
   });
 });
 
-describe('calculateProvisionedRunnerCountDivergences', () => {
+describe('calculateRunnerInstanceCountDivergences', () => {
   it('returns no divergences when advertised and backend counts match', () => {
-    const result = calculateProvisionedRunnerCountDivergences({
+    const result = calculateRunnerInstanceCountDivergences({
       advertisedTemplates: [template('linux', 1, 2)],
       backendCounts: [
         {templateKey: 'linux', state: 'starting', count: 1},
@@ -248,7 +248,7 @@ describe('calculateProvisionedRunnerCountDivergences', () => {
   });
 
   it('detects backend-higher and advertised-higher counts', () => {
-    const result = calculateProvisionedRunnerCountDivergences({
+    const result = calculateRunnerInstanceCountDivergences({
       advertisedTemplates: [template('linux', 1, 5)],
       backendCounts: [
         {templateKey: 'linux', state: 'starting', count: 3},
@@ -263,7 +263,7 @@ describe('calculateProvisionedRunnerCountDivergences', () => {
   });
 
   it('aggregates duplicate advertised template keys before comparing', () => {
-    const result = calculateProvisionedRunnerCountDivergences({
+    const result = calculateRunnerInstanceCountDivergences({
       advertisedTemplates: [template('linux', 1, 1), template('linux', 2, 3)],
       backendCounts: [
         {templateKey: 'linux', state: 'starting', count: 3},
@@ -275,7 +275,7 @@ describe('calculateProvisionedRunnerCountDivergences', () => {
   });
 
   it('detects backend-only template keys as backend-higher', () => {
-    const result = calculateProvisionedRunnerCountDivergences({
+    const result = calculateRunnerInstanceCountDivergences({
       advertisedTemplates: [template('linux', 0, 0)],
       backendCounts: [{templateKey: 'gpu', state: 'running', count: 2}],
     });

package/src/core/demand.ts

@@ -2,12 +2,6 @@ import {setTimeout as sleep} from 'node:timers/promises';
 import {logger} from '@shipfox/node-opentelemetry';
 import {config} from '#config.js';
 import {db} from '#db/db.js';
-import {
-  type ActiveProvisionedRunnerTemplateCount,
-  listActiveProvisionedRunnerCountsByTemplateTx,
-  listProvisionerTerminateIntentRowsTx,
-  type ProvisionedRunnerTerminateIntent,
-} from '#db/provisioned-runners.js';
 import {
   type DemandStat,
   deleteReservationsByIds,
@@ -16,8 +10,14 @@ import {
   type ReservationTemplate,
 } from '#db/reservations.js';
 import {
-  provisionedRunnerCountDivergenceCount,
-  provisionedRunnerTerminateIntentIssuedCount,
+  type ActiveRunnerInstanceTemplateCount,
+  listActiveRunnerInstanceCountsByTemplateTx,
+  listProvisionerTerminateIntentRowsTx,
+  type RunnerInstanceTerminateIntent,
+} from '#db/runner-instances.js';
+import {
+  providerRunnerCountDivergenceCount,
+  providerRunnerTerminateIntentIssuedCount,
 } from '#metrics/instance.js';
 
 export interface PollDemandParams {
@@ -34,10 +34,10 @@ export interface PollDemandParams {
 export interface PollDemandResult {
   stats: DemandStat[];
   reservations: ReservationGrant[];
-  terminateProvisionedRunnerIds: string[];
+  terminateRunnerInstanceIds: string[];
 }
 
-export interface ProvisionedRunnerCountDivergence {
+export interface RunnerInstanceCountDivergence {
   templateKey: string;
   state: 'starting' | 'running';
   direction: 'backend-higher' | 'advertised-higher';
@@ -46,8 +46,8 @@ export interface ProvisionedRunnerCountDivergence {
 
 interface PollDemandSnapshot {
   result: PollDemandResult;
-  divergences: ProvisionedRunnerCountDivergence[];
-  terminateIntents: ProvisionedRunnerTerminateIntent[];
+  divergences: RunnerInstanceCountDivergence[];
+  terminateIntents: RunnerInstanceTerminateIntent[];
 }
 
 export async function pollDemand(params: PollDemandParams): Promise<PollDemandResult> {
@@ -62,7 +62,7 @@ export async function pollDemand(params: PollDemandParams): Promise<PollDemandRe
   );
   let interval = config.RESERVATION_POLL_INTERVAL_MS;
   let lastSnapshot: PollDemandSnapshot = {
-    result: {stats: [], reservations: [], terminateProvisionedRunnerIds: []},
+    result: {stats: [], reservations: [], terminateRunnerInstanceIds: []},
     divergences: [],
     terminateIntents: [],
   };
@@ -87,7 +87,7 @@ export async function pollDemand(params: PollDemandParams): Promise<PollDemandRe
       });
       const result: PollDemandResult = {
         ...demand,
-        terminateProvisionedRunnerIds: terminateIntents.map((intent) => intent.provisionedRunnerId),
+        terminateRunnerInstanceIds: terminateIntents.map((intent) => intent.providerRunnerId),
       };
 
       if (!shouldReturn(result, params.maxReservations, totalCapacity, deadlinePassed)) {
@@ -97,9 +97,9 @@ export async function pollDemand(params: PollDemandParams): Promise<PollDemandRe
       return {
         result,
         terminateIntents,
-        divergences: calculateProvisionedRunnerCountDivergences({
+        divergences: calculateRunnerInstanceCountDivergences({
           advertisedTemplates: params.templates,
-          backendCounts: await listActiveProvisionedRunnerCountsByTemplateTx(tx, {
+          backendCounts: await listActiveRunnerInstanceCountsByTemplateTx(tx, {
             workspaceId: params.workspaceId,
             provisionerId: params.provisionerId,
           }),
@@ -145,7 +145,7 @@ export function shouldReturn(
     maxReservations === 0 ||
     totalCapacity === 0 ||
     result.reservations.length > 0 ||
-    result.terminateProvisionedRunnerIds.length > 0 ||
+    result.terminateRunnerInstanceIds.length > 0 ||
     deadlinePassed
   );
 }
@@ -158,10 +158,10 @@ export function withJitter(ms: number): number {
   return Math.random() * ms;
 }
 
-export function calculateProvisionedRunnerCountDivergences(params: {
+export function calculateRunnerInstanceCountDivergences(params: {
   advertisedTemplates: ReservationTemplate[];
-  backendCounts: ActiveProvisionedRunnerTemplateCount[];
-}): ProvisionedRunnerCountDivergence[] {
+  backendCounts: ActiveRunnerInstanceTemplateCount[];
+}): RunnerInstanceCountDivergence[] {
   const advertisedCounts = new Map<string, number>();
   const backendCounts = new Map<string, number>();
 
@@ -212,10 +212,10 @@ function recordPollDemandMetrics(params: PollDemandParams, snapshot: PollDemandS
         ? {template_key: divergence.templateKey}
         : {}),
     };
-    provisionedRunnerCountDivergenceCount.add(divergence.delta, attributes);
+    providerRunnerCountDivergenceCount.add(divergence.delta, attributes);
   }
   for (const intent of snapshot.terminateIntents) {
-    provisionedRunnerTerminateIntentIssuedCount.add(1, {
+    providerRunnerTerminateIntentIssuedCount.add(1, {
       surface: 'poll-demand',
       reason: intent.reason,
     });

package/src/core/entities/capacity-assignment.ts

@@ -0,0 +1,8 @@
+export interface CapacityAssignment {
+  id: string;
+  capacityId: string;
+  reservationId: string;
+  workspaceId: string;
+  provisionerId: string;
+  createdAt: Date;
+}

package/src/core/entities/ephemeral-registration-token.ts

@@ -3,7 +3,7 @@ export interface EphemeralRegistrationToken {
   workspaceId: string;
   provisionerId: string;
   reservationId: string | null;
-  provisionedRunnerId: string;
+  providerRunnerId: string;
   hashedToken: string;
   prefix: string;
   expiresAt: Date;

package/src/core/entities/provisioner-capability-snapshot.ts

@@ -0,0 +1,12 @@
+export interface ProvisionerCapabilitySnapshot {
+  id: string;
+  workspaceId: string;
+  provisionerId: string;
+  templateKey: string;
+  labels: string[];
+  availableSlots: number;
+  starting: number;
+  running: number;
+  advertisedAt: Date;
+  createdAt: Date;
+}

package/src/core/entities/provisioner-token.ts

@@ -1,6 +1,8 @@
-export interface ProvisionerToken {
+export type ProvisionerScope = 'installation' | 'workspace';
+
+export interface ProvisionerTokenBase {
   id: string;
-  workspaceId: string;
+  scope: ProvisionerScope;
   hashedToken: string;
   prefix: string;
   name: string | null;
@@ -13,4 +15,8 @@ export interface ProvisionerToken {
   updatedAt: Date;
 }
 
+export type ProvisionerToken =
+  | (ProvisionerTokenBase & {scope: 'installation'; workspaceId: null})
+  | (ProvisionerTokenBase & {scope: 'workspace'; workspaceId: string});
+
 export type ActiveProvisionerToken = ProvisionerToken & {lastSeenAt: Date};

package/src/core/entities/{provisioned-runner.ts → runner-instance.ts}

@@ -1,4 +1,4 @@
-export type ProvisionedRunnerState =
+export type RunnerInstanceState =
   | 'starting'
   | 'running'
   | 'stopping'
@@ -6,15 +6,15 @@ export type ProvisionedRunnerState =
   | 'failed'
   | 'terminated';
 
-export interface ProvisionedRunner {
+export interface RunnerInstance {
   id: string;
-  workspaceId: string;
+  workspaceId: string | null;
   provisionerId: string;
-  provisionedRunnerId: string;
+  providerRunnerId: string;
   reservationId: string | null;
   templateKey: string | null;
   labels: string[];
-  state: ProvisionedRunnerState;
+  state: RunnerInstanceState;
   reason: string | null;
   runnerSessionId: string | null;
   providerKind: string | null;

package/src/core/entities/runner-session.ts

@@ -5,14 +5,16 @@ export interface RunnerSession {
   workspaceId: string;
   scope: 'workspace';
   registrationTokenId: string;
-  registrationTokenKind: 'manual' | 'ephemeral';
+  registrationTokenKind: 'manual' | 'ephemeral' | 'activation';
+  runnerInstanceId: string | null;
   provisionerId: string | null;
-  provisionedRunnerId: string | null;
+  providerRunnerId: string | null;
   labels: string[];
   toolCapabilities: RunnerToolCapabilitiesDto | null;
   toolCapabilitiesReportedAt: Date | null;
   maxClaims: number | null;
   claimsUsed: number;
+  revokedAt: Date | null;
   createdAt: Date;
   updatedAt: Date;
 }