tapimo 0.10.0 → 0.10.1

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

@@ -664,7 +664,7 @@ export namespace schema {
         .datetime()
         .check(
           z.describe('Block timestamp as an ISO 8601 string.'),
-          z.meta({ examples: ['2026-01-14T18:38:03.000Z'] }),
+          z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
         ),
       token: z.optional(
         z
@@ -790,7 +790,7 @@ export namespace schema {
         .datetime()
         .check(
           z.describe('When the block was produced, as an ISO 8601 timestamp.'),
-          z.meta({ examples: ['2026-01-14T18:38:03.000Z'] }),
+          z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
         ),
       topics: z.array(Schema.Hash).check(
         z.describe('Log topics, starting with the event signature hash (topic 0).'),
@@ -881,7 +881,7 @@ export namespace schema {
         .datetime()
         .check(
           z.describe('When the block was produced, as an ISO 8601 timestamp.'),
-          z.meta({ examples: ['2026-01-14T18:38:03.000Z'] }),
+          z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
         ),
     })
     .check(z.describe('Payload for a `block:created` event (a new block header).'))
@@ -2303,7 +2303,7 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
               const dispatchables: poll.Dispatchable[] = []
               for (const item of page.items) dispatchables.push(await buildDispatchable(item))
               options.signal?.throwIfAborted()
-              const delivered = await dispatchBatch(dispatchables)
+              const delivered = await dispatchBatch(dispatchables, { db })
               if (delivered.ok) {
                 accepted = page.items.at(-1)?.cursor
                 result.dispatched += dispatchables.length
@@ -2406,7 +2406,9 @@ export declare namespace poll {
      */
     dispatch?: ((input: Dispatchable) => Promise<Webhooks.Result>) | undefined
     /** Batch delivery transport. A successful result confirms every row in the input. */
-    dispatchBatch?: ((input: readonly Dispatchable[]) => Promise<Webhooks.Result>) | undefined
+    dispatchBatch?:
+      | ((input: readonly Dispatchable[], context: DispatchContext) => Promise<Webhooks.Result>)
+      | undefined
     /** Event types to poll (default all). */
     eventTypes?: readonly EventType[] | undefined
     /** Current chain head; the poller emits up to `head - confirmations`. */
@@ -2426,6 +2428,12 @@ export declare namespace poll {
     /** Stops scanning and dispatch when the caller loses its execution lease. */
     signal?: AbortSignal | undefined
   }
+
+  /** Runtime context shared with a batch delivery transport. */
+  type DispatchContext = {
+    /** Database instance already resolved for this poll. */
+    db: Db.Db
+  }
   /** Summary counters for one poll tick. */
   type Result = {
     /** Chain that was polled. */
@@ -3124,7 +3132,12 @@ async function scanLogs(options: {
     if (blockNumber === undefined || logIndex === undefined) continue
     if (atOrBefore(blockNumber, logIndex, window.skip)) continue
     if (!matchesLog(log, f, event)) continue
-    const data = toLogEvent(log, blockIso(await cache.header(blockNumber)), f.signature, event)
+    const data = toLogEvent(
+      log,
+      Value.blockToIso(await cache.header(blockNumber)),
+      f.signature,
+      event,
+    )
     if (data) {
       items.push({ cursor: [data.blockNumber, data.logIndex], data })
       if (items.length >= batchSize) return { hasMore: true, items }
@@ -3178,12 +3191,6 @@ function matchesLog(
 
 // block:created (getBlock)
 
-/** Converts a viem block's `timestamp` (seconds) to an ISO 8601 string. */
-function blockIso(block: RpcBlock | undefined): string | undefined {
-  if (!block || typeof block.timestamp !== 'bigint') return undefined
-  return new Date(Number(block.timestamp) * 1000).toISOString()
-}
-
 type BlockEventData = {
   number: number
   hash: string
@@ -3203,7 +3210,7 @@ function toBlockEvent(block: RpcBlock): BlockEventData | undefined {
   const miner = Schema.Address.safeParse(block.miner)
   const gasUsed = typeof block.gasUsed === 'bigint' ? Number(block.gasUsed) : undefined
   const gasLimit = typeof block.gasLimit === 'bigint' ? Number(block.gasLimit) : undefined
-  const timestamp = blockIso(block)
+  const timestamp = Value.blockToIso(block)
   const transactionCount = Array.isArray(block.transactions) ? block.transactions.length : 0
   if (
     number === undefined ||
@@ -3318,6 +3325,9 @@ async function scanTxs(options: {
       ? (block['transactions'] as unknown[])
       : []
     const timestamp = asString(block['timestamp'])
+    // A transaction's own `blockTimestamp` is seconds-only, so the delivered
+    // timestamp comes from the enclosing block, which carries milliseconds.
+    const blockTime = Value.blockToIso(block)
     for (let offset = 0; offset < transactions.length; offset++) {
       const transaction = transactions[offset] as Record<string, unknown>
       const transactionIndex = Value.hexToNumber(transaction['transactionIndex']) ?? offset
@@ -3325,7 +3335,8 @@ async function scanTxs(options: {
       if (!matchesTx(transaction, f, includeCalls, timestamp, blockNumber)) continue
       const parsed = Transactions.schema.Rpc.Transaction.safeParse(transaction)
       if (!parsed.success) continue
-      const data = Transactions.humanizeTransaction(parsed.data)
+      const humanized = Transactions.humanizeTransaction(parsed.data)
+      const data = blockTime === undefined ? humanized : { ...humanized, timestamp: blockTime }
       items.push({ cursor: [blockNumber, transactionIndex], data })
       if (items.length >= batchSize) return { hasMore: true, items }
     }
@@ -3482,6 +3493,202 @@ function unauthorized(c: Context<App.Environment>) {
   })
 }
 
+// Pure per-block scanning (no RPC, no cursors, no pagination).
+
+// Pure over its inputs: the caller fetches the raw block (with transactions)
+// and its logs; enrichment happens downstream. Rows require a parsable block number.
+/**
+ * Matches one fetched block against a subscription set, producing the rows
+ * each event type delivers. Invalid stored filters fail closed into `invalid`.
+ */
+export function scanBlock<const subscription extends scanBlock.Subscription>(
+  options: scanBlock.Options<subscription>,
+): scanBlock.Result<subscription> {
+  const { block, logs, subscriptions } = options
+  const blockNumber = Value.hexToNumber(block['number'])
+  const timestamp = Value.blockToIso(block)
+  const header = toScanHeader(block)
+  const viemLogs = logs.map(fromRpcLog)
+  const matches: scanBlock.Match<subscription>[] = []
+  const invalid: scanBlock.Invalid<subscription>[] = []
+
+  for (const subscription of subscriptions) {
+    const filters = (() => {
+      try {
+        return parseFilters(subscription.eventType, subscription.filters)
+      } catch (error) {
+        invalid.push({ error, subscription })
+        return undefined
+      }
+    })()
+    if (filters === undefined) continue
+    const matched = matches.length
+    const push = (data: unknown, logIndex: number) => {
+      if (blockNumber !== undefined) matches.push({ blockNumber, data, logIndex, subscription })
+    }
+
+    // A throwing matcher invalidates only this subscription, rolling back any
+    // rows it matched before the failure.
+    try {
+      switch (subscription.eventType) {
+        case 'block:created': {
+          const f = filters as z.output<typeof schema.BlockFilters>
+          if (!matchesBlock(header, f)) break
+          const data = toBlockEvent(header)
+          if (data) push(data, 0)
+          break
+        }
+        case 'log:emitted': {
+          const f = filters as z.output<typeof schema.LogFilters>
+          const event = parseEvent(f.signature)
+          if (f.signature && (!event || !/^[A-Za-z_]\w*$/.test(event.name))) {
+            invalid.push({
+              error: new Webhooks.InvalidFilterError('log:emitted', [
+                { message: 'Unsupported event signature.', path: ['signature'] },
+              ]),
+              subscription,
+            })
+            break
+          }
+          // Validate arg names up front so a bad filter fails closed even
+          // when the block has no decodable logs.
+          const unknown =
+            event && f.args
+              ? Object.keys(f.args).find(
+                  (name) => !event.inputs.some((input) => input.name === name),
+                )
+              : undefined
+          if (unknown !== undefined) {
+            invalid.push({
+              error: new Webhooks.InvalidFilterError('log:emitted', [
+                { message: `Unknown event argument: ${unknown}.`, path: ['args', unknown] },
+              ]),
+              subscription,
+            })
+            break
+          }
+          for (const log of viemLogs) {
+            const decoded = event ? decodeScanLog(log, event) : log
+            const logIndex = decoded.logIndex ?? undefined
+            if (logIndex === undefined) continue
+            if (!matchesLog(decoded, f, event)) continue
+            const data = toLogEvent(decoded, timestamp, f.signature, event)
+            if (data) push(data, logIndex)
+          }
+          break
+        }
+        case 'token:transfer': {
+          if (timestamp === undefined) break
+          const f = filters as WebhookTransfer.Filters
+          for (const log of logs) {
+            const data = WebhookTransfer.decode(log, timestamp)
+            if (!data || !WebhookTransfer.matches(data, f)) continue
+            push(data, data.logIndex)
+          }
+          break
+        }
+        case 'transaction:included': {
+          const f = filters as z.output<typeof schema.TxFilters>
+          const includeCalls = f.includeCalls ?? true
+          const transactions = Array.isArray(block['transactions'])
+            ? (block['transactions'] as unknown[])
+            : []
+          const rawTimestamp = asString(block['timestamp'])
+          for (let offset = 0; offset < transactions.length; offset++) {
+            const transaction = transactions[offset]
+            if (!transaction || typeof transaction !== 'object') continue
+            const tx = transaction as Record<string, unknown>
+            const transactionIndex = Value.hexToNumber(tx['transactionIndex']) ?? offset
+            if (!matchesTx(tx, f, includeCalls, rawTimestamp, blockNumber ?? 0)) continue
+            const parsed = Transactions.schema.Rpc.Transaction.safeParse(tx)
+            if (!parsed.success) continue
+            const humanized = Transactions.humanizeTransaction(parsed.data)
+            // A transaction's own timestamp is seconds-only; the enclosing
+            // block carries milliseconds.
+            push(
+              timestamp === undefined ? humanized : { ...humanized, timestamp },
+              transactionIndex,
+            )
+          }
+          break
+        }
+      }
+    } catch (error) {
+      matches.length = matched
+      invalid.push({ error, subscription })
+    }
+  }
+  return { invalid, matches }
+}
+
+/** Normalizes a raw RPC header to the viem-shaped fields the block matchers read. */
+function toScanHeader(block: Record<string, unknown>): RpcBlock {
+  const quantity = (value: unknown) => {
+    try {
+      return typeof value === 'string' || typeof value === 'number' || typeof value === 'bigint'
+        ? BigInt(value)
+        : undefined
+    } catch {
+      return undefined
+    }
+  }
+  return {
+    ...block,
+    gasLimit: quantity(block['gasLimit']),
+    gasUsed: quantity(block['gasUsed']),
+    number: quantity(block['number']),
+    timestamp: quantity(block['timestamp']),
+  } as RpcBlock
+}
+
+export declare namespace scanBlock {
+  /** The subscription fields matching consumes; extra fields flow through. */
+  type Subscription = {
+    /** Event type selecting the matcher and payload shape. */
+    eventType: EventType
+    /** Stored filter predicates, validated fail-closed per event type. */
+    filters: Record<string, unknown>
+  }
+
+  /** One fetched block plus the subscriptions to match it against. */
+  type Options<subscription extends Subscription> = {
+    /** Raw `eth_getBlockByNumber(_, true)` result: header plus raw transactions. */
+    block: Record<string, unknown>
+    /** Raw `eth_getLogs` entries for exactly this block, in log order. */
+    logs: readonly RpcLog[]
+    /** Active subscriptions for the chain; any mix of event types. */
+    subscriptions: readonly subscription[]
+  }
+
+  /** One deliverable row for one subscription. */
+  type Match<subscription extends Subscription> = {
+    /** Block the row was produced from. */
+    blockNumber: number
+    /** Payload the matching read endpoint returns (pre-enrichment). */
+    data: unknown
+    /** Row position within the block (log or transaction index; 0 for blocks). */
+    logIndex: number
+    /** The matched subscription, passed through verbatim. */
+    subscription: subscription
+  }
+
+  /** A subscription whose stored filters failed validation. */
+  type Invalid<subscription extends Subscription> = {
+    /** The validation failure. */
+    error: unknown
+    /** The subscription with invalid filters. */
+    subscription: subscription
+  }
+
+  /** Matches plus fail-closed filter rejections. */
+  type Result<subscription extends Subscription> = {
+    /** Subscriptions skipped because their stored filters failed validation. */
+    invalid: readonly Invalid<subscription>[]
+    /** Deliverable rows in subscription order, block order within each type. */
+    matches: readonly Match<subscription>[]
+  }
+}
+
 class BlockUnavailableError extends Error {
   override name = 'Webhooks.BlockUnavailableError'
 

package/src/apps/data/routes/zones.bench.ts

@@ -0,0 +1,32 @@
+import * as Tidx from '../../../internal/Tidx.js'
+import * as Viem from '../../../internal/Viem.js'
+import * as TestApp from '../../../../test/App.js'
+import * as QueryBench from '../../../../test/QueryBench.js'
+
+const senderTag = `0x${'00'.repeat(32)}`
+const zoneChainIds = {
+  4217: 421_700_002,
+  42431: 424_310_002,
+} as const
+
+QueryBench.bench({
+  chainId: false,
+  name: 'listZoneWithdrawals',
+  path: {
+    4217: `/v1/zones/withdrawals/${senderTag}?chainId=${zoneChainIds[4217]}`,
+    42431: `/v1/zones/withdrawals/${senderTag}?chainId=${zoneChainIds[42431]}`,
+  },
+  zones: ({ chainId }) => {
+    const rpcUrl = Viem.resolveUrl(process.env.RPC_URL, chainId) ?? Viem.url[chainId]
+    const tidxUrl = Viem.resolveUrl(process.env.TIDX_URL, chainId) ?? Tidx.url[chainId]
+    if (!rpcUrl || !tidxUrl) throw new Error(`Missing Zone upstream for chain ${chainId}.`)
+    return [
+      TestApp.zone({
+        chainId: zoneChainIds[chainId],
+        rpcUrl,
+        sourceChainId: chainId,
+        tidxUrl,
+      }),
+    ]
+  },
+})

package/src/apps/data/routes/zones.test.ts

@@ -419,7 +419,7 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
         },
         {
           "examples": [
-            421700001,
+            1424310001,
           ],
           "name": "chainId",
           "required": true,

package/src/apps/data/routes/zones.ts

@@ -43,7 +43,7 @@ export namespace schema {
       .strictObject({
         chainId: Schema.ChainId.check(
           z.describe('The chain id of the Zone where the withdrawal originated.'),
-          z.meta({ examples: [421_700_001] }),
+          z.meta({ examples: [1_424_310_001] }),
         ),
       })
       .check(z.describe('Query parameters used to select the originating Zone.'))

package/src/apps/funding/routes/chains.test.ts

@@ -22,7 +22,7 @@ const providers = [
     integratorId: '0xdead',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
-  Relay.relay({ userAddress: '0x1111111111111111111111111111111111111111' }),
+  Relay.relay({ userAddresses: TestFunding.relayQuoteUsers }),
   Rhino.rhino(),
   Squid.squid({
     integratorId: 'squid-integrator-id',

package/src/apps/funding/routes/deposit-addresses.test.ts

@@ -45,7 +45,7 @@ const providers = [
     integratorId: '0xdead',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
-  Relay.relay({ userAddress: '0x1111111111111111111111111111111111111111' }),
+  Relay.relay({ userAddresses: TestFunding.relayQuoteUsers }),
   Rhino.rhino(),
   Squid.squid({
     integratorId: 'squid-integrator-id',

package/src/apps/funding/routes/deposit-addresses.ts

@@ -712,7 +712,7 @@ export function depositAddresses(options: depositAddresses.Options = {}) {
     .post(
       '/v1/funding/deposit-addresses/:id{fda_[A-Za-z0-9_-]+}/reconcile',
       Auth.policy({
-        apiKey: { rateLimit: { perMinute: 10 }, scopes: ['funding:write'] },
+        apiKey: { rateLimit: { limit: 10, period: 'minute' }, scopes: ['funding:write'] },
       }),
       OpenApi.validate('param', schema.reconcileFundingDepositAddress.Params, {
         code: 'param_invalid',

package/src/apps/funding/routes/providers.test.ts

@@ -28,7 +28,7 @@ const providers = [
     integratorId: '0xdead',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
-  Relay.relay({ userAddress: '0x1111111111111111111111111111111111111111' }),
+  Relay.relay({ userAddresses: TestFunding.relayQuoteUsers }),
   Rhino.rhino(),
   Squid.squid({
     integratorId: 'squid-integrator-id',

package/src/apps/funding/routes/quotes.test.ts

@@ -28,7 +28,7 @@ const providers = [
     integratorId: '0xdead',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
-  Relay.relay({ userAddress: '0x1111111111111111111111111111111111111111' }),
+  Relay.relay({ userAddresses: TestFunding.relayQuoteUsers }),
   Rhino.rhino(),
   Squid.squid({
     integratorId: 'squid-integrator-id',

package/src/apps/funding/routes/transfers.test.ts

@@ -27,11 +27,8 @@ const db = TestApp.database()
 /** Providers exercised against executable calls on a forked source chain. */
 const executableProviders = [
   {
-    create: (sender: string) =>
-      Relay.relay({
-        ...(process.env.RELAY_API_KEY ? { apiKey: process.env.RELAY_API_KEY } : {}),
-        userAddress: sender,
-      }),
+    create: (_sender: string) =>
+      Relay.relay(process.env.RELAY_API_KEY ? { apiKey: process.env.RELAY_API_KEY } : {}),
     id: 'relay',
   },
 ] as const
@@ -282,7 +279,7 @@ describe('POST /funding/transfers', () => {
       providerResponse(),
   ) {
     return FundingProvider.from({
-      ...Relay.relay({ userAddress: '0x1111111111111111111111111111111111111111' }),
+      ...Relay.relay(),
       prepareTransfer,
     })
   }

package/src/apps/funding/routes/transfers.ts

@@ -110,7 +110,7 @@ export namespace schema {
           .check(
             z.regex(/^eip155:\d+$/),
             z.describe('Configured Zone CAIP-2 id.'),
-            z.meta({ examples: ['eip155:421700001'] }),
+            z.meta({ examples: ['eip155:1424310001'] }),
           ),
         destinationToken: FundingTransfer.schema.CreateRequest.shape.destinationToken,
         mode: destinationCreateFields.mode,

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

@@ -699,7 +699,7 @@ export function billing() {
       Auth.policy({
         apiKey: false,
         mpp: false,
-        public: { rateLimit: { perMinute: 600 } },
+        public: { rateLimit: { limit: 600, period: 'minute' } },
         session: false,
       }),
       OpenApi.describeRoute({ hide: true, summary: 'Stripe webhook' }),

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

@@ -10,8 +10,8 @@ import * as Value from '../../../internal/Value.js'
 import * as Viem from '../../../internal/Viem.js'
 import type { Environment } from '../App.js'
 
-const addressRateLimit = { perMinute: 1 } satisfies RateLimit.Limit
-const userRateLimit = { perMinute: 3 } satisfies RateLimit.Limit
+const addressRateLimit = { limit: 1, period: 'minute' } satisfies RateLimit.Limit
+const userRateLimit = { limit: 3, period: 'minute' } satisfies RateLimit.Limit
 
 /** OpenAPI schemas owned by the sandbox faucet. */
 export namespace schema {

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

@@ -1,7 +1,10 @@
 import { serve } from '@hono/node-server'
 import * as Accounts from 'accounts/server'
 import { exportJWK, generateKeyPair } from 'jose'
+import { P256 } from 'ox'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import { Account } from 'viem/tempo'
+import { tempoTestnet } from 'viem/tempo/chains'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Me from './me.js'
@@ -18,6 +21,34 @@ function createApp() {
   })
 }
 
+describe('SIWE verification', () => {
+  test('surfaces configured RPC failures as dependency errors', async () => {
+    const account = Account.fromHeadlessWebAuthn(P256.randomPrivateKey(), {
+      origin,
+      rpId: 'localhost',
+    })
+    let chainId_seen: number | undefined
+    const app = TestApp.create({
+      rpc: ({ chainId }) => {
+        chainId_seen = chainId
+        return { url: 'http://127.0.0.1:1' }
+      },
+    })
+
+    const { verifyResponse } = await TestApp.signIn(app, account, {
+      chainId: tempoTestnet.id,
+    })
+
+    expect(verifyResponse.status).toBe(502)
+    expect(chainId_seen).toMatchInlineSnapshot(`42431`)
+    expect(await verifyResponse.json()).toMatchInlineSnapshot(`
+      {
+        "error": "signature verification unavailable",
+      }
+    `)
+  })
+})
+
 describe('GET /me', () => {
   test('returns the signed-in user', async () => {
     const app = createApp()

package/src/apps/mcp.ts

@@ -138,7 +138,10 @@ export function mcp(options: mcp.Options) {
   const app = new Hono<App.Environment>()
     .post(
       '/mcp',
-      Auth.policy({ apiKey: { scopes: [] }, public: { rateLimit: { perMinute: 100 } } }),
+      Auth.policy({
+        apiKey: { scopes: [] },
+        public: { rateLimit: { limit: 100, period: 'minute' } },
+      }),
       OpenApi.describeRoute({
         description:
           "A stateless streamable-HTTP MCP server: send JSON-RPC 2.0 messages as `POST` with `Accept: application/json, text/event-stream`. Tools mirror the API's data domain, plus `docs_*` documentation search. Anonymous requests allow 100 requests per minute; send `Authorization: Bearer <api key>` for protected tools.",

package/src/db/Db.ts

@@ -36,6 +36,7 @@ import type * as Users from './tables/users.js'
 import type * as VerifiedTokenRequests from './tables/verifiedTokenRequests.js'
 import type * as VerifiedTokens from './tables/verifiedTokens.js'
 import type * as WebhookDeliveries from './tables/webhookDeliveries.js'
+import type * as WebhookQueueEvents from './tables/webhookQueueEvents.js'
 import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
 
 /**
@@ -82,6 +83,7 @@ export type Database = {
   verified_token_requests: VerifiedTokenRequests.Table
   verified_tokens: VerifiedTokens.Table
   webhook_deliveries: WebhookDeliveries.Table
+  webhook_queue_events: WebhookQueueEvents.Table
   webhook_subscriptions: WebhookSubscriptions.Table
 }
 
@@ -1281,6 +1283,85 @@ export const migrations: readonly Migration[] = [
         .on('fundingDepositAddresses')
         .columns(['orgId', 'environment', 'address', 'projectId']),
   },
+  {
+    name: '0115_webhook_queue_events',
+    up: (db) =>
+      db.schema
+        .createTable('webhookQueueEvents')
+        .ifNotExists()
+        .addColumn('subscriptionId', 'text', (c) =>
+          c.notNull().references('webhookSubscriptions.id').onDelete('cascade'),
+        )
+        .addColumn('eventId', 'text', (c) => c.notNull())
+        .addColumn('envelope', 'jsonb', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('expiresAt', 'text', (c) => c.notNull())
+        .addPrimaryKeyConstraint('webhook_queue_events_pkey', ['subscriptionId', 'eventId']),
+  },
+  {
+    name: '0116_webhook_queue_events_expires_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_queue_events_expires_idx')
+        .ifNotExists()
+        .on('webhookQueueEvents')
+        .column('expiresAt'),
+  },
+  {
+    name: '0117_webhook_queue_events_ledger_columns',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE webhook_queue_events
+          ADD COLUMN IF NOT EXISTS status text NOT NULL DEFAULT 'pending',
+          ADD COLUMN IF NOT EXISTS attempt_count integer NOT NULL DEFAULT 0,
+          ADD COLUMN IF NOT EXISTS attempting_at text,
+          ADD COLUMN IF NOT EXISTS next_attempt_at text`,
+      ),
+  },
+  {
+    name: '0118_webhook_queue_events_status_check',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE webhook_queue_events DROP CONSTRAINT IF EXISTS webhook_queue_events_status_check, ADD CONSTRAINT webhook_queue_events_status_check CHECK (status IN ('failed', 'pending', 'skipped', 'succeeded'))`,
+      ),
+  },
+  {
+    name: '0119_webhook_queue_events_pending_index',
+    up: (db) =>
+      // NULLS FIRST matches the due-sweep order (null = due immediately);
+      // INCLUDE lets the pending gauge take min(created_at) index-only.
+      raw(
+        db,
+        sql`CREATE INDEX IF NOT EXISTS webhook_queue_events_pending_idx ON webhook_queue_events (next_attempt_at NULLS FIRST) INCLUDE (created_at) WHERE status = 'pending'`,
+      ),
+  },
+  {
+    name: '0120_webhook_queue_events_pending_index_drop',
+    up: (db) => raw(db, sql`DROP INDEX IF EXISTS webhook_queue_events_pending_idx`),
+  },
+  {
+    name: '0121_webhook_queue_events_pending_index_expiry',
+    up: (db) =>
+      // Recreated with expires_at so claimable and gauge queries, which all
+      // filter expiry at query time, stay index-only.
+      raw(
+        db,
+        sql`CREATE INDEX IF NOT EXISTS webhook_queue_events_pending_idx ON webhook_queue_events (next_attempt_at NULLS FIRST) INCLUDE (created_at, expires_at) WHERE status = 'pending'`,
+      ),
+  },
+  {
+    name: '0122_webhook_queue_events_expired_pending_cleanup',
+    up: (db) =>
+      // Pre-ledger rows already past their staging TTL were dead under the
+      // old read path; pending rows no longer expire, so drop them once
+      // instead of resurrecting them as eternal obligations.
+      raw(
+        db,
+        sql`DELETE FROM webhook_queue_events WHERE status = 'pending' AND attempting_at IS NULL AND expires_at <= to_char(now() AT TIME ZONE 'utc', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`,
+      ),
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -874,3 +874,35 @@ export const WebhookDelivery = z.object({
 
 /** Columns of the `webhook_deliveries` table. */
 export type WebhookDelivery = z.output<typeof WebhookDelivery>
+
+/** 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.')),
+  attemptingAt: z
+    .nullable(z.string())
+    .check(z.describe('ISO timestamp of the current claim, or null when unclaimed.')),
+  createdAt: z.string().check(z.describe('ISO timestamp when the envelope was staged.')),
+  envelope: z
+    .custom<Webhooks.Envelope>()
+    .check(z.describe('The full webhook envelope retained outside Cloudflare Queues.')),
+  eventId: z.string().check(z.describe('Idempotent event id (`evt_...`).')),
+  expiresAt: z
+    .string()
+    .check(
+      z.describe(
+        'ISO dedupe retention deadline, restarted at terminal transitions; inert while pending.',
+      ),
+    ),
+  nextAttemptAt: z
+    .nullable(z.string())
+    .check(z.describe('ISO retry due time, or null when due immediately.')),
+  status: z
+    .enum(['failed', 'pending', 'skipped', 'succeeded'])
+    .check(z.describe('Delivery-obligation lifecycle status.')),
+  subscriptionId: z
+    .string()
+    .check(z.describe('Owning subscription id (`wh_...`); FK with `ON DELETE CASCADE`.')),
+})
+
+/** Columns of the `webhook_queue_events` table. */
+export type WebhookQueueEvent = z.output<typeof WebhookQueueEvent>