tapimo 0.11.0 → 0.12.0

package/src/db/tables/webhookDeliveries.ts

@@ -225,6 +225,10 @@ export async function get(
   return row ? toDelivery(row) : null
 }
 
+// Per-statement delete bound: prune runs every minute, so a backlog drains in
+// a few ticks instead of one unbounded DELETE churning the origin.
+const pruneBatchLimit = 50_000
+
 /**
  * Deletes deliveries past their retention deadline. Called best-effort from
  * the poller tick.
@@ -236,7 +240,16 @@ export async function get(
 export async function pruneExpired(db: Db.Db, now: string): Promise<number> {
   const result = await db.kysely
     .deleteFrom('webhook_deliveries')
+    // Repeated on the outer delete: the row recheck under concurrency re-runs
+    // only this predicate, so a row renewed mid-statement survives.
     .where('expiresAt', '<=', now)
+    .where('id', 'in', (eb) =>
+      eb
+        .selectFrom('webhook_deliveries')
+        .select('id')
+        .where('expiresAt', '<=', now)
+        .limit(pruneBatchLimit),
+    )
     .executeTakeFirst()
   return Number(result.numDeletedRows)
 }

package/src/db/tables/webhookQueueCompletions.ts

@@ -0,0 +1,55 @@
+import type * as Webhooks from '../../internal/Webhooks.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `webhook_queue_completions` table, derived from `Schema.WebhookQueueCompletion`. */
+export type Table = db_Schema.WebhookQueueCompletion
+
+/** A terminal delivery-obligation outcome. */
+export type TerminalStatus = db_Schema.WebhookQueueCompletion['status']
+
+/**
+ * Reads the unexpired completion for a reference, if any. Rows are written by
+ * the queue-event terminal transition and only ever read for dedupe.
+ */
+export async function get(
+  db: Db.Db,
+  reference: Webhooks.QueueReference,
+  now: string,
+): Promise<Table | null> {
+  return (
+    (await db.kysely
+      .selectFrom('webhook_queue_completions')
+      .selectAll()
+      .where('eventId', '=', reference.eventId)
+      .where('subscriptionId', '=', reference.subscriptionId)
+      .where('expiresAt', '>', now)
+      .executeTakeFirst()) ?? null
+  )
+}
+
+// Per-statement delete bound: prune runs every minute, so a backlog drains in
+// a few ticks instead of one unbounded DELETE churning the origin.
+const pruneBatchLimit = 50_000
+
+/** Deletes expired completions, bounded per call; expiry is filtered at query time, so pruning is space-only. */
+export async function pruneExpired(db: Db.Db, now: string): Promise<number> {
+  const result = await db.kysely
+    .deleteFrom('webhook_queue_completions')
+    // Repeated on the outer delete: the row recheck under concurrency re-runs
+    // only this predicate, so a completion renewed mid-statement survives.
+    .where('expiresAt', '<=', now)
+    .where(({ eb, refTuple, selectFrom }) =>
+      eb(
+        refTuple('subscriptionId', 'eventId'),
+        'in',
+        selectFrom('webhook_queue_completions')
+          .select(['subscriptionId', 'eventId'])
+          .where('expiresAt', '<=', now)
+          .limit(pruneBatchLimit)
+          .$asTuple('subscriptionId', 'eventId'),
+      ),
+    )
+    .executeTakeFirst()
+  return Number(result.numDeletedRows)
+}

package/src/db/tables/webhookQueueEvents.ts

@@ -2,17 +2,20 @@ import { type ExpressionBuilder, type Generated, type Insertable, type Selectabl
 
 import type * as Webhooks from '../../internal/Webhooks.js'
 import type * as Db from '../Db.js'
+import * as WebhookQueueCompletions from './webhookQueueCompletions.js'
 import type * as db_Schema from '../Schema.js'
 
 /** Columns of the `webhook_queue_events` table, derived from `Schema.WebhookQueueEvent`. */
 export type Table = Omit<
   db_Schema.WebhookQueueEvent,
-  'attemptCount' | 'attemptingAt' | 'nextAttemptAt' | 'observedAt' | 'status'
+  'attemptCount' | 'attemptingAt' | 'expiresAt' | 'nextAttemptAt' | 'observedAt' | 'status'
 > & {
   /** Delivery attempts claimed so far; database default 0. */
   attemptCount: Generated<number>
   /** ISO timestamp of the current claim; database default null. */
   attemptingAt: Generated<string | null>
+  /** Legacy dedupe deadline; unwritten since completions took over. */
+  expiresAt: Generated<string | null>
   /** ISO retry due time; database default null (due immediately). */
   nextAttemptAt: Generated<string | null>
   /** ISO head-observation stamp; database default null (replays carry none). */
@@ -24,12 +27,9 @@ export type Table = Omit<
 /** A stored webhook Queue event. */
 export type Record = Selectable<Table>
 
-/** A terminal delivery-obligation outcome. */
-export type TerminalStatus = Exclude<db_Schema.WebhookQueueEvent['status'], 'pending'>
-
 /**
- * Reads one pending envelope. Terminal rows read as absent so no consumer
- * can redeliver a completed obligation or disturb its dedupe row.
+ * Reads one pending envelope. The status filter only ever excludes rows
+ * completed before the completions split; completions now leave the table.
  */
 export async function get(
   db: Db.Db,
@@ -47,42 +47,56 @@ export async function get(
 }
 
 /**
- * Stages envelopes as fresh obligations. Pending conflicts keep their first
- * envelope and backoff position; terminal conflicts inside the dedupe window
- * suppress the replay; terminal conflicts past it are replaced, so an expired
- * dedupe row pruning has not yet reclaimed never blocks a replay.
+ * Stages envelopes as fresh obligations. Unexpired completions and any
+ * existing row suppress the replay; a replay stages only when neither exists,
+ * which a completion past its dedupe window guarantees for completed work.
  */
 export async function ensure(db: Db.Db, rows: readonly Insertable<Table>[]): Promise<number> {
   if (rows.length === 0) return 0
+  const values = sql.join(
+    rows.map(
+      (row) =>
+        sql`(${row.subscriptionId}::text, ${row.eventId}::text, ${JSON.stringify(row.envelope)}::jsonb, ${row.createdAt}::text, ${row.nextAttemptAt ?? null}::text, ${row.observedAt ?? null}::text)`,
+    ),
+  )
+  // The VALUES source is raw because kysely has no table constructor for it,
+  // but both real tables stay in the builder so WithSchemaPlugin qualifies
+  // them (previews isolate by schema; raw identifiers would escape it). The
+  // completion check must ride the insert: a separate read would let a
+  // completion commit between the statements and re-stage just-finished work.
+  // `column1..6` are Postgres's default VALUES names, in the row order above;
+  // the window comparison uses each row's own staging time, not a shared clock.
+  // Conflicts only ever hit pending rows (or pre-split terminal rows during
+  // the drain), and both suppress the replay; a legitimate post-expiry replay
+  // meets no conflict because its completed row was deleted.
   const result = await db.kysely
     .insertInto('webhook_queue_events')
-    .values([...rows])
-    .onConflict((oc) =>
-      oc
-        .columns(['subscriptionId', 'eventId'])
-        .doUpdateSet((eb) => ({
-          attemptCount: 0,
-          attemptingAt: null,
-          createdAt: eb.ref('excluded.createdAt'),
-          envelope: eb.ref('excluded.envelope'),
-          expiresAt: eb.ref('excluded.expiresAt'),
-          nextAttemptAt: eb.ref('excluded.nextAttemptAt'),
-          // Refreshed with the rest: a replacement keeping the replaced row's
-          // stamp would measure observation-to-attempt from an observation
-          // that belongs to a delivery made days earlier.
-          observedAt: eb.ref('excluded.observedAt'),
-          status: 'pending',
-        }))
-        .where((eb) =>
-          eb.and([
-            eb('webhook_queue_events.status', '!=', 'pending'),
-            eb('webhook_queue_events.expiresAt', '<=', eb.ref('excluded.createdAt')),
-          ]),
+    .columns(['subscriptionId', 'eventId', 'envelope', 'createdAt', 'nextAttemptAt', 'observedAt'])
+    .expression((eb) =>
+      eb
+        .selectFrom(sql`(VALUES ${values})`.as('v'))
+        .select([
+          sql`v.column1`.as('subscriptionId'),
+          sql`v.column2`.as('eventId'),
+          sql`v.column3`.as('envelope'),
+          sql`v.column4`.as('createdAt'),
+          sql`v.column5`.as('nextAttemptAt'),
+          sql`v.column6`.as('observedAt'),
+        ])
+        .where(({ exists, not, selectFrom }) =>
+          not(
+            exists(
+              selectFrom('webhook_queue_completions')
+                .select('eventId')
+                .where('subscriptionId', '=', sql<string>`v.column1`)
+                .where('eventId', '=', sql<string>`v.column2`)
+                .where('expiresAt', '>', sql<string>`v.column4`),
+            ),
+          ),
         ),
     )
+    .onConflict((oc) => oc.columns(['subscriptionId', 'eventId']).doNothing())
     .executeTakeFirst()
-  // The command tag counts inserted rows plus replaced expired rows; live
-  // conflicts fall out of the conditional update and are not counted.
   return Number(result.numInsertedOrUpdatedRows ?? 0n)
 }
 
@@ -114,13 +128,23 @@ export async function claim(
     .executeTakeFirst()
   if (claimed) return { record: claimed, type: 'claimed' }
 
+  // Queue first, completions second: a complete() landing between the reads
+  // then still surfaces its completion, so a finished obligation never reads
+  // as missing, the one claim outcome alerts treat as a fault.
   const existing = await db.kysely
     .selectFrom('webhook_queue_events')
     .select(['attemptingAt', 'nextAttemptAt', 'status'])
     .where('subscriptionId', '=', reference.subscriptionId)
     .where('eventId', '=', reference.eventId)
     .executeTakeFirst()
-  if (!existing) return { type: 'missing' }
+  if (!existing) {
+    // An unexpired completion reads as terminal so claim-outcome metrics keep
+    // their meaning; an expired one reads as missing, like a pruned row.
+    const completed = await WebhookQueueCompletions.get(db, reference, options.now)
+    if (completed) return { status: completed.status, type: 'terminal' }
+    return { type: 'missing' }
+  }
+  // Reachable only for rows completed before the completions split.
   if (existing.status !== 'pending') return { status: existing.status, type: 'terminal' }
   if (existing.attemptingAt !== null && existing.attemptingAt > options.staleBefore)
     return { type: 'attempting' }
@@ -142,12 +166,12 @@ export declare namespace claim {
     | { record: Record; type: 'claimed' }
     | { type: 'missing' }
     | { nextAttemptAt: string | null; type: 'scheduled' }
-    | { status: TerminalStatus; type: 'terminal' }
+    | { status: WebhookQueueCompletions.TerminalStatus; type: 'terminal' }
 }
 
 /**
- * Marks a claimed obligation terminal, starting its dedupe retention window;
- * pending rows never expire, so this stamp is the only expiry that matters.
+ * Marks a claimed obligation terminal: one atomic statement deletes the queue
+ * row and writes the insert-only completion that starts the dedupe window.
  * The `attemptingAt` predicate fences stale claimants.
  */
 export async function complete(
@@ -156,14 +180,38 @@ export async function complete(
   options: complete.Options,
 ): Promise<boolean> {
   const result = await db.kysely
-    .updateTable('webhook_queue_events')
-    .set({ attemptingAt: null, expiresAt: options.expiresAt, status: options.status })
-    .where('subscriptionId', '=', reference.subscriptionId)
-    .where('eventId', '=', reference.eventId)
-    .where('status', '=', 'pending')
-    .where('attemptingAt', '=', options.claimedAt)
+    .with('done', (qb) =>
+      qb
+        .deleteFrom('webhook_queue_events')
+        .where('subscriptionId', '=', reference.subscriptionId)
+        .where('eventId', '=', reference.eventId)
+        .where('status', '=', 'pending')
+        .where('attemptingAt', '=', options.claimedAt)
+        .returning(['subscriptionId', 'eventId']),
+    )
+    .insertInto('webhook_queue_completions')
+    .columns(['subscriptionId', 'eventId', 'status', 'expiresAt'])
+    .expression((eb) =>
+      eb
+        .selectFrom('done')
+        .select((s) => [
+          'subscriptionId',
+          'eventId',
+          s.val(options.status).as('status'),
+          s.val(options.expiresAt).as('expiresAt'),
+        ]),
+    )
+    // Re-completing a replayed obligation: the latest delivery outcome wins
+    // and retention restarts, matching pre-split replay semantics; doNothing
+    // would also report zero rows and fail a fence that won.
+    .onConflict((oc) =>
+      oc.columns(['subscriptionId', 'eventId']).doUpdateSet((eb) => ({
+        expiresAt: eb.ref('excluded.expiresAt'),
+        status: eb.ref('excluded.status'),
+      })),
+    )
     .executeTakeFirst()
-  return result.numUpdatedRows === 1n
+  return result.numInsertedOrUpdatedRows === 1n
 }
 
 export declare namespace complete {
@@ -171,10 +219,10 @@ export declare namespace complete {
   type Options = {
     /** Claim marker returned by {@link claim}; fences stale claimants. */
     claimedAt: string
-    /** Replacement ISO retention deadline for the terminal dedupe row. */
+    /** ISO retention deadline for the dedupe completion. */
     expiresAt: string
     /** Terminal outcome. */
-    status: TerminalStatus
+    status: WebhookQueueCompletions.TerminalStatus
   }
 }
 
@@ -275,17 +323,3 @@ export declare namespace pending {
     oldestDueAt: string | null
   }
 }
-
-/**
- * Deletes terminal dedupe rows past their retention deadline. Pending rows
- * never expire: owed work drains only through terminal transitions
- * (delivery, permanent failure, or the skip after auto-disable).
- */
-export async function pruneExpired(db: Db.Db, now: string): Promise<number> {
-  const result = await db.kysely
-    .deleteFrom('webhook_queue_events')
-    .where('expiresAt', '<=', now)
-    .where('status', '!=', 'pending')
-    .executeTakeFirst()
-  return Number(result.numDeletedRows)
-}

package/src/db/tables/webhookSubscriptions.ts

@@ -447,37 +447,57 @@ export async function getCursor(db: Db.Db, id: string): Promise<string | null> {
 
 /**
  * Records a successful delivery: resets the consecutive-failure counter and
- * stamps `lastDeliveryAt`.
+ * stamps `lastDeliveryAt`. Skipped when neither field would move, so
+ * deliveries stop contending on the row's lock.
  *
  * @param db - The database.
  * @param id - The subscription id (`wh_…`).
- * @param now - Delivery timestamp (ISO).
- * @returns The updated subscription, or `undefined` when the row is absent.
+ * @param options - Delivery timestamp and stamp-staleness bound.
+ * @returns The updated subscription, or `undefined` when nothing was written.
  */
 export async function recordSuccess(
   db: Db.Db,
   id: string,
-  now: string,
+  options: recordSuccess.Options,
 ): Promise<Webhooks.Subscription | undefined> {
+  const { now, staleBefore } = options
   const row = await db.kysely
     .updateTable('webhook_subscriptions')
     .set({ failureCount: 0, lastDeliveryAt: now, updatedAt: now })
     .where('id', '=', id)
+    .where((eb) =>
+      eb.or([
+        eb('failureCount', '>', 0),
+        eb('lastDeliveryAt', 'is', null),
+        eb('lastDeliveryAt', '<', staleBefore),
+      ]),
+    )
     .returningAll()
     .executeTakeFirst()
   return row ? toSubscription(row) : undefined
 }
 
+export declare namespace recordSuccess {
+  /** Clock bounds for one success record. */
+  type Options = {
+    /** Delivery timestamp (ISO). */
+    now: string
+    /** Rewrite the stamp only when it predates this (ISO). */
+    staleBefore: string
+  }
+}
+
 /**
  * Records a failed delivery: atomically increments the consecutive-failure
  * counter and disables the subscription once it reaches `maxFailures` (raw
  * fragments use storage column names — they bypass the camelCase mapping).
+ * Skipped once disabled at the cap, when nothing would move.
  *
  * @param db - The database.
  * @param id - The subscription id (`wh_…`).
  * @param maxFailures - Consecutive failures before auto-disabling.
  * @param now - Failure timestamp (ISO).
- * @returns The updated subscription, or `undefined` when the row is absent.
+ * @returns The updated subscription, or `undefined` when nothing was written.
  */
 export async function recordFailure(
   db: Db.Db,
@@ -493,11 +513,19 @@ export async function recordFailure(
       updatedAt: now,
     })
     .where('id', '=', id)
+    // In-flight failures race the disable and would queue on the row lock. A
+    // re-enabled subscription keeps its capped counter; the status arm lets
+    // its next failure re-disable it.
+    .where((eb) => eb.or([eb('failureCount', '<', maxFailures), eb('status', '!=', 'disabled')]))
     .returningAll()
     .executeTakeFirst()
   return row ? toSubscription(row) : undefined
 }
 
+// Smaller than the ledger-table bounds: each subscription delete cascades
+// into deliveries, queue events, and completions, fanning the statement out.
+const pruneBatchLimit = 1_000
+
 /**
  * Deletes expired subscriptions (their delivery rows cascade). Called
  * best-effort on a schedule.
@@ -507,10 +535,21 @@ export async function recordFailure(
  * @returns The number of rows deleted.
  */
 export async function pruneExpired(db: Db.Db, now: string): Promise<number> {
+  // Bounded like the ledger prunes: this delete cascades into deliveries,
+  // queue events, and completions, so it fans out the widest of the four.
   const result = await db.kysely
     .deleteFrom('webhook_subscriptions')
-    .where('expiresAt', 'is not', null)
+    // Repeated on the outer delete: the row recheck under concurrency re-runs
+    // only this predicate, so a subscription renewed mid-statement survives.
     .where('expiresAt', '<=', now)
+    .where('id', 'in', (eb) =>
+      eb
+        .selectFrom('webhook_subscriptions')
+        .select('id')
+        .where('expiresAt', 'is not', null)
+        .where('expiresAt', '<=', now)
+        .limit(pruneBatchLimit),
+    )
     .executeTakeFirst()
   return Number(result.numDeletedRows)
 }

package/src/internal/Auth.ts

@@ -587,11 +587,21 @@ export function middleware<
     const overrides = options.overrides as
       | Record<string, PolicyOverride | false | undefined>
       | undefined
-    const configuredOverride = overrides?.[key]
+    const routePolicies = policies(c)
+    const configuredOverride = (() => {
+      const configured = overrides?.[key]
+      if (configured !== undefined) return configured
+      const inheritedMethod = routePolicies.find(
+        (policy) => policy.inheritOverridesFrom,
+      )?.inheritOverridesFrom
+      if (inheritedMethod === undefined) return undefined
+      const inheritedKey = `${inheritedMethod.toUpperCase()} ${key.slice(key.indexOf(' ') + 1)}`
+      return overrides?.[inheritedKey]
+    })()
     const routeOverride =
       management && configuredOverride ? { mpp: configuredOverride.mpp } : configuredOverride
     const endpointPolicy = bindMppScope(
-      resolvePolicy(base, defaults, [...policies(c), routeOverride], description),
+      resolvePolicy(base, defaults, [...routePolicies, routeOverride], description),
       scope,
     )
     if (!endpointPolicy) return next()
@@ -1000,12 +1010,20 @@ export declare namespace install {
 }
 
 /** Creates route middleware that contributes an auth policy override. */
-export function policy(options: PolicyOverride): MiddlewareHandler {
+export function policy(options: policy.Options): MiddlewareHandler {
   const middleware = createMiddleware((_, next) => next()) as MiddlewareHandler & PolicyHandler
   middleware[policySymbol] = options
   return middleware
 }
 
+export declare namespace policy {
+  /** Route policy plus metadata for compatibility aliases. */
+  type Options = PolicyOverride & {
+    /** HTTP method whose configured override this route inherits when its own is absent. */
+    inheritOverridesFrom?: string | undefined
+  }
+}
+
 /** Adds management POSTs for OpenAPI-registered MPP GET resources. */
 export function installMppManagementRoutes(
   app: Hono<any, any>,
@@ -1106,7 +1124,7 @@ type OpenApiRoute = {
 }
 
 type PolicyHandler = {
-  [policySymbol]?: PolicyOverride | undefined
+  [policySymbol]?: policy.Options | undefined
 }
 
 type MppManagementHandler = {
@@ -1283,7 +1301,7 @@ function policies(c: hono_Context) {
   return matchedRoutes(c)
     .slice(c.req.routeIndex + 1)
     .map(policyFromRoute)
-    .filter((policy): policy is PolicyOverride => policy !== undefined)
+    .filter((routePolicy): routePolicy is policy.Options => routePolicy !== undefined)
 }
 
 function openApiSpec(route: RouterRoute) {

package/src/internal/Cache.ts

@@ -58,10 +58,8 @@ export function response<environment extends Env>(
 ): MiddlewareHandler<environment> {
   const defaultCacheControl = options.cacheControl ?? policies.default
   const vary = options.vary ?? ['Accept-Encoding', 'Authorization', 'Tempo-API-Key', 'X-API-Key']
-  // hono/cache suffixes its key with `::<directive>=<value>` for every
-  // configured vary directive (trimmed, lowercased, deduped). Mirror that
-  // normalization so the `no-cache` purge below deletes exactly the entry the
-  // wrapped middleware reads — drift here would make refreshes silently miss.
+  // Mirror hono/cache's vary normalization so the `no-cache` purge below
+  // deletes exactly the entry the wrapped middleware reads.
   const varyKeyDirectives = [
     ...new Set(vary.map((name) => name.trim().toLowerCase()).filter(Boolean)),
   ]
@@ -95,10 +93,19 @@ export function response<environment extends Env>(
     type Caches = { open(name: string): Promise<{ delete(key: string): Promise<unknown> }> }
     const caches = (globalThis as { caches?: Caches }).caches
     if (noCache && !noStore && caches) {
-      let key = await options.key(c)
+      // hono/cache 4.13 wraps generated keys in a canonical URL containing the
+      // request method and vary values. Keep this in sync with its
+      // `createCacheKey` so refreshes remove the stored GET response.
+      const key = await options.key(c)
+      const url = new URL('/.hono/cache', c.req.url)
+      url.searchParams.append('__hono_cache_key', key.split('#', 1)[0] ?? key)
+      url.searchParams.append('__hono_cache_method', c.req.method)
       for (const name of varyKeyDirectives)
-        key += `::${name}=${encodeURIComponent(c.req.raw.headers.get(name) ?? '')}`
-      await (await caches.open(options.name)).delete(key)
+        url.searchParams.append(
+          '__hono_cache_vary',
+          JSON.stringify([name, c.req.raw.headers.get(name) ?? '']),
+        )
+      await (await caches.open(options.name)).delete(url.href)
     }
 
     // Run ETag inside Hono's cache miss path so fresh responses are hashed

package/src/internal/EarnVaults.capabilities.test.ts

@@ -0,0 +1,33 @@
+import * as EarnVaults from './EarnVaults.js'
+
+describe('addZoneRouteCapabilities', () => {
+  test('adds private routing and router swaps', () => {
+    expect(
+      EarnVaults.addZoneRouteCapabilities({
+        asyncRedeem: false,
+        boundedRedeem: true,
+        deposit: true,
+        exactWithdraw: true,
+        inKindDeposit: true,
+        privateRouting: false,
+        redeem: true,
+        routerSwaps: false,
+      }),
+    ).toMatchObject({ privateRouting: true, routerSwaps: true })
+  })
+})
+
+describe('deriveZoneId', () => {
+  test('derives IDs from mainnet and testnet Zone chain schemes', () => {
+    expect([
+      EarnVaults.deriveZoneId(421_700_006),
+      EarnVaults.deriveZoneId(1_424_310_001),
+    ]).toStrictEqual([6, 1])
+  })
+
+  test('rejects a source chain ID', () => {
+    expect(() => EarnVaults.deriveZoneId(31_318)).toThrowErrorMatchingInlineSnapshot(
+      `[EarnVaults.InvalidRegistryError: Chain 31318 does not use a supported Zone chain-ID scheme.]`,
+    )
+  })
+})

package/src/internal/EarnVaults.test.ts

@@ -1,6 +1,7 @@
 import { parseAbi } from 'viem'
 import { tempoTestnet } from 'viem/tempo/chains'
 
+import * as TestEarn from '../../test/Earn.js'
 import * as Runtime from '../../test/runtime.js'
 import * as TestViem from '../../test/Viem.js'
 import * as Zones from '../apps/Zones.js'
@@ -43,6 +44,17 @@ describe('schema.ResolveInput', () => {
   })
 })
 
+describe('schema.ZoneRoute', () => {
+  test('normalizes the router address', () => {
+    expect(
+      EarnVaults.schema.ZoneRoute.parse({
+        ...TestEarn.zoneRoute,
+        earnRouter: TestEarn.zoneRoute.earnRouter.toUpperCase().replace('0X', '0x'),
+      }),
+    ).toStrictEqual(TestEarn.zoneRoute)
+  })
+})
+
 describe('classifyEngineType', () => {
   test('classifies supported capability fingerprints', () => {
     expect([
@@ -193,3 +205,70 @@ describe('resolve', () => {
     60_000,
   )
 })
+
+describe('resolveZoneRoutes', () => {
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'verifies immutable router bindings and derives private tokens',
+    async () => {
+      const getClient = Viem.createGetClient({
+        defaultChainId: tempoTestnet.id,
+        rpc: TestViem.rpc,
+        zones: [TestEarn.zone],
+      })
+      const discovery = await EarnVaults.resolve({
+        getClient,
+        input: {
+          chainId: tempoTestnet.id,
+          vaultAddress: TestEarn.zoneVaultAddress,
+        },
+        zones: [TestEarn.zone],
+      })
+      const routes = await EarnVaults.resolveZoneRoutes({
+        discovery,
+        getClient,
+        routes: [TestEarn.zoneRoute],
+        zones: [TestEarn.zone],
+      })
+
+      expect(routes).toHaveLength(1)
+      expect(routes[0]).toMatchObject({
+        ...TestEarn.zoneRoute,
+        name: TestEarn.zone.name,
+      })
+      expect(routes[0]?.inputTokens).toHaveLength(1)
+      expect(routes[0]?.outputTokens).toStrictEqual(routes[0]?.inputTokens)
+      await expect(
+        EarnVaults.resolveZoneRoutes({
+          discovery,
+          getClient,
+          routes: [TestEarn.zoneRoute, TestEarn.zoneRoute],
+          zones: [TestEarn.zone],
+        }),
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `[EarnVaults.InvalidRegistryError: Zone 1424310001 is configured more than once.]`,
+      )
+      await expect(
+        EarnVaults.resolveZoneRoutes({
+          discovery,
+          getClient,
+          routes: [
+            { ...TestEarn.zoneRoute, deploymentBlock: TestEarn.zoneRoute.deploymentBlock + 1 },
+          ],
+          zones: [TestEarn.zone],
+        }),
+      ).rejects.toMatchObject({
+        result: {
+          issues: [
+            {
+              actual: String(TestEarn.zoneRoute.deploymentBlock + 1),
+              code: 'zone-deployment-block-mismatch',
+              message: 'Earn router deployment block does not match its code boundary.',
+            },
+          ],
+          status: 'mismatch',
+        },
+      })
+    },
+    60_000,
+  )
+})