tapimo 0.10.2 → 0.12.0

package/src/db/Schema.ts

@@ -1,6 +1,7 @@
 import * as z from 'zod/mini'
 import type { Address } from 'viem'
 
+import type * as EarnVaults from '../internal/EarnVaults.js'
 import type * as funding_Catalog from '../internal/funding/Catalog.js'
 import type * as funding_Deposit from '../internal/funding/Deposit.js'
 import type * as funding_DepositAddress from '../internal/funding/DepositAddress.js'
@@ -106,6 +107,9 @@ export const EarnVault = z
     slug: z.string().check(z.describe('Stable URL slug assigned when the vault is registered.')),
     updatedAt: z.string().check(z.describe('When the vault registration last changed (ISO 8601).')),
     vaultAddress: z.custom<Address>().check(z.describe('Earn vault address (lowercase).')),
+    zones: z
+      .custom<readonly EarnVaults.ZoneRoute[]>()
+      .check(z.describe('Curated private Zone routes (`jsonb`).')),
   })
   .check(z.describe('One curated Earn vault row.'))
 
@@ -792,6 +796,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 +827,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
@@ -875,6 +885,23 @@ export const WebhookDelivery = z.object({
 /** Columns of the `webhook_deliveries` table. */
 export type WebhookDelivery = z.output<typeof WebhookDelivery>
 
+/** An insert-only dedupe record marking a delivery obligation terminal. */
+export const WebhookQueueCompletion = z.object({
+  eventId: z.string().check(z.describe('Idempotent event id (`evt_...`).')),
+  expiresAt: z
+    .string()
+    .check(z.describe('ISO dedupe retention deadline; rows past it are invisible and pruned.')),
+  status: z
+    .enum(['failed', 'skipped', 'succeeded'])
+    .check(z.describe('Terminal delivery-obligation outcome.')),
+  subscriptionId: z
+    .string()
+    .check(z.describe('Owning subscription id (`wh_...`); FK with `ON DELETE CASCADE`.')),
+})
+
+/** Columns of the `webhook_queue_completions` table. */
+export type WebhookQueueCompletion = z.output<typeof WebhookQueueCompletion>
+
 /** A durable webhook envelope staged before its compact Queue reference is admitted. */
 export const WebhookQueueEvent = z.object({
   attemptCount: z.number().check(z.describe('Delivery attempts claimed so far.')),
@@ -887,18 +914,29 @@ export const WebhookQueueEvent = z.object({
     .check(z.describe('The full webhook envelope retained outside Cloudflare Queues.')),
   eventId: z.string().check(z.describe('Idempotent event id (`evt_...`).')),
   expiresAt: z
-    .string()
+    .nullable(z.string())
     .check(
       z.describe(
-        'ISO dedupe retention deadline, restarted at terminal transitions; inert while pending.',
+        'Unwritten since completions took over dedupe; non-null only on rows staged before the split.',
       ),
     ),
   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.')),
+    .check(
+      z.describe(
+        'Always `pending` since completions took over terminal state; other values occur only on rows completed before the split.',
+      ),
+    ),
   subscriptionId: z
     .string()
     .check(z.describe('Owning subscription id (`wh_...`); FK with `ON DELETE CASCADE`.')),

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

@@ -11,6 +11,13 @@ const input = {
   ],
   privateOutputTokens: ['0x20c00000000000000000000057F242B21a53ae4D'],
   vaultAddress: '0x2f05f4d3625B2eFFb383eFbEDAFd2D8F04371636',
+  zones: [
+    {
+      chainId: 1_424_310_001,
+      deploymentBlock: 31_039_238,
+      earnRouter: '0x9144086A79dea966d8bf1B52125eBED8919fC45c',
+    },
+  ],
 } as const satisfies EarnVaults.upsert.Options
 
 describe('upsert', () => {
@@ -36,6 +43,13 @@ describe('upsert', () => {
           ],
           "updatedAt": "2026-01-01T00:00:00.000Z",
           "vaultAddress": "0x2f05f4d3625b2effb383efbedafd2d8f04371636",
+          "zones": [
+            {
+              "chainId": 1424310001,
+              "deploymentBlock": 31039238,
+              "earnRouter": "0x9144086a79dea966d8bf1b52125ebed8919fc45c",
+            },
+          ],
         }
       `)
     } finally {
@@ -68,6 +82,7 @@ describe('upsert', () => {
         privateInputTokens: stored.privateInputTokens,
         privateOutputTokens: stored.privateOutputTokens,
         updatedAt: stored.updatedAt,
+        zones: stored.zones,
       }).toMatchInlineSnapshot(`
         {
           "createdAt": "2026-01-01T00:00:00.000Z",
@@ -76,6 +91,13 @@ describe('upsert', () => {
           "privateInputTokens": [],
           "privateOutputTokens": [],
           "updatedAt": "2026-01-02T00:00:00.000Z",
+          "zones": [
+            {
+              "chainId": 1424310001,
+              "deploymentBlock": 31039238,
+              "earnRouter": "0x9144086a79dea966d8bf1b52125ebed8919fc45c",
+            },
+          ],
         }
       `)
 

package/src/db/tables/earnVaults.ts

@@ -10,7 +10,7 @@ const slugSuffix = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', 8)
 /** Columns of the `earn_vaults` table. */
 export type Table = Omit<
   db_Schema.EarnVault,
-  'chainId' | 'privateInputTokens' | 'privateOutputTokens'
+  'chainId' | 'privateInputTokens' | 'privateOutputTokens' | 'zones'
 > & {
   /** Bigint chain id, read as a string from pg and written as a number. */
   chainId: ColumnType<string, number, number>
@@ -18,6 +18,8 @@ export type Table = Omit<
   privateInputTokens: JSONColumnType<db_Schema.EarnVault['privateInputTokens'], string, string>
   /** Tokens supported for private redemptions. */
   privateOutputTokens: JSONColumnType<db_Schema.EarnVault['privateOutputTokens'], string, string>
+  /** Curated private Zone routes. */
+  zones: JSONColumnType<db_Schema.EarnVault['zones'], string, string>
 }
 
 /** A stored curated Earn vault. */
@@ -76,6 +78,7 @@ export async function upsert(db: Db.Db, options: upsert.Options): Promise<Record
       slug,
       updatedAt: now,
       vaultAddress: normalize(options.vaultAddress),
+      zones: JSON.stringify(normalizeZones(options.zones)),
     })
     .onConflict((oc) =>
       oc.columns(['chainId', 'vaultAddress']).doUpdateSet({
@@ -85,6 +88,7 @@ export async function upsert(db: Db.Db, options: upsert.Options): Promise<Record
         privateOutputTokens: JSON.stringify(options.privateOutputTokens),
         ...(options.slug !== undefined ? { slug } : {}),
         updatedAt: now,
+        zones: JSON.stringify(normalizeZones(options.zones)),
       }),
     )
     .returningAll()
@@ -109,6 +113,8 @@ export declare namespace upsert {
     slug?: string | undefined
     /** Earn vault address. */
     vaultAddress: Address
+    /** Curated private Zone routes. */
+    zones: db_Schema.EarnVault['zones']
   }
 }
 
@@ -149,3 +155,7 @@ function toRecord(row: Selectable<Table>): Record {
 function normalize(address: string): Address {
   return address.toLowerCase() as Address
 }
+
+function normalizeZones(zones: db_Schema.EarnVault['zones']): db_Schema.EarnVault['zones'] {
+  return zones.map((zone) => ({ ...zone, earnRouter: normalize(zone.earnRouter) }))
+}

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/webhookDeliveries.ts

@@ -225,6 +225,10 @@ export async function get(
   return row ? toDelivery(row) : null
 }
 
+// Per-statement delete bound: prune runs every minute, so a backlog drains in
+// a few ticks instead of one unbounded DELETE churning the origin.
+const pruneBatchLimit = 50_000
+
 /**
  * Deletes deliveries past their retention deadline. Called best-effort from
  * the poller tick.
@@ -236,7 +240,16 @@ export async function get(
 export async function pruneExpired(db: Db.Db, now: string): Promise<number> {
   const result = await db.kysely
     .deleteFrom('webhook_deliveries')
+    // Repeated on the outer delete: the row recheck under concurrency re-runs
+    // only this predicate, so a row renewed mid-statement survives.
     .where('expiresAt', '<=', now)
+    .where('id', 'in', (eb) =>
+      eb
+        .selectFrom('webhook_deliveries')
+        .select('id')
+        .where('expiresAt', '<=', now)
+        .limit(pruneBatchLimit),
+    )
     .executeTakeFirst()
   return Number(result.numDeletedRows)
 }

package/src/db/tables/webhookQueueCompletions.ts

@@ -0,0 +1,55 @@
+import type * as Webhooks from '../../internal/Webhooks.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `webhook_queue_completions` table, derived from `Schema.WebhookQueueCompletion`. */
+export type Table = db_Schema.WebhookQueueCompletion
+
+/** A terminal delivery-obligation outcome. */
+export type TerminalStatus = db_Schema.WebhookQueueCompletion['status']
+
+/**
+ * Reads the unexpired completion for a reference, if any. Rows are written by
+ * the queue-event terminal transition and only ever read for dedupe.
+ */
+export async function get(
+  db: Db.Db,
+  reference: Webhooks.QueueReference,
+  now: string,
+): Promise<Table | null> {
+  return (
+    (await db.kysely
+      .selectFrom('webhook_queue_completions')
+      .selectAll()
+      .where('eventId', '=', reference.eventId)
+      .where('subscriptionId', '=', reference.subscriptionId)
+      .where('expiresAt', '>', now)
+      .executeTakeFirst()) ?? null
+  )
+}
+
+// Per-statement delete bound: prune runs every minute, so a backlog drains in
+// a few ticks instead of one unbounded DELETE churning the origin.
+const pruneBatchLimit = 50_000
+
+/** Deletes expired completions, bounded per call; expiry is filtered at query time, so pruning is space-only. */
+export async function pruneExpired(db: Db.Db, now: string): Promise<number> {
+  const result = await db.kysely
+    .deleteFrom('webhook_queue_completions')
+    // Repeated on the outer delete: the row recheck under concurrency re-runs
+    // only this predicate, so a completion renewed mid-statement survives.
+    .where('expiresAt', '<=', now)
+    .where(({ eb, refTuple, selectFrom }) =>
+      eb(
+        refTuple('subscriptionId', 'eventId'),
+        'in',
+        selectFrom('webhook_queue_completions')
+          .select(['subscriptionId', 'eventId'])
+          .where('expiresAt', '<=', now)
+          .limit(pruneBatchLimit)
+          .$asTuple('subscriptionId', 'eventId'),
+      ),
+    )
+    .executeTakeFirst()
+  return Number(result.numDeletedRows)
+}

package/src/db/tables/webhookQueueEvents.ts

@@ -2,19 +2,24 @@ import { type ExpressionBuilder, type Generated, type Insertable, type Selectabl
 
 import type * as Webhooks from '../../internal/Webhooks.js'
 import type * as Db from '../Db.js'
+import * as WebhookQueueCompletions from './webhookQueueCompletions.js'
 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' | 'expiresAt' | 'nextAttemptAt' | 'observedAt' | 'status'
 > & {
   /** Delivery attempts claimed so far; database default 0. */
   attemptCount: Generated<number>
   /** ISO timestamp of the current claim; database default null. */
   attemptingAt: Generated<string | null>
+  /** Legacy dedupe deadline; unwritten since completions took over. */
+  expiresAt: 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']>
 }
@@ -22,12 +27,9 @@ export type Table = Omit<
 /** A stored webhook Queue event. */
 export type Record = Selectable<Table>
 
-/** A terminal delivery-obligation outcome. */
-export type TerminalStatus = Exclude<db_Schema.WebhookQueueEvent['status'], 'pending'>
-
 /**
- * Reads one pending envelope. Terminal rows read as absent so no consumer
- * can redeliver a completed obligation or disturb its dedupe row.
+ * Reads one pending envelope. The status filter only ever excludes rows
+ * completed before the completions split; completions now leave the table.
  */
 export async function get(
   db: Db.Db,
@@ -45,38 +47,56 @@ export async function get(
 }
 
 /**
- * Stages envelopes as fresh obligations. Pending conflicts keep their first
- * envelope and backoff position; terminal conflicts inside the dedupe window
- * suppress the replay; terminal conflicts past it are replaced, so an expired
- * dedupe row pruning has not yet reclaimed never blocks a replay.
+ * Stages envelopes as fresh obligations. Unexpired completions and any
+ * existing row suppress the replay; a replay stages only when neither exists,
+ * which a completion past its dedupe window guarantees for completed work.
  */
 export async function ensure(db: Db.Db, rows: readonly Insertable<Table>[]): Promise<number> {
   if (rows.length === 0) return 0
+  const values = sql.join(
+    rows.map(
+      (row) =>
+        sql`(${row.subscriptionId}::text, ${row.eventId}::text, ${JSON.stringify(row.envelope)}::jsonb, ${row.createdAt}::text, ${row.nextAttemptAt ?? null}::text, ${row.observedAt ?? null}::text)`,
+    ),
+  )
+  // The VALUES source is raw because kysely has no table constructor for it,
+  // but both real tables stay in the builder so WithSchemaPlugin qualifies
+  // them (previews isolate by schema; raw identifiers would escape it). The
+  // completion check must ride the insert: a separate read would let a
+  // completion commit between the statements and re-stage just-finished work.
+  // `column1..6` are Postgres's default VALUES names, in the row order above;
+  // the window comparison uses each row's own staging time, not a shared clock.
+  // Conflicts only ever hit pending rows (or pre-split terminal rows during
+  // the drain), and both suppress the replay; a legitimate post-expiry replay
+  // meets no conflict because its completed row was deleted.
   const result = await db.kysely
     .insertInto('webhook_queue_events')
-    .values([...rows])
-    .onConflict((oc) =>
-      oc
-        .columns(['subscriptionId', 'eventId'])
-        .doUpdateSet((eb) => ({
-          attemptCount: 0,
-          attemptingAt: null,
-          createdAt: eb.ref('excluded.createdAt'),
-          envelope: eb.ref('excluded.envelope'),
-          expiresAt: eb.ref('excluded.expiresAt'),
-          nextAttemptAt: eb.ref('excluded.nextAttemptAt'),
-          status: 'pending',
-        }))
-        .where((eb) =>
-          eb.and([
-            eb('webhook_queue_events.status', '!=', 'pending'),
-            eb('webhook_queue_events.expiresAt', '<=', eb.ref('excluded.createdAt')),
-          ]),
+    .columns(['subscriptionId', 'eventId', 'envelope', 'createdAt', 'nextAttemptAt', 'observedAt'])
+    .expression((eb) =>
+      eb
+        .selectFrom(sql`(VALUES ${values})`.as('v'))
+        .select([
+          sql`v.column1`.as('subscriptionId'),
+          sql`v.column2`.as('eventId'),
+          sql`v.column3`.as('envelope'),
+          sql`v.column4`.as('createdAt'),
+          sql`v.column5`.as('nextAttemptAt'),
+          sql`v.column6`.as('observedAt'),
+        ])
+        .where(({ exists, not, selectFrom }) =>
+          not(
+            exists(
+              selectFrom('webhook_queue_completions')
+                .select('eventId')
+                .where('subscriptionId', '=', sql<string>`v.column1`)
+                .where('eventId', '=', sql<string>`v.column2`)
+                .where('expiresAt', '>', sql<string>`v.column4`),
+            ),
+          ),
         ),
     )
+    .onConflict((oc) => oc.columns(['subscriptionId', 'eventId']).doNothing())
     .executeTakeFirst()
-  // The command tag counts inserted rows plus replaced expired rows; live
-  // conflicts fall out of the conditional update and are not counted.
   return Number(result.numInsertedOrUpdatedRows ?? 0n)
 }
 
@@ -108,13 +128,23 @@ export async function claim(
     .executeTakeFirst()
   if (claimed) return { record: claimed, type: 'claimed' }
 
+  // Queue first, completions second: a complete() landing between the reads
+  // then still surfaces its completion, so a finished obligation never reads
+  // as missing, the one claim outcome alerts treat as a fault.
   const existing = await db.kysely
     .selectFrom('webhook_queue_events')
     .select(['attemptingAt', 'nextAttemptAt', 'status'])
     .where('subscriptionId', '=', reference.subscriptionId)
     .where('eventId', '=', reference.eventId)
     .executeTakeFirst()
-  if (!existing) return { type: 'missing' }
+  if (!existing) {
+    // An unexpired completion reads as terminal so claim-outcome metrics keep
+    // their meaning; an expired one reads as missing, like a pruned row.
+    const completed = await WebhookQueueCompletions.get(db, reference, options.now)
+    if (completed) return { status: completed.status, type: 'terminal' }
+    return { type: 'missing' }
+  }
+  // Reachable only for rows completed before the completions split.
   if (existing.status !== 'pending') return { status: existing.status, type: 'terminal' }
   if (existing.attemptingAt !== null && existing.attemptingAt > options.staleBefore)
     return { type: 'attempting' }
@@ -136,12 +166,12 @@ export declare namespace claim {
     | { record: Record; type: 'claimed' }
     | { type: 'missing' }
     | { nextAttemptAt: string | null; type: 'scheduled' }
-    | { status: TerminalStatus; type: 'terminal' }
+    | { status: WebhookQueueCompletions.TerminalStatus; type: 'terminal' }
 }
 
 /**
- * Marks a claimed obligation terminal, starting its dedupe retention window;
- * pending rows never expire, so this stamp is the only expiry that matters.
+ * Marks a claimed obligation terminal: one atomic statement deletes the queue
+ * row and writes the insert-only completion that starts the dedupe window.
  * The `attemptingAt` predicate fences stale claimants.
  */
 export async function complete(
@@ -150,14 +180,38 @@ export async function complete(
   options: complete.Options,
 ): Promise<boolean> {
   const result = await db.kysely
-    .updateTable('webhook_queue_events')
-    .set({ attemptingAt: null, expiresAt: options.expiresAt, status: options.status })
-    .where('subscriptionId', '=', reference.subscriptionId)
-    .where('eventId', '=', reference.eventId)
-    .where('status', '=', 'pending')
-    .where('attemptingAt', '=', options.claimedAt)
+    .with('done', (qb) =>
+      qb
+        .deleteFrom('webhook_queue_events')
+        .where('subscriptionId', '=', reference.subscriptionId)
+        .where('eventId', '=', reference.eventId)
+        .where('status', '=', 'pending')
+        .where('attemptingAt', '=', options.claimedAt)
+        .returning(['subscriptionId', 'eventId']),
+    )
+    .insertInto('webhook_queue_completions')
+    .columns(['subscriptionId', 'eventId', 'status', 'expiresAt'])
+    .expression((eb) =>
+      eb
+        .selectFrom('done')
+        .select((s) => [
+          'subscriptionId',
+          'eventId',
+          s.val(options.status).as('status'),
+          s.val(options.expiresAt).as('expiresAt'),
+        ]),
+    )
+    // Re-completing a replayed obligation: the latest delivery outcome wins
+    // and retention restarts, matching pre-split replay semantics; doNothing
+    // would also report zero rows and fail a fence that won.
+    .onConflict((oc) =>
+      oc.columns(['subscriptionId', 'eventId']).doUpdateSet((eb) => ({
+        expiresAt: eb.ref('excluded.expiresAt'),
+        status: eb.ref('excluded.status'),
+      })),
+    )
     .executeTakeFirst()
-  return result.numUpdatedRows === 1n
+  return result.numInsertedOrUpdatedRows === 1n
 }
 
 export declare namespace complete {
@@ -165,10 +219,10 @@ export declare namespace complete {
   type Options = {
     /** Claim marker returned by {@link claim}; fences stale claimants. */
     claimedAt: string
-    /** Replacement ISO retention deadline for the terminal dedupe row. */
+    /** ISO retention deadline for the dedupe completion. */
     expiresAt: string
     /** Terminal outcome. */
-    status: TerminalStatus
+    status: WebhookQueueCompletions.TerminalStatus
   }
 }
 
@@ -269,17 +323,3 @@ export declare namespace pending {
     oldestDueAt: string | null
   }
 }
-
-/**
- * Deletes terminal dedupe rows past their retention deadline. Pending rows
- * never expire: owed work drains only through terminal transitions
- * (delivery, permanent failure, or the skip after auto-disable).
- */
-export async function pruneExpired(db: Db.Db, now: string): Promise<number> {
-  const result = await db.kysely
-    .deleteFrom('webhook_queue_events')
-    .where('expiresAt', '<=', now)
-    .where('status', '!=', 'pending')
-    .executeTakeFirst()
-  return Number(result.numDeletedRows)
-}