tapimo 0.10.0 → 0.10.2

package/src/internal/Credential.ts

@@ -0,0 +1,58 @@
+/** Shared or per-chain credentials. */
+export type ChainCredential = string | Record<number, string>
+
+/** Parses shared or per-chain credentials from an environment value. */
+export function parseCredential(value: ChainCredential | undefined): parseCredential.ReturnType {
+  if (!value) return undefined
+  if (typeof value !== 'string') return value
+  const credentials = (() => {
+    try {
+      return JSON.parse(value) as unknown
+    } catch {
+      return value
+    }
+  })()
+  if (typeof credentials === 'string') return credentials
+  if (
+    !credentials ||
+    typeof credentials !== 'object' ||
+    Array.isArray(credentials) ||
+    Object.values(credentials).some((credential) => typeof credential !== 'string')
+  )
+    throw new Error('Expected a credential or a chain-id-to-credential JSON object.')
+  return credentials as Record<number, string>
+}
+
+export declare namespace parseCredential {
+  /** Parsed shared or per-chain credentials. */
+  type ReturnType = ChainCredential | undefined
+}
+
+/** Resolves a chain credential and infers its HTTP authorization scheme. */
+export function resolveCredential(
+  options: resolveCredential.Options,
+): resolveCredential.ReturnType {
+  const credentials = parseCredential(options.value)
+  const credential = typeof credentials === 'string' ? credentials : credentials?.[options.chainId]
+  if (!credential) return { basicAuth: undefined }
+  if (credential.includes(':')) return { basicAuth: credential }
+  return { basicAuth: undefined, bearerAuth: credential }
+}
+
+export declare namespace resolveCredential {
+  /** Options for resolving a chain credential. */
+  type Options = {
+    /** Chain id selecting a per-chain credential. */
+    chainId: number
+    /** Shared or per-chain credentials. */
+    value?: ChainCredential | undefined
+  }
+
+  /** Resolved HTTP authorization credentials. */
+  type ReturnType = {
+    /** Basic credentials inferred from a value containing a colon. */
+    basicAuth: string | undefined
+    /** Bearer credential inferred from a value without a colon. */
+    bearerAuth?: string | undefined
+  }
+}

package/src/internal/EarnRates.ts

@@ -246,6 +246,12 @@ async function measurePage(options: measurePage.Options): Promise<Measurement |
       () => undefined,
     )
 
+  // The migration scan is independent of historical quotes, so keep its TIDX
+  // round trip off the RPC critical path.
+  const migrations = recentMigrations(options).then(
+    (value) => ({ status: 'fulfilled', value }) as const,
+    (reason: unknown) => ({ reason, status: 'rejected' }) as const,
+  )
   const rates = new Map<string, string>()
   await Promise.all(
     options.vaults.map(async (vault) => {
@@ -263,13 +269,13 @@ async function measurePage(options: measurePage.Options): Promise<Measurement |
     }),
   )
   if (rates.size === 0) return { measuredAt, rates }
+  const migrationResult = await migrations
 
   // A migration inside the window bridges two different yield engines, so the
-  // window resets instead of reporting growth across the swap. Scanned only
-  // once a rate exists for it to invalidate.
-  const migrations = await recentMigrations(options)
-  if (!migrations) return undefined
-  for (const { blockNumber, vault } of migrations)
+  // window resets instead of reporting growth across the swap.
+  if (migrationResult.status === 'rejected') throw migrationResult.reason
+  if (!migrationResult.value) return undefined
+  for (const { blockNumber, vault } of migrationResult.value)
     if (blockNumber > start.number && blockNumber <= end.number) rates.delete(vault)
   return { measuredAt, rates }
 }
@@ -306,9 +312,9 @@ async function boundaryBlocks(options: boundaryBlocks.Options): Promise<Boundari
       const result = await options.getTidx(chainId).fetch({
         chainId,
         query: `
-          (SELECT num, timestamp FROM blocks WHERE timestamp <= '${endInstant}' ORDER BY num DESC LIMIT 1)
+          (SELECT num, timestamp FROM blocks WHERE timestamp <= '${endInstant}' ORDER BY timestamp DESC, num DESC LIMIT 1)
           UNION ALL
-          (SELECT num, timestamp FROM blocks WHERE timestamp <= '${startInstant}' ORDER BY num DESC LIMIT 1)
+          (SELECT num, timestamp FROM blocks WHERE timestamp <= '${startInstant}' ORDER BY timestamp DESC, num DESC LIMIT 1)
         ` as string,
       })
       const rows = result.rows.flatMap((row) => {

package/src/internal/EarnVaults.test.ts

@@ -76,7 +76,7 @@ describe('resolve', () => {
       const getClient = Viem.createGetClient({
         defaultChainId: tempoTestnet.id,
         rpc: TestViem.rpc,
-        zones: [Zones.zoneModerato],
+        zones: [Zones.zoneModeratoInternal],
       })
       const { instantLiquidity, sharePrice, state, ...discovery } = await EarnVaults.resolve({
         getClient,
@@ -84,7 +84,7 @@ describe('resolve', () => {
           chainId: tempoTestnet.id,
           vaultAddress,
         },
-        zones: [Zones.zoneModerato],
+        zones: [Zones.zoneModeratoInternal],
       })
       expect({
         depositsPaused: state.depositsPaused,

package/src/internal/Log.test.ts

@@ -51,10 +51,11 @@ describe('middleware', () => {
     `)
   })
 
-  test('includes a failed optional funding transfer count', async () => {
+  test('includes failed optional funding counts', async () => {
     const entries: Log.Entry[] = []
     const api = app({ emit: (entry) => void entries.push(entry) })
     api.get('/v1/funding/transfers', (c) => {
+      c.set('fundingDepositCountFailed', true)
       c.set('fundingTransferCountFailed', true)
       return c.json({ data: [], nextCursor: null }, 200)
     })
@@ -63,6 +64,7 @@ describe('middleware', () => {
 
     expect(stable(entries[0]!)).toMatchInlineSnapshot(`
       {
+        "fundingDepositCountFailed": true,
         "fundingTransferCountFailed": true,
         "level": "info",
         "method": "GET",

package/src/internal/Log.ts

@@ -10,10 +10,14 @@ import type * as Timing from './Timing.js'
 
 /** Hono variables read by the request logger and written by other layers. */
 export type Variables = {
+  /** Tempo chain selected for the request. */
+  chainId?: number | undefined
   /** Whether the original request exception was already reported. */
   errorCaptured?: boolean | undefined
   /** Stable error code recorded by `Response.error` for the request log entry. */
   errorCode?: string | undefined
+  /** Whether the optional funding deposit count query failed. */
+  fundingDepositCountFailed?: true | undefined
   /** Bounded MPP relay outcome emitted by the credential routes. */
   mpp?: Entry['mpp'] | undefined
   /** Bounded outcomes for funding providers attempted by the request. */
@@ -125,12 +129,16 @@ export type Sponsorship = {
 export type Entry = {
   /** `'hit'` when the edge response cache served the request without reaching the origin handlers. */
   cache?: 'hit' | undefined
+  /** Tempo chain selected for the request. */
+  chainId?: number | undefined
   /** Total request duration in milliseconds. */
   duration: number
   /** Whether the original request exception was already reported. */
   errorCaptured?: boolean | undefined
   /** Stable error code when the response is a JSON error envelope (e.g. `not_found`, `api_key_invalid`). */
   errorCode?: string | undefined
+  /** Whether the optional funding deposit count query failed. */
+  fundingDepositCountFailed?: true | undefined
   /** Bounded funding provider attempts made while serving the request. */
   fundingProviderAttempts?: readonly FundingProviderAttempt[] | undefined
   /** Whether the optional funding transfer count query failed. */
@@ -253,7 +261,11 @@ export function middleware<environment extends Environment = Environment>(
     const error = c.error as ErrorMetadata | undefined
     const principal = c.get('principal' as never) as Auth.Principal | undefined
     const errorCaptured = c.get('errorCaptured' as never) as boolean | undefined
+    const chainId = c.get('chainId' as never) as number | undefined
     const errorCode = c.get('errorCode' as never) as string | undefined
+    const fundingDepositCountFailed = c.get('fundingDepositCountFailed' as never) as
+      | true
+      | undefined
     const fundingProviderAttempts =
       error?.fundingProviderAttempts ??
       (c.get('fundingProviderAttempts' as never) as Entry['fundingProviderAttempts'] | undefined)
@@ -300,9 +312,11 @@ export function middleware<environment extends Environment = Environment>(
 
     const result = fn({
       ...(c.get('edgeCacheStatus' as never) === 'hit' ? { cache: 'hit' as const } : {}),
+      ...(chainId === undefined ? {} : { chainId }),
       duration: round(duration),
       ...(errorCaptured === undefined ? {} : { errorCaptured }),
       ...(errorCode === undefined ? {} : { errorCode }),
+      ...(fundingDepositCountFailed === undefined ? {} : { fundingDepositCountFailed }),
       ...(fundingProviderAttempts === undefined ? {} : { fundingProviderAttempts }),
       ...(fundingTransferCountFailed === undefined ? {} : { fundingTransferCountFailed }),
       level:

package/src/internal/MetricSink.test.ts

@@ -11,7 +11,7 @@ type MetricEvent = {
 }
 
 describe('requests', () => {
-  test('records optional funding transfer count failures on successful pages', () => {
+  test('records optional funding count failures on successful pages', () => {
     const events: MetricEvent[] = []
     const metrics = Metrics.from({
       count(name, value, tags) {
@@ -25,6 +25,7 @@ describe('requests', () => {
 
     record({
       duration: 10,
+      fundingDepositCountFailed: true,
       fundingTransferCountFailed: true,
       level: 'info',
       method: 'GET',
@@ -34,6 +35,22 @@ describe('requests', () => {
       status: 200,
     })
 
+    expect(events.find((event) => event.name === 'funding_deposit_count_failure_count'))
+      .toMatchInlineSnapshot(`
+      {
+        "name": "funding_deposit_count_failure_count",
+        "tags": {
+          "cache": "miss",
+          "method": "GET",
+          "principal_environment": "none",
+          "principal_type": "unknown",
+          "route": "/v1/funding/transfers",
+        },
+        "type": "count",
+        "value": 1,
+      }
+    `)
+
     expect(events.find((event) => event.name === 'funding_transfer_count_failure_count'))
       .toMatchInlineSnapshot(`
       {
@@ -637,6 +654,93 @@ describe('webhooks', () => {
     `)
   })
 
+  test('records scan pipeline blocks, backlog, and finality lag', () => {
+    const events: MetricEvent[] = []
+    const metrics = Metrics.from({
+      count(name, value, tags) {
+        events.push({ name, tags, type: 'count', value })
+      },
+      flush() {},
+      gauge(name, value, tags) {
+        events.push({ name, tags, type: 'gauge', value })
+      },
+      histogram() {},
+    })
+    const sink = MetricSink.webhooks(metrics)
+
+    sink.record({ chainId: 42431, matches: 3, origin: 'socket', outcome: 'dispatched', type: 'webhook:scan-block' }) // prettier-ignore
+    sink.record({ chainId: 42431, matches: 0, origin: 'poll', outcome: 'deferred', type: 'webhook:scan-block' }) // prettier-ignore
+    sink.record({ chainId: 42431, oldestPendingAgeMs: 5_000, pendingCount: 2, type: 'webhook:scan-backlog' }) // prettier-ignore
+    sink.record({ chainId: 42431, lagBlocks: 1, type: 'webhook:scan-finality' })
+
+    expect(events.map(({ name, tags, value }) => `${name}=${value} ${JSON.stringify(tags)}`))
+      .toMatchInlineSnapshot(`
+        [
+          "webhook_scan_block_count=1 {"chain_id":"42431","origin":"socket","outcome":"dispatched"}",
+          "webhook_scan_match_count=3 {"chain_id":"42431","origin":"socket","outcome":"dispatched"}",
+          "webhook_scan_block_count=1 {"chain_id":"42431","origin":"poll","outcome":"deferred"}",
+          "webhook_scan_pending_count=2 {"chain_id":"42431"}",
+          "webhook_scan_oldest_pending_age_ms=5000 {"chain_id":"42431"}",
+          "webhook_scan_finality_lag_blocks=1 {"chain_id":"42431"}",
+        ]
+      `)
+  })
+
+  test('records obligation staging and claim outcomes', () => {
+    const events: MetricEvent[] = []
+    const metrics = Metrics.from({
+      count(name, value, tags) {
+        events.push({ name, tags, type: 'count', value })
+      },
+      flush() {},
+      gauge() {},
+      histogram() {},
+    })
+    const sink = MetricSink.webhooks(metrics)
+
+    sink.record({ count: 3, outcome: 'created', type: 'webhook:delivery-job-ensure' })
+    sink.record({ count: 2, outcome: 'existing', type: 'webhook:delivery-job-ensure' })
+    sink.record({ outcome: 'claimed', type: 'webhook:delivery-job-claim' })
+    sink.record({ outcome: 'terminal', type: 'webhook:delivery-job-claim' })
+
+    expect(events).toMatchInlineSnapshot(`
+      [
+        {
+          "name": "webhook_delivery_job_ensure_count",
+          "tags": {
+            "outcome": "created",
+          },
+          "type": "count",
+          "value": 3,
+        },
+        {
+          "name": "webhook_delivery_job_ensure_count",
+          "tags": {
+            "outcome": "existing",
+          },
+          "type": "count",
+          "value": 2,
+        },
+        {
+          "name": "webhook_delivery_job_claim_count",
+          "tags": {
+            "outcome": "claimed",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "webhook_delivery_job_claim_count",
+          "tags": {
+            "outcome": "terminal",
+          },
+          "type": "count",
+          "value": 1,
+        },
+      ]
+    `)
+  })
+
   test('records scan boundaries with bounded workload dimensions', () => {
     const events: MetricEvent[] = []
     const metrics = Metrics.from({
@@ -867,6 +971,7 @@ describe('webhooks', () => {
     } satisfies Webhooks.Envelope
 
     sink.record({
+      attempt: 1,
       envelope,
       queueAttempt: 2,
       result: { durationMs: 25, ok: true, status: 204 },
@@ -957,6 +1062,7 @@ describe('webhooks', () => {
     expect(JSON.stringify(events)).not.toMatch(/evt_private|org_private|wh_private|whsec_private/)
 
     sink.record({
+      attempt: 3,
       envelope,
       queueAttempt: 3,
       result: { error: 'upstream unavailable', ok: false, status: 503 },
@@ -967,7 +1073,7 @@ describe('webhooks', () => {
 
     expect(events.at(-1)?.tags).toMatchObject({
       queue_attempt_bucket: '3-5',
-      queue_disposition: 'retried',
+      queue_disposition: 'scheduled_retry',
     })
   })
 })

package/src/internal/MetricSink.ts

@@ -51,6 +51,21 @@ export type WebhookEvent =
       /** Identifies durable coordinator progress. */
       type: 'webhook:head-progress'
     }
+  | {
+      /** Tempo chain whose listener was checked. */
+      chainId: number
+      /** Heads refused in a row by the monotonic guard; zero on a delivering listener. */
+      skippedHeads: number
+      /** Identifies heads received and discarded rather than heads not received. */
+      type: 'webhook:head-skipped'
+    }
+  | {
+      chainId: number
+      /** Blocks the probed chain head leads the listener's newest observation. */
+      lagBlocks: number
+      /** Identifies the out-of-band listener head probe. */
+      type: 'webhook:listener-head-lag'
+    }
   | {
       /** Tempo chain whose recovery poke was dequeued. */
       chainId: number
@@ -145,6 +160,49 @@ export type WebhookEvent =
       type: 'webhook:enqueue'
     }
   | {
+      chainId: number
+      /** Rows matched when dispatched; zero otherwise. */
+      matches: number
+      /** How the head that enqueued this block was observed. */
+      origin: string
+      /** One scanned block's outcome. */
+      outcome: 'deferred' | 'dispatched' | 'empty'
+      /** Identifies one block-fanout scan. */
+      type: 'webhook:scan-block'
+    }
+  | {
+      chainId: number
+      /** Age of the oldest tracked block, absent when none are pending. */
+      oldestPendingAgeMs?: number | undefined
+      /** Tracked blocks awaiting completion reports. */
+      pendingCount: number
+      /** Identifies the coordinator's tracked-scan backlog. */
+      type: 'webhook:scan-backlog'
+    }
+  | {
+      chainId: number
+      /** Blocks between the observed head and the finalized head. */
+      lagBlocks: number
+      /** Identifies the finality gate's settling distance. */
+      type: 'webhook:scan-finality'
+    }
+  | {
+      /** Atomic ledger claim outcome. */
+      outcome: 'attempting' | 'claimed' | 'missing' | 'scheduled' | 'terminal'
+      /** Identifies a delivery-obligation claim. */
+      type: 'webhook:delivery-job-claim'
+    }
+  | {
+      /** Obligations represented by this outcome. */
+      count: number
+      /** Whether staging created or found the obligation. */
+      outcome: 'created' | 'existing'
+      /** Identifies obligation staging ahead of Queue handoff. */
+      type: 'webhook:delivery-job-ensure'
+    }
+  | {
+      /** Delivery attempt ordinal: the ledger claim count on the queue path. */
+      attempt: number
       envelope: Webhooks.Envelope
       /** Cloudflare Queue delivery attempt, absent outside the Queue path. */
       queueAttempt?: number | undefined
@@ -244,6 +302,9 @@ export function requests(backend: Metrics): RequestSink {
       backend.histogram('funding_quote_provider_duration_ms', attempt.durationMs, tags_attempt)
     }
 
+    if (entry.fundingDepositCountFailed)
+      backend.count('funding_deposit_count_failure_count', 1, tags)
+
     if (entry.fundingTransferCountFailed)
       backend.count('funding_transfer_count_failure_count', 1, tags)
 
@@ -340,6 +401,16 @@ export function webhooks(backend: Metrics): WebhookSink {
             chain_id: String(event.chainId),
           })
           return
+        case 'webhook:head-skipped':
+          backend.gauge('webhook_head_skipped_count', event.skippedHeads, {
+            chain_id: String(event.chainId),
+          })
+          return
+        case 'webhook:listener-head-lag':
+          backend.gauge('webhook_listener_head_lag_blocks', event.lagBlocks, {
+            chain_id: String(event.chainId),
+          })
+          return
         case 'webhook:poll-failure':
           backend.count('webhook_poll_failure_count', 1, {
             chain_id: String(event.chainId),
@@ -456,6 +527,38 @@ export function webhooks(backend: Metrics): WebhookSink {
           })
           return
         }
+        case 'webhook:scan-block': {
+          const tags = {
+            chain_id: String(event.chainId),
+            origin: event.origin,
+            outcome: event.outcome,
+          }
+          backend.count('webhook_scan_block_count', 1, tags)
+          if (event.matches > 0) backend.count('webhook_scan_match_count', event.matches, tags)
+          return
+        }
+        case 'webhook:scan-backlog': {
+          const tags = { chain_id: String(event.chainId) }
+          backend.gauge('webhook_scan_pending_count', event.pendingCount, tags)
+          backend.gauge('webhook_scan_oldest_pending_age_ms', event.oldestPendingAgeMs ?? 0, tags)
+          return
+        }
+        case 'webhook:scan-finality': {
+          backend.gauge('webhook_scan_finality_lag_blocks', event.lagBlocks, {
+            chain_id: String(event.chainId),
+          })
+          return
+        }
+        case 'webhook:delivery-job-claim': {
+          backend.count('webhook_delivery_job_claim_count', 1, { outcome: event.outcome })
+          return
+        }
+        case 'webhook:delivery-job-ensure': {
+          backend.count('webhook_delivery_job_ensure_count', event.count, {
+            outcome: event.outcome,
+          })
+          return
+        }
         case 'webhook:delivery': {
           const { envelope, result, subscription, timings } = event
           const queueTags =
@@ -463,7 +566,11 @@ export function webhooks(backend: Metrics): WebhookSink {
               ? {}
               : {
                   queue_attempt_bucket: attemptBucket(event.queueAttempt),
-                  queue_disposition: WebhookDestination.isRetryable(result) ? 'retried' : 'acked',
+                  // Retryable results ack the message and schedule a ledger
+                  // retry; the Queue transport never redelivers them.
+                  queue_disposition: WebhookDestination.isRetryable(result)
+                    ? 'scheduled_retry'
+                    : 'acked',
                 }
           const tags = {
             chain_id: String(envelope.chainId),
@@ -473,7 +580,7 @@ export function webhooks(backend: Metrics): WebhookSink {
           const outcome = result.ok ? 'succeeded' : 'failed'
           backend.count('webhook_delivery_attempt_count', 1, {
             ...tags,
-            attempt_bucket: attemptBucket(subscription.failureCount + 1),
+            attempt_bucket: attemptBucket(event.attempt),
             outcome,
             ...queueTags,
             status_class: statusClass(result),
@@ -495,6 +602,9 @@ export function webhooks(backend: Metrics): WebhookSink {
           if (timings?.endToEndMs !== undefined)
             backend.histogram('webhook_delivery_end_to_end_ms', timings.endToEndMs, {
               ...tags,
+              // Unlimited-horizon ledger retries emit hour-plus samples;
+              // the bucket keeps first-attempt percentiles interpretable.
+              attempt_bucket: attemptBucket(event.attempt),
               outcome,
             })
           if (timings?.eventToEnvelopeMs !== undefined)

package/src/internal/RateLimit.test.ts

@@ -1,13 +1,14 @@
 import { RateLimit, Store } from 'tapimo'
 
 describe('memory', () => {
-  test('tracks fixed-window quota in a store', async () => {
+  test('tracks fixed-minute quota in a store', async () => {
     const store = RateLimit.memory({
       now: () => new Date('2026-05-25T00:00:30.000Z'),
     })
-    const first = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
-    const second = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
-    const third = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+    const limit = { limit: 2, period: 'minute' } as const
+    const first = await store.consume({ key: 'public:anonymous', limit })
+    const second = await store.consume({ key: 'public:anonymous', limit })
+    const third = await store.consume({ key: 'public:anonymous', limit })
 
     expect(first).toMatchInlineSnapshot(`
       {
@@ -35,25 +36,26 @@ describe('memory', () => {
     `)
   })
 
-  test('restarts the count when the next window opens', async () => {
-    // The window reset rides on counter expiry (the key is stable, not
-    // bucket-suffixed), so the store clock and the consume clock must agree.
+  test('restarts the count when the next second opens', async () => {
+    // The window reset rides on counter expiry, so the store clock and the
+    // consume clock must agree.
     vi.useFakeTimers()
     try {
-      vi.setSystemTime(new Date('2026-05-25T00:00:30.000Z'))
+      vi.setSystemTime(new Date('2026-05-25T00:00:30.250Z'))
       const store = RateLimit.memory()
-      await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
-      await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+      const limit = { limit: 2, period: 'second' } as const
+      await store.consume({ key: 'public:anonymous', limit })
+      await store.consume({ key: 'public:anonymous', limit })
 
-      vi.setSystemTime(new Date('2026-05-25T00:01:00.001Z'))
-      const next = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+      vi.setSystemTime(new Date('2026-05-25T00:00:31.001Z'))
+      const next = await store.consume({ key: 'public:anonymous', limit })
 
       expect(next).toMatchInlineSnapshot(`
         {
           "allowed": true,
           "limit": 2,
           "remaining": 1,
-          "reset": 1779667320,
+          "reset": 1779667232,
         }
       `)
     } finally {
@@ -72,19 +74,22 @@ describe('memory', () => {
       },
     })
     const store = RateLimit.memory({
-      // 30s into the minute, so 30s of the window remains.
-      now: () => new Date('2026-05-25T00:00:30.000Z'),
+      // 250ms into the second, so 750ms of the window remains.
+      now: () => new Date('2026-05-25T00:00:30.250Z'),
       store: recording,
     })
 
-    await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+    await store.consume({
+      key: 'public:anonymous',
+      limit: { limit: 2, period: 'second' },
+    })
 
     expect(increments).toMatchInlineSnapshot(`
       [
         {
-          "key": "ratelimit:public:anonymous",
+          "key": "ratelimit:second:1779667230:public:anonymous",
           "options": {
-            "ttl": 30000,
+            "ttl": 750,
           },
         },
       ]

package/src/internal/RateLimit.ts

@@ -6,9 +6,15 @@ import * as Store from './Store.js'
 export namespace schema {
   /** A rate-limit policy; the source of truth for {@link Limit}. */
   export const Limit = z.object({
-    perMinute: z
+    limit: z
       .number()
-      .check(z.int(), z.nonnegative(), z.describe('Number of requests allowed per minute.')),
+      .check(z.int(), z.nonnegative(), z.describe('Number of requests allowed per period.')),
+    period: z
+      .union([z.literal('minute'), z.literal('second')])
+      .check(
+        z.describe('Fixed window used to enforce the request limit.'),
+        z.meta({ examples: ['minute'] }),
+      ),
   })
 }
 
@@ -49,11 +55,8 @@ export namespace RateLimitStore {
  * Each consume is a single `Store.increment`, so a backend with a native
  * counter (e.g. a Durable Object) is one atomic round trip; backends without
  * one fall back to get + put, acceptable for dev/in-process stores only.
- * The storage key is stable per quota key — the
- * window lives in the TTL: the counter expires exactly at the end of the
- * current minute, so the next window's first hit restarts at 1 and idle keys
- * hold no storage. The sub-minute TTL rules out Cloudflare KV as a backend,
- * which is unsuitable for enforced counters anyway.
+ * The storage key includes the fixed-window bucket, so backend latency cannot
+ * carry a previous count into a later window.
  */
 export function memory(options: memory.Options = {}): RateLimitStore {
   const store = options.store ?? Store.memory()
@@ -62,19 +65,24 @@ export function memory(options: memory.Options = {}): RateLimitStore {
   return {
     async consume(options) {
       const time = now().getTime()
-      const bucket = Math.floor(time / 60_000)
-      // Every increment within a window recomputes the TTL against the same
-      // window end, so the counter's absolute expiry never moves under load.
-      const count = await Store.increment(store, `ratelimit:${options.key}`, {
-        ttl: (bucket + 1) * 60_000 - time,
-      })
-      const limit = options.limit.perMinute
+      const window = options.limit.period === 'second' ? 1_000 : 60_000
+      const bucket = Math.floor(time / window)
+      // The bucket isolates window counts if the backing store applies the TTL
+      // after the next window starts.
+      const count = await Store.increment(
+        store,
+        `ratelimit:${options.limit.period}:${bucket}:${options.key}`,
+        {
+          ttl: (bucket + 1) * window - time,
+        },
+      )
+      const limit = options.limit.limit
 
       return {
         allowed: count <= limit,
         limit,
         remaining: Math.max(limit - count, 0),
-        reset: Math.ceil(((bucket + 1) * 60_000) / 1_000),
+        reset: Math.ceil(((bucket + 1) * window) / 1_000),
       }
     },
   }