tapimo 0.5.1 → 0.5.2

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

@@ -1,5 +1,5 @@
 import { type Context, Hono } from 'hono'
-import { type AbiEvent, parseAbiItem } from 'viem'
+import { type AbiEvent, decodeEventLog, encodeEventTopics, parseAbiItem, type RpcLog } from 'viem'
 import * as z from 'zod/mini'
 
 import type * as App from '../../../App.js'
@@ -15,6 +15,7 @@ import type * as Tidx from '../../../internal/Tidx.js'
 import * as Ttl from '../../../internal/Ttl.js'
 import * as Value from '../../../internal/Value.js'
 import type * as Viem from '../../../internal/Viem.js'
+import type * as WebhookDestination from '../../../internal/WebhookDestination.js'
 import * as Webhooks from '../../../internal/Webhooks.js'
 import * as Receipts from './receipts.js'
 import * as Transactions from './transactions.js'
@@ -30,6 +31,9 @@ const defaultMaxPerOwner = 100
  */
 const mppTtlMs = 30 * 24 * 60 * 60 * 1_000
 
+const redactedBetterstackToken = '[redacted]'
+const redactedSlackUrl = 'https://hooks.slack.com/…'
+
 /**
  * The subscribable webhook event types, in alphabetical order. The source of
  * truth for the event-type *set*: the {@link EventType} union and the route zod
@@ -97,12 +101,11 @@ export namespace schema {
       z.meta({ examples: ['https://example.com/webhooks'] }),
     )
 
-  const SlackUrl = z
-    .url()
-    .check(
-      z.describe('Your Slack incoming-webhook URL (`https://hooks.slack.com/services/…`).'),
-      z.meta({ examples: ['https://hooks.slack.com/services/T000/B000/XXXXXXXX'] }),
-    )
+  const SlackUrl = z.url().check(
+    z.refine((url) => url !== redactedSlackUrl, { error: 'A Slack webhook URL is required.' }),
+    z.describe('Your Slack incoming-webhook URL (`https://hooks.slack.com/services/…`).'),
+    z.meta({ examples: ['https://hooks.slack.com/services/T000/B000/XXXXXXXX'] }),
+  )
 
   const BetterstackUrl = z
     .url()
@@ -113,13 +116,14 @@ export namespace schema {
       z.meta({ examples: ['https://s1234567.eu-nbg-2.betterstackdata.com'] }),
     )
 
-  const BetterstackToken = z
-    .string()
-    .check(
-      z.minLength(1),
-      z.describe('Your Better Stack source token (sent as `Authorization: Bearer …`).'),
-      z.meta({ examples: ['FczKcxEhjEDE58dBX7XaeX1q'] }),
-    )
+  const BetterstackToken = z.string().check(
+    z.minLength(1),
+    z.refine((token) => token !== redactedBetterstackToken, {
+      error: 'A Better Stack source token is required.',
+    }),
+    z.describe('Your Better Stack source token (sent as `Authorization: Bearer …`).'),
+    z.meta({ examples: ['FczKcxEhjEDE58dBX7XaeX1q'] }),
+  )
 
   /**
    * Where matched events are delivered: a `url` destination (a signed event POST
@@ -149,6 +153,26 @@ export namespace schema {
       ),
     )
 
+  const PublicDestination = z
+    .discriminatedUnion('type', [
+      z.object({
+        type: z.literal('url'),
+        url: Url,
+      }),
+      z.object({
+        type: z.literal('slack'),
+        url: z.literal(redactedSlackUrl).check(z.describe('Redacted Slack webhook URL.')),
+      }),
+      z.object({
+        token: z
+          .literal(redactedBetterstackToken)
+          .check(z.describe('Redacted Better Stack source token.')),
+        type: z.literal('betterstack'),
+        url: BetterstackUrl,
+      }),
+    ])
+    .check(z.describe('Delivery destination with bearer credentials redacted.'))
+
   /**
    * Equality / membership operator for a filterable field. A consumer can pass a
    * bare value (shorthand for exact equality, the common case) or an operator
@@ -399,15 +423,10 @@ export namespace schema {
       z.refine((f) => !f.args || f.signature, {
         error: '`args` requires `signature` to decode the event.',
       }),
-      z.refine(
-        (f) =>
-          Boolean(f.address) ||
-          (Boolean(f.signature || f.topic0) && Boolean(f.topic1 || f.topic2 || f.topic3 || f.args)),
-        {
-          error:
-            'Addressless log filters must include an event signature or topic0 plus at least one indexed topic or argument.',
-        },
-      ),
+      z.refine((f) => hasLogPushdown(f), {
+        error:
+          'Log filters must include a pushdown-capable address or an event/topic0 anchor plus an indexed topic or argument.',
+      }),
     )
 
   /**
@@ -507,7 +526,7 @@ export namespace schema {
           z.describe('When the subscription was created, as an ISO 8601 timestamp.'),
           z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
         ),
-      destination: Destination,
+      destination: PublicDestination,
       eventType: EventType.check(z.meta({ examples: ['token:transfer'] })),
       expiresAt: z
         .optional(z.iso.datetime())
@@ -1032,7 +1051,9 @@ export namespace schema {
       .check(z.describe('Details for creating a webhook subscription.'))
 
     export const Response = z
-      .extend(Subscription, {
+      .object({
+        ...Subscription.shape,
+        destination: Destination,
         secret: z
           .string()
           .check(
@@ -2294,6 +2315,7 @@ export function matchesOperator(
     return value.toLowerCase().startsWith(String(o['startsWith']).toLowerCase())
   if ('in' in o) return (o['in'] as readonly unknown[]).some((v) => operandEquals(value, v, kind))
   if ('not' in o) return !operandEquals(value, o['not'], kind)
+  if ('eq' in o && kind === 'string') return operandEquals(value, o['eq'], kind)
   // Comparison object: AND-combine whichever of eq/gt/gte/lt/lte are present.
   const n = toBig(value)
   let ok = true
@@ -2510,31 +2532,124 @@ function toLogEvent(
   }
 }
 
+/** Narrows an exact or membership operator into an RPC filter value. */
+function pushValue(op: unknown): unknown {
+  const value = (() => {
+    if (typeof op !== 'object' || op === null) return op
+    const operator = op as Record<string, unknown>
+    if ('eq' in operator) return operator['eq']
+    if (Array.isArray(operator['in']) && operator['in'].length > 0) return operator['in']
+    return undefined
+  })()
+  const scalar = (item: unknown) => ['bigint', 'boolean', 'number', 'string'].includes(typeof item)
+  if (scalar(value)) return value
+  if (Array.isArray(value) && value.length > 0 && value.every(scalar)) return value
+  return undefined
+}
+
+/** Narrows an `eq`/`in` operator into a hex RPC filter value. */
+function pushHex(op: unknown): `0x${string}` | `0x${string}`[] | undefined {
+  const value = pushValue(op)
+  if (typeof value === 'string') return value as `0x${string}`
+  if (Array.isArray(value) && value.every((item) => typeof item === 'string'))
+    return value as `0x${string}`[]
+  return undefined
+}
+
 /** Narrows an `eq`/`in` address operator into the `getLogs` address pushdown. */
-function pushAddress(op: unknown): `0x${string}` | `0x${string}`[] | undefined {
-  if (op === undefined) return undefined
-  if (typeof op === 'string') return op as `0x${string}`
-  if (typeof op === 'object' && op !== null) {
-    const o = op as Record<string, unknown>
-    if (typeof o['eq'] === 'string') return o['eq'] as `0x${string}`
-    if (Array.isArray(o['in']))
-      return o['in'].filter((v): v is string => typeof v === 'string') as `0x${string}`[]
+function pushAddress(op: unknown) {
+  return pushHex(op)
+}
+
+/** Parses a human-readable event signature without letting refinements throw. */
+function parseEvent(signature: string | undefined): AbiEvent | undefined {
+  if (!signature) return undefined
+  try {
+    const item = parseAbiItem(signature)
+    return item.type === 'event' ? item : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Returns exact indexed arguments that viem can push into `eth_getLogs`. */
+function pushEventArgs(args: Record<string, unknown> | undefined, event: AbiEvent) {
+  const pushed: Record<string, unknown> = {}
+  for (const [name, op] of Object.entries(args ?? {})) {
+    const input = event.inputs.find((item) => item.indexed && item.name === name)
+    const value = pushValue(op)
+    if (input && value !== undefined) pushed[name] = value
+  }
+  return pushed
+}
+
+/** Checks that the accepted filter has a selective `eth_getLogs` representation. */
+function hasLogPushdown(f: z.output<typeof schema.LogFilters>): boolean {
+  if (pushAddress(f.address) !== undefined) return true
+
+  const secondaryTopic = [f.topic1, f.topic2, f.topic3].some(
+    (topic) => pushHex(topic) !== undefined,
+  )
+  const event = parseEvent(f.signature)
+  if (event && !event.anonymous)
+    return secondaryTopic || Object.keys(pushEventArgs(f.args, event)).length > 0
+  return pushHex(f.topic0) !== undefined && secondaryTopic
+}
+
+/** Builds raw topic filters, preserving null wildcards between constrained positions. */
+function pushTopics(f: z.output<typeof schema.LogFilters>, event: AbiEvent | undefined) {
+  const topics: (`0x${string}` | `0x${string}`[] | null | undefined)[] = [
+    event ? encodeEventTopics({ abi: [event] })[0] : pushHex(f.topic0),
+    pushHex(f.topic1),
+    pushHex(f.topic2),
+    pushHex(f.topic3),
+  ]
+  while (topics.at(-1) === undefined) topics.pop()
+  return topics.map((topic) => topic ?? null)
+}
+
+/** Converts one raw JSON-RPC log into the viem-shaped scanner input. */
+function fromRpcLog(log: RpcLog): ScanLog {
+  return {
+    address: log.address,
+    blockNumber: log.blockNumber === null ? null : BigInt(log.blockNumber),
+    data: log.data,
+    logIndex: Value.hexToNumber(log.logIndex) ?? null,
+    topics: log.topics,
+    transactionHash: log.transactionHash,
+    transactionIndex: Value.hexToNumber(log.transactionIndex) ?? null,
+  }
+}
+
+/** Best-effort decodes a raw log using the subscription event. */
+function decodeScanLog(log: ScanLog, event: AbiEvent): ScanLog {
+  try {
+    const decoded = decodeEventLog({
+      abi: [event],
+      data: log.data as `0x${string}`,
+      strict: false,
+      topics: log.topics as [`0x${string}`, ...`0x${string}`[]],
+    })
+    return {
+      ...log,
+      args: decoded.args,
+      eventName: decoded.eventName,
+    }
+  } catch {
+    return log
   }
-  // `not`/range forms can't be pushed; widen here, re-check in JS.
-  return undefined
 }
 
 /**
- * Scans contract event logs over the confirmed window via viem's `getLogs`,
- * then re-checks **every** filter in JS (so operators the RPC can't express —
- * `not`, ranges, decoded `args` — still apply). Two modes:
+ * Scans contract event logs over the confirmed window via `eth_getLogs`,
+ * then re-checks **every** filter in JS. Operators the RPC cannot express
+ * (`not`, ranges, non-indexed `args`) still apply. Two modes:
  * - **raw** (no `signature`): `topic0..3` are matched directly.
- * - **decoded** (`signature` present): `getLogs` is given the `event`, so it
- *   pushes the event selector down, filters to matching logs, and best-effort
- *   decodes `args` — which the JS pass then matches by name.
+ * - **decoded** (`signature` present): the selector, raw topics, and supported
+ *   indexed `args` are pushed down before the JS pass matches decoded values.
  *
- * `address` (`eq`/`in`) is pushed down to the node; all other operators are
- * re-checked in JS over the narrow window.
+ * Exact and membership address/topic operators are pushed down to the node;
+ * all operators are re-checked in JS over the narrow window.
  */
 async function scanLogs(options: {
   cache: ChainCache
@@ -2549,8 +2664,8 @@ async function scanLogs(options: {
   const window = scanWindow(cursor, safeBlock, maxBlocks)
   if (!window) return { items: [], scannedThrough: undefined }
 
-  const event = f.signature ? (parseAbiItem(f.signature) as AbiEvent) : undefined
-  if (event && !/^[A-Za-z_]\w*$/.test(event.name))
+  const event = parseEvent(f.signature)
+  if (f.signature && (!event || !/^[A-Za-z_]\w*$/.test(event.name)))
     throw new Webhooks.InvalidFilterError('log:emitted', [
       { message: 'Unsupported event signature.', path: ['signature'] },
     ])
@@ -2558,18 +2673,29 @@ async function scanLogs(options: {
   const address = pushAddress(f.address)
   const fromBlock = BigInt(window.from)
   const toBlock = BigInt(window.to)
-  const logs = (event
-    ? await client.getLogs({
+  const topics = pushTopics(f, event)
+  const hasRawTopics = topics.slice(1).some((topic) => topic !== null)
+  const args = event ? pushEventArgs(f.args, event) : {}
+  const logs = (!event || hasRawTopics
+    ? (
+        await rpc<RpcLog[]>(client, 'eth_getLogs', [
+          {
+            ...(address ? { address } : {}),
+            fromBlock: blockTag(window.from),
+            ...(topics.length > 0 ? { topics } : {}),
+            toBlock: blockTag(window.to),
+          },
+        ])
+      )
+        .map(fromRpcLog)
+        .map((log) => (event ? decodeScanLog(log, event) : log))
+    : await client.getLogs({
         ...(address ? { address } : {}),
+        ...(Object.keys(args).length > 0 ? { args: args as never } : {}),
         event,
         fromBlock,
         strict: false,
         toBlock,
-      })
-    : await client.getLogs({
-        ...(address ? { address } : {}),
-        fromBlock,
-        toBlock,
       })) as unknown as ScanLog[]
 
   logs.sort((a, b) => {
@@ -2884,7 +3010,7 @@ function toPublic(subscription: Webhooks.Subscription) {
     chainId: subscription.chainId,
     ...(subscription.context === undefined ? {} : { context: subscription.context }),
     createdAt: subscription.createdAt,
-    destination: subscription.destination,
+    destination: redactDestination(subscription.destination),
     eventType: subscription.eventType,
     ...(subscription.expiresAt === undefined ? {} : { expiresAt: subscription.expiresAt }),
     failureCount: subscription.failureCount,
@@ -2900,7 +3026,18 @@ function toPublic(subscription: Webhooks.Subscription) {
 
 /** Public read shape plus the one-time signing secret (creation only). */
 function toCreated(subscription: Webhooks.Subscription) {
-  return { ...toPublic(subscription), secret: subscription.secret }
+  return {
+    ...toPublic(subscription),
+    destination: subscription.destination,
+    secret: subscription.secret,
+  }
+}
+
+/** Redacts bearer credentials from the destination returned by read endpoints. */
+function redactDestination(destination: WebhookDestination.Destination) {
+  if (destination.type === 'slack') return { ...destination, url: redactedSlackUrl }
+  if (destination.type === 'betterstack') return { ...destination, token: redactedBetterstackToken }
+  return destination
 }
 
 function mutationError(c: Context<App.Environment>, cause: unknown) {

package/src/apps/management/Billing.test.ts

@@ -62,6 +62,7 @@ type StubSubscription = { items?: readonly Billing.MeterKind[]; status: string }
 function stubStripe(options: {
   meterEvent?: ((params: { identifier: string }) => void) | undefined
   subscriptions?: readonly StubSubscription[] | undefined
+  subscriptionsList?: (() => Promise<void>) | undefined
 }) {
   const meterEvents: {
     event_name: string
@@ -127,7 +128,10 @@ function stubStripe(options: {
         subscriptionsCreated.push(params)
         return {}
       },
-      list: async () => ({ data: subscriptions }),
+      list: async () => {
+        await options.subscriptionsList?.()
+        return { data: subscriptions }
+      },
     },
   }
   return { itemsCreated, meterEvents, stripe: stripe as never as Stripe, subscriptionsCreated }
@@ -433,6 +437,51 @@ describe('createRequestUsageReporter', () => {
     await db.close()
   })
 
+  test('behavior: overlapping ticks cannot claim the same observed watermark twice', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    await StripeCustomers.setStatus(db, 'org_1', 'active')
+
+    const paused = Promise.withResolvers<void>()
+    const resume = Promise.withResolvers<void>()
+    const delayed = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+      subscriptionsList: async () => {
+        paused.resolve()
+        await resume.promise
+      },
+    })
+    const delayedTick = Billing.createRequestUsageReporter({
+      db,
+      now,
+      readCounts: async () => [{ bucketStart, count: 5, orgId: 'org_1' }],
+      stripe: delayed.stripe,
+    }).tick()
+
+    // Pause after this tick observes an empty watermark, then let an
+    // overlapping tick report and settle that same count first.
+    await paused.promise
+    const winner = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now,
+        readCounts: async () => [{ bucketStart, count: 5, orgId: 'org_1' }],
+        stripe: winner.stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+
+    resume.resolve()
+    expect(await delayedTick).toStrictEqual({ failed: 0, reported: 0, skipped: 0 })
+    expect(winner.meterEvents).toHaveLength(1)
+    expect(delayed.meterEvents).toHaveLength(0)
+    expect((await RequestUsage.getBucket(db, { bucketStart, environment: 'production', orgId: 'org_1' }))?.reportedCount).toBe(5) // prettier-ignore
+    await db.close()
+  })
+
   test('behavior: seals only hours older than the settlement delay', async () => {
     const db = create()
     await db.migrate()

package/src/apps/management/Billing.ts

@@ -510,7 +510,8 @@ export function createRequestUsageReporter(
               subscriptions.set(orgId, subscription)
             }
 
-            const sequence = await RequestUsage.countReported(database, key)
+            // The observed watermark is stable for every tick claiming this delta.
+            const sequence = watermark?.reportedCount ?? 0
             const identifier = usageIdentifier(environment, orgId, bucketStart, sequence)
             const inserted = await RequestUsage.insertPending(database, {
               ...key,
@@ -599,17 +600,17 @@ function startOfHour(ms: number) {
 
 /**
  * Deterministic meter-event identifier, bounded under Stripe's 100-char limit:
- * `rq_${env}_${sha(orgId)[:12]}_${bucketEpochHour}_${sequence}`.
+ * `rq_${env}_${sha(orgId)[:12]}_${bucketEpochHour}_${observedWatermark}`.
  */
 function usageIdentifier(
   environment: StripeCustomers.Record['environment'],
   orgId: string,
   bucketStart: string,
-  sequence: number,
+  observedWatermark: number,
 ) {
   const hash = Hash.keccak256(Hex.fromString(orgId)).slice(2, 14)
   const epochHour = Math.floor(new Date(bucketStart).getTime() / hourMs)
-  return `rq_${environment}_${hash}_${epochHour}_${sequence}`
+  return `rq_${environment}_${hash}_${epochHour}_${observedWatermark}`
 }
 
 /**

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

@@ -750,7 +750,12 @@ export function billing() {
           // the gate never opens (`Billing.status` reads the stored status)
           // without a subscription to invoice the spend against. A failure
           // here surfaces as 5xx and Stripe redelivers.
-          if (status === 'active') await core_Billing.ensureSubscription(client, customer)
+          if (status === 'active')
+            await core_Billing.ensureSubscription(
+              client,
+              customer,
+              core_Billing.kindsFor(record.environment),
+            )
           await StripeCustomers.setStatus(db, record.orgId, status, record.environment)
           await syncKeyBilling(c, { environment: record.environment, orgId: record.orgId, status })
           return c.json({ received: true }, 200)

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

@@ -298,7 +298,13 @@ export function orgs() {
         description: 'Delete an organization and all of its projects.',
         operationId: 'deleteOrganization',
         responses: OpenApi.responses({
-          errors: { 404: 'No accessible organization was found for this id.' },
+          errors: {
+            404: 'No accessible organization was found for this id.',
+            409: {
+              codes: ['sponsorships_unreported'],
+              description: 'Billable sponsorships are still awaiting settlement.',
+            },
+          },
           success: {
             description: 'Confirmation that the organization was deleted.',
             schema: schema.deleteOrganization.Response,
@@ -318,6 +324,8 @@ export function orgs() {
 
         const db = Db.get(c.get('db'))
         try {
+          if (await Organizations.hasUnreportedSponsorships(db, Auth.org(c).id))
+            return sponsorshipsUnreported(c)
           const kv = c.get('kv')
           if (kv)
             for (const record of await ApiKeys.listByOrg(kv.store, Auth.org(c).id, {
@@ -331,12 +339,22 @@ export function orgs() {
             200,
           )
         } catch (cause) {
+          if (cause instanceof Organizations.UnreportedSponsorshipsError)
+            return sponsorshipsUnreported(c)
           return Response.upstream(c, cause)
         }
       },
     )
 }
 
+function sponsorshipsUnreported(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'sponsorships_unreported',
+    message: 'Billable sponsorships are still awaiting settlement',
+    status: 409,
+  })
+}
+
 function serializeOrganization(
   record: Organizations.Record & { role?: Memberships.Role | undefined },
 ) {

package/src/apps/relay/Sponsorships.ts

@@ -10,10 +10,12 @@ import {
 import { getTransactionReceipt } from 'viem/actions'
 
 import * as Db from '../../db/Db.js'
+import * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Fees from '../../internal/Fees.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Tidx from '../../internal/Tidx.js'
 import * as Viem from '../../internal/Viem.js'
+import * as Billing from '../management/Billing.js'
 
 /**
  * Runs one finalization pass over pending sponsored transactions: rows with a
@@ -177,7 +179,12 @@ export async function reconcile(db: Db.Db, options: reconcile.Options): Promise<
         )
         const intent = bySignPayload.get(signPayload)
         if (!intent) continue
-        await SponsoredTransactions.assignTransactionHash(db, intent.id, hash)
+        await SponsoredTransactions.assignTransactionHash(
+          db,
+          intent.id,
+          hash,
+          await options.limitFor?.(intent),
+        )
         bySignPayload.delete(signPayload)
         result.matched++
       } catch {
@@ -204,6 +211,12 @@ export declare namespace reconcile {
     getClient: (chainId: number) => Client
     /** TIDX client resolver keyed by the intent's chain id. */
     getTidx: (chainId: number) => Tidx.Client
+    /** Resolves the current period spend limit before reopening a failed intent. */
+    limitFor?:
+      | ((
+          intent: SponsoredTransactions.Record,
+        ) => Promise<SponsoredTransactions.reserve.Limit | undefined>)
+      | undefined
     /** Lookback slack before the oldest intent's creation. @default 2 minutes */
     skewMs?: number | undefined
   }
@@ -270,6 +283,16 @@ export function createFinalizer(options: createFinalizer.Options): createFinaliz
               feePayer,
               getClient,
               getTidx: (chainId) => getTidx(chainId as Viem.ChainId),
+              limitFor: async (intent) => {
+                if (!intent.billable || !Viem.isMainnet(intent.chainId)) return undefined
+                const settings = await BillingSettings.get(db, intent.orgId)
+                if (settings?.spendLimit == null) return undefined
+                return {
+                  chainIds: [Viem.chainId.mainnet],
+                  max: Billing.toBaseUnits(settings.spendLimit),
+                  since: Billing.periodStart(settings.period),
+                }
+              },
             })
           : { matched: 0, scanned: 0 }
       const finalized = await finalize(db, {

package/src/db/Db.ts

@@ -641,6 +641,10 @@ export const migrations: readonly Migration[] = [
         .on('inviteLinkRedemptions')
         .columns(['inviteLinkId', 'createdAt']),
   },
+  {
+    name: '0058_request_usage_sequence_bigint',
+    up: (db) => raw(db, sql`ALTER TABLE request_usage_meter_events ALTER COLUMN sequence TYPE bigint`), // prettier-ignore
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -272,7 +272,7 @@ export const RequestUsageMeterEvent = z.object({
     .check(z.describe('When Stripe acknowledged the event (ISO 8601), or null.')),
   sequence: z
     .number()
-    .check(z.describe('Delta sequence within the bucket; `0` is the initial seal, `1..n` later deltas.')), // prettier-ignore
+    .check(z.describe('Reported-count watermark observed when this delta was claimed.')),
   state: z
     .enum(['pending', 'reported', 'skipped'])
     .check(z.describe('Exactly-once state: `pending` retries, `reported` is done, `skipped` is audited.')), // prettier-ignore

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

@@ -4,6 +4,8 @@ import * as Runtime from '../../../test/runtime.js'
 import * as Webhooks from '../../internal/Webhooks.js'
 import * as Db from '../Db.js'
 import * as Organizations from './organizations.js'
+import * as SponsoredTransactions from './sponsoredTransactions.js'
+import * as StripeCustomers from './stripeCustomers.js'
 
 const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
 
@@ -127,6 +129,34 @@ describe('upsert', () => {
 })
 
 describe('deleteOrganization', () => {
+  test('behavior: preserves an org with unreported billable sponsorships', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.create(db, { id: 'org_1', name: 'One' })
+    await StripeCustomers.create(db, {
+      orgId: 'org_1',
+      stripeCustomerId: 'cus_org_1',
+    })
+    await SponsoredTransactions.upsert(db, {
+      apiKeyId: 'key_1',
+      billable: true,
+      chainId: 4217,
+      environment: 'production',
+      orgId: 'org_1',
+      projectId: 'prj_1',
+      signPayload: `0x${'bb'.repeat(32)}`,
+      transaction: `0x76${'cc'.repeat(16)}`,
+      transactionHash: `0x${'aa'.repeat(32)}`,
+    })
+
+    await expect(Organizations.deleteOrganization(db, 'org_1')).rejects.toThrow(
+      Organizations.UnreportedSponsorshipsError,
+    )
+    expect(await Organizations.get(db, 'org_1')).toBeDefined()
+    expect(await StripeCustomers.get(db, 'org_1')).toBeDefined()
+    await db.close()
+  })
+
   test('behavior: deletes api-key-owned webhook subscriptions', async () => {
     const db = create()
     await db.migrate()