@shipfox/api-triggers 2.0.0

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

@@ -0,0 +1,145 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import type {JobListenerSubscription} from '#core/entities/job-listener-subscription.js';
+import type {TriggerEventOrigin} from '#core/entities/received-event.js';
+import type {TriggerSubscription} from '#core/entities/subscription.js';
+import {
+  insertReceivedEvent,
+  markReceivedEventDiscarded,
+  markReceivedEventErrored,
+  markReceivedEventFailed,
+  markReceivedEventRouted,
+  upsertDispatchErrorDecision,
+  upsertFilterErrorDecision,
+  upsertListenerDispatchErrorDecision,
+  upsertListenerFilterErrorDecision,
+  upsertListenerTriggeredDecision,
+  upsertTriggeredDecision,
+} from '#db/event-history.js';
+
+const MAX_REASON_LENGTH = 2000;
+
+// A bounded, deterministic reason string safe to persist: error messages can be
+// long or carry untrusted data, so cap the length and never serialize the object.
+export function toReason(error: unknown): string {
+  let message: string;
+  try {
+    message = error instanceof Error ? error.message : String(error);
+  } catch {
+    message = '[unprintable thrown value]';
+  }
+  return message.slice(0, MAX_REASON_LENGTH);
+}
+
+export interface TriggerRun {
+  id: string;
+  name: string;
+}
+
+export interface TriggerHistoryRecorder {
+  triggered(subscription: TriggerSubscription, run: TriggerRun): Promise<void>;
+  filterErrored(subscription: TriggerSubscription, reason: string): Promise<void>;
+  dispatchErrored(subscription: TriggerSubscription, reason: string): Promise<void>;
+  listenerTriggered(subscription: JobListenerSubscription): Promise<void>;
+  listenerFilterErrored(subscription: JobListenerSubscription, reason: string): Promise<void>;
+  listenerDispatchErrored(subscription: JobListenerSubscription, reason: string): Promise<void>;
+  discarded(): Promise<void>;
+  routed(matchedCount: number): Promise<void>;
+  failed(matchedCount: number): Promise<void>;
+  allErrored(matchedCount: number): Promise<void>;
+}
+
+export interface BeginTriggerHistoryParams {
+  eventRef: string;
+  origin: TriggerEventOrigin;
+  workspaceId: string;
+  provider: string | null;
+  source: string;
+  event: string;
+  deliveryId: string | null;
+  connectionId: string | null;
+  connectionName: string | null;
+  payload: Record<string, unknown> | null;
+  receivedAt: Date;
+}
+
+// History writes are best-effort and log stable ids only, never payloads or tokens.
+// If the parent insert fails there is no row to attach to, so later calls no-op.
+export async function beginTriggerHistory(
+  params: BeginTriggerHistoryParams,
+): Promise<TriggerHistoryRecorder> {
+  const receivedEventId = await safe(params.eventRef, 'insert-received-event', () =>
+    insertReceivedEvent(params),
+  );
+
+  const record = async (
+    label: string,
+    write: (receivedEventId: string) => Promise<unknown>,
+    subscriptionId?: string,
+  ): Promise<void> => {
+    if (receivedEventId === undefined) return;
+    await safe(params.eventRef, label, () => write(receivedEventId), subscriptionId);
+  };
+
+  return {
+    triggered: (subscription, run) =>
+      record(
+        'triggered-decision',
+        (id) => upsertTriggeredDecision({receivedEventId: id, subscription, run}),
+        subscription.id,
+      ),
+    filterErrored: (subscription, reason) =>
+      record(
+        'filter-error-decision',
+        (id) => upsertFilterErrorDecision({receivedEventId: id, subscription, reason}),
+        subscription.id,
+      ),
+    dispatchErrored: (subscription, reason) =>
+      record(
+        'dispatch-error-decision',
+        (id) => upsertDispatchErrorDecision({receivedEventId: id, subscription, reason}),
+        subscription.id,
+      ),
+    listenerTriggered: (subscription) =>
+      record(
+        'listener-triggered-decision',
+        (id) => upsertListenerTriggeredDecision({receivedEventId: id, subscription}),
+        subscription.id,
+      ),
+    listenerFilterErrored: (subscription, reason) =>
+      record(
+        'listener-filter-error-decision',
+        (id) => upsertListenerFilterErrorDecision({receivedEventId: id, subscription, reason}),
+        subscription.id,
+      ),
+    listenerDispatchErrored: (subscription, reason) =>
+      record(
+        'listener-dispatch-error-decision',
+        (id) => upsertListenerDispatchErrorDecision({receivedEventId: id, subscription, reason}),
+        subscription.id,
+      ),
+    discarded: () => record('discard-event', (id) => markReceivedEventDiscarded(id)),
+    routed: (matchedCount) =>
+      record('route-event', (id) => markReceivedEventRouted(id, matchedCount)),
+    failed: (matchedCount) =>
+      record('fail-event', (id) => markReceivedEventFailed(id, matchedCount)),
+    allErrored: (matchedCount) =>
+      record('all-errored-event', (id) => markReceivedEventErrored(id, matchedCount)),
+  };
+}
+
+async function safe<T>(
+  eventRef: string,
+  label: string,
+  fn: () => Promise<T>,
+  subscriptionId?: string,
+): Promise<T | undefined> {
+  try {
+    return await fn();
+  } catch (error) {
+    logger().warn(
+      {err: error, label, eventRef, ...(subscriptionId ? {subscriptionId} : {})},
+      'trigger history write failed; ignored (best-effort)',
+    );
+    return undefined;
+  }
+}

package/src/core/route-event-to-job-listeners.test.ts

@@ -0,0 +1,369 @@
+import {jobListenerSubscriptionFactory} from '#test/index.js';
+import type {TriggerHistoryRecorder} from './record-trigger-history.js';
+
+const deliverEventToListener = vi.fn();
+const findMatchingJobListenerSubscriptions = vi.fn();
+const listenerTriggered = vi.fn();
+const listenerFilterErrored = vi.fn();
+const listenerDispatchErrored = vi.fn();
+const loggerWarn = vi.fn();
+
+vi.mock('@shipfox/api-workflows', () => ({
+  deliverEventToListener: (...args: unknown[]) => deliverEventToListener(...args),
+}));
+
+vi.mock('@shipfox/node-opentelemetry', () => ({
+  logger: () => ({warn: loggerWarn}),
+}));
+
+vi.mock('#db/job-listener-subscriptions.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('#db/job-listener-subscriptions.js')>();
+  return {
+    ...actual,
+    findMatchingJobListenerSubscriptions: (
+      ...args: Parameters<typeof actual.findMatchingJobListenerSubscriptions>
+    ) => {
+      if (findMatchingJobListenerSubscriptions.getMockImplementation()) {
+        return findMatchingJobListenerSubscriptions(...args);
+      }
+      return actual.findMatchingJobListenerSubscriptions(...args);
+    },
+  };
+});
+
+const {routeEventToJobListeners} = await import('./route-event-to-job-listeners.js');
+
+interface RouteOverrides {
+  eventRef?: string;
+  workspaceId?: string;
+  source?: string;
+  event?: string;
+  payload?: unknown;
+}
+
+function route(overrides: RouteOverrides = {}) {
+  return routeEventToJobListeners({
+    history: buildHistory(),
+    eventRef: overrides.eventRef ?? crypto.randomUUID(),
+    workspaceId: overrides.workspaceId ?? crypto.randomUUID(),
+    provider: 'github',
+    source: overrides.source ?? 'github',
+    event: overrides.event ?? 'pull_request_review',
+    deliveryId: crypto.randomUUID(),
+    payload: overrides.payload ?? {action: 'submitted'},
+    receivedAt: new Date('2026-01-01T00:00:00.000Z'),
+  });
+}
+
+function buildHistory(): TriggerHistoryRecorder {
+  return {
+    triggered: vi.fn(),
+    filterErrored: vi.fn(),
+    dispatchErrored: vi.fn(),
+    listenerTriggered,
+    listenerFilterErrored,
+    listenerDispatchErrored,
+    discarded: vi.fn(),
+    routed: vi.fn(),
+    failed: vi.fn(),
+    allErrored: vi.fn(),
+  };
+}
+
+describe('routeEventToJobListeners', () => {
+  beforeEach(() => {
+    deliverEventToListener.mockReset();
+    findMatchingJobListenerSubscriptions.mockReset();
+    listenerTriggered.mockReset();
+    listenerFilterErrored.mockReset();
+    listenerDispatchErrored.mockReset();
+    loggerWarn.mockReset();
+    deliverEventToListener.mockResolvedValue({buffered: true, skipped: false});
+  });
+
+  it('computes resolve as the effective disposition when on and until match one job', async () => {
+    const workspaceId = crypto.randomUUID();
+    const jobId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      jobId,
+      kind: 'on',
+      matcherOrdinal: 0,
+      source: 'github',
+      event: 'pull_request_review',
+    });
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      jobId,
+      kind: 'until',
+      matcherOrdinal: 0,
+      source: 'github',
+      event: 'pull_request_review',
+    });
+
+    const result = await route({workspaceId});
+
+    expect(deliverEventToListener).toHaveBeenCalledTimes(1);
+    expect(deliverEventToListener).toHaveBeenCalledWith(
+      expect.objectContaining({jobId, disposition: 'resolve'}),
+    );
+    expect(listenerTriggered).toHaveBeenCalledTimes(1);
+    expect(listenerTriggered).toHaveBeenCalledWith(expect.objectContaining({kind: 'until'}));
+    expect(result).toMatchObject({
+      engagedCount: 1,
+      matchedJobCount: 1,
+      acceptedJobCount: 1,
+      deliveredCount: 1,
+      transientErrored: false,
+    });
+  });
+
+  it('does not deliver when no listener subscription matches', async () => {
+    const workspaceId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      source: 'github',
+      event: 'push',
+    });
+
+    const result = await route({workspaceId, event: 'pull_request'});
+
+    expect(deliverEventToListener).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      engagedCount: 0,
+      matchedJobCount: 0,
+      acceptedJobCount: 0,
+      deliveredCount: 0,
+      transientErrored: false,
+    });
+  });
+
+  it('does not count skipped stale subscriptions as accepted deliveries', async () => {
+    const workspaceId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      source: 'github',
+      event: 'pull_request_review',
+    });
+    deliverEventToListener.mockResolvedValueOnce({buffered: false, skipped: true});
+
+    const result = await route({workspaceId});
+
+    expect(result).toMatchObject({
+      engagedCount: 0,
+      matchedJobCount: 1,
+      acceptedJobCount: 0,
+      deliveredCount: 0,
+      transientErrored: false,
+    });
+  });
+
+  it('surfaces transient delivery errors after attempting every matched job', async () => {
+    const workspaceId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      jobId: crypto.randomUUID(),
+      source: 'github',
+      event: 'pull_request_review',
+    });
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      jobId: crypto.randomUUID(),
+      source: 'github',
+      event: 'pull_request_review',
+    });
+    const error = new Error('workflow db down');
+    deliverEventToListener.mockRejectedValueOnce(error);
+
+    const result = await route({workspaceId});
+
+    expect(deliverEventToListener).toHaveBeenCalledTimes(2);
+    expect(listenerDispatchErrored).toHaveBeenCalledTimes(1);
+    expect(listenerDispatchErrored).toHaveBeenCalledWith(
+      expect.objectContaining({source: 'github', event: 'pull_request_review'}),
+      'workflow db down',
+    );
+    expect(listenerTriggered).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({
+      engagedCount: 2,
+      matchedJobCount: 2,
+      acceptedJobCount: 1,
+      deliveredCount: 1,
+      transientErrored: true,
+      transientError: error,
+    });
+  });
+
+  it('delivers only when a listener filter matches the payload and snapshot', async () => {
+    const workspaceId = crypto.randomUUID();
+    const jobId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      jobId,
+      source: 'github',
+      event: 'pull_request_review',
+      config: {
+        filter: 'event.issue.number == jobs.build.outputs.pr_number',
+        filter_snapshot: {jobs: {build: {outputs: {pr_number: 42}}}},
+      },
+    });
+
+    const result = await route({workspaceId, payload: {issue: {number: 42}}});
+
+    expect(deliverEventToListener).toHaveBeenCalledTimes(1);
+    expect(listenerTriggered).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({engagedCount: 1, matchedJobCount: 1, acceptedJobCount: 1});
+  });
+
+  it('does not deliver or record a decision when a listener filter returns false', async () => {
+    const workspaceId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      source: 'github',
+      event: 'pull_request_review',
+      config: {
+        filter: 'event.issue.number == jobs.build.outputs.pr_number',
+        filter_snapshot: {jobs: {build: {outputs: {pr_number: 42}}}},
+      },
+    });
+
+    const result = await route({workspaceId, payload: {issue: {number: 7}}});
+
+    expect(deliverEventToListener).not.toHaveBeenCalled();
+    expect(listenerTriggered).not.toHaveBeenCalled();
+    expect(listenerFilterErrored).not.toHaveBeenCalled();
+    expect(result).toMatchObject({engagedCount: 0, matchedJobCount: 0, acceptedJobCount: 0});
+  });
+
+  it.each([
+    {name: 'missing jobs snapshot', filterSnapshot: {}},
+    {name: 'empty jobs snapshot', filterSnapshot: {jobs: {}}},
+  ])('records filter-error when listener filter evaluation fails with $name', async ({
+    filterSnapshot,
+  }) => {
+    const workspaceId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      source: 'github',
+      event: 'pull_request_review',
+      config: {
+        filter: 'event.issue.number == jobs.build.outputs.pr_number',
+        filter_snapshot: filterSnapshot,
+      },
+    });
+
+    const result = await route({workspaceId, payload: {issue: {number: 42}}});
+
+    expect(deliverEventToListener).not.toHaveBeenCalled();
+    expect(listenerFilterErrored).toHaveBeenCalledTimes(1);
+    expect(listenerFilterErrored).toHaveBeenCalledWith(
+      expect.objectContaining({source: 'github', event: 'pull_request_review'}),
+      'Listener filter evaluation failed',
+    );
+    expect(result).toMatchObject({engagedCount: 1, matchedJobCount: 0, acceptedJobCount: 0});
+  });
+
+  it('records filter-error when a listener snapshot is malformed', async () => {
+    const workspaceId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      source: 'github',
+      event: 'pull_request_review',
+      config: {
+        filter: 'event.issue.number == jobs.build.outputs.pr_number',
+        filter_snapshot: ['not-object'],
+      },
+    });
+
+    const result = await route({workspaceId, payload: {issue: {number: 42}}});
+
+    expect(deliverEventToListener).not.toHaveBeenCalled();
+    expect(listenerFilterErrored).toHaveBeenCalledWith(
+      expect.anything(),
+      'Listener filter snapshot must be an object when set',
+    );
+    expect(result).toMatchObject({engagedCount: 1, matchedJobCount: 0});
+  });
+
+  it('chooses the lowest ordinal when multiple same-kind matchers pass for one job', async () => {
+    const workspaceId = crypto.randomUUID();
+    const jobId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      jobId,
+      kind: 'on',
+      matcherOrdinal: 1,
+      source: 'github',
+      event: 'pull_request_review',
+    });
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      jobId,
+      kind: 'on',
+      matcherOrdinal: 0,
+      source: 'github',
+      event: 'pull_request_review',
+    });
+
+    await route({workspaceId});
+
+    expect(deliverEventToListener).toHaveBeenCalledTimes(1);
+    expect(listenerTriggered).toHaveBeenCalledWith(
+      expect.objectContaining({jobId, kind: 'on', matcherOrdinal: 0}),
+    );
+  });
+
+  it('chooses a deterministic subscription id order for duplicate matcher keys', async () => {
+    const workspaceId = crypto.randomUUID();
+    const jobId = crypto.randomUUID();
+    const kept = jobListenerSubscriptionFactory.build({
+      id: '00000000-0000-7000-8000-000000000001',
+      workspaceId,
+      jobId,
+      kind: 'on',
+      matcherOrdinal: 0,
+      source: 'github',
+      event: 'pull_request_review',
+    });
+    const first = jobListenerSubscriptionFactory.build({
+      id: '00000000-0000-7000-8000-000000000002',
+      workspaceId,
+      jobId,
+      kind: 'on',
+      matcherOrdinal: 0,
+      source: 'github',
+      event: 'pull_request_review',
+    });
+    findMatchingJobListenerSubscriptions.mockResolvedValueOnce([first, kept]);
+
+    const result = await route({workspaceId});
+
+    expect(loggerWarn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        jobId,
+        keptSubscriptionId: first.id,
+        candidateSubscriptionId: kept.id,
+        matcherKind: 'on',
+        matcherOrdinal: 0,
+      }),
+      'duplicate job listener matcher key encountered; choosing deterministic subscription id order',
+    );
+    expect(listenerTriggered).toHaveBeenCalledWith(expect.objectContaining({id: kept.id}));
+    expect(result).toMatchObject({engagedCount: 1, matchedJobCount: 1, acceptedJobCount: 1});
+  });
+
+  it('does not record triggered for skipped stale listener jobs', async () => {
+    const workspaceId = crypto.randomUUID();
+    await jobListenerSubscriptionFactory.create({
+      workspaceId,
+      source: 'github',
+      event: 'pull_request_review',
+    });
+    deliverEventToListener.mockResolvedValueOnce({buffered: false, skipped: true});
+
+    const result = await route({workspaceId});
+
+    expect(listenerTriggered).not.toHaveBeenCalled();
+    expect(result).toMatchObject({engagedCount: 0, matchedJobCount: 1, acceptedJobCount: 0});
+  });
+});

package/src/core/route-event-to-job-listeners.ts

@@ -0,0 +1,184 @@
+import {deliverEventToListener, type JobListenerEventDisposition} from '@shipfox/api-workflows';
+import {logger} from '@shipfox/node-opentelemetry';
+import {findMatchingJobListenerSubscriptions} from '#db/job-listener-subscriptions.js';
+import {evaluateStoredFilter, type StoredFilterEvaluation} from './config.js';
+import type {JobListenerSubscription} from './entities/job-listener-subscription.js';
+import {type TriggerHistoryRecorder, toReason} from './record-trigger-history.js';
+
+export interface RouteEventToJobListenersParams {
+  history: TriggerHistoryRecorder;
+  eventRef: string;
+  workspaceId: string;
+  provider: string;
+  source: string;
+  event: string;
+  deliveryId: string;
+  payload: unknown;
+  receivedAt: Date;
+}
+
+export interface RouteEventToJobListenersResult {
+  /**
+   * Listener outcomes that should contribute to received_event.matched_count:
+   * filter errors, accepted deliveries, and dispatch errors. Stale skipped jobs
+   * are intentionally excluded because they did not produce an auditable decision.
+   */
+  engagedCount: number;
+  /**
+   * Jobs with an effective matcher after source/event/filter checks, including
+   * stale skipped jobs.
+   */
+  matchedJobCount: number;
+  acceptedJobCount: number;
+  deliveredCount: number;
+  transientErrored: boolean;
+  transientError: unknown;
+}
+
+export async function routeEventToJobListeners(
+  params: RouteEventToJobListenersParams,
+): Promise<RouteEventToJobListenersResult> {
+  const subscriptions = await findMatchingJobListenerSubscriptions({
+    workspaceId: params.workspaceId,
+    source: params.source,
+    event: params.event,
+  });
+
+  let filterErrorCount = 0;
+  const effectiveMatchByJobId = new Map<string, JobListenerSubscription>();
+  for (const subscription of subscriptions) {
+    const filterResult = evaluateListenerFilter({subscription, payload: params.payload});
+    if (filterResult.kind === 'filtered') continue;
+    if (filterResult.kind === 'filter-error') {
+      filterErrorCount += 1;
+      await params.history.listenerFilterErrored(subscription, filterResult.reason);
+      continue;
+    }
+
+    const previous = effectiveMatchByJobId.get(subscription.jobId);
+    if (!previous || shouldReplaceEffectiveMatcher(previous, subscription)) {
+      effectiveMatchByJobId.set(subscription.jobId, subscription);
+    }
+  }
+
+  let acceptedJobCount = 0;
+  let deliveredCount = 0;
+  let sawTransientError = false;
+  let dispatchErrorCount = 0;
+  let firstTransientError: unknown;
+
+  for (const subscription of effectiveMatchByJobId.values()) {
+    const disposition = listenerDisposition(subscription);
+    try {
+      const result = await deliverEventToListener({
+        jobId: subscription.jobId,
+        disposition,
+        eventRef: params.eventRef,
+        deliveryId: params.deliveryId,
+        source: params.source,
+        event: params.event,
+        provider: params.provider,
+        payload: params.payload,
+        receivedAt: params.receivedAt,
+      });
+      if (!result.skipped) {
+        acceptedJobCount += 1;
+        await params.history.listenerTriggered(subscription);
+      }
+      if (result.buffered) deliveredCount += 1;
+    } catch (error) {
+      dispatchErrorCount += 1;
+      await params.history.listenerDispatchErrored(subscription, toReason(error));
+      if (!sawTransientError) {
+        sawTransientError = true;
+        firstTransientError = error;
+      }
+    }
+  }
+
+  return {
+    engagedCount: filterErrorCount + acceptedJobCount + dispatchErrorCount,
+    matchedJobCount: effectiveMatchByJobId.size,
+    acceptedJobCount,
+    deliveredCount,
+    transientErrored: sawTransientError,
+    transientError: sawTransientError ? firstTransientError : undefined,
+  };
+}
+
+interface EvaluateListenerFilterParams {
+  subscription: JobListenerSubscription;
+  payload: unknown;
+}
+
+function evaluateListenerFilter(params: EvaluateListenerFilterParams): StoredFilterEvaluation {
+  const filter = params.subscription.config.filter;
+  if (filter === null || filter === undefined) return {kind: 'matched'};
+  if (typeof filter !== 'string' || filter.trim() === '') {
+    return evaluateStoredFilter({
+      value: filter,
+      context: {event: params.payload},
+      invalidReason: 'Listener subscription filter must be a non-empty string when set',
+      evaluationFailedReason: 'Listener filter evaluation failed',
+    });
+  }
+
+  const snapshot = readFilterSnapshot(params.subscription);
+  if (snapshot.kind === 'invalid') return snapshot.result;
+
+  return evaluateStoredFilter({
+    value: filter,
+    context: {...snapshot.value, event: params.payload},
+    invalidReason: 'Listener subscription filter must be a non-empty string when set',
+    evaluationFailedReason: 'Listener filter evaluation failed',
+  });
+}
+
+function readFilterSnapshot(
+  subscription: JobListenerSubscription,
+):
+  | {kind: 'valid'; value: Record<string, unknown>}
+  | {kind: 'invalid'; result: Extract<StoredFilterEvaluation, {kind: 'filter-error'}>} {
+  const value = subscription.config.filter_snapshot;
+  if (value === undefined) return {kind: 'valid', value: {}};
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    return {kind: 'valid', value: value as Record<string, unknown>};
+  }
+  return {
+    kind: 'invalid',
+    result: {
+      kind: 'filter-error',
+      reason: 'Listener filter snapshot must be an object when set',
+    },
+  };
+}
+
+function listenerDisposition(subscription: JobListenerSubscription): JobListenerEventDisposition {
+  return subscription.kind === 'until' ? 'resolve' : 'fire';
+}
+
+function listenerMatcherSortKey(subscription: JobListenerSubscription): string {
+  const kindRank = subscription.kind === 'until' ? '0' : '1';
+  return `${kindRank}:${subscription.matcherOrdinal.toString().padStart(10, '0')}`;
+}
+
+function shouldReplaceEffectiveMatcher(
+  previous: JobListenerSubscription,
+  candidate: JobListenerSubscription,
+): boolean {
+  const previousKey = listenerMatcherSortKey(previous);
+  const candidateKey = listenerMatcherSortKey(candidate);
+  if (candidateKey !== previousKey) return candidateKey < previousKey;
+
+  logger().warn(
+    {
+      jobId: candidate.jobId,
+      keptSubscriptionId: previous.id,
+      candidateSubscriptionId: candidate.id,
+      matcherKind: candidate.kind,
+      matcherOrdinal: candidate.matcherOrdinal,
+    },
+    'duplicate job listener matcher key encountered; choosing deterministic subscription id order',
+  );
+  return candidate.id < previous.id;
+}