@shipfox/api-triggers 2.0.0

package/src/core/fire-cron.test.ts

@@ -0,0 +1,146 @@
+import {eq} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {triggersDecisions} from '#db/schema/decisions.js';
+import {triggersReceivedEvents} from '#db/schema/received-events.js';
+import {triggerSubscriptionFactory} from '#test/index.js';
+import {TriggerSubscriptionNotCronError} from './errors.js';
+
+const runWorkflow = vi.fn();
+
+// Keep a real-enough permanent-error class + the classifier so the cron path's
+// permanent/transient branching is exercised without loading the workflows module graph.
+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 {fireCronSubscription} = await import('./fire-cron.js');
+
+const SLOT = new Date('2026-07-05T02:00:00.000Z');
+
+function eventsForWorkspace(workspaceId: string) {
+  return db()
+    .select()
+    .from(triggersReceivedEvents)
+    .where(eq(triggersReceivedEvents.workspaceId, workspaceId));
+}
+
+function decisionsForEvent(receivedEventId: string) {
+  return db()
+    .select()
+    .from(triggersDecisions)
+    .where(eq(triggersDecisions.receivedEventId, receivedEventId));
+}
+
+describe('fireCronSubscription', () => {
+  beforeEach(() => {
+    runWorkflow.mockReset();
+  });
+
+  test('records a routed cron event and a triggered decision on success', async () => {
+    const subscription = await triggerSubscriptionFactory.create({
+      source: 'cron',
+      event: 'tick',
+      config: {with: {environment: 'staging'}},
+    });
+    const run = {id: crypto.randomUUID(), name: 'Cron run'};
+    runWorkflow.mockResolvedValue(run);
+
+    const result = await fireCronSubscription({
+      subscriptionId: subscription.id,
+      scheduledSlot: SLOT,
+    });
+
+    expect(result).toEqual({outcome: 'fired', run});
+    const [payload] = runWorkflow.mock.calls[0] as [Record<string, unknown>];
+    expect(payload.triggerPayload).toEqual({
+      provider: 'cron',
+      source: 'cron',
+      event: 'tick',
+      scheduleId: subscription.id,
+    });
+    expect(payload.inputs).toEqual({environment: 'staging'});
+    expect(payload.triggerIdempotencyKey).toBe(`${subscription.id}:${SLOT.toISOString()}`);
+    const [event] = await eventsForWorkspace(subscription.workspaceId);
+    if (!event) throw new Error('received event not found');
+    expect(event.origin).toBe('cron');
+    expect(event.source).toBe('cron');
+    expect(event.provider).toBeNull();
+    expect(event.outcome).toBe('routed');
+    expect(event.eventRef).toBe(`${subscription.id}:${SLOT.toISOString()}`);
+    const decisions = await decisionsForEvent(event.id);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]?.decision).toBe('triggered');
+    expect(decisions[0]?.runId).toBe(run.id);
+  });
+
+  test('returns errored (terminal) and records a dispatch-error decision on a permanent failure', async () => {
+    const subscription = await triggerSubscriptionFactory.create({
+      source: 'cron',
+      event: 'tick',
+      config: {},
+    });
+    runWorkflow.mockRejectedValue(new DefinitionNotFoundError('def-gone'));
+
+    const result = await fireCronSubscription({
+      subscriptionId: subscription.id,
+      scheduledSlot: SLOT,
+    });
+
+    expect(result).toEqual({outcome: 'errored'});
+    const [event] = await eventsForWorkspace(subscription.workspaceId);
+    if (!event) throw new Error('received event not found');
+    expect(event.outcome).toBe('errored');
+    expect(event.processedAt).toBeInstanceOf(Date);
+    const decisions = await decisionsForEvent(event.id);
+    expect(decisions[0]?.decision).toBe('dispatch-error');
+    expect(decisions[0]?.reason).toContain('Definition not found');
+  });
+
+  test('re-throws and leaves the event non-terminal on a transient failure', async () => {
+    const subscription = await triggerSubscriptionFactory.create({
+      source: 'cron',
+      event: 'tick',
+      config: {},
+    });
+    runWorkflow.mockRejectedValue(new Error('cron boom'));
+
+    await expect(
+      fireCronSubscription({subscriptionId: subscription.id, scheduledSlot: SLOT}),
+    ).rejects.toThrow('cron boom');
+
+    const [event] = await eventsForWorkspace(subscription.workspaceId);
+    if (!event) throw new Error('received event not found');
+    expect(event.outcome).toBe('failed');
+    expect(event.processedAt).toBeNull();
+    const decisions = await decisionsForEvent(event.id);
+    expect(decisions[0]?.decision).toBe('dispatch-error');
+  });
+
+  test('throws and records nothing when the subscription is not a cron trigger', async () => {
+    const subscription = await triggerSubscriptionFactory.create({
+      source: 'manual',
+      event: 'fire',
+      config: {},
+    });
+
+    await expect(
+      fireCronSubscription({subscriptionId: subscription.id, scheduledSlot: SLOT}),
+    ).rejects.toThrow(TriggerSubscriptionNotCronError);
+
+    expect(await eventsForWorkspace(subscription.workspaceId)).toHaveLength(0);
+    expect(runWorkflow).not.toHaveBeenCalled();
+  });
+});

package/src/core/fire-cron.ts

@@ -0,0 +1,98 @@
+import {isPermanentRunWorkflowError, runWorkflow, type WorkflowRun} from '@shipfox/api-workflows';
+import {getTriggerSubscriptionById} from '#db/subscriptions.js';
+import {cronFiredCount, cronFireLag} from '#metrics/instance.js';
+import {readConfigInputs} from './config.js';
+import {TriggerSubscriptionNotCronError, TriggerSubscriptionNotFoundError} from './errors.js';
+import {beginTriggerHistory, toReason} from './record-trigger-history.js';
+
+export interface FireCronSubscriptionParams {
+  subscriptionId: string;
+  /**
+   * The `next_fire_at` value the schedule held when it was claimed. Anchoring the
+   * idempotency key and history `event_ref` on this slot, rather than wall-clock
+   * time, makes a retry of the same occurrence a deterministic no-op.
+   */
+  scheduledSlot: Date;
+}
+
+export type FireCronSubscriptionResult =
+  | {outcome: 'fired'; run: WorkflowRun}
+  | {outcome: 'errored'};
+
+/**
+ * Fires one cron schedule occurrence. Mirrors `fireManualSubscription`, but is driven
+ * by the drain activity rather than an HTTP route, and reports the outcome instead of
+ * throwing on a permanent failure so the caller can advance the schedule past a
+ * permanently broken definition:
+ *
+ * - `{outcome: 'fired'}` on success (or an idempotent replay of an already-created run),
+ * - `{outcome: 'errored'}` on a permanent `runWorkflow` failure (recorded, schedule advances),
+ * - throws on a transient failure so the caller rolls back the advance and retries.
+ */
+export async function fireCronSubscription(
+  params: FireCronSubscriptionParams,
+): Promise<FireCronSubscriptionResult> {
+  const subscription = await getTriggerSubscriptionById(params.subscriptionId);
+  if (!subscription) throw new TriggerSubscriptionNotFoundError(params.subscriptionId);
+  if (subscription.source !== 'cron') {
+    throw new TriggerSubscriptionNotCronError(params.subscriptionId, subscription.source);
+  }
+
+  // Deterministic per-occurrence identity: unique across (subscription, slot), stable
+  // across retries. Used for both the run idempotency key and the received-event ref.
+  const eventRef = `${subscription.id}:${params.scheduledSlot.toISOString()}`;
+  const historyBase = {
+    origin: 'cron' as const,
+    workspaceId: subscription.workspaceId,
+    provider: null,
+    source: subscription.source,
+    event: subscription.event,
+    deliveryId: null,
+    connectionId: null,
+    connectionName: null,
+    payload: null,
+    // The scheduled occurrence is the logical arrival time of the tick event.
+    receivedAt: params.scheduledSlot,
+    eventRef,
+  };
+
+  let run: WorkflowRun;
+  try {
+    run = await runWorkflow({
+      workspaceId: subscription.workspaceId,
+      projectId: subscription.projectId,
+      definitionId: subscription.workflowDefinitionId,
+      triggerPayload: {
+        provider: 'cron',
+        source: 'cron',
+        event: 'tick',
+        scheduleId: subscription.id,
+      },
+      inputs: readConfigInputs(subscription),
+      triggerIdempotencyKey: eventRef,
+    });
+  } catch (error) {
+    const failure = await beginTriggerHistory(historyBase);
+    await failure.dispatchErrored(subscription, toReason(error));
+    if (isPermanentRunWorkflowError(error)) {
+      recordFire('errored', params.scheduledSlot);
+      await failure.allErrored(1);
+      return {outcome: 'errored'};
+    }
+    // Transient: leave the event non-terminal and re-throw so the caller rolls back
+    // the advance and the schedule stays due for the next tick.
+    await failure.failed(1);
+    throw error;
+  }
+
+  const history = await beginTriggerHistory(historyBase);
+  await history.triggered(subscription, run);
+  recordFire('fired', params.scheduledSlot);
+  await history.routed(1);
+  return {outcome: 'fired', run};
+}
+
+function recordFire(outcome: 'fired' | 'errored', scheduledSlot: Date): void {
+  cronFiredCount.add(1, {outcome});
+  cronFireLag.record(Math.max(0, Date.now() - scheduledSlot.getTime()));
+}

package/src/core/fire-manual.test.ts

@@ -0,0 +1,157 @@
+import {eq} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {triggersDecisions} from '#db/schema/decisions.js';
+import {triggersReceivedEvents} from '#db/schema/received-events.js';
+import {triggerSubscriptionFactory} from '#test/index.js';
+import {TriggerSubscriptionNotManualError} from './errors.js';
+
+const runWorkflow = vi.fn();
+
+// Keep real-enough permanent-error classes + the classifier so the manual path's
+// permanent/transient branching is exercised without loading the workflows module graph.
+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 {fireManualSubscription} = await import('./fire-manual.js');
+
+function eventsForWorkspace(workspaceId: string) {
+  return db()
+    .select()
+    .from(triggersReceivedEvents)
+    .where(eq(triggersReceivedEvents.workspaceId, workspaceId));
+}
+
+function decisionsForEvent(receivedEventId: string) {
+  return db()
+    .select()
+    .from(triggersDecisions)
+    .where(eq(triggersDecisions.receivedEventId, receivedEventId));
+}
+
+describe('fireManualSubscription (trigger history)', () => {
+  beforeEach(() => {
+    runWorkflow.mockReset();
+  });
+
+  test('records a routed manual event and a triggered decision on success', async () => {
+    const subscription = await triggerSubscriptionFactory.create({
+      source: 'manual',
+      event: 'fire',
+      config: {},
+    });
+    const run = {id: crypto.randomUUID(), name: 'Manual run'};
+    runWorkflow.mockResolvedValue(run);
+
+    const result = await fireManualSubscription({
+      subscriptionId: subscription.id,
+      callerWorkspaceId: subscription.workspaceId,
+      userId: crypto.randomUUID(),
+    });
+
+    expect(result).toEqual(run);
+    const [event] = await db()
+      .select()
+      .from(triggersReceivedEvents)
+      .where(eq(triggersReceivedEvents.eventRef, run.id));
+    if (!event) throw new Error('received event not found');
+    expect(event.origin).toBe('manual');
+    expect(event.outcome).toBe('routed');
+    expect(event.matchedCount).toBe(1);
+    const decisions = await decisionsForEvent(event.id);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]?.decision).toBe('triggered');
+    expect(decisions[0]?.runId).toBe(run.id);
+    expect(decisions[0]?.runName).toBe('Manual run');
+  });
+
+  test('records a failed manual event with a dispatch-error decision and re-throws when runWorkflow throws', async () => {
+    const subscription = await triggerSubscriptionFactory.create({
+      source: 'manual',
+      event: 'fire',
+      config: {},
+    });
+    runWorkflow.mockRejectedValue(new Error('manual boom'));
+
+    await expect(
+      fireManualSubscription({
+        subscriptionId: subscription.id,
+        callerWorkspaceId: subscription.workspaceId,
+        userId: crypto.randomUUID(),
+      }),
+    ).rejects.toThrow('manual boom');
+
+    const events = await eventsForWorkspace(subscription.workspaceId);
+    expect(events).toHaveLength(1);
+    const event = events[0];
+    if (!event) throw new Error('received event not found');
+    expect(event.origin).toBe('manual');
+    expect(event.outcome).toBe('failed');
+    expect(event.matchedCount).toBe(1);
+    expect(event.processedAt).toBeNull();
+    const decisions = await decisionsForEvent(event.id);
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0]?.decision).toBe('dispatch-error');
+    expect(decisions[0]?.reason).toContain('manual boom');
+  });
+
+  test('records an errored (terminal) manual event when runWorkflow fails permanently', async () => {
+    const subscription = await triggerSubscriptionFactory.create({
+      source: 'manual',
+      event: 'fire',
+      config: {},
+    });
+    runWorkflow.mockRejectedValue(new DefinitionNotFoundError('def-gone'));
+
+    await expect(
+      fireManualSubscription({
+        subscriptionId: subscription.id,
+        callerWorkspaceId: subscription.workspaceId,
+        userId: crypto.randomUUID(),
+      }),
+    ).rejects.toThrow('Definition not found');
+
+    const events = await eventsForWorkspace(subscription.workspaceId);
+    expect(events).toHaveLength(1);
+    const event = events[0];
+    if (!event) throw new Error('received event not found');
+    expect(event.outcome).toBe('errored');
+    expect(event.matchedCount).toBe(1);
+    expect(event.processedAt).toBeInstanceOf(Date);
+    const decisions = await decisionsForEvent(event.id);
+    expect(decisions[0]?.decision).toBe('dispatch-error');
+    expect(decisions[0]?.reason).toContain('Definition not found');
+  });
+
+  test('does not record a received event when the subscription is not a manual trigger', async () => {
+    const subscription = await triggerSubscriptionFactory.create({
+      source: 'github',
+      event: 'push',
+      config: {},
+    });
+
+    await expect(
+      fireManualSubscription({
+        subscriptionId: subscription.id,
+        callerWorkspaceId: subscription.workspaceId,
+        userId: crypto.randomUUID(),
+      }),
+    ).rejects.toThrow(TriggerSubscriptionNotManualError);
+
+    expect(await eventsForWorkspace(subscription.workspaceId)).toHaveLength(0);
+    expect(runWorkflow).not.toHaveBeenCalled();
+  });
+});

package/src/core/fire-manual.ts

@@ -0,0 +1,92 @@
+import {randomUUID} from 'node:crypto';
+import {isPermanentRunWorkflowError, runWorkflow, type WorkflowRun} from '@shipfox/api-workflows';
+import {getTriggerSubscriptionById} from '#db/subscriptions.js';
+import {
+  eventOutcomeCount,
+  eventReceivedCount,
+  subscriptionTriggeredCount,
+} from '#metrics/instance.js';
+import {readConfigInputs} from './config.js';
+import {
+  TriggerSubscriptionNotFoundError,
+  TriggerSubscriptionNotManualError,
+  TriggerWorkspaceMismatchError,
+} from './errors.js';
+import {beginTriggerHistory, toReason} from './record-trigger-history.js';
+
+export interface FireManualSubscriptionParams {
+  subscriptionId: string;
+  callerWorkspaceId: string;
+  userId: string;
+  inputs?: Record<string, unknown> | undefined;
+}
+
+export async function fireManualSubscription(
+  params: FireManualSubscriptionParams,
+): Promise<WorkflowRun> {
+  const subscription = await getTriggerSubscriptionById(params.subscriptionId);
+  if (!subscription) throw new TriggerSubscriptionNotFoundError(params.subscriptionId);
+  if (subscription.source !== 'manual') {
+    throw new TriggerSubscriptionNotManualError(params.subscriptionId, subscription.source);
+  }
+  // Defence in depth: unreachable from the HTTP route, but required for any direct caller.
+  if (subscription.workspaceId !== params.callerWorkspaceId) {
+    throw new TriggerWorkspaceMismatchError(
+      params.subscriptionId,
+      subscription.workspaceId,
+      params.callerWorkspaceId,
+    );
+  }
+
+  // Manual fires have no upstream event id. Use the run id after success; failed
+  // attempts need a synthesized ref because there is no run to key on.
+  const historyBase = {
+    origin: 'manual' as const,
+    workspaceId: subscription.workspaceId,
+    provider: null,
+    source: subscription.source,
+    event: subscription.event,
+    deliveryId: null,
+    connectionId: null,
+    connectionName: null,
+    payload: null,
+    receivedAt: new Date(),
+  };
+
+  eventReceivedCount.add(1, {provider: 'manual'});
+
+  let run: WorkflowRun;
+  try {
+    run = await runWorkflow({
+      workspaceId: subscription.workspaceId,
+      projectId: subscription.projectId,
+      definitionId: subscription.workflowDefinitionId,
+      triggerPayload: {
+        provider: 'manual',
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: subscription.id,
+        userId: params.userId,
+      },
+      inputs: params.inputs ?? readConfigInputs(subscription),
+    });
+  } catch (error) {
+    const failure = await beginTriggerHistory({...historyBase, eventRef: randomUUID()});
+    await failure.dispatchErrored(subscription, toReason(error));
+    if (isPermanentRunWorkflowError(error)) {
+      eventOutcomeCount.add(1, {provider: 'manual', outcome: 'errored'});
+      await failure.allErrored(1);
+    } else {
+      eventOutcomeCount.add(1, {provider: 'manual', outcome: 'failed'});
+      await failure.failed(1);
+    }
+    throw error;
+  }
+
+  const history = await beginTriggerHistory({...historyBase, eventRef: run.id});
+  await history.triggered(subscription, run);
+  subscriptionTriggeredCount.add(1, {provider: 'manual'});
+  eventOutcomeCount.add(1, {provider: 'manual', outcome: 'routed'});
+  await history.routed(1);
+  return run;
+}

package/src/core/index.ts

@@ -0,0 +1,34 @@
+export {
+  type ComputeNextFireAtParams,
+  computeNextFireAt,
+} from './compute-next-fire-at.js';
+export {readConfigInputs} from './config.js';
+export {
+  type DispatchIntegrationEventParams,
+  dispatchIntegrationEvent,
+} from './dispatch-integration-event.js';
+export {
+  type CronDrainSummary,
+  type DrainDueCronSchedulesParams,
+  drainDueCronSchedules,
+} from './drain-cron-schedules.js';
+export type {CronSchedule} from './entities/cron-schedule.js';
+export type {TriggerSubscription} from './entities/subscription.js';
+export {
+  ManualTriggerNotFoundError,
+  TriggerSubscriptionNotCronError,
+  TriggerSubscriptionNotFoundError,
+  TriggerSubscriptionNotManualError,
+  TriggerWorkspaceMismatchError,
+} from './errors.js';
+export {
+  type FireCronSubscriptionParams,
+  type FireCronSubscriptionResult,
+  fireCronSubscription,
+} from './fire-cron.js';
+export {type FireManualSubscriptionParams, fireManualSubscription} from './fire-manual.js';
+export {
+  type RouteEventToJobListenersParams,
+  type RouteEventToJobListenersResult,
+  routeEventToJobListeners,
+} from './route-event-to-job-listeners.js';

package/src/core/record-trigger-history.test.ts

@@ -0,0 +1,159 @@
+import {jobListenerSubscriptionFactory, triggerSubscriptionFactory} from '#test/index.js';
+
+const runWorkflow = vi.fn();
+const insertReceivedEvent = vi.fn();
+const markReceivedEventRouted = vi.fn();
+const upsertTriggeredDecision = vi.fn();
+
+vi.mock('@shipfox/api-workflows', () => ({
+  runWorkflow: (...args: unknown[]) => runWorkflow(...args),
+  isPermanentRunWorkflowError: () => false,
+}));
+
+vi.mock('#db/event-history.js', () => ({
+  insertReceivedEvent: (...args: unknown[]) => insertReceivedEvent(...args),
+  markReceivedEventDiscarded: vi.fn(),
+  markReceivedEventRouted: (...args: unknown[]) => markReceivedEventRouted(...args),
+  markReceivedEventFailed: vi.fn(),
+  markReceivedEventErrored: vi.fn(),
+  upsertTriggeredDecision: (...args: unknown[]) => upsertTriggeredDecision(...args),
+  upsertDispatchErrorDecision: vi.fn(),
+  upsertFilterErrorDecision: vi.fn(),
+  upsertListenerTriggeredDecision: vi.fn(),
+  upsertListenerDispatchErrorDecision: vi.fn(),
+  upsertListenerFilterErrorDecision: vi.fn(),
+}));
+
+// Import after mocks so the code under test sees the spies.
+const {beginTriggerHistory, toReason} = await import('./record-trigger-history.js');
+const {fireManualSubscription} = await import('./fire-manual.js');
+
+describe('trigger history is best-effort and never blocks triggering', () => {
+  beforeEach(() => {
+    runWorkflow.mockReset();
+    insertReceivedEvent.mockReset();
+    insertReceivedEvent.mockRejectedValue(new Error('history db down'));
+  });
+
+  test('beginTriggerHistory resolves and its methods never throw when the insert fails', async () => {
+    const recorder = await beginTriggerHistory({
+      eventRef: crypto.randomUUID(),
+      origin: 'integration',
+      workspaceId: crypto.randomUUID(),
+      provider: 'github',
+      source: 'github',
+      event: 'push',
+      deliveryId: null,
+      connectionId: null,
+      connectionName: null,
+      payload: null,
+      receivedAt: new Date(),
+    });
+    const subscription = triggerSubscriptionFactory.build();
+    const listenerSubscription = jobListenerSubscriptionFactory.build();
+
+    await expect(
+      recorder.triggered(subscription, {id: crypto.randomUUID(), name: 'r'}),
+    ).resolves.toBeUndefined();
+    await expect(recorder.dispatchErrored(subscription, 'boom')).resolves.toBeUndefined();
+    await expect(recorder.filterErrored(subscription, 'bad filter')).resolves.toBeUndefined();
+    await expect(recorder.listenerTriggered(listenerSubscription)).resolves.toBeUndefined();
+    await expect(
+      recorder.listenerDispatchErrored(listenerSubscription, 'boom'),
+    ).resolves.toBeUndefined();
+    await expect(
+      recorder.listenerFilterErrored(listenerSubscription, 'bad filter'),
+    ).resolves.toBeUndefined();
+    await expect(recorder.discarded()).resolves.toBeUndefined();
+    await expect(recorder.routed(1)).resolves.toBeUndefined();
+    await expect(recorder.failed(1)).resolves.toBeUndefined();
+    await expect(recorder.allErrored(1)).resolves.toBeUndefined();
+  });
+
+  test('fireManualSubscription still returns the run when history recording fails', async () => {
+    const run = {id: crypto.randomUUID(), name: 'Manual run'};
+    runWorkflow.mockResolvedValue(run);
+    const subscription = await triggerSubscriptionFactory.create({
+      source: 'manual',
+      event: 'fire',
+      config: {},
+    });
+
+    const result = await fireManualSubscription({
+      subscriptionId: subscription.id,
+      callerWorkspaceId: subscription.workspaceId,
+      userId: crypto.randomUUID(),
+    });
+
+    expect(result).toEqual(run);
+    expect(runWorkflow).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('a per-write failure after a successful insert is swallowed', () => {
+  beforeEach(() => {
+    insertReceivedEvent.mockReset();
+    markReceivedEventRouted.mockReset();
+    upsertTriggeredDecision.mockReset();
+    insertReceivedEvent.mockResolvedValue(crypto.randomUUID());
+    markReceivedEventRouted.mockRejectedValue(new Error('route write failed'));
+    upsertTriggeredDecision.mockRejectedValue(new Error('decision write failed'));
+  });
+
+  test('recorder methods resolve when the insert succeeds but a later write throws', async () => {
+    const recorder = await beginTriggerHistory({
+      eventRef: crypto.randomUUID(),
+      origin: 'integration',
+      workspaceId: crypto.randomUUID(),
+      provider: 'github',
+      source: 'github',
+      event: 'push',
+      deliveryId: null,
+      connectionId: null,
+      connectionName: null,
+      payload: null,
+      receivedAt: new Date(),
+    });
+    const subscription = triggerSubscriptionFactory.build();
+
+    await expect(
+      recorder.triggered(subscription, {id: crypto.randomUUID(), name: 'r'}),
+    ).resolves.toBeUndefined();
+    await expect(recorder.routed(1)).resolves.toBeUndefined();
+
+    // Prove the post-insert writes were actually attempted (not skipped by the
+    // missing-id no-op), so the assertions exercise the swallow path they claim to.
+    expect(upsertTriggeredDecision).toHaveBeenCalledTimes(1);
+    expect(markReceivedEventRouted).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('toReason', () => {
+  test('caps an over-long message at the maximum reason length', () => {
+    const reason = toReason(new Error('x'.repeat(5000)));
+
+    expect(reason).toHaveLength(2000);
+  });
+
+  test('stringifies a non-Error throwable', () => {
+    const reason = toReason('plain string failure');
+
+    expect(reason).toBe('plain string failure');
+  });
+
+  test('falls back when a non-Error throwable cannot be stringified', () => {
+    const reason = toReason({
+      toString() {
+        throw new Error('string conversion failed');
+      },
+    });
+
+    expect(reason).toBe('[unprintable thrown value]');
+  });
+
+  test('passes a short Error message through verbatim', () => {
+    const reason = toReason(new Error('definition deleted'));
+
+    expect(reason).toBe('definition deleted');
+  });
+});