tapimo 0.5.0 → 0.5.2

package/src/internal/Auth.ts

@@ -58,6 +58,8 @@ export type Context = {
    * framework default.
    */
   publicRateLimit?: RateLimit.Limit | undefined
+  /** Resolves a trusted client IP for public quota identity. */
+  publicClientIp?: ((request: Request) => string | undefined) | undefined
   /** Rate-limit store used by API handlers. */
   rateLimit?: RateLimit.Store | undefined
   /** Session lane resolution (the session surface's capability), or undefined when sessions are unmounted. */
@@ -523,6 +525,9 @@ export function middleware<
     // API-key-only routes (no per-route `policy.public`) still fall back to the
     // deployment's configured public quota.
     publicRateLimit: defaults.public.rateLimit,
+    ...(options.public && options.public.clientIp
+      ? { publicClientIp: options.public.clientIp }
+      : {}),
     ...(options.mpp === false
       ? {}
       : {
@@ -608,6 +613,8 @@ export declare namespace middleware {
     /** Default public access policy. Pass false to disable anonymous access. */
     public?:
       | {
+          /** Resolves the client IP from trusted runtime or proxy metadata. Defaults to `cf-connecting-ip`. */
+          clientIp?: ((request: Request) => string | undefined) | undefined
           /** Anonymous public quota for protected routes. */
           rateLimit?: RateLimit.Limit | undefined
         }
@@ -1406,6 +1413,16 @@ export function require<environment extends Environment = Environment>(
     const hasQueryApiKey = new URL(c.req.url).searchParams.has('key')
     // Auth owns `key`; strict route schemas must not validate it.
     stripApiKeyQuery(c)
+    // Reject unknown chains before MPP builds a chain-bound challenge. Route
+    // groups publish their supported chains into the shared app context.
+    const chainId = explicitChainId(c)
+    const supportedChainIds = (c.var as Record<string, unknown>)['supportedChainIds']
+    if (
+      chainId !== undefined &&
+      supportedChainIds instanceof Set &&
+      !supportedChainIds.has(chainId)
+    )
+      return Response.unsupportedChainId(c, chainId, supportedChainIds)
     const proceed = async () => {
       await next()
       // Query credential responses must not enter shared caches.
@@ -1557,7 +1574,7 @@ export function require<environment extends Environment = Environment>(
       }
     }
 
-    const publicPrincipal = principalFromPublic(c)
+    const publicPrincipal = principalFromPublic(c, auth)
     if (hasPayment) {
       c.set('principal', publicPrincipal)
       return requirePayment(c, proceed, {
@@ -1891,15 +1908,10 @@ function principalFromApiKey(apiKey: ApiKey.ApiKey): Principal {
   }
 }
 
-function principalFromPublic(c: hono_Context): Principal {
-  const forwarded = c.req.header('x-forwarded-for')?.split(',')[0]?.trim()
+function principalFromPublic(c: hono_Context, auth: Context): Principal {
+  const ip = auth.publicClientIp ? auth.publicClientIp(c.req.raw) : c.req.header('cf-connecting-ip')
   return {
-    id:
-      c.req.header('cf-connecting-ip') ??
-      c.req.header('x-real-ip') ??
-      forwarded ??
-      c.req.header('x-test-client-ip') ??
-      'anonymous',
+    id: ip ? RateLimit.normalizeIp(ip) : 'anonymous',
     type: 'public',
   }
 }

package/src/internal/Cache.test.ts

@@ -1,6 +1,25 @@
 import { Hono } from 'hono'
+import * as z from 'zod/mini'
 import * as Cache from './Cache.js'
 
+describe('urlKey', () => {
+  test('serializes parsed arrays as repeated query parameters', async () => {
+    const schema = z.object({ include: z.array(z.string()) })
+    const app = new Hono<{ Variables: { chainId: number } }>()
+    app.use('*', async (c, next) => {
+      c.set('chainId', 4217)
+      await next()
+    })
+    app.get('/', (c) => c.text(Cache.urlKey(c, schema)))
+
+    const left = await (await app.request('/?include=a%2Cb&include=c')).text()
+    const right = await (await app.request('/?include=a&include=b%2Cc')).text()
+
+    expect(left).toMatchInlineSnapshot(`"http://localhost/?chainId=4217&include=a%2Cb&include=c"`)
+    expect(right).toMatchInlineSnapshot(`"http://localhost/?chainId=4217&include=a&include=b%2Cc"`)
+  })
+})
+
 describe('response', () => {
   test('preserves rate-limit headers without caching them', async () => {
     await withCaches(async () => {

package/src/internal/Cache.ts

@@ -192,11 +192,23 @@ export function urlKey<
   schema extends z.ZodMiniType,
 >(c: Context<environment>, schema: schema): string {
   const url = new URL(c.req.url)
-  const query = schema.parse(Object.fromEntries(url.searchParams)) as Record<string, unknown>
+  const query = schema.parse(
+    Object.fromEntries(
+      Object.entries(c.req.queries()).map(([key, values]) => [
+        key,
+        values.length === 1 ? values[0] : values,
+      ]),
+    ),
+  ) as Record<string, unknown>
   url.search = ''
   if (query['chainId'] === undefined) url.searchParams.set('chainId', String(c.get('chainId')))
   for (const [key, value] of Object.entries(query)) {
     if (value === undefined) continue
+    if (Array.isArray(value)) {
+      for (const item of value)
+        url.searchParams.append(key, String(item as number | string | boolean))
+      continue
+    }
     url.searchParams.set(key, String(value as number | string | boolean))
   }
   return url.toString()

package/src/internal/EdgeCache.test.ts

@@ -130,6 +130,33 @@ describe('middleware', () => {
     expect(store.size).toMatchInlineSnapshot(`0`)
   })
 
+  test('strips payment headers from private responses before sharing them', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    const miss = await app.request('/private')
+    const hit = await app.request('/private')
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`1`)
+    expect(store.size).toMatchInlineSnapshot(`1`)
+    expect(miss.headers.get('payment-receipt')).toMatchInlineSnapshot(`"payer-specific"`)
+    expect(miss.headers.get('payment-session-snapshot')).toMatchInlineSnapshot(`"session-specific"`)
+    expect(hit.headers.get('payment-receipt')).toMatchInlineSnapshot(`null`)
+    expect(hit.headers.get('payment-session-snapshot')).toMatchInlineSnapshot(`null`)
+    expect(hit.headers.get('cache-control')).toMatchInlineSnapshot(
+      `"public, max-age=30, s-maxage=30"`,
+    )
+  })
+
+  test('does not cache responses marked `no-store`', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    await app.request('/no-store')
+    await app.request('/no-store')
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+    expect(store.size).toMatchInlineSnapshot(`0`)
+  })
+
   test('does not cache routes that did not opt in', async () => {
     const { app, store, downstreamCalls } = createApp()
 
@@ -271,6 +298,19 @@ function createApp(
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     return c.json({ ok: false }, 500)
   })
+  app.get('/private', cacheable, (c) => {
+    c.set('edgeCache', { maxAge: 30 })
+    c.header('Cache-Control', 'private, max-age=30')
+    c.header('Payment-Receipt', 'payer-specific')
+    c.header('Payment-Session-Snapshot', 'session-specific')
+    return c.json({ ok: true })
+  })
+  app.get('/no-store', cacheable, (c) => {
+    c.set('edgeCache', { maxAge: 30 })
+    c.header('Cache-Control', 'no-store')
+    c.header('Payment-Receipt', 'payer-specific')
+    return c.json({ ok: true })
+  })
   app.get('/binary', cacheable, (c) => {
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     // Bytes that are not valid UTF-8 (PNG signature) — corrupted if stored via

package/src/internal/EdgeCache.ts

@@ -33,12 +33,16 @@ const volatileHeaders = [
   'cf-cache-status',
   'content-encoding',
   'content-length',
-  'server-timing',
-  'set-cookie',
+  'payment-receipt',
+  'payment-session-snapshot',
   'ratelimit-limit',
   'ratelimit-remaining',
   'ratelimit-reset',
+  'ratelimit-scope',
+  'server-timing',
+  'set-cookie',
   'tempo-request-id',
+  'www-authenticate',
 ]
 
 /**
@@ -115,6 +119,8 @@ export function middleware<environment extends Env>(
     if (c.res.status < 200 || c.res.status >= 300) return
     if (c.res.headers.has('set-cookie')) return
     if (c.res.headers.get('content-type')?.includes('text/event-stream')) return
+    const responseDirectives = (c.res.headers.get('cache-control') ?? '').toLowerCase()
+    if (responseDirectives.includes('no-cache') || responseDirectives.includes('no-store')) return
 
     // Store a public, sanitized copy; the client still receives the original
     // (private, metered) response for this miss. Clone synchronously — the
@@ -247,7 +253,9 @@ function isTextual(contentType: string | null): boolean {
 function cacheKey(requestUrl: string) {
   const url = new URL(requestUrl)
   url.searchParams.sort()
-  return url.toString()
+  // Version the key so entries written before a sanitizer change cannot
+  // survive the deployment that changes the shared-cache boundary.
+  return `edge:v2:${url.toString()}`
 }
 
 function getWaitUntil(c: { executionCtx?: { waitUntil(promise: Promise<unknown>): void } }) {

package/src/internal/FundingQuotes.test.ts

@@ -83,9 +83,11 @@ describe('listQuotes', () => {
       },
     })
 
-    await expect(quotes).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[FundingQuotes.ProviderQuoteError]`,
-    )
+    const cause = await quotes.catch((error: unknown) => error)
+    expect(cause).toMatchObject({
+      failures: [{ cause: expect.any(Error), provider: 'relay' }],
+      name: 'FundingQuotes.ProviderQuoteError',
+    })
   })
 
   test('rejects successful provider responses without output amounts', async () => {
@@ -145,6 +147,32 @@ describe('listQuotes', () => {
 
     expect(seen?.cache.bypass).toBe(true)
   })
+
+  test('returns successful quotes when another provider fails', async () => {
+    const quotes = await FundingQuotes.listQuotes({
+      ...baseUsdcRequest,
+      adapters: {
+        across: {
+          async probeQuote() {
+            throw new Error('upstream unavailable')
+          },
+        },
+        relay: {
+          async probeQuote() {
+            return {
+              outputAmount: '990000',
+              sampledAt: '2026-01-01T00:00:00Z',
+              status: 'available',
+            }
+          },
+        },
+      },
+      provider: undefined,
+    })
+
+    expect(quotes).toHaveLength(1)
+    expect(quotes[0]?.provider.id).toBe('relay')
+  })
 })
 
 describe('listChains', () => {
@@ -153,6 +181,84 @@ describe('listChains', () => {
       'eip155:1',
       'eip155:8453',
       'eip155:56',
+      'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      'tron:0x2b6653dc',
+    ])
+  })
+
+  test('uses chain-specific token keys for non-EVM inventory', () => {
+    const chains = FundingQuotes.listChains()
+    expect(chains.find((chain) => chain.kind === 'solana')?.tokens[0]?.tokenKey).toBe(
+      'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    )
+    expect(chains.find((chain) => chain.kind === 'tron')?.tokens[0]?.tokenKey).toBe(
+      'tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+    )
+  })
+})
+
+describe('listQuoteCandidates', () => {
+  test('round-trips the advertised Solana chain and token ids', () => {
+    const [candidate] = FundingQuotes.listQuoteCandidates({
+      provider: 'rhino',
+      sourceAmount: '1000000',
+      sourceAmountUnits: 'baseUnits',
+      sourceChain: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      sourceToken:
+        'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    })
+
+    expect(candidate?.id).toBe('solana-usdc-tempo-usdce-rhino')
+  })
+
+  test('keeps non-EVM token identifiers case-sensitive', () => {
+    expect(
+      FundingQuotes.listQuoteCandidates({
+        provider: 'rhino',
+        sourceAmount: '1000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'solana',
+        sourceToken: 'epjfwdd5aufqssqem2qn1xzybapc8g4wegkzwytdt1v',
+      }),
+    ).toEqual([])
+  })
+
+  test('resolves the complete Tron token key', () => {
+    const [candidate] = FundingQuotes.listQuoteCandidates({
+      destinationToken: 'USDT0',
+      provider: 'rhino',
+      sourceAmount: '1000000',
+      sourceAmountUnits: 'baseUnits',
+      sourceChain: 'tron:0x2b6653dc',
+      sourceToken: 'tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+    })
+
+    expect(candidate?.id).toBe('tron-usdt-tempo-usdt0-rhino')
+  })
+
+  test('selects proven Squid stablecoin corridors', () => {
+    const candidates = [
+      FundingQuotes.listQuoteCandidates({
+        destinationToken: 'USDC.e',
+        provider: 'squid',
+        sourceAmount: '1000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'base',
+        sourceToken: 'USDC',
+      })[0],
+      FundingQuotes.listQuoteCandidates({
+        destinationToken: 'USDT0',
+        provider: 'squid',
+        sourceAmount: '1000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'ethereum',
+        sourceToken: 'USDT',
+      })[0],
+    ]
+
+    expect(candidates.map((candidate) => candidate?.id)).toEqual([
+      'base-usdc-tempo-usdce-squid',
+      'ethereum-usdt-tempo-usdt0-squid',
     ])
   })
 })
@@ -161,6 +267,13 @@ describe('listProviders', () => {
   test('reports deployment configuration', () => {
     expect(FundingQuotes.listProviders()).toMatchInlineSnapshot(`
       [
+        {
+          "id": "across",
+          "kind": "intentBridge",
+          "name": "Across",
+          "requiresApiKey": true,
+          "status": "unconfigured",
+        },
         {
           "id": "relay",
           "kind": "solverNetwork",
@@ -168,6 +281,20 @@ describe('listProviders', () => {
           "requiresApiKey": false,
           "status": "unconfigured",
         },
+        {
+          "id": "rhino",
+          "kind": "bridge",
+          "name": "Rhino",
+          "requiresApiKey": false,
+          "status": "unconfigured",
+        },
+        {
+          "id": "squid",
+          "kind": "solverNetwork",
+          "name": "Squid",
+          "requiresApiKey": true,
+          "status": "unconfigured",
+        },
       ]
     `)
   })

package/src/internal/FundingQuotes.ts

@@ -18,6 +18,7 @@ const sourceChains = [
     kind: 'evm',
     name: 'Ethereum',
     providerIds: {
+      across: '1',
       relay: '1',
     },
     slug: 'ethereum',
@@ -71,7 +72,9 @@ const sourceChains = [
     kind: 'evm',
     name: 'Base',
     providerIds: {
+      across: '8453',
       relay: '8453',
+      rhino: 'BASE',
     },
     slug: 'base',
     tokens: [
@@ -108,6 +111,7 @@ const sourceChains = [
     kind: 'evm',
     name: 'BNB Smart Chain',
     providerIds: {
+      across: '56',
       relay: '56',
     },
     slug: 'bnb',
@@ -130,6 +134,48 @@ const sourceChains = [
       },
     ],
   },
+  {
+    addressFormat: 'base58',
+    aliases: ['solana', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'],
+    id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+    kind: 'solana',
+    name: 'Solana',
+    providerIds: {
+      rhino: 'SOLANA',
+    },
+    slug: 'solana',
+    tokens: [
+      {
+        address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        coingeckoId: 'usd-coin',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'SPL',
+        symbol: 'USDC',
+      },
+    ],
+  },
+  {
+    addressFormat: 'base58check',
+    aliases: ['tron', 'tron:0x2b6653dc'],
+    id: 'tron:0x2b6653dc',
+    kind: 'tron',
+    name: 'Tron',
+    providerIds: {
+      rhino: 'TRON',
+    },
+    slug: 'tron',
+    tokens: [
+      {
+        address: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'TRC-20',
+        symbol: 'USDT',
+      },
+    ],
+  },
 ] as const
 
 /** Tempo destination tokens supported by funding quote providers. */
@@ -178,6 +224,13 @@ const destinationTokens = [
 
 /** Providers supported by live funding quotes. */
 const providers = [
+  {
+    id: 'across',
+    kind: 'intentBridge',
+    name: 'Across',
+    requiresApiKey: true,
+    status: 'unconfigured',
+  },
   {
     id: 'relay',
     kind: 'solverNetwork',
@@ -185,6 +238,20 @@ const providers = [
     requiresApiKey: false,
     status: 'unconfigured',
   },
+  {
+    id: 'rhino',
+    kind: 'bridge',
+    name: 'Rhino',
+    requiresApiKey: false,
+    status: 'unconfigured',
+  },
+  {
+    id: 'squid',
+    kind: 'solverNetwork',
+    name: 'Squid',
+    requiresApiKey: true,
+    status: 'unconfigured',
+  },
 ] as const
 
 type TokenInput = (typeof sourceChains)[number]['tokens'][number]
@@ -262,6 +329,8 @@ export type QuoteProbeInput = {
 
 /** Quote probe data returned by a provider adapter. */
 export type QuoteProbeResult = {
+  /** Timestamp after which the provider quote is no longer valid. */
+  expiresAt?: string | undefined
   /** Slippage-adjusted minimum destination amount in base units. */
   minimumOutputAmount?: string | undefined
   /** Expected destination amount in base units. */
@@ -294,9 +363,22 @@ export type ProviderAdapter = {
 /** Provider adapter registry, keyed by provider id. */
 export type ProviderAdapters = Partial<Record<ProviderId, ProviderAdapter>>
 
+/** A provider adapter failure retained for bounded request diagnostics. */
+export type ProviderFailure = {
+  /** Error thrown by the provider boundary. */
+  cause: unknown
+  /** Provider that failed. */
+  provider: ProviderId
+}
+
 /** Curated provider support rows used to select live quote probes. */
 const inventory: readonly InventoryEntry[] = [
+  { destinationToken: 'usdce', provider: 'across', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
   { destinationToken: 'usdce', provider: 'relay', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC', 'USDT'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'rhino', sourceChains: ['base', 'solana'], sourceTokens: ['USDC'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'squid', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
+  { destinationToken: 'usdt0', provider: 'rhino', sourceChains: ['tron'], sourceTokens: ['USDT'] }, // prettier-ignore
+  { destinationToken: 'usdt0', provider: 'squid', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDT'] }, // prettier-ignore
 ]
 
 type InventoryEntry = {
@@ -367,8 +449,12 @@ export async function listQuotes(options: listQuotes.Options) {
   const quotes = results.flatMap((result) =>
     result.status === 'fulfilled' && result.value ? [result.value] : [],
   )
-  if (quotes.length === 0 && results.some((result) => result.status === 'rejected'))
-    throw new ProviderQuoteError()
+  const failures = results.flatMap((result, index) =>
+    result.status === 'rejected'
+      ? [{ cause: result.reason, provider: candidates[index]!.provider.id }]
+      : [],
+  )
+  if (quotes.length === 0 && failures.length > 0) throw new ProviderQuoteError(failures)
   return quotes
 }
 
@@ -439,8 +525,13 @@ export declare namespace listQuotes {
 /** Source amount unit accepted by the funding quote request. */
 export type SourceAmountUnits = 'baseUnits' | 'decimal'
 
-function tokenKey(chain: { id: string }, token: TokenInput | DestinationTokenInput) {
-  return `${chain.id}/erc20:${token.address}`
+function tokenKey(chain: { id: string; kind: string }, token: TokenInput | DestinationTokenInput) {
+  const namespace = (() => {
+    if (chain.kind === 'solana') return 'token'
+    if (chain.kind === 'tron') return 'trc20'
+    return 'erc20'
+  })()
+  return `${chain.id}/${namespace}:${token.address}`
 }
 
 function decimalFromBaseUnits(baseUnits: string, decimals: number) {
@@ -485,7 +576,7 @@ async function quoteCandidate(
     quote.outputAmount === undefined ||
     quote.outputAmount === null
   )
-    throw new ProviderQuoteError()
+    throw new InvalidProviderQuoteError()
   return formatFundingQuote(candidate, {
     ...quote,
     outputAmount: quote.outputAmount,
@@ -595,6 +686,7 @@ function formatFundingQuote(candidate: QuoteCandidate, quote: SuccessfulQuotePro
       tier: quote.status === 'thin' ? ('thin' as const) : ('liquid' as const),
     },
     quote: {
+      ...(quote.expiresAt !== undefined ? { expiresAt: quote.expiresAt } : {}),
       inputAmount: candidate.sourceAmount.amount,
       ...(quote.minimumOutputAmount !== undefined
         ? { minimumOutputAmount: quote.minimumOutputAmount }
@@ -685,10 +777,13 @@ function matchesTokenIdentifier(
 }
 
 function resolveSourceChain(input: string) {
+  const trimmed = input.trim()
   const normalized = normalizeInput(input)
   const chain = sourceChains.find(
     (candidate) =>
-      candidate.id === normalized || (candidate.aliases as readonly string[]).includes(normalized),
+      candidate.id === trimmed ||
+      candidate.slug === normalized ||
+      (candidate.kind === 'evm' && (candidate.aliases as readonly string[]).includes(normalized)),
   )
   if (!chain) throw new UnsupportedSourceChainError()
   return chain
@@ -722,6 +817,14 @@ export class ProviderAdapterTimeoutError extends Error {
 /** Error thrown when every matching provider fails to produce a quote. */
 export class ProviderQuoteError extends Error {
   override name = 'FundingQuotes.ProviderQuoteError'
+
+  /** Provider failures that prevented a successful quote. */
+  failures: readonly ProviderFailure[]
+
+  constructor(failures: readonly ProviderFailure[]) {
+    super()
+    this.failures = failures
+  }
 }
 
 /** Error thrown when the caller filters to an unknown provider. */
@@ -733,3 +836,7 @@ export class UnsupportedProviderError extends Error {
 export class UnsupportedSourceChainError extends Error {
   override name = 'FundingQuotes.UnsupportedSourceChainError'
 }
+
+class InvalidProviderQuoteError extends Error {
+  override name = 'FundingQuotes.InvalidProviderQuoteError'
+}

package/src/internal/Log.ts

@@ -12,6 +12,8 @@ export type Variables = {
   errorCode?: string | undefined
   /** Redacted provider failure details recorded by an upstream adapter. */
   providerFailure?: Entry['provider'] | undefined
+  /** Redacted provider failures when multiple upstream adapters fail. */
+  providerFailures?: Entry['providerFailures'] | undefined
 }
 
 /** Hono environment shape used by the request logger. */
@@ -28,6 +30,20 @@ export type Environment = {
 /** Log level, derived from the response status. */
 export type Level = 'error' | 'info' | 'warn'
 
+/** Redacted upstream provider failure details. */
+export type ProviderFailure = {
+  /** Stable provider error code, when one is safe to retain. */
+  code?: string | undefined
+  /** Failure boundary that rejected the provider request. */
+  failure: 'http' | 'network' | 'payload' | 'timeout' | 'unknown'
+  /** Provider identifier. */
+  id: string
+  /** Provider operation identifier. */
+  operation: string
+  /** Upstream HTTP status, when a response was received. */
+  status?: number | undefined
+}
+
 /** One canonical request log entry. */
 export type Entry = {
   /** `'hit'` when the edge response cache served the request without reaching the origin handlers. */
@@ -64,20 +80,9 @@ export type Entry = {
       }
     | undefined
   /** Redacted upstream provider failure details, when an adapter request fails. */
-  provider?:
-    | {
-        /** Stable provider error code, when one is safe to retain. */
-        code?: string | undefined
-        /** Failure boundary that rejected the provider request. */
-        failure: 'http' | 'network' | 'payload' | 'unknown'
-        /** Provider identifier. */
-        id: string
-        /** Provider operation identifier. */
-        operation: string
-        /** Upstream HTTP status, when a response was received. */
-        status?: number | undefined
-      }
-    | undefined
+  provider?: ProviderFailure | undefined
+  /** Redacted failures for every provider when multiple adapters fail. */
+  providerFailures?: readonly ProviderFailure[] | undefined
   /** Raw query string (no leading `?`) with API-key tokens redacted, when present. */
   query?: string | undefined
   /** Rate limit state from the `RateLimit-*` response headers, when enforced. */
@@ -136,6 +141,7 @@ export function middleware<environment extends Environment = Environment>(
     const principal = c.get('principal' as never) as Auth.Principal | undefined
     const errorCode = c.get('errorCode' as never) as string | undefined
     const provider = c.get('providerFailure' as never) as Entry['provider']
+    const providerFailures = c.get('providerFailures' as never) as Entry['providerFailures']
 
     // The `request` total metric duplicates `duration` (measured here, one
     // layer further out), so only operation timings are kept.
@@ -186,6 +192,7 @@ export function middleware<environment extends Environment = Environment>(
             },
           }),
       ...(provider === undefined ? {} : { provider }),
+      ...(providerFailures === undefined ? {} : { providerFailures }),
       ...(query ? { query } : {}),
       ...(rateLimit === undefined ? {} : { rateLimit }),
       requestId: c.get('requestId' as never) as string,