@shipfox/api-triggers 2.0.0

package/src/core/dispatch-integration-event.ts

@@ -0,0 +1,150 @@
+import {isPermanentRunWorkflowError, runWorkflow} from '@shipfox/api-workflows';
+import {findMatchingSubscriptions} from '#db/subscriptions.js';
+import {
+  eventOutcomeCount,
+  eventReceivedCount,
+  subscriptionTriggeredCount,
+} from '#metrics/instance.js';
+import {evaluateTriggerFilter, readConfigInputs} from './config.js';
+import {beginTriggerHistory, toReason} from './record-trigger-history.js';
+import {routeEventToJobListeners} from './route-event-to-job-listeners.js';
+
+export interface DispatchIntegrationEventParams {
+  eventRef: string;
+  workspaceId: string;
+  provider: string;
+  source: string;
+  event: string;
+  deliveryId: string;
+  connectionId: string;
+  connectionName: string | null;
+  payload: unknown;
+  receivedAt: Date;
+}
+
+// Source-agnostic dispatcher: any inbound integration event fans out to every
+// workspace subscription registered for its (source, event) and to every listening
+// job subscribed to it, passing the raw payload through untouched. The module knows
+// nothing about github, gitlab, etc.
+//
+// Continue-on-error: every matched subscription and listener is attempted so one broken
+// subscription cannot starve its siblings. A permanent failure (deleted definition, project
+// mismatch) is recorded and skipped; a transient one is recorded and re-thrown so the outbox
+// replays the whole event and converges (succeeded siblings dedup on the idempotency key). The
+// event reaches a terminal outcome only when no transient error remains: `routed` if any run
+// was created or any listening job matched, `discarded` if nothing matched, otherwise `errored`.
+// History is best-effort; the thrown transient error, not the recorded outcome, drives the retry.
+export async function dispatchIntegrationEvent(
+  params: DispatchIntegrationEventParams,
+): Promise<void> {
+  eventReceivedCount.add(1, {provider: params.provider});
+
+  const history = await beginTriggerHistory({
+    eventRef: params.eventRef,
+    origin: 'integration',
+    workspaceId: params.workspaceId,
+    provider: params.provider,
+    source: params.source,
+    event: params.event,
+    deliveryId: params.deliveryId,
+    connectionId: params.connectionId,
+    connectionName: params.connectionName,
+    payload: (params.payload ?? null) as Record<string, unknown> | null,
+    receivedAt: params.receivedAt,
+  });
+
+  const subscriptions = await findMatchingSubscriptions({
+    workspaceId: params.workspaceId,
+    source: params.source,
+    event: params.event,
+  });
+
+  let triggeredCount = 0;
+  let triggerEngagedCount = 0;
+  let sawTransientError = false;
+  let firstTransientError: unknown;
+
+  for (const subscription of subscriptions) {
+    const filterResult = evaluateTriggerFilter({
+      subscription,
+      source: params.source,
+      event: params.event,
+      payload: params.payload,
+    });
+    if (filterResult.kind === 'filtered') continue;
+    if (filterResult.kind === 'filter-error') {
+      triggerEngagedCount += 1;
+      await history.filterErrored(subscription, filterResult.reason);
+      continue;
+    }
+    triggerEngagedCount += 1;
+
+    try {
+      const run = await runWorkflow({
+        workspaceId: subscription.workspaceId,
+        projectId: subscription.projectId,
+        definitionId: subscription.workflowDefinitionId,
+        triggerPayload: {
+          provider: params.provider,
+          source: params.source,
+          event: params.event,
+          deliveryId: params.deliveryId,
+          data: params.payload,
+        },
+        inputs: readConfigInputs(subscription),
+        triggerIdempotencyKey: `${subscription.id}:${params.eventRef}`,
+      });
+      await history.triggered(subscription, run);
+      triggeredCount += 1;
+      subscriptionTriggeredCount.add(1, {provider: params.provider});
+    } catch (error) {
+      await history.dispatchErrored(subscription, toReason(error));
+      // Track presence with a flag, not `firstTransientError === undefined`: a thrown
+      // value of `undefined` is still a transient failure and must drive the replay.
+      if (!isPermanentRunWorkflowError(error) && !sawTransientError) {
+        sawTransientError = true;
+        firstTransientError = error;
+      }
+    }
+  }
+
+  const listenerResult = await routeEventToJobListeners({
+    history,
+    eventRef: params.eventRef,
+    workspaceId: params.workspaceId,
+    provider: params.provider,
+    source: params.source,
+    event: params.event,
+    deliveryId: params.deliveryId,
+    payload: params.payload,
+    receivedAt: params.receivedAt,
+  });
+
+  if (listenerResult.transientErrored && !sawTransientError) {
+    sawTransientError = true;
+    firstTransientError = listenerResult.transientError;
+  }
+
+  const totalMatchedCount = triggerEngagedCount + listenerResult.engagedCount;
+
+  if (sawTransientError) {
+    eventOutcomeCount.add(1, {provider: params.provider, outcome: 'failed'});
+    await history.failed(totalMatchedCount);
+    throw firstTransientError;
+  }
+
+  if (triggeredCount > 0 || listenerResult.acceptedJobCount > 0) {
+    eventOutcomeCount.add(1, {provider: params.provider, outcome: 'routed'});
+    await history.routed(totalMatchedCount);
+    return;
+  }
+
+  if (totalMatchedCount === 0) {
+    eventOutcomeCount.add(1, {provider: params.provider, outcome: 'discarded'});
+    await history.discarded();
+    return;
+  }
+
+  eventOutcomeCount.add(1, {provider: params.provider, outcome: 'errored'});
+  await history.allErrored(totalMatchedCount);
+}

package/src/core/drain-cron-schedules.test.ts

@@ -0,0 +1,265 @@
+import {eq} from 'drizzle-orm';
+import type {CronSchedule} from '#core/entities/cron-schedule.js';
+import type {TriggerSubscription} from '#core/entities/subscription.js';
+import {countDueCronSchedules} from '#db/cron-schedules.js';
+import {db} from '#db/db.js';
+import {triggersCronSchedules} from '#db/schema/cron-schedules.js';
+import {triggersDecisions} from '#db/schema/decisions.js';
+import {triggersReceivedEvents} from '#db/schema/received-events.js';
+import {cronScheduleFactory, triggerSubscriptionFactory} from '#test/index.js';
+
+const runWorkflow = vi.fn();
+
+vi.mock('@shipfox/api-workflows', () => {
+  class DefinitionNotFoundError extends Error {
+    constructor(definitionId: string) {
+      super(`Definition not found: ${definitionId}`);
+      this.name = 'DefinitionNotFoundError';
+    }
+  }
+  return {
+    runWorkflow: (...args: unknown[]) => runWorkflow(...args),
+    DefinitionNotFoundError,
+    isPermanentRunWorkflowError: (error: unknown) => error instanceof DefinitionNotFoundError,
+  };
+});
+
+import {DefinitionNotFoundError} from '@shipfox/api-workflows';
+
+// Import after mocks so the function under test sees the spy.
+const {drainDueCronSchedules} = await import('./drain-cron-schedules.js');
+
+const MINUTE_MS = 60 * 1000;
+
+// The drain claim is global over a shared test DB, so assertions target the specific
+// subscriptions each test creates (via the deterministic idempotency key) and use
+// lower bounds for any global count, mirroring the prune activity test.
+interface DueCron {
+  subscription: TriggerSubscription;
+  schedule: CronSchedule;
+  key: string;
+}
+
+async function createCronSchedule(params: {
+  nextFireAt: Date;
+  cronExpression?: string;
+  config?: Record<string, unknown>;
+}): Promise<DueCron> {
+  const subscription = await triggerSubscriptionFactory.create({
+    source: 'cron',
+    event: 'tick',
+    config: params.config ?? {},
+  });
+  const schedule = await cronScheduleFactory.create({
+    subscriptionId: subscription.id,
+    workspaceId: subscription.workspaceId,
+    cronExpression: params.cronExpression ?? '*/5 * * * *',
+    timezone: 'UTC',
+    nextFireAt: params.nextFireAt,
+  });
+  return {subscription, schedule, key: `${subscription.id}:${schedule.nextFireAt.toISOString()}`};
+}
+
+function callsWithKey(key: string) {
+  return runWorkflow.mock.calls.filter(
+    ([params]) => (params as {triggerIdempotencyKey?: string}).triggerIdempotencyKey === key,
+  );
+}
+
+async function reload(subscriptionId: string) {
+  const [row] = await db()
+    .select()
+    .from(triggersCronSchedules)
+    .where(eq(triggersCronSchedules.subscriptionId, subscriptionId));
+  if (!row) throw new Error('cron schedule row not found');
+  return row;
+}
+
+describe('drainDueCronSchedules', () => {
+  beforeEach(() => {
+    runWorkflow.mockReset();
+  });
+
+  test('fires a due schedule exactly once, records cron history, and advances next_fire_at', async () => {
+    const {subscription, schedule, key} = await createCronSchedule({
+      nextFireAt: new Date(Date.now() - MINUTE_MS),
+    });
+    const run = {id: crypto.randomUUID(), name: 'Cron run'};
+    runWorkflow.mockResolvedValue(run);
+
+    const summary = await drainDueCronSchedules({batchSize: 1000, jitterWindowSeconds: 0});
+
+    expect(callsWithKey(key)).toHaveLength(1);
+    expect(summary.fired).toBeGreaterThanOrEqual(1);
+    const [event] = await db()
+      .select()
+      .from(triggersReceivedEvents)
+      .where(eq(triggersReceivedEvents.eventRef, key));
+    if (!event) throw new Error('received event not found');
+    expect(event.origin).toBe('cron');
+    expect(event.outcome).toBe('routed');
+    const decisions = await db()
+      .select()
+      .from(triggersDecisions)
+      .where(eq(triggersDecisions.receivedEventId, event.id));
+    expect(decisions[0]?.decision).toBe('triggered');
+    expect(decisions[0]?.runId).toBe(run.id);
+    const row = await reload(subscription.id);
+    expect(row.nextFireAt.getTime()).toBeGreaterThan(Date.now());
+    expect(row.lastFiredAt?.getTime()).toBe(schedule.nextFireAt.getTime());
+  });
+
+  test('does not claim a schedule whose next fire time is still in the future', async () => {
+    const future = new Date(Date.now() + 60 * MINUTE_MS);
+    const {subscription, key} = await createCronSchedule({nextFireAt: future});
+    runWorkflow.mockResolvedValue({id: crypto.randomUUID(), name: 'r'});
+
+    await drainDueCronSchedules({batchSize: 1000, jitterWindowSeconds: 0});
+
+    expect(callsWithKey(key)).toHaveLength(0);
+    const row = await reload(subscription.id);
+    expect(row.nextFireAt.getTime()).toBe(future.getTime());
+    expect(row.lastFiredAt).toBeNull();
+  });
+
+  test('overdue schedule fires once and skips the intermediate windows', async () => {
+    const {subscription, key} = await createCronSchedule({
+      nextFireAt: new Date(Date.now() - 60 * MINUTE_MS),
+      cronExpression: '*/5 * * * *',
+    });
+    runWorkflow.mockResolvedValue({id: crypto.randomUUID(), name: 'r'});
+
+    await drainDueCronSchedules({batchSize: 1000, jitterWindowSeconds: 0});
+
+    expect(callsWithKey(key)).toHaveLength(1);
+    const row = await reload(subscription.id);
+    const now = Date.now();
+    expect(row.nextFireAt.getTime()).toBeGreaterThan(now);
+    expect(row.nextFireAt.getTime()).toBeLessThan(now + 6 * MINUTE_MS);
+  });
+
+  test('passes the deterministic idempotency key and the subscription inputs to runWorkflow', async () => {
+    const {subscription, key} = await createCronSchedule({
+      nextFireAt: new Date(Date.now() - MINUTE_MS),
+      config: {with: {environment: 'staging'}},
+    });
+    runWorkflow.mockResolvedValue({id: crypto.randomUUID(), name: 'r'});
+
+    await drainDueCronSchedules({batchSize: 1000, jitterWindowSeconds: 0});
+
+    const [params] = callsWithKey(key)[0] as [Record<string, unknown>];
+    expect(params.triggerIdempotencyKey).toBe(key);
+    expect(params.inputs).toEqual({environment: 'staging'});
+    expect(params.triggerPayload).toEqual({
+      provider: 'cron',
+      source: 'cron',
+      event: 'tick',
+      scheduleId: subscription.id,
+    });
+  });
+
+  test('records a dispatch-error decision and still advances on a permanent runWorkflow failure', async () => {
+    const {subscription, key} = await createCronSchedule({
+      nextFireAt: new Date(Date.now() - MINUTE_MS),
+    });
+    runWorkflow.mockRejectedValue(new DefinitionNotFoundError('def-gone'));
+
+    await drainDueCronSchedules({batchSize: 1000, jitterWindowSeconds: 0});
+
+    const [event] = await db()
+      .select()
+      .from(triggersReceivedEvents)
+      .where(eq(triggersReceivedEvents.eventRef, key));
+    if (!event) throw new Error('received event not found');
+    expect(event.outcome).toBe('errored');
+    const decisions = await db()
+      .select()
+      .from(triggersDecisions)
+      .where(eq(triggersDecisions.receivedEventId, event.id));
+    expect(decisions[0]?.decision).toBe('dispatch-error');
+    const row = await reload(subscription.id);
+    expect(row.nextFireAt.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  test('leaves the schedule due and unfired on a transient runWorkflow failure', async () => {
+    const {subscription, schedule} = await createCronSchedule({
+      nextFireAt: new Date(Date.now() - MINUTE_MS),
+    });
+    runWorkflow.mockRejectedValue(new Error('database unavailable'));
+
+    await drainDueCronSchedules({batchSize: 1000, jitterWindowSeconds: 0});
+
+    const row = await reload(subscription.id);
+    expect(row.nextFireAt.getTime()).toBe(schedule.nextFireAt.getTime());
+    expect(row.lastFiredAt).toBeNull();
+  });
+
+  test('invokes the liveness callback once per claimed schedule', async () => {
+    await createCronSchedule({nextFireAt: new Date(Date.now() - MINUTE_MS)});
+    runWorkflow.mockResolvedValue({id: crypto.randomUUID(), name: 'r'});
+    const onScheduleProcessed = vi.fn();
+
+    const summary = await drainDueCronSchedules({
+      batchSize: 1000,
+      jitterWindowSeconds: 0,
+      onScheduleProcessed,
+    });
+
+    expect(summary.claimed).toBeGreaterThanOrEqual(1);
+    expect(onScheduleProcessed).toHaveBeenCalledTimes(summary.claimed);
+  });
+
+  test('claims at most batchSize schedules per drain and leaves the rest due', async () => {
+    const mine: DueCron[] = [];
+    for (let index = 0; index < 5; index += 1) {
+      mine.push(await createCronSchedule({nextFireAt: new Date(Date.now() - MINUTE_MS)}));
+    }
+    runWorkflow.mockResolvedValue({id: crypto.randomUUID(), name: 'r'});
+
+    const summary = await drainDueCronSchedules({batchSize: 3, jitterWindowSeconds: 0});
+
+    expect(summary.claimed).toBe(3);
+    expect(runWorkflow).toHaveBeenCalledTimes(3);
+    // The capped drain advanced at most 3 rows total, so at least 2 of my 5 stay due.
+    let stillDue = 0;
+    for (const {subscription} of mine) {
+      const row = await reload(subscription.id);
+      if (row.nextFireAt.getTime() <= Date.now()) stillDue += 1;
+    }
+    expect(stillDue).toBeGreaterThanOrEqual(2);
+  });
+
+  test('two concurrent drains fire each due schedule exactly once (SKIP LOCKED)', async () => {
+    const mine: DueCron[] = [];
+    for (let index = 0; index < 4; index += 1) {
+      mine.push(await createCronSchedule({nextFireAt: new Date(Date.now() - MINUTE_MS)}));
+    }
+    // Hold the batch locks briefly so both drains are in flight while claiming.
+    runWorkflow.mockImplementation(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return {id: crypto.randomUUID(), name: 'r'};
+    });
+
+    await Promise.all([
+      drainDueCronSchedules({batchSize: 1000, jitterWindowSeconds: 0}),
+      drainDueCronSchedules({batchSize: 1000, jitterWindowSeconds: 0}),
+    ]);
+
+    for (const {subscription, schedule, key} of mine) {
+      expect(callsWithKey(key)).toHaveLength(1);
+      const row = await reload(subscription.id);
+      expect(row.lastFiredAt?.getTime()).toBe(schedule.nextFireAt.getTime());
+      expect(row.nextFireAt.getTime()).toBeGreaterThan(Date.now());
+    }
+  });
+});
+
+describe('countDueCronSchedules (backlog gauge source)', () => {
+  test('counts a schedule whose next fire time is due', async () => {
+    await createCronSchedule({nextFireAt: new Date(Date.now() - MINUTE_MS)});
+
+    const due = await countDueCronSchedules();
+
+    expect(due).toBeGreaterThanOrEqual(1);
+  });
+});

package/src/core/drain-cron-schedules.ts

@@ -0,0 +1,90 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import {advanceCronSchedule, claimDueCronSchedules, selectDbNow} from '#db/cron-schedules.js';
+import {db} from '#db/db.js';
+import {computeNextFireAt} from './compute-next-fire-at.js';
+import {fireCronSubscription} from './fire-cron.js';
+
+export interface DrainDueCronSchedulesParams {
+  readonly batchSize: number;
+  readonly jitterWindowSeconds: number;
+  /**
+   * Liveness signal invoked once per processed schedule (e.g. the Temporal activity
+   * heartbeat), so a batch stuck on a slow `runWorkflow` is visible rather than
+   * looking hung until the start-to-close timeout fires.
+   */
+  readonly onScheduleProcessed?: (() => void) | undefined;
+}
+
+export interface CronDrainSummary {
+  readonly claimed: number;
+  readonly fired: number;
+  readonly errored: number;
+  readonly retried: number;
+}
+
+/**
+ * Claims one bounded batch of due cron schedules and, per row, advances the schedule
+ * and fires the workflow. There is no internal drain loop, so the per-activity ceiling
+ * stays a hard `batchSize`.
+ *
+ * The batch is claimed and processed inside a single transaction, so its `FOR UPDATE
+ * SKIP LOCKED` locks are held until commit and concurrent activities/pods claim disjoint
+ * rows. Each row runs in a nested savepoint that advances `next_fire_at` before firing:
+ * on a transient failure the savepoint rolls back only that row's advance, leaving it due
+ * for retry, without blocking the rest of the batch. Firing before the advance commits
+ * makes a crash between the two re-fire the (idempotent) occurrence rather than skip it.
+ */
+export async function drainDueCronSchedules(
+  params: DrainDueCronSchedulesParams,
+): Promise<CronDrainSummary> {
+  let claimed = 0;
+  let fired = 0;
+  let errored = 0;
+  let retried = 0;
+
+  await db().transaction(async (tx) => {
+    // One database-clock reading shared by the due check and every advance, so the two
+    // never disagree under application/database clock skew.
+    const now = await selectDbNow(tx);
+    const due = await claimDueCronSchedules({tx, limit: params.batchSize, now});
+    claimed = due.length;
+
+    for (const schedule of due) {
+      const scheduledSlot = schedule.nextFireAt;
+      try {
+        const result = await tx.transaction(async (rowTx) => {
+          const nextFireAt = computeNextFireAt({
+            cronExpression: schedule.cronExpression,
+            timezone: schedule.timezone,
+            from: now,
+            subscriptionId: schedule.subscriptionId,
+            jitterWindowSeconds: params.jitterWindowSeconds,
+          });
+          await advanceCronSchedule({
+            tx: rowTx,
+            subscriptionId: schedule.subscriptionId,
+            nextFireAt,
+            lastFiredAt: scheduledSlot,
+          });
+          return await fireCronSubscription({
+            subscriptionId: schedule.subscriptionId,
+            scheduledSlot,
+          });
+        });
+        if (result.outcome === 'fired') fired += 1;
+        else errored += 1;
+      } catch (error) {
+        // Transient failure: the savepoint rolled back the advance, so the schedule
+        // stays due and the next tick (or an activity retry) re-claims it.
+        retried += 1;
+        logger().warn(
+          {err: error, subscriptionId: schedule.subscriptionId},
+          'cron drain: transient fire failure; schedule left due for retry',
+        );
+      }
+      params.onScheduleProcessed?.();
+    }
+  });
+
+  return {claimed, fired, errored, retried};
+}

package/src/core/entities/cron-schedule.ts

@@ -0,0 +1,10 @@
+export interface CronSchedule {
+  subscriptionId: string;
+  workspaceId: string;
+  cronExpression: string;
+  timezone: string;
+  nextFireAt: Date;
+  lastFiredAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}

package/src/core/entities/decision.ts

@@ -0,0 +1,24 @@
+import type {JobListenerMatcherKind} from './job-listener-subscription.js';
+
+export const triggerDecisionOutcomes = ['triggered', 'filter-error', 'dispatch-error'] as const;
+export type TriggerDecisionOutcome = (typeof triggerDecisionOutcomes)[number];
+export type TriggerDecisionSubscriptionKind = 'trigger' | 'listener';
+
+export interface TriggerDecision {
+  id: string;
+  receivedEventId: string;
+  subscriptionKind: TriggerDecisionSubscriptionKind;
+  subscriptionId: string;
+  subscriptionName: string;
+  workflowDefinitionId: string | null;
+  projectId: string | null;
+  workflowRunId: string | null;
+  jobId: string | null;
+  matcherKind: JobListenerMatcherKind | null;
+  matcherOrdinal: number | null;
+  decision: TriggerDecisionOutcome;
+  runId: string | null;
+  runName: string | null;
+  reason: string | null;
+  createdAt: Date;
+}

package/src/core/entities/index.ts

@@ -0,0 +1,5 @@
+export type {
+  JobListenerMatcherKind,
+  JobListenerSubscription,
+} from './job-listener-subscription.js';
+export type {TriggerSubscription} from './subscription.js';

package/src/core/entities/job-listener-subscription.ts

@@ -0,0 +1,14 @@
+export type JobListenerMatcherKind = 'on' | 'until';
+
+export interface JobListenerSubscription {
+  id: string;
+  workspaceId: string;
+  workflowRunId: string;
+  jobId: string;
+  kind: JobListenerMatcherKind;
+  matcherOrdinal: number;
+  source: string;
+  event: string;
+  config: Record<string, unknown>;
+  createdAt: Date;
+}

package/src/core/entities/received-event.ts

@@ -0,0 +1,36 @@
+export const triggerEventOrigins = ['integration', 'manual', 'cron'] as const;
+export type TriggerEventOrigin = (typeof triggerEventOrigins)[number];
+
+export const triggerEventOutcomes = [
+  'received',
+  'routed',
+  'discarded',
+  'failed',
+  'errored',
+] as const;
+export type TriggerEventOutcome = (typeof triggerEventOutcomes)[number];
+
+export interface TriggerReceivedEvent {
+  id: string;
+  eventRef: string;
+  origin: TriggerEventOrigin;
+  workspaceId: string;
+  provider: string | null;
+  source: string;
+  event: string;
+  deliveryId: string | null;
+  connectionId: string | null;
+  connectionName: string | null;
+  outcome: TriggerEventOutcome;
+  matchedCount: number;
+  payload: Record<string, unknown> | null;
+  receivedAt: Date;
+  processedAt: Date | null;
+  createdAt: Date;
+}
+
+/**
+ * Trigger event shape for list read models.
+ * It omits payload because webhook bodies can be large/untrusted and only detail views render them.
+ */
+export type TriggerReceivedEventSummary = Omit<TriggerReceivedEvent, 'payload'>;

package/src/core/entities/subscription.ts

@@ -0,0 +1,12 @@
+export interface TriggerSubscription {
+  id: string;
+  workspaceId: string;
+  projectId: string;
+  workflowDefinitionId: string;
+  name: string;
+  source: string;
+  event: string;
+  config: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}

package/src/core/errors.ts

@@ -0,0 +1,63 @@
+export class TriggerSubscriptionNotFoundError extends Error {
+  readonly subscriptionId: string;
+
+  constructor(subscriptionId: string) {
+    super(`Trigger subscription not found: ${subscriptionId}`);
+    this.name = 'TriggerSubscriptionNotFoundError';
+    this.subscriptionId = subscriptionId;
+  }
+}
+
+export class ManualTriggerNotFoundError extends Error {
+  readonly workflowDefinitionId: string;
+
+  constructor(workflowDefinitionId: string) {
+    super(`Workflow definition ${workflowDefinitionId} has no manual trigger`);
+    this.name = 'ManualTriggerNotFoundError';
+    this.workflowDefinitionId = workflowDefinitionId;
+  }
+}
+
+export class TriggerSubscriptionNotManualError extends Error {
+  readonly subscriptionId: string;
+  readonly source: string;
+
+  constructor(subscriptionId: string, source: string) {
+    super(
+      `Trigger subscription ${subscriptionId} has source '${source}', expected 'manual' for manual fire`,
+    );
+    this.name = 'TriggerSubscriptionNotManualError';
+    this.subscriptionId = subscriptionId;
+    this.source = source;
+  }
+}
+
+export class TriggerSubscriptionNotCronError extends Error {
+  readonly subscriptionId: string;
+  readonly source: string;
+
+  constructor(subscriptionId: string, source: string) {
+    super(
+      `Trigger subscription ${subscriptionId} has source '${source}', expected 'cron' for cron fire`,
+    );
+    this.name = 'TriggerSubscriptionNotCronError';
+    this.subscriptionId = subscriptionId;
+    this.source = source;
+  }
+}
+
+export class TriggerWorkspaceMismatchError extends Error {
+  readonly subscriptionId: string;
+  readonly subscriptionWorkspaceId: string;
+  readonly callerWorkspaceId: string;
+
+  constructor(subscriptionId: string, subscriptionWorkspaceId: string, callerWorkspaceId: string) {
+    super(
+      `Trigger subscription ${subscriptionId} belongs to workspace ${subscriptionWorkspaceId}, not ${callerWorkspaceId}`,
+    );
+    this.name = 'TriggerWorkspaceMismatchError';
+    this.subscriptionId = subscriptionId;
+    this.subscriptionWorkspaceId = subscriptionWorkspaceId;
+    this.callerWorkspaceId = callerWorkspaceId;
+  }
+}