tapimo 0.10.2 → 0.11.0

package/src/apps/management/routes/webhooks.test.ts

@@ -10,7 +10,10 @@ import * as Orgs from './orgs.js'
 import * as Webhooks from './webhooks.js'
 
 const origin = 'http://localhost'
-const webhook = { supportedChainIds: [4217, 42431] } satisfies App.Webhook
+const webhook = {
+  applicationEventTypes: ['funding:deposit.updated'],
+  supportedChainIds: [4217, 42431],
+} satisfies App.Webhook
 
 function json(method: 'PATCH' | 'POST', cookie: string, body: unknown) {
   return {
@@ -47,6 +50,81 @@ async function organization(app: ReturnType<typeof createApp>, cookie: string) {
 }
 
 describe('webhooks', () => {
+  test('creates funding deposit subscriptions without reading the RPC head', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db })
+    const cookie = await session(app)
+    const org = await organization(app, cookie)
+    const response = await app.request(
+      `/v1/orgs/${org.id}/webhooks`,
+      json('POST', cookie, {
+        chainId: 4217,
+        destination: { type: 'url', url: 'https://example.com/funding' },
+        environment: 'production',
+        eventType: 'funding:deposit.updated',
+        filters: { status: 'completed' },
+      }),
+    )
+    const created = await TestApp.json(response, Webhooks.schema.createWebhook.Response)
+    const stored = await core_Webhooks.getSubscription(
+      db,
+      { orgId: org.id, type: 'api_key' },
+      created.id,
+    )
+    const listedResponse = await app.request(`/v1/orgs/${org.id}/webhooks`, {
+      headers: { cookie },
+    })
+    const listed = await TestApp.json(listedResponse, Webhooks.schema.ListResponse)
+
+    expect(response.status).toBe(200)
+    expect(created.environment).toBe('production')
+    expect(listed.data[0]?.environment).toBe('production')
+    expect(stored?.environment).toBe('production')
+    expect(await core_Webhooks.getCursor(db, created.id)).toBeNull()
+  })
+
+  test('preserves a production funding environment on testnet', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db })
+    const cookie = await session(app)
+    const org = await organization(app, cookie)
+    const response = await app.request(
+      `/v1/orgs/${org.id}/webhooks`,
+      json('POST', cookie, {
+        chainId: 42431,
+        destination: { type: 'url', url: 'https://example.com/funding-testnet' },
+        environment: 'production',
+        eventType: 'funding:deposit.updated',
+      }),
+    )
+    const created = await TestApp.json(response, Webhooks.schema.createWebhook.Response)
+    const stored = await core_Webhooks.getSubscription(
+      db,
+      { orgId: org.id, type: 'api_key' },
+      created.id,
+    )
+
+    expect(response.status).toBe(200)
+    expect(created.environment).toBe('production')
+    expect(stored?.environment).toBe('production')
+  })
+
+  test('requires an explicit environment for funding deposit subscriptions', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const org = await organization(app, cookie)
+    const response = await app.request(
+      `/v1/orgs/${org.id}/webhooks`,
+      json('POST', cookie, {
+        chainId: 4217,
+        destination: { type: 'url', url: 'https://example.com/funding' },
+        eventType: 'funding:deposit.updated',
+      }),
+    )
+
+    expect(response.status).toBe(400)
+  })
+
   test('creates, lists, pauses, and deletes an organization webhook', async () => {
     const db = TestApp.database()
     const app = createApp({ db })

package/src/apps/management/routes/webhooks.ts

@@ -22,13 +22,29 @@ export namespace schema {
 
   /** Schemas for creating an organization webhook. */
   export namespace createWebhook {
+    const Environment = z
+      .enum(['production', 'sandbox'])
+      .check(
+        z.describe('API-key environment whose private funding deposits are delivered.'),
+        z.meta({ examples: ['production'] }),
+      )
+
     /** Organization webhook creation requires an explicit network. */
     export const Body = z
       .intersection(
         webhookSchema.createWebhook.Body,
-        z.object({ chainId: webhookSchema.Subscription.shape.chainId }),
+        z.object({
+          chainId: webhookSchema.Subscription.shape.chainId,
+          environment: z.optional(Environment),
+        }),
+      )
+      .check(
+        z.refine(
+          (body) => body.eventType !== 'funding:deposit.updated' || body.environment !== undefined,
+          { error: '`environment` is required for funding deposit subscriptions.' },
+        ),
+        z.describe('Details for creating an organization webhook subscription.'),
       )
-      .check(z.describe('Details for creating an organization webhook subscription.'))
 
     const secret = webhookSchema.createWebhook.Response.shape.secret
     const urlDestination = z.object({
@@ -181,6 +197,7 @@ export function webhooks(options: webhooks.Options = {}) {
               codes: [
                 'body_invalid',
                 'chain_id_unsupported',
+                'event_type_unsupported',
                 'filters_invalid',
                 'param_invalid',
                 'url_invalid',
@@ -213,6 +230,15 @@ export function webhooks(options: webhooks.Options = {}) {
         if (!options.webhook) return notEnabled(c)
 
         const body = c.req.valid('json')
+        if (
+          body.eventType === 'funding:deposit.updated' &&
+          !options.webhook.applicationEventTypes?.includes(body.eventType)
+        )
+          return Response.error(c, {
+            code: 'event_type_unsupported',
+            message: 'Webhook event type is not available in this deployment',
+            status: 400,
+          })
         const chainId = body.chainId
         const supportedChainIds = new Set(options.webhook.supportedChainIds)
         if (!supportedChainIds.has(chainId))
@@ -225,20 +251,26 @@ export function webhooks(options: webhooks.Options = {}) {
           const owner_ = owner(Auth.org(c).id)
           if ((await Webhooks.countSubscriptions(db, owner_)) >= maxPerOwner)
             throw new Webhooks.LimitExceededError(maxPerOwner)
-          const startBlockNumber = Number(await c.get('getClient')(chainId).getBlockNumber())
+          const startBlockNumber =
+            body.eventType === 'funding:deposit.updated'
+              ? undefined
+              : Number(await c.get('getClient')(chainId).getBlockNumber())
           const subscription = await Webhooks.createSubscription(
             db,
             {
               chainId,
               ...(body.context === undefined ? {} : { context: body.context }),
               destination: body.destination,
+              ...(body.eventType === 'funding:deposit.updated' && body.environment !== undefined
+                ? { environment: body.environment }
+                : {}),
               eventType: body.eventType,
               filters: body.filters,
               owner: owner_,
             },
             {
               maxPerOwner,
-              startBlockNumber,
+              ...(startBlockNumber === undefined ? {} : { startBlockNumber }),
             },
           )
           return c.json(
@@ -609,6 +641,10 @@ function publicSubscription(subscription: Webhooks.Subscription) {
     ...(subscription.context === undefined ? {} : { context: subscription.context }),
     createdAt: subscription.createdAt,
     destination,
+    ...(subscription.eventType === 'funding:deposit.updated' &&
+    subscription.environment !== undefined
+      ? { environment: subscription.environment }
+      : {}),
     eventType: subscription.eventType,
     ...(subscription.expiresAt === undefined ? {} : { expiresAt: subscription.expiresAt }),
     failureCount: subscription.failureCount,

package/src/db/Db.test.ts

@@ -71,11 +71,7 @@ describe('postgres', () => {
       await Organizations.create(tx, { id: 'org_qualified', name: 'Qualified' })
     })
     expect((await Organizations.get(db, 'org_qualified'))?.name).toBe('Qualified')
-    expect(
-      await WebhookSubscriptions.compareAndSetCursors(db, {
-        cursors: [{ cursor: 'next', expectedCursor: null, subscriptionId: 'wh_missing' }],
-      }),
-    ).toEqual(new Set())
+    expect(await WebhookSubscriptions.getCursor(db, 'wh_missing')).toBeNull()
     await db.close()
   })
 

package/src/db/Db.ts

@@ -1398,6 +1398,29 @@ export const migrations: readonly Migration[] = [
         .on('fundingDeposits')
         .columns(['orgId', 'environment', 'projectId', 'createdAt', 'id']),
   },
+  {
+    name: '0127_webhook_subscriptions_environment',
+    up: (db) => raw(db, sql`ALTER TABLE webhook_subscriptions ADD COLUMN IF NOT EXISTS environment text`), // prettier-ignore
+  },
+  {
+    name: '0128_webhook_subscriptions_project',
+    up: (db) => raw(db, sql`ALTER TABLE webhook_subscriptions ADD COLUMN IF NOT EXISTS project_id text`), // prettier-ignore
+  },
+  {
+    name: '0129_webhook_subscriptions_funding_deposit_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_subscriptions_funding_deposit_idx')
+        .ifNotExists()
+        .on('webhookSubscriptions')
+        .columns(['eventType', 'ownerType', 'ownerId', 'environment', 'projectId', 'chainId'])
+        .where(sql.ref('status'), '=', sql.lit('active')),
+  },
+  {
+    name: '0130_webhook_queue_events_observed_at',
+    up: (db) =>
+      raw(db, sql`ALTER TABLE webhook_queue_events ADD COLUMN IF NOT EXISTS observed_at text`),
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -792,6 +792,9 @@ export const WebhookSubscription = z.object({
   destination: z
     .custom<Webhooks.Destination>()
     .check(z.describe('Delivery destination (`jsonb`).')),
+  environment: z
+    .nullable(z.enum(['production', 'sandbox']))
+    .check(z.describe('API-key environment for private resource events, or null.')),
   eventType: z
     .custom<Webhooks.EventType>()
     .check(z.describe('Event type the subscription listens to.')),
@@ -820,6 +823,9 @@ export const WebhookSubscription = z.object({
   pollerCursor: z
     .nullable(z.string())
     .check(z.describe('Poller keyset cursor, or null before the first tick.')),
+  projectId: z
+    .nullable(z.string())
+    .check(z.describe('API-key project attribution for private resource events, or null.')),
   secret: z.string().check(z.describe('HMAC signing secret.')),
   status: z.custom<Webhooks.Status>().check(z.describe('Lifecycle status.')),
   updatedAt: z
@@ -896,6 +902,13 @@ export const WebhookQueueEvent = z.object({
   nextAttemptAt: z
     .nullable(z.string())
     .check(z.describe('ISO retry due time, or null when due immediately.')),
+  observedAt: z
+    .nullable(z.string())
+    .check(
+      z.describe(
+        'ISO timestamp the coordinator observed the head owing this event, or null on replays.',
+      ),
+    ),
   status: z
     .enum(['failed', 'pending', 'skipped', 'succeeded'])
     .check(z.describe('Delivery-obligation lifecycle status.')),

package/src/db/tables/organizations.test.ts

@@ -363,8 +363,11 @@ describe('deleteOrganization', () => {
     expect(await Organizations.deleteOrganization(db, 'org_1')).toBe(true)
 
     expect(await Webhooks.listSubscriptions(db, deletedOrg)).toEqual([])
-    const active = await Webhooks.listActive(db, 4217, 'token:transfer')
-    expect(active.map(({ id }) => id).sort()).toEqual(
+    const active = await Webhooks.listActiveForChain(db, {
+      chainId: 4217,
+      eventTypes: ['token:transfer'],
+    })
+    expect(active.map(({ subscription }) => subscription.id).sort()).toEqual(
       [keptApiKey.id, keptMppSubscription.id].sort(),
     )
     await db.close()

package/src/db/tables/webhookQueueEvents.ts

@@ -7,7 +7,7 @@ import type * as db_Schema from '../Schema.js'
 /** Columns of the `webhook_queue_events` table, derived from `Schema.WebhookQueueEvent`. */
 export type Table = Omit<
   db_Schema.WebhookQueueEvent,
-  'attemptCount' | 'attemptingAt' | 'nextAttemptAt' | 'status'
+  'attemptCount' | 'attemptingAt' | 'nextAttemptAt' | 'observedAt' | 'status'
 > & {
   /** Delivery attempts claimed so far; database default 0. */
   attemptCount: Generated<number>
@@ -15,6 +15,8 @@ export type Table = Omit<
   attemptingAt: Generated<string | null>
   /** ISO retry due time; database default null (due immediately). */
   nextAttemptAt: Generated<string | null>
+  /** ISO head-observation stamp; database default null (replays carry none). */
+  observedAt: Generated<string | null>
   /** Delivery-obligation lifecycle status; database default `pending`. */
   status: Generated<db_Schema.WebhookQueueEvent['status']>
 }
@@ -65,6 +67,10 @@ export async function ensure(db: Db.Db, rows: readonly Insertable<Table>[]): Pro
           envelope: eb.ref('excluded.envelope'),
           expiresAt: eb.ref('excluded.expiresAt'),
           nextAttemptAt: eb.ref('excluded.nextAttemptAt'),
+          // Refreshed with the rest: a replacement keeping the replaced row's
+          // stamp would measure observation-to-attempt from an observation
+          // that belongs to a delivery made days earlier.
+          observedAt: eb.ref('excluded.observedAt'),
           status: 'pending',
         }))
         .where((eb) =>

package/src/db/tables/webhookSubscriptions.ts

@@ -1,6 +1,7 @@
 import type { ExpressionBuilder, Selectable } from 'kysely'
 import { sql } from 'kysely'
 
+import * as Scope from '../../Scope.js'
 import type * as Webhooks from '../../internal/Webhooks.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
@@ -40,6 +41,7 @@ export function toSubscription(row: Record): Webhooks.Subscription {
     ...(row.context === null ? {} : { context: row.context }),
     createdAt: row.createdAt,
     destination: row.destination,
+    ...(row.environment === null ? {} : { environment: row.environment }),
     eventType: row.eventType,
     ...(row.expiresAt === null ? {} : { expiresAt: row.expiresAt }),
     failureCount: row.failureCount,
@@ -50,6 +52,7 @@ export function toSubscription(row: Record): Webhooks.Subscription {
       row.ownerType === 'api_key'
         ? { orgId: row.ownerId, type: 'api_key' }
         : { payer: row.ownerId, type: 'mpp' },
+    ...(row.projectId === null ? {} : { projectId: row.projectId }),
     secret: row.secret,
     status: row.status,
     updatedAt: row.updatedAt,
@@ -75,6 +78,7 @@ export async function insert(
       context: subscription.context ?? null,
       createdAt: subscription.createdAt,
       destination: subscription.destination,
+      environment: subscription.environment ?? null,
       eventType: subscription.eventType,
       expiresAt: subscription.expiresAt ?? null,
       failureCount: subscription.failureCount,
@@ -84,6 +88,7 @@ export async function insert(
       ownerId: ownerId(subscription.owner),
       ownerType: subscription.owner.type,
       pollerCursor: options.pollerCursor ?? null,
+      projectId: subscription.projectId ?? null,
       secret: subscription.secret,
       status: subscription.status,
       updatedAt: subscription.updatedAt,
@@ -94,7 +99,7 @@ export async function insert(
 export declare namespace insert {
   /** Options for {@link insert}. */
   type Options = {
-    /** Initial poller cursor committed with the subscription. */
+    /** Initial cursor committed with the subscription. */
     pollerCursor?: string | undefined
   }
 }
@@ -129,7 +134,7 @@ export declare namespace insertWithinLimit {
     maxPerOwner: number
     /** ISO timestamp used to exclude expired rows from the count. */
     now: string
-    /** Initial poller cursor committed with the subscription. */
+    /** Initial cursor committed with the subscription. */
     pollerCursor?: string | undefined
   }
 }
@@ -149,15 +154,17 @@ export async function get(
   owner: Webhooks.Owner,
   id: string,
   now: string,
+  access?: Webhooks.Access,
 ): Promise<Webhooks.Subscription | null> {
-  const row = await db.kysely
+  let query = db.kysely
     .selectFrom('webhook_subscriptions')
     .selectAll()
     .where('id', '=', id)
     .where('ownerType', '=', owner.type)
     .where('ownerId', '=', ownerId(owner))
     .where(live(now))
-    .executeTakeFirst()
+  if (access) query = query.where(privateResourceAccess(access))
+  const row = await query.executeTakeFirst()
   return row ? toSubscription(row) : null
 }
 
@@ -183,6 +190,7 @@ export async function list(
     .where('ownerId', '=', ownerId(owner))
     .where(live(options.now))
     .orderBy('id', 'desc')
+  if (options.access) query = query.where(privateResourceAccess(options.access))
   if (options.cursor) query = query.where('id', '<', options.cursor)
   if (options.offset) query = query.offset(options.offset)
   if (options.limit !== undefined) query = query.limit(options.limit)
@@ -192,6 +200,8 @@ export async function list(
 export declare namespace list {
   /** Options for {@link list}. */
   type Options = {
+    /** Private-resource visibility scope. */
+    access?: Webhooks.Access | undefined
     /** Return subscriptions older than this id (keyset paging, newest first). */
     cursor?: string | undefined
     /** Maximum subscriptions to return. */
@@ -211,14 +221,20 @@ export declare namespace list {
  * @param now - ISO timestamp expiry is evaluated against.
  * @returns The count.
  */
-export async function count(db: Db.Db, owner: Webhooks.Owner, now: string): Promise<number> {
-  const row = await db.kysely
+export async function count(
+  db: Db.Db,
+  owner: Webhooks.Owner,
+  now: string,
+  access?: Webhooks.Access,
+): Promise<number> {
+  let query = db.kysely
     .selectFrom('webhook_subscriptions')
     .select((eb) => eb.fn.countAll().as('count'))
     .where('ownerType', '=', owner.type)
     .where('ownerId', '=', ownerId(owner))
     .where(live(now))
-    .executeTakeFirstOrThrow()
+  if (access) query = query.where(privateResourceAccess(access))
+  const row = await query.executeTakeFirstOrThrow()
   return Number(row.count)
 }
 
@@ -275,21 +291,42 @@ export async function remove(
   owner: Webhooks.Owner,
   id: string,
   now: string,
+  access?: Webhooks.Access,
 ): Promise<boolean> {
-  const result = await db.kysely
+  let query = db.kysely
     .deleteFrom('webhook_subscriptions')
     .where('id', '=', id)
     .where('ownerType', '=', owner.type)
     .where('ownerId', '=', ownerId(owner))
     .where(live(now))
-    .executeTakeFirst()
+  if (access) query = query.where(privateResourceAccess(access))
+  const result = await query.executeTakeFirst()
   return result.numDeletedRows > 0n
 }
 
+function privateResourceAccess(access: Webhooks.Access) {
+  const fundingRead = access.scopes.some(
+    (scope) => scope === Scope.wildcard || scope === 'funding:read',
+  )
+  return (eb: ExpressionBuilder<Db.Database, 'webhook_subscriptions'>) =>
+    eb.or([
+      eb('eventType', '!=', 'funding:deposit.updated'),
+      ...(fundingRead
+        ? [
+            eb.and([
+              eb('eventType', '=', 'funding:deposit.updated'),
+              eb('environment', '=', access.environment),
+              ...(access.projectId === undefined ? [] : [eb('projectId', '=', access.projectId)]),
+            ]),
+          ]
+        : []),
+    ])
+}
+
 /**
- * Lists live `active` subscriptions for a `(chainId, eventType)` stream — the
- * poller's per-stream lookup, served by the partial status index. Each row
- * carries its poller cursor so the poller avoids a per-subscription read.
+ * Lists live `active` subscriptions for a `(chainId, eventType)` stream,
+ * served by the partial status index. Each row carries its cursor so callers
+ * avoid a per-subscription read.
  *
  * @param db - The database.
  * @param chainId - Chain the stream belongs to.
@@ -316,8 +353,8 @@ export async function listActive(
 }
 
 /**
- * Lists every live `active` subscription on a chain in one read. The poller
- * groups the rows by event type so empty streams cost no extra database reads.
+ * Lists every live `active` subscription on a chain in one read. Callers
+ * group the rows by event type so empty streams cost no extra database reads.
  *
  * @param db - The database.
  * @param options - Chain, configured event types, and expiry time.
@@ -342,43 +379,58 @@ export async function listActiveForChain(
 }
 
 export declare namespace listActiveForChain {
-  /** Filters for the poller's chain-level subscription read. */
+  /** Filters for the chain-level subscription read. */
   type Options = {
     /** Chain whose subscriptions to read. */
     chainId: number
-    /** Event types configured for this poller tick. */
+    /** Event types eligible for the read. */
     eventTypes: readonly Webhooks.EventType[]
     /** ISO timestamp expiry is evaluated against. */
     now: string
   }
 }
 
-/**
- * Reads the poller cursors of every live `active` subscription on a chain,
- * across event types. Feeds the cron's cursor-freshness fallback gate.
- *
- * @param db - The database.
- * @param chainId - Chain whose cursors to read.
- * @param now - ISO timestamp expiry is evaluated against.
- * @returns The non-null cursors, unordered.
- */
-export async function listActiveCursors(
+/** Lists live funding deposit subscriptions visible to one deposit owner. */
+export async function listActiveForFundingDeposit(
   db: Db.Db,
-  chainId: number,
-  now: string,
-): Promise<string[]> {
-  const rows = await db.kysely
+  options: listActiveForFundingDeposit.Options,
+): Promise<Webhooks.Subscription[]> {
+  let query = db.kysely
     .selectFrom('webhook_subscriptions')
-    .select('pollerCursor')
-    .where('chainId', '=', chainId)
+    .selectAll()
+    .where('chainId', '=', options.chainId)
+    .where('environment', '=', options.environment)
+    .where('eventType', '=', 'funding:deposit.updated')
+    .where('ownerId', '=', options.orgId)
+    .where('ownerType', '=', 'api_key')
     .where('status', '=', 'active')
-    .where(live(now))
-    .execute()
-  return rows.flatMap((row) => (row.pollerCursor === null ? [] : [row.pollerCursor]))
+    .where(live(options.now))
+  const projectId = options.projectId
+  query =
+    projectId === undefined
+      ? query.where('projectId', 'is', null)
+      : query.where((eb) => eb.or([eb('projectId', 'is', null), eb('projectId', '=', projectId)]))
+  return (await query.orderBy('id').execute()).map(toSubscription)
+}
+
+export declare namespace listActiveForFundingDeposit {
+  /** Ownership scope and chain for a funding deposit event. */
+  type Options = {
+    /** Destination Tempo chain id. */
+    chainId: number
+    /** Deposit API-key environment. */
+    environment: 'production' | 'sandbox'
+    /** ISO timestamp used to exclude expired subscriptions. */
+    now: string
+    /** Owning organization id. */
+    orgId: string
+    /** Attributed deposit project, when present. */
+    projectId?: string | undefined
+  }
 }
 
 /**
- * Reads a subscription's poller cursor.
+ * Reads a subscription's keyset cursor.
  *
  * @param db - The database.
  * @param id - The subscription id (`wh_…`).
@@ -393,107 +445,6 @@ export async function getCursor(db: Db.Db, id: string): Promise<string | null> {
   return row?.pollerCursor ?? null
 }
 
-/**
- * Writes a subscription's poller cursor. Deliberately does not touch
- * `updatedAt` — the cursor advances every tick and is not a user mutation.
- *
- * @param db - The database.
- * @param id - The subscription id (`wh_…`).
- * @param cursor - The keyset cursor to store.
- */
-export async function setCursor(db: Db.Db, id: string, cursor: string): Promise<void> {
-  await db.kysely
-    .updateTable('webhook_subscriptions')
-    .set({ pollerCursor: cursor })
-    .where('id', '=', id)
-    .execute()
-}
-
-/**
- * Writes a poller cursor only when the stored cursor still matches the caller's
- * observed value.
- *
- * @param db - The database.
- * @param options - Subscription, expected cursor, and next cursor.
- * @returns Whether the cursor was updated.
- */
-export async function compareAndSetCursor(
-  db: Db.Db,
-  options: compareAndSetCursor.Options,
-): Promise<boolean> {
-  let query = db.kysely
-    .updateTable('webhook_subscriptions')
-    .set({ pollerCursor: options.cursor })
-    .where('id', '=', options.subscriptionId)
-  query =
-    options.expectedCursor === null
-      ? query.where('pollerCursor', 'is', null)
-      : query.where('pollerCursor', '=', options.expectedCursor)
-  const result = await query.executeTakeFirst()
-  return result.numUpdatedRows > 0n
-}
-
-export declare namespace compareAndSetCursor {
-  /** Options for {@link compareAndSetCursor}. */
-  type Options = {
-    /** Next keyset cursor. */
-    cursor: string
-    /** Cursor observed before scanning, or null for an uninitialized subscription. */
-    expectedCursor: string | null
-    /** Subscription whose cursor advances. */
-    subscriptionId: string
-  }
-}
-
-/**
- * Writes multiple poller cursors when each stored value still matches the
- * caller's observed value.
- *
- * @param db - The database.
- * @param options - Candidate cursor writes.
- * @returns Subscription ids whose cursors were updated.
- */
-export async function compareAndSetCursors(
-  db: Db.Db,
-  options: compareAndSetCursors.Options,
-): Promise<Set<string>> {
-  if (options.cursors.length === 0) return new Set()
-  const values = JSON.stringify(options.cursors)
-  type Candidate = {
-    cursor: string
-    expectedCursor: string | null
-    subscriptionId: string
-  }
-  const result = await db.kysely
-    .with(
-      'candidates',
-      () => sql<Candidate>`(
-      SELECT
-        candidate."subscriptionId" AS subscription_id,
-        candidate."expectedCursor" AS expected_cursor,
-        candidate.cursor
-      FROM jsonb_to_recordset(${values}::jsonb)
-        AS candidate("subscriptionId" text, "expectedCursor" text, cursor text)
-    )`,
-    )
-    .updateTable('webhook_subscriptions as subscription')
-    .from('candidates as candidate')
-    .set((eb) => ({ pollerCursor: eb.ref('candidate.cursor') }))
-    .whereRef('subscription.id', '=', 'candidate.subscriptionId')
-    .whereRef('subscription.pollerCursor', 'is not distinct from', 'candidate.expectedCursor')
-    .returning('subscription.id as subscriptionId')
-    .execute()
-  return new Set(result.map((row) => row.subscriptionId))
-}
-
-export declare namespace compareAndSetCursors {
-  /** Options for {@link compareAndSetCursors}. */
-  type Options = {
-    /** Candidate cursor writes. */
-    cursors: readonly compareAndSetCursor.Options[]
-  }
-}
-
 /**
  * Records a successful delivery: resets the consecutive-failure counter and
  * stamps `lastDeliveryAt`.
@@ -549,7 +500,7 @@ export async function recordFailure(
 
 /**
  * Deletes expired subscriptions (their delivery rows cascade). Called
- * best-effort from the poller tick.
+ * best-effort on a schedule.
  *
  * @param db - The database.
  * @param now - ISO timestamp expiry is evaluated against.