tapimo 0.2.0 → 0.3.0

package/src/db/tables/requestUsage.ts

@@ -0,0 +1,231 @@
+import { type ColumnType, type Selectable, sql } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** A `bigint` count column: read as a string from pg, written as a number. */
+type Count = ColumnType<string, number, number>
+
+/** Environment a request-usage row attributes to. */
+export type Environment = db_Schema.RequestUsageBucket['environment']
+
+/** Exactly-once state of a meter event. */
+export type State = db_Schema.RequestUsageMeterEvent['state']
+
+/** Columns of the `request_usage_buckets` table (pg representation). */
+export type BucketTable = {
+  bucketStart: string
+  environment: Environment
+  orgId: string
+  reportedCount: Count
+  updatedAt: string
+}
+
+/** Columns of the `request_usage_meter_events` table (pg representation). */
+export type MeterEventTable = {
+  bucketStart: string
+  deltaCount: Count
+  environment: Environment
+  error: string | null
+  firstAttemptedAt: string
+  identifier: string
+  orgId: string
+  reason: string | null
+  reportedAt: string | null
+  sequence: number
+  state: State
+  stripeCustomerId: string
+}
+
+/** A stored per-hour request-count watermark. */
+export type Bucket = db_Schema.RequestUsageBucket
+
+/** A stored request-count meter event. */
+export type MeterEvent = db_Schema.RequestUsageMeterEvent
+
+/** Identifies one hourly bucket for an org in an environment. */
+export type BucketKey = {
+  /** UTC hour start (ISO 8601). */
+  bucketStart: string
+  /** Environment the requests were served under. */
+  environment: Environment
+  /** Organization id (`org_…`). */
+  orgId: string
+}
+
+/**
+ * Reads a bucket watermark.
+ *
+ * @param db - The database.
+ * @param key - The bucket key.
+ * @returns The watermark, or `undefined` when none has been reported yet.
+ */
+export async function getBucket(db: Db.Db, key: BucketKey): Promise<Bucket | undefined> {
+  const row = await db.kysely
+    .selectFrom('request_usage_buckets')
+    .selectAll()
+    .where('orgId', '=', key.orgId)
+    .where('environment', '=', key.environment)
+    .where('bucketStart', '=', key.bucketStart)
+    .executeTakeFirst()
+  return row ? toBucket(row) : undefined
+}
+
+/**
+ * Lists the meter events still awaiting a Stripe acknowledgement in an
+ * environment, oldest first — the reporter's crash-recovery drive.
+ *
+ * @param db - The database.
+ * @param environment - The environment to scan.
+ * @returns The pending meter events.
+ */
+export async function listPending(db: Db.Db, environment: Environment): Promise<MeterEvent[]> {
+  const rows = await db.kysely
+    .selectFrom('request_usage_meter_events')
+    .selectAll()
+    .where('environment', '=', environment)
+    .where('state', '=', 'pending')
+    .orderBy('firstAttemptedAt', 'asc')
+    .orderBy('identifier', 'asc')
+    .execute()
+  return rows.map(toMeterEvent)
+}
+
+/**
+ * Counts the meter events already reported for a bucket — the next delta's
+ * `sequence`, so a new seal never collides with a settled one.
+ *
+ * @param db - The database.
+ * @param key - The bucket key.
+ * @returns The count of reported events for the bucket.
+ */
+export async function countReported(db: Db.Db, key: BucketKey): Promise<number> {
+  const row = await db.kysely
+    .selectFrom('request_usage_meter_events')
+    .select((eb) => eb.fn.countAll<string>().as('count'))
+    .where('orgId', '=', key.orgId)
+    .where('environment', '=', key.environment)
+    .where('bucketStart', '=', key.bucketStart)
+    .where('state', '=', 'reported')
+    .executeTakeFirstOrThrow()
+  return Number(row.count)
+}
+
+/**
+ * Inserts a frozen `pending` meter event, claiming a delta. Idempotent on the
+ * deterministic `identifier`: a re-seal after a crash resolves to the existing
+ * row rather than duplicating the delta.
+ *
+ * @param db - The database.
+ * @param input - The event to insert.
+ * @returns Whether this call inserted the row.
+ */
+export async function insertPending(db: Db.Db, input: insertPending.Input): Promise<boolean> {
+  const now = new Date().toISOString()
+  const inserted = await db.kysely
+    .insertInto('request_usage_meter_events')
+    .values({
+      bucketStart: input.bucketStart,
+      deltaCount: input.deltaCount,
+      environment: input.environment,
+      error: null,
+      firstAttemptedAt: now,
+      identifier: input.identifier,
+      orgId: input.orgId,
+      reason: null,
+      reportedAt: null,
+      sequence: input.sequence,
+      state: 'pending',
+      stripeCustomerId: input.stripeCustomerId,
+    })
+    .onConflict((oc) => oc.doNothing())
+    .returning('identifier')
+    .executeTakeFirst()
+  return Boolean(inserted)
+}
+
+export declare namespace insertPending {
+  /** Fields accepted when sealing a pending meter event. */
+  type Input = {
+    /** UTC hour start the delta bills for (ISO 8601). */
+    bucketStart: string
+    /** Frozen request count this event bills (positive). */
+    deltaCount: number
+    /** Environment the requests were served under. */
+    environment: Environment
+    /** Deterministic id; also the Stripe identifier and idempotency key. */
+    identifier: string
+    /** Organization id (`org_…`). */
+    orgId: string
+    /** Delta sequence within the bucket. */
+    sequence: number
+    /** Stripe customer id the event bills against. */
+    stripeCustomerId: string
+  }
+}
+
+/**
+ * Marks a pending event reported and advances its bucket watermark by the
+ * event's frozen delta, atomically. A no-op once reported, so a retry after a
+ * crash between the Stripe ack and this write never double-advances.
+ *
+ * @param db - The database.
+ * @param identifier - The event identifier.
+ * @param at - When Stripe acknowledged the event (ISO 8601).
+ * @returns Whether this call settled the event (false when already reported).
+ */
+export function settle(db: Db.Db, identifier: string, at: string): Promise<boolean> {
+  return db.transaction(async (tx) => {
+    const updated = await tx.kysely
+      .updateTable('request_usage_meter_events')
+      .set({ error: null, reportedAt: at, state: 'reported' })
+      .where('identifier', '=', identifier)
+      .where('state', '=', 'pending')
+      .returningAll()
+      .executeTakeFirst()
+    if (!updated) return false
+    await tx.kysely
+      .insertInto('request_usage_buckets')
+      .values({
+        bucketStart: updated.bucketStart,
+        environment: updated.environment,
+        orgId: updated.orgId,
+        reportedCount: Number(updated.deltaCount),
+        updatedAt: at,
+      })
+      .onConflict((oc) =>
+        oc.columns(['orgId', 'environment', 'bucketStart']).doUpdateSet({
+          reportedCount: sql`request_usage_buckets.reported_count + ${updated.deltaCount}`,
+          updatedAt: at,
+        }),
+      )
+      .execute()
+    return true
+  })
+}
+
+/**
+ * Records a transient failure on a pending event; it stays pending for retry.
+ *
+ * @param db - The database.
+ * @param identifier - The event identifier.
+ * @param error - The failure detail.
+ */
+export async function markError(db: Db.Db, identifier: string, error: string): Promise<void> {
+  await db.kysely
+    .updateTable('request_usage_meter_events')
+    .set({ error: error.slice(0, 500) })
+    .where('identifier', '=', identifier)
+    .where('state', '=', 'pending')
+    .execute()
+}
+
+/** Maps a bucket row to its domain record. */
+function toBucket(row: Selectable<BucketTable>): Bucket {
+  return { ...row, reportedCount: Number(row.reportedCount) }
+}
+
+/** Maps a meter-event row to its domain record. */
+function toMeterEvent(row: Selectable<MeterEventTable>): MeterEvent {
+  return { ...row, deltaCount: Number(row.deltaCount) }
+}

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

@@ -25,7 +25,7 @@ function redact(record: SponsoredTransactions.Record) {
     ...record,
     createdAt: '<timestamp>',
     finalizedAt: record.finalizedAt === null ? null : '<timestamp>',
-    id: /^stx_[\w-]{21}$/.test(record.id) ? 'stx_<id>' : record.id,
+    id: /^stx_[0-9A-Za-z]{24}$/.test(record.id) ? 'stx_<id>' : record.id,
   }
 }
 
@@ -41,11 +41,14 @@ describe('upsert', () => {
         "billable": true,
         "chainId": 42431,
         "createdAt": "<timestamp>",
+        "currency": null,
         "environment": "production",
         "feeAmount": null,
+        "feeMax": null,
         "feeToken": null,
         "finalizedAt": null,
         "id": "stx_<id>",
+        "meterReportedAt": null,
         "orgId": "org_1",
         "projectId": "prj_1",
         "signPayload": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
@@ -216,3 +219,107 @@ describe('fail', () => {
     await db.close()
   })
 })
+
+describe('migration 0032', () => {
+  test('behavior: rescales legacy attodollar fee amounts idempotently', async () => {
+    const db = create()
+    await db.migrate()
+    // A pre-scaling row stored raw attodollars: 2.1e18 + 1, non-divisible so
+    // the rescale must round up.
+    const legacy = await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'31'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.finalize(db, legacy.id, {
+      feeAmount: '2100000000000000001',
+      finalizedAt: new Date().toISOString(),
+    })
+    // An already-scaled row sits far below the threshold and stays untouched.
+    const scaled = await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'32'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.finalize(db, scaled.id, {
+      feeAmount: '420000',
+      finalizedAt: new Date().toISOString(),
+    })
+
+    const rescale = Db.migrations.find((migration) => migration.name === '0032_sponsored_transactions_fee_amount_rescale') // prettier-ignore
+    // Applying twice proves the threshold guard: a re-run never rescales again.
+    for (let run = 0; run < 2; run++) {
+      await rescale!.up(db.kysely).execute()
+      expect((await SponsoredTransactions.get(db, legacy.id))?.feeAmount).toBe('2100001')
+      expect((await SponsoredTransactions.get(db, scaled.id))?.feeAmount).toBe('420000')
+    }
+    await db.close()
+  })
+})
+
+describe('spend', () => {
+  test('behavior: sums finalized fees plus pending caps within scope', async () => {
+    const db = create()
+    await db.migrate()
+    const chainIds = [input.chainId]
+    // Finalized in scope: counts its actual fee, never its cap.
+    const finalized = await SponsoredTransactions.upsert(db, { ...input, feeMax: '900000', signPayload: `0x${'01'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.finalize(db, finalized.id, {
+      feeAmount: '100000',
+      finalizedAt: new Date().toISOString(),
+    })
+    // Pending in scope: counts its signed cap.
+    await SponsoredTransactions.upsert(db, { ...input, feeMax: '250000', signPayload: `0x${'02'.repeat(32)}` }) // prettier-ignore
+    // Pending without a recorded cap (pre-column row): contributes nothing.
+    await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'03'.repeat(32)}` })
+    // Failed: out of scope regardless of cap.
+    const failed = await SponsoredTransactions.upsert(db, { ...input, feeMax: '700000', signPayload: `0x${'04'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.fail(db, failed.id, new Date().toISOString())
+    // Non-billable and foreign-chain rows: out of scope.
+    await SponsoredTransactions.upsert(db, { ...input, billable: false, environment: 'sandbox', feeMax: '500000', signPayload: `0x${'05'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.upsert(db, { ...input, chainId: 1337, feeMax: '500000', signPayload: `0x${'06'.repeat(32)}` }) // prettier-ignore
+    // Other orgs: out of scope.
+    await SponsoredTransactions.upsert(db, { ...input, feeMax: '500000', orgId: 'org_2', signPayload: `0x${'07'.repeat(32)}` }) // prettier-ignore
+
+    expect(await SponsoredTransactions.spend(db, { chainIds, orgId: 'org_1', since: '2000-01-01T00:00:00.000Z' })).toBe(350000n) // prettier-ignore
+    await db.close()
+  })
+
+  test('behavior: rows created before the window start are out of scope', async () => {
+    const db = create()
+    await db.migrate()
+    await SponsoredTransactions.upsert(db, { ...input, feeMax: '250000', signPayload: `0x${'08'.repeat(32)}` }) // prettier-ignore
+    const future = new Date(Date.now() + 60_000).toISOString()
+    expect(await SponsoredTransactions.spend(db, { chainIds: [input.chainId], orgId: 'org_1', since: future })).toBe(0n) // prettier-ignore
+    await db.close()
+  })
+})
+
+describe('listUnreported', () => {
+  test('behavior: lists finalized billable in-scope rows, oldest first', async () => {
+    const db = create()
+    await db.migrate()
+    const chainIds = [input.chainId]
+    const first = await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'11'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.finalize(db, first.id, { feeAmount: '100', finalizedAt: '2026-01-01T00:00:00.000Z' }) // prettier-ignore
+    const second = await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'12'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.finalize(db, second.id, { feeAmount: '200', finalizedAt: '2026-01-02T00:00:00.000Z' }) // prettier-ignore
+    // Pending, sandbox, and foreign-chain rows never report.
+    await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'13'.repeat(32)}` })
+    await SponsoredTransactions.upsert(db, { ...input, billable: false, environment: 'sandbox', signPayload: `0x${'14'.repeat(32)}` }) // prettier-ignore
+
+    const rows = await SponsoredTransactions.listUnreported(db, { chainIds })
+    expect(rows.map((row) => row.id)).toStrictEqual([first.id, second.id])
+
+    await SponsoredTransactions.markReported(db, first.id, new Date().toISOString())
+    const remaining = await SponsoredTransactions.listUnreported(db, { chainIds })
+    expect(remaining.map((row) => row.id)).toStrictEqual([second.id])
+    await db.close()
+  })
+})
+
+describe('markReported', () => {
+  test('behavior: marks once; re-marking never overwrites the first timestamp', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'15'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.finalize(db, record.id, { feeAmount: '100', finalizedAt: '2026-01-01T00:00:00.000Z' }) // prettier-ignore
+    await SponsoredTransactions.markReported(db, record.id, '2026-01-02T00:00:00.000Z')
+    await SponsoredTransactions.markReported(db, record.id, '2026-01-03T00:00:00.000Z')
+    const row = await SponsoredTransactions.get(db, record.id)
+    expect(row?.meterReportedAt).toMatchInlineSnapshot(`"2026-01-02T00:00:00.000Z"`)
+    await db.close()
+  })
+})

package/src/db/tables/sponsoredTransactions.ts

@@ -1,7 +1,7 @@
 import type { ExpressionBuilder, Selectable } from 'kysely'
 import { sql } from 'kysely'
-import { nanoid } from 'nanoid'
 
+import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
 
@@ -28,11 +28,14 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     billable: input.billable,
     chainId: input.chainId,
     createdAt: new Date().toISOString(),
+    currency: input.currency ?? null,
     environment: input.environment,
     feeAmount: null,
+    feeMax: input.feeMax ?? null,
     feeToken: input.feeToken ?? null,
     finalizedAt: null,
-    id: `stx_${nanoid()}`,
+    id: Id.generate('stx'),
+    meterReportedAt: null,
     orgId: input.orgId,
     projectId: input.projectId,
     signPayload: input.signPayload,
@@ -45,6 +48,9 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     .values(record)
     .onConflict((oc) =>
       oc.column('signPayload').doUpdateSet((eb) => ({
+        // Same sign payload = same envelope = same cap; only fills older nulls.
+        currency: eb.fn.coalesce(eb.ref('sponsored_transactions.currency'), eb.ref('excluded.currency')), // prettier-ignore
+        feeMax: eb.fn.coalesce(eb.ref('sponsored_transactions.feeMax'), eb.ref('excluded.feeMax')),
         // A raw submission fills the intent's hash; a duplicate intent never
         // clears an already-known hash.
         transactionHash: eb.fn.coalesce(
@@ -69,8 +75,12 @@ export declare namespace upsert {
     billable: boolean
     /** Chain the sponsored transaction targets. */
     chainId: number
+    /** Lowercase fee currency snapshot (`usd`), when resolved. */
+    currency?: string | undefined
     /** Key environment the sponsorship was requested under. */
     environment: Table['environment']
+    /** Signed fee cap (`gas × maxFeePerGas`) in base units, when known. */
+    feeMax?: string | undefined
     /** Fee token the sponsorship resolved, when known. */
     feeToken?: string | undefined
     /** Organization id (`org_…`) the spend attributes to. */
@@ -224,6 +234,219 @@ export async function fail(db: Db.Db, id: string, finalizedAt: string): Promise<
     .execute()
 }
 
+/**
+ * Records a sponsorship and enforces the period spend limit atomically. A
+ * per-org advisory lock serializes concurrent sponsorships so each one's
+ * signed cap is counted before the limit check; without it a burst reads
+ * pre-burst spend and overshoots. Throws {@link PeriodSpendLimitError} (rolling
+ * back the row) when the limit would be exceeded.
+ *
+ * @param db - The database (primary; never a cached replica).
+ * @param input - The sponsorship to record.
+ * @param limit - The period spend limit to enforce.
+ * @returns The stored record.
+ */
+export async function reserve(
+  db: Db.Db,
+  input: upsert.Input,
+  limit: reserve.Limit,
+): Promise<Record> {
+  return db.transaction(async (tx) => {
+    // `hashtext` maps the org id into the advisory-lock keyspace; the class
+    // namespaces it against other advisory-lock users. Released at tx end.
+    await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${input.orgId}))`.execute(tx.kysely) // prettier-ignore
+    const record = await upsert(tx, input)
+    if (record.billable) {
+      const committed = await spend(tx, {
+        chainIds: limit.chainIds,
+        orgId: input.orgId,
+        since: limit.since,
+      })
+      if (committed > limit.max) throw new PeriodSpendLimitError()
+    }
+    return record
+  })
+}
+
+/** Advisory-lock class namespacing per-org sponsorship serialization. */
+const billingLockClass = 1112294220
+
+export declare namespace reserve {
+  /** The period spend limit enforced by {@link reserve}. */
+  type Limit = {
+    /** Chains whose spend counts (mainnet chain ids). */
+    chainIds: readonly number[]
+    /** Limit in fee-token base units. */
+    max: bigint
+    /** Window start (ISO 8601). */
+    since: string
+  }
+}
+
+/**
+ * Billable spend committed since a cutoff, in fee-token base units: finalized
+ * rows at their actual fee plus pending rows at their signed fee cap, so
+ * in-flight sponsorships consume limit budget until receipts land.
+ *
+ * @param db - The database.
+ * @param options - Aggregation scope.
+ * @returns The committed spend in base units.
+ */
+export async function spend(db: Db.Db, options: spend.Options): Promise<bigint> {
+  const { chainIds, environment = 'production', orgId, since } = options
+  const query = db.kysely
+    .selectFrom('sponsored_transactions')
+    .select([
+      sql<string>`coalesce(sum(case when status = 'finalized' then fee_amount::numeric else 0 end), 0)`.as('finalized'), // prettier-ignore
+      sql<string>`coalesce(sum(case when status = 'pending' then fee_max::numeric else 0 end), 0)`.as('pending'), // prettier-ignore
+    ])
+    .where('orgId', '=', orgId)
+    .where('environment', '=', environment)
+    // Redundant with the CASE arms, but lets the billing index's
+    // (org_id, status, created_at) shape serve the range scan.
+    .where('status', 'in', ['finalized', 'pending'])
+    .where('chainId', 'in', [...chainIds])
+    .where('createdAt', '>=', since)
+  // Production mirrors the sponsorship gate — only billable rows count. Sandbox
+  // rows are non-billable by construction, so the figure is display-only.
+  const row = await (environment === 'production' ? query.where('billable', '=', true) : query) //
+    .executeTakeFirstOrThrow()
+  return BigInt(row.finalized) + BigInt(row.pending)
+}
+
+export declare namespace spend {
+  /** Options for {@link spend}. */
+  type Options = {
+    /** Chains whose spend counts (mainnet chain ids). */
+    chainIds: readonly number[]
+    /** Environment whose spend counts; production mirrors the billing gate, sandbox is display-only. Defaults to `production`. */
+    environment?: Table['environment'] | undefined
+    /** Organization id (`org_…`) the spend attributes to. */
+    orgId: string
+    /** Window start (ISO 8601); rows created earlier are out of scope. */
+    since: string
+  }
+}
+
+/**
+ * Sponsorship usage bucketed by time for one organization: row counts and
+ * committed fees per bucket. Fee semantics mirror {@link spend}: finalized
+ * rows at their actual fee, pending rows at their signed cap, failed rows at
+ * zero. Buckets with no rows are omitted.
+ *
+ * @param db - The database.
+ * @param options - Aggregation scope.
+ * @returns Time-ordered usage buckets.
+ */
+export async function usage(db: Db.Db, options: usage.Options): Promise<usage.Bucket[]> {
+  // TODO: convert to an OLAP-friendly approach (rollup table or columnar store)
+  // when per-org range scans grow slow.
+  const { environment, from, interval, orgId, projectId, to } = options
+  // `sql.lit` inlines the enum-validated interval so the GROUP BY expression
+  // matches the SELECT expression textually; truncation happens in UTC wall
+  // time regardless of the session time zone.
+  const bucket = sql`date_trunc(${sql.lit(interval)}, (created_at::timestamptz) at time zone 'UTC')`
+  let query = db.kysely
+    .selectFrom('sponsored_transactions')
+    .select([
+      sql<string>`to_char(${bucket}, 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`.as('timestamp'),
+      sql<string>`count(*)`.as('count'),
+      sql<string>`coalesce(sum(case when status = 'finalized' then fee_amount::numeric when status = 'pending' then fee_max::numeric else 0 end), 0)`.as('feeTotal'), // prettier-ignore
+    ])
+    .where('orgId', '=', orgId)
+    // Text-range bounds keep the (org_id, created_at) index serving the scan.
+    .where('createdAt', '>=', from)
+    .where('createdAt', '<', to)
+    .groupBy(bucket)
+    .orderBy(bucket)
+  if (environment !== undefined) query = query.where('environment', '=', environment)
+  if (projectId !== undefined) query = query.where('projectId', '=', projectId)
+  const rows = await query.execute()
+  return rows.map((row) => ({
+    count: Number(row.count),
+    feeTotal: BigInt(row.feeTotal),
+    timestamp: row.timestamp,
+  }))
+}
+
+export declare namespace usage {
+  /** One time bucket of sponsorship usage. */
+  type Bucket = {
+    /** Sponsored transactions recorded in the bucket, any status. */
+    count: number
+    /** Committed fees in fee-token base units: finalized fees plus pending caps. */
+    feeTotal: bigint
+    /** Bucket start (ISO 8601), aligned to UTC calendar boundaries. */
+    timestamp: string
+  }
+
+  /** Options for {@link usage}. */
+  type Options = {
+    /** Key environment to restrict to; omit for all. */
+    environment?: Table['environment'] | undefined
+    /** Window start (ISO 8601), inclusive. */
+    from: string
+    /** Bucket width, aligned to UTC calendar boundaries. */
+    interval: 'day' | 'hour' | 'month' | 'week'
+    /** Organization id (`org_…`) the usage attributes to. */
+    orgId: string
+    /** Project id (`prj_…`) to restrict to; omit for all. */
+    projectId?: string | undefined
+    /** Window end (ISO 8601), exclusive. */
+    to: string
+  }
+}
+
+/**
+ * Lists finalized billable rows not yet reported to the billing meter, oldest
+ * first, for the metering job.
+ *
+ * @param db - The database.
+ * @param options - Reporting scope.
+ * @returns The unreported records.
+ */
+export function listUnreported(db: Db.Db, options: listUnreported.Options): Promise<Record[]> {
+  let query = db.kysely
+    .selectFrom('sponsored_transactions')
+    .selectAll()
+    .where('status', '=', 'finalized')
+    .where('billable', '=', true)
+    .where('chainId', 'in', [...options.chainIds])
+    .where('meterReportedAt', 'is', null)
+    // `id` breaks same-millisecond `finalizedAt` ties for a deterministic scan.
+    .orderBy('finalizedAt', 'asc')
+    .orderBy('id', 'asc')
+  if (options.limit !== undefined) query = query.limit(options.limit)
+  return query.execute()
+}
+
+export declare namespace listUnreported {
+  /** Options for {@link listUnreported}. */
+  type Options = {
+    /** Chains whose spend is metered (mainnet chain ids). */
+    chainIds: readonly number[]
+    /** Maximum rows to return. */
+    limit?: number | undefined
+  }
+}
+
+/**
+ * Marks a row as reported to the billing meter. A no-op once marked — the
+ * durable exactly-once guard for the metering job.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param at - When the report was acknowledged (ISO 8601).
+ */
+export async function markReported(db: Db.Db, id: string, at: string): Promise<void> {
+  await db.kysely
+    .updateTable('sponsored_transactions')
+    .set({ meterReportedAt: at })
+    .where('id', '=', id)
+    .where('meterReportedAt', 'is', null)
+    .execute()
+}
+
 /** Intent status predicate; failed rows are recovery candidates only briefly. */
 function intentStatus(failedSince: string | undefined) {
   return (eb: ExpressionBuilder<Db.Database, 'sponsored_transactions'>) => {
@@ -234,3 +457,8 @@ function intentStatus(failedSince: string | undefined) {
     ])
   }
 }
+
+/** Thrown by {@link reserve} when recording would exceed the org's period spend limit. */
+export class PeriodSpendLimitError extends Error {
+  override name = 'SponsoredTransactions.PeriodSpendLimitError'
+}