tapimo 0.19.0 → 0.20.0

package/src/internal/ZoneAccess.test.ts

@@ -1,38 +1,124 @@
 import { Context } from 'hono'
 
 import * as TestApp from '../../test/App.js'
-import * as Organizations from '../db/tables/organizations.js'
-import * as Projects from '../db/tables/projects.js'
+import * as Db from '../db/Db.js'
 import * as ZoneDelegations from '../db/tables/zoneDelegations.js'
 import * as Metrics from '../Metrics.js'
 import * as Auth from './Auth.js'
 import type * as Log from './Log.js'
+import * as Store from './Store.js'
 import * as Viem from './Viem.js'
 import * as ZoneAccess from './ZoneAccess.js'
 
 const chainId = 421_700_001
+const account = `0x${'ab'.repeat(20)}`
+const token = `0x${'cd'.repeat(20)}`
+
+/** A whole-zone delegation for the shared test organization. */
+const delegation = {
+  accountsAll: true,
+  chainId,
+  environment: 'production',
+  orgId: TestApp.key.orgId,
+  tokensAll: true,
+} as const
 
 describe('check', () => {
   test.each([
-    { expected: 'wildcard', scopes: ['*'], verb: 'read' },
-    { expected: 'scope', scopes: [`zone:${chainId}:read`], verb: 'read' },
-    { expected: undefined, scopes: [`zone:${chainId}:write`], verb: 'read' },
-    { expected: undefined, scopes: [`zone:${chainId + 1}:read`], verb: 'read' },
-    { expected: 'scope', scopes: [`zone:${chainId}:write`], verb: 'write' },
-    { expected: undefined, scopes: [`zone:${chainId}:read`], verb: 'write' },
-    // Generic scopes admit nothing until delegations decide admission.
-    { expected: undefined, scopes: ['zone:read'], verb: 'read' },
-  ] as const)('grants $expected to $scopes for $verb', ({ expected, scopes, verb }) => {
-    const c = context({ scopes })
-    const result = ZoneAccess.check(c, { chainId, verb })
-    expect(result.allowed ? result.grant : undefined).toBe(expected)
+    { delegated: [chainId], expected: 'delegation', scopes: ['zone:read'], verb: 'read', zoneTags: [chainId] }, // prettier-ignore
+    // The wildcard grants no Zone; a tagged `*` key reads only through an explicit `zone:read`.
+    { delegated: [chainId], expected: undefined, scopes: ['*'], verb: 'read', zoneTags: [chainId] }, // prettier-ignore
+    { delegated: [chainId], expected: 'delegation', scopes: ['*', 'zone:read'], verb: 'read', zoneTags: [chainId] }, // prettier-ignore
+    // Absent tags mean no Zone, whatever the scopes grant.
+    { delegated: [chainId], expected: undefined, scopes: ['zone:read'], verb: 'read', zoneTags: undefined }, // prettier-ignore
+    { delegated: [chainId], expected: undefined, scopes: ['zone:read'], verb: 'read', zoneTags: [chainId + 1] }, // prettier-ignore
+    // Tags select among the organization's delegations; they grant nothing alone.
+    {
+      delegated: [],
+      expected: undefined,
+      scopes: ['zone:read'],
+      verb: 'read',
+      zoneTags: [chainId],
+    },
+    // Delegations never loaded (no `load` ran) fail closed.
+    { delegated: undefined, expected: undefined, scopes: ['zone:read'], verb: 'read', zoneTags: [chainId] }, // prettier-ignore
+    // Retired per-Zone read scopes grant nothing, even beside tags and a delegation.
+    { delegated: [chainId], expected: undefined, scopes: [`zone:${chainId}:read`], verb: 'read', zoneTags: [chainId] }, // prettier-ignore
+    { delegated: [chainId], expected: undefined, scopes: ['data:read'], verb: 'read', zoneTags: [chainId] }, // prettier-ignore
+    // A stored per-Zone write scope keeps admitting its own Zone this release, without tags or a delegation.
+    { delegated: [], expected: 'scope', scopes: [`zone:${chainId}:write`], verb: 'write', zoneTags: undefined }, // prettier-ignore
+    { delegated: [chainId], expected: undefined, scopes: [`zone:${chainId + 1}:write`], verb: 'write', zoneTags: undefined }, // prettier-ignore
+    // The generic write scope broadcasts only to tagged Zones the organization is delegated; revoking the delegation stops it.
+    { delegated: [chainId], expected: 'scope', scopes: ['zone:write'], verb: 'write', zoneTags: [chainId] }, // prettier-ignore
+    { delegated: [], expected: undefined, scopes: ['zone:write'], verb: 'write', zoneTags: [chainId] }, // prettier-ignore
+    { delegated: undefined, expected: undefined, scopes: ['zone:write'], verb: 'write', zoneTags: [chainId] }, // prettier-ignore
+    { delegated: [chainId], expected: undefined, scopes: ['zone:write'], verb: 'write', zoneTags: undefined }, // prettier-ignore
+    { delegated: [chainId], expected: undefined, scopes: ['zone:write'], verb: 'write', zoneTags: [chainId + 1] }, // prettier-ignore
+    // The wildcard grants no Zone broadcast, and write scopes never read.
+    { delegated: [chainId], expected: undefined, scopes: ['*'], verb: 'write', zoneTags: [chainId] }, // prettier-ignore
+    { delegated: [chainId], expected: undefined, scopes: ['zone:read'], verb: 'write', zoneTags: [chainId] }, // prettier-ignore
+    { delegated: [chainId], expected: undefined, scopes: ['zone:write'], verb: 'read', zoneTags: [chainId] }, // prettier-ignore
+  ] as const)(
+    'grants $expected to $scopes tagged $zoneTags for $verb with delegations $delegated',
+    ({ delegated, expected, scopes, verb, zoneTags }) => {
+      const c = context({ delegated, scopes, zoneTags })
+      const result = ZoneAccess.check(c, { chainId, verb })
+      expect(result.allowed ? result.grant : undefined).toBe(expected)
+    },
+  )
+
+  test('refuses delegated access as unavailable when the delegation read failed', () => {
+    const refusal = (options: {
+      scopes: readonly string[]
+      verb: ZoneAccess.Verb
+      zoneTags?: readonly number[]
+    }) => {
+      // prettier-ignore
+      const c = context(options)
+      c.set('zoneDelegations' as never, { failed: true } as never)
+      const result = ZoneAccess.check(c, { chainId, verb: options.verb })
+      return result.allowed ? result.grant : result.error.status
+    }
+    expect([
+      refusal({ scopes: ['zone:read'], verb: 'read', zoneTags: [chainId] }),
+      refusal({ scopes: ['zone:write'], verb: 'write', zoneTags: [chainId] }),
+      // Keys no delegation could admit keep their 403.
+      refusal({ scopes: ['zone:read'], verb: 'read', zoneTags: [chainId + 1] }),
+      refusal({ scopes: ['*'], verb: 'read', zoneTags: [chainId] }),
+      // Stored per-Zone write scopes never depend on delegations.
+      refusal({ scopes: [`zone:${chainId}:write`], verb: 'write' }),
+    ]).toEqual([503, 503, 403, 403, 'scope'])
+  })
+
+  test('keeps unreadable delegations eligible and fails listings closed with a 503', () => {
+    const c = context({ scopes: ['zone:read'], zoneTags: [chainId] })
+    c.set('zoneDelegations' as never, { failed: true } as never)
+    // Selection keeps the Zone so `authorize` answers the retriable 503 instead of a 403.
+    expect(ZoneAccess.eligible(c, { chainId })).toBe(true)
+    expect(() => ZoneAccess.visible(c, { chainId })).toThrow(
+      expect.objectContaining({ status: 503 }),
+    )
+    const untagged = context({ scopes: ['zone:read'], zoneTags: [chainId + 1] })
+    untagged.set('zoneDelegations' as never, { failed: true } as never)
+    expect([ZoneAccess.eligible(untagged, { chainId }), ZoneAccess.visible(untagged, { chainId })]).toEqual([false, false]) // prettier-ignore
+  })
+
+  test('needs a delegation covering every account and token without the request addresses', () => {
+    const c = context({ delegated: [], scopes: ['zone:read'], zoneTags: [chainId] })
+    c.set('zoneDelegations' as never, { records: [record({ accountsAll: false })] } as never)
+    expect(ZoneAccess.check(c, { chainId, verb: 'read' }).allowed).toBe(false)
+    c.set('zoneDelegations' as never, { records: [record({ tokensAll: false })] } as never)
+    expect(ZoneAccess.check(c, { chainId, verb: 'read' }).allowed).toBe(false)
+    c.set('zoneDelegations' as never, { records: [record({})] } as never)
+    expect(ZoneAccess.check(c, { chainId, verb: 'read' }).allowed).toBe(true)
   })
 
   test('never records a decision', () => {
-    const c = context({ scopes: ['data:read'] })
+    const c = context({ delegated: [chainId], scopes: ['zone:read'], zoneTags: [chainId] })
     ZoneAccess.check(c, { chainId, verb: 'read' })
-    ZoneAccess.check(context({ scopes: ['*'] }), { chainId, verb: 'read' })
+    ZoneAccess.check(context({ scopes: ['*'] }), { chainId, verb: 'write' })
     expect(c.get('zoneAccess' as never)).toBeUndefined()
+    expect(c.get('zoneAccessDecisions' as never)).toBeUndefined()
   })
 
   test('admits a caller Zone token and records it as the grant', () => {
@@ -68,7 +154,7 @@ describe('check', () => {
           "allowed": false,
           "error": {
             "code": "api_key_forbidden",
-            "message": "Chain ID 421700001 is a Zone. Use an API key granting \`zone:421700001:read\`.",
+            "message": "Chain ID 421700001 is a Zone. Use an API key granting \`zone:read\` and tagged for Zone 421700001, issued to an organization delegated that Zone.",
             "status": 403,
           },
         }
@@ -91,38 +177,131 @@ describe('check', () => {
       denial({ suggestZoneToken: true, verb: 'write' }),
     ]).toMatchInlineSnapshot(`
       [
-        "Chain ID 421700001 is a Zone. Use an API key granting \`zone:421700001:read\`.",
-        "Chain id 421700001 is a zone. Use an API key granting \`zone:421700001:read\`, or pass a Zone token via \`X-Authorization-Token\`.",
-        "Broadcasting to zone 421700001 requires \`zone:421700001:write\`.",
-        "Broadcasting to zone 421700001 requires \`zone:421700001:write\`, or a Zone token via \`X-Authorization-Token\`.",
+        "Chain ID 421700001 is a Zone. Use an API key granting \`zone:read\` and tagged for Zone 421700001, issued to an organization delegated that Zone.",
+        "Chain ID 421700001 is a Zone. Use an API key granting \`zone:read\` and tagged for Zone 421700001, issued to an organization delegated that Zone, or pass a Zone token via \`X-Authorization-Token\`.",
+        "Broadcasting to zone 421700001 requires \`zone:write\` with a tag for Zone 421700001, issued to an organization delegated that Zone.",
+        "Broadcasting to zone 421700001 requires \`zone:write\` with a tag for Zone 421700001, issued to an organization delegated that Zone, or a Zone token via \`X-Authorization-Token\`.",
       ]
     `)
   })
 })
 
 describe('deny', () => {
-  test('removes only the grant from the recorded decision', () => {
-    const c = context({ scopes: [`zone:${chainId}:read`] })
+  test('removes only the grant from the recorded decision and its metered copy', async () => {
+    const c = context({ delegated: [chainId], scopes: ['zone:read'], zoneTags: [chainId] })
     ZoneAccess.deny(c)
     expect(c.get('zoneAccess' as never)).toBeUndefined()
-    ZoneAccess.authorize(c, { chainId, verb: 'read' })
+    await ZoneAccess.authorize(c, { chainId, verb: 'read' })
     ZoneAccess.deny(c)
     expect(c.get('zoneAccess' as never)).toMatchInlineSnapshot(`
       {
         "accounts": [],
         "chainId": 421700001,
-        "scopeGrant": "scope",
+        "delegation": {
+          "decision": "allow",
+          "id": "zd_421700001",
+        },
         "tokens": [],
         "verb": "read",
       }
     `)
+    expect(c.get('zoneAccessDecisions' as never)).toEqual([c.get('zoneAccess' as never)])
+  })
+})
+
+describe('ensure', () => {
+  test('loads delegations once for Zone-capable keys and fails closed on read errors', async () => {
+    const db = TestApp.database()
+    await TestApp.delegateZone(db, { chainIds: [chainId] })
+    const counts: string[] = []
+    const metrics = Metrics.from({
+      count: (name) => void counts.push(name),
+      flush() {},
+      gauge() {},
+      histogram() {},
+    })
+    const wire = (c: Context, source: Db.Source) => {
+      c.set('db' as never, source as never)
+      c.set('metrics' as never, metrics as never)
+      c.set('store' as never, Store.memory() as never)
+      c.set('zones' as never, new Map([[chainId, {}]]) as never)
+      return c
+    }
+    const reader = wire(context({ scopes: ['zone:read'], zoneTags: [chainId] }), db)
+    const untagged = wire(context({ scopes: ['zone:read'] }), db)
+    const writer = wire(context({ scopes: [`zone:${chainId}:write`] }), db)
+    const broken = wire(
+      context({ scopes: ['zone:read'], zoneTags: [chainId] }),
+      Db.postgres({ connectionString: 'postgresql://unused@127.0.0.1:1/unused' }),
+    )
+    await Promise.all([reader, untagged, writer, broken].map((c) => ZoneAccess.ensure(c)))
+
+    expect(
+      (reader.get('zoneDelegations' as never) as ZoneAccess.Delegations & { records: unknown[] })
+        .records,
+    ).toMatchObject([{ chainId }])
+    expect(untagged.get('zoneDelegations' as never)).toBeUndefined()
+    expect(writer.get('zoneDelegations' as never)).toBeUndefined()
+    expect(broken.get('zoneDelegations' as never)).toEqual({ failed: true })
+    expect(counts).toEqual([ZoneAccess.lookupFailureMetric])
+    expect(ZoneAccess.check(broken, { chainId, verb: 'read' }).allowed).toBe(false)
+  })
+
+  test('serves cached delegations while refreshing, and reads Postgres past the maximum age', async () => {
+    vi.useFakeTimers({ now: new Date('2026-10-23T20:40:00.000Z'), toFake: ['Date'] })
+    try {
+      const healthy = TestApp.database()
+      await TestApp.delegateZone(healthy, { chainIds: [chainId] })
+      const unreachable = Db.postgres({
+        connectionString: 'postgresql://unused@127.0.0.1:1/unused',
+      })
+      let down = false
+      const source: Db.Source = () => (down ? unreachable : healthy)
+      // One colo cache shared by every request, as `caches.default` is.
+      const store = Store.memory()
+      const tags: (Metrics.Tags | undefined)[] = []
+      const metrics = Metrics.from({
+        count: (_name, _value, tag) => void tags.push(tag),
+        flush() {},
+        gauge() {},
+        histogram() {},
+      })
+      const read = async () => {
+        const c = context({ scopes: ['zone:read'], zoneTags: [chainId] })
+        c.set('db' as never, source as never)
+        c.set('metrics' as never, metrics as never)
+        c.set('store' as never, store as never)
+        c.set('zones' as never, new Map([[chainId, {}]]) as never)
+        await ZoneAccess.ensure(c)
+        const result = ZoneAccess.check(c, { chainId, verb: 'read' })
+        return result.allowed ? result.grant : result.error.status
+      }
+      const elapse = (ms: number) => vi.setSystemTime(Date.now() + ms)
+
+      expect(await read()).toBe('delegation')
+      down = true
+      // A fresh entry answers without touching Postgres.
+      elapse(ZoneAccess.delegationTtl - 1_000)
+      expect(await read()).toBe('delegation')
+      expect(tags).toEqual([])
+      // An aging entry still answers; only its background refresh fails.
+      elapse(10_000)
+      expect(await read()).toBe('delegation')
+      await vi.waitFor(() => expect(tags).toEqual([{ phase: 'refresh' }]))
+      // Past the maximum age the request reads Postgres and refuses as unavailable.
+      elapse(ZoneAccess.delegationMaxAge)
+      expect(await read()).toBe(503)
+      expect(tags).toEqual([{ phase: 'refresh' }, { phase: 'request' }])
+    } finally {
+      vi.useRealTimers()
+    }
   })
 })
 
 describe('authorize', () => {
-  test('records lowercase accounts and tokens, even when denied', () => {
+  test('records lowercase accounts and tokens, even when denied', async () => {
     const c = context({ scopes: ['data:read'] })
-    ZoneAccess.authorize(c, {
+    await ZoneAccess.authorize(c, {
       accounts: [`0x${'AB'.repeat(20)}`],
       chainId,
       tokens: [`0x${'CD'.repeat(20)}`],
@@ -143,13 +322,9 @@ describe('authorize', () => {
   })
 
   test('records the accounts a Zone RPC batch reads', async () => {
-    const entries: Log.Entry[] = []
-    const reader = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`] }
-    const app = TestApp.create({
-      auth: { keys: [reader] },
-      logger: (entry) => void entries.push(entry),
-      zones: [TestApp.zone({ chainId, rpcUrl: `https://${chainId}.rpc.test` })],
-    })
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
+    const { app, db, entries } = await setup([reader])
+    await ZoneDelegations.create(db, delegation)
 
     await app.request(`/rpc/${chainId}`, {
       body: JSON.stringify([
@@ -169,25 +344,19 @@ describe('authorize', () => {
               "0xabababababababababababababababababababab",
               "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
             ],
-            "zoneGrant": "scope",
+            "zoneGrant": "delegation",
           },
         ]
       `)
   })
 
   test('clears the grant when a later check refuses the request', async () => {
-    const entries: Log.Entry[] = []
-    const reader = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`] }
-    const sandbox = {
-      environment: 'sandbox' as const,
-      id: 'key_sandbox',
-      orgId: TestApp.key.orgId,
-      scopes: ['data:read', `zone:${chainId + 1}:read`],
-      token: 'secret_sandbox',
-    }
-    const app = TestApp.create({
-      auth: { keys: [reader, sandbox] },
-      logger: (entry) => void entries.push(entry),
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
+    const sandbox = TestApp.zoneReader(
+      { environment: 'sandbox' as const, id: 'key_sandbox', orgId: TestApp.key.orgId, scopes: ['data:read'], token: 'secret_sandbox' }, // prettier-ignore
+      [chainId + 1],
+    )
+    const { app, db, entries } = await setup([reader, sandbox], {
       zones: [
         TestApp.zone({ chainId, rpcUrl: `https://${chainId}.rpc.test` }),
         TestApp.zone({
@@ -197,23 +366,26 @@ describe('authorize', () => {
         }),
       ],
     })
+    await ZoneDelegations.create(db, delegation)
+    await ZoneDelegations.create(db, { ...delegation, chainId: chainId + 1, environment: 'sandbox' }) // prettier-ignore
 
-    // A read scope admits the chain, but the method allowlist refuses the broadcast.
+    // The delegation admits the chain, but the method allowlist refuses the broadcast.
     const broadcast = await app.request(`/rpc/${chainId}`, {
       body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_sendRawTransaction' }),
       headers: { 'tempo-api-key': reader.token },
       method: 'POST',
     })
-    // The sandbox refusal of a mainnet Zone follows the recorded scope grant.
+    // The sandbox refusal of a mainnet Zone follows the recorded grant.
     const mainnet = await app.request(`/v1/tokenlist?chainId=${chainId + 1}`, {
       headers: { 'tempo-api-key': sandbox.token },
     })
 
     expect([broadcast.status, mainnet.status]).toStrictEqual([403, 403])
     expect(
-      entries.map(({ errorCode, zoneChainId, zoneGrant }) => ({
+      entries.map(({ errorCode, zoneChainId, zoneDelegationDecision, zoneGrant }) => ({
         errorCode,
         zoneChainId,
+        zoneDelegationDecision,
         zoneGrant,
       })),
     ).toMatchInlineSnapshot(`
@@ -221,11 +393,13 @@ describe('authorize', () => {
         {
           "errorCode": "api_key_forbidden",
           "zoneChainId": 421700001,
+          "zoneDelegationDecision": undefined,
           "zoneGrant": undefined,
         },
         {
           "errorCode": "api_key_forbidden",
           "zoneChainId": 421700002,
+          "zoneDelegationDecision": "allow",
           "zoneGrant": undefined,
         },
       ]
@@ -233,19 +407,15 @@ describe('authorize', () => {
   })
 
   test('logs Zone reads with the grant, accounts, and trusted client IP', async () => {
-    const entries: Log.Entry[] = []
-    const reader = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`] }
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
     const outsider = {
       id: 'key_outsider',
       orgId: TestApp.key.orgId,
       scopes: ['data:read'],
       token: 'secret_outsider',
     }
-    const app = TestApp.create({
-      auth: { keys: [outsider, reader] },
-      logger: (entry) => void entries.push(entry),
-      zones: [TestApp.zone({ chainId, rpcUrl: `https://${chainId}.rpc.test` })],
-    })
+    const { app, db, entries } = await setup([outsider, reader])
+    await ZoneDelegations.create(db, delegation)
     const granted = new Request(`http://tempo-api.test/v1/tokenlist?chainId=${chainId}`, {
       headers: { 'tempo-api-key': reader.token },
     })
@@ -297,7 +467,7 @@ describe('authorize', () => {
           "status": 200,
           "zoneAccounts": [],
           "zoneChainId": 421700001,
-          "zoneGrant": "scope",
+          "zoneGrant": "delegation",
           "zoneTokens": [],
         },
         {
@@ -348,52 +518,119 @@ describe('authorize', () => {
     `)
   })
 
-  test('refuses a key holding only the generic zone:read scope', async () => {
-    const entries: Log.Entry[] = []
-    const generic = { ...TestApp.key, scopes: ['data:read', 'zone:read'] }
-    const app = TestApp.create({
-      auth: { keys: [generic] },
-      logger: (entry) => void entries.push(entry),
-      zones: [TestApp.zone({ chainId, rpcUrl: `https://${chainId}.rpc.test` })],
-    })
-    const read = await app.fetch(
-      new Request(`http://tempo-api.test/v1/tokenlist?chainId=${chainId}`, {
-        headers: { 'tempo-api-key': generic.token },
-      }),
+  test('refuses zone:read keys without a tag or without a delegation, and retired per-Zone scopes', async () => {
+    const untagged = { ...TestApp.key, scopes: ['data:read', 'zone:read'] }
+    const undelegated = TestApp.zoneReader(
+      { ...TestApp.key, id: 'key_undelegated', orgId: 'org_undelegated', scopes: ['data:read'], token: 'secret_undelegated' }, // prettier-ignore
+      [chainId],
     )
+    const legacy = { ...TestApp.key, id: 'key_legacy', scopes: ['data:read', `zone:${chainId}:read`], token: 'secret_legacy' } // prettier-ignore
+    // The additive rewrite left both formats on the record; only the new one grants.
+    const both = { ...TestApp.key, id: 'key_both', scopes: ['data:read', `zone:${chainId}:read`, 'zone:read'], token: 'secret_both', zoneTags: [chainId] } // prettier-ignore
+    const { app, db, entries } = await setup([untagged, undelegated, legacy, both])
+    await ZoneDelegations.create(db, delegation)
+    const read = (key: { token: string }) =>
+      app.fetch(
+        new Request(`http://tempo-api.test/v1/tokenlist?chainId=${chainId}`, {
+          headers: { 'tempo-api-key': key.token },
+        }),
+      )
     const rpc = await app.fetch(
       new Request(`http://tempo-api.test/rpc/${chainId}`, {
         body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
-        headers: { 'tempo-api-key': generic.token },
+        headers: { 'tempo-api-key': untagged.token },
         method: 'POST',
       }),
     )
-    expect([read.status, rpc.status]).toEqual([403, 403])
-    const { requestId: _requestId, ...error } = (await read.json()).error
+    const first = await read(untagged)
+    expect([first.status, (await read(undelegated)).status, (await read(legacy)).status, (await read(both)).status, rpc.status]).toEqual([403, 403, 403, 200, 403]) // prettier-ignore
+    const { requestId: _requestId, ...error } = (await first.json()).error
     expect(error).toMatchInlineSnapshot(`
       {
         "code": "api_key_forbidden",
-        "message": "Chain ID 421700001 is a Zone. Use an API key granting \`zone:421700001:read\`.",
+        "message": "Chain ID 421700001 is a Zone. Use an API key granting \`zone:read\` and tagged for Zone 421700001, issued to an organization delegated that Zone.",
       }
     `)
-    expect(entries.map(({ zoneGrant }) => zoneGrant)).toEqual([undefined, undefined])
+    // The raw RPC probe logs first; only the rewritten record earns a grant.
+    expect(entries.map(({ zoneGrant }) => zoneGrant)).toEqual([undefined, undefined, undefined, undefined, 'delegation']) // prettier-ignore
+  })
+
+  test('refuses reads with a retriable 503 when the delegation read fails', async () => {
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
+    const { app, counts, entries } = await setup([reader], {
+      db: Db.postgres({ connectionString: 'postgresql://unused@127.0.0.1:1/unused' }),
+    })
+    const response = await app.request(`/v1/tokenlist?chainId=${chainId}`, {
+      headers: { 'tempo-api-key': reader.token },
+    })
+    const { requestId: _requestId, ...error } = (await response.json()).error
+    expect({ error, status: response.status }).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "zone_access_unavailable",
+          "message": "Zone 421700001 access could not be verified. Retry the request.",
+        },
+        "status": 503,
+      }
+    `)
+    // A query stage on a failed read places the stall in Postgres (through Hyperdrive), not the cache.
+    expect(stages(response)).toEqual(expect.arrayContaining(['zone_delegations', 'zone_delegations_cache', 'zone_delegations_query'])) // prettier-ignore
+    expect(entries.map(({ errorCode, zoneGrant }) => ({ errorCode, zoneGrant }))).toEqual([{ errorCode: 'zone_access_unavailable', zoneGrant: undefined }]) // prettier-ignore
+    expect(counts.filter(({ name }) => name === ZoneAccess.lookupFailureMetric).map(({ tags }) => tags)).toEqual([{ phase: 'request' }]) // prettier-ignore
+  })
+
+  test('refuses raw Zone RPC with a retriable 503 when the delegation read fails', async () => {
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
+    const { app } = await setup([reader], {
+      db: Db.postgres({ connectionString: 'postgresql://unused@127.0.0.1:1/unused' }),
+    })
+    const response = await app.request(`/rpc/${chainId}`, {
+      body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+      headers: { 'content-type': 'application/json', 'tempo-api-key': reader.token },
+      method: 'POST',
+    })
+    expect([response.status, (await response.json()).error.code]).toEqual([503, 'zone_access_unavailable']) // prettier-ignore
+  })
+
+  test('refuses Zone broadcasts and inferred Zones with a 503 when the delegation read fails', async () => {
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
+    const writer = { ...TestApp.key, id: 'key_writer', scopes: ['data:read', 'zone:write'], token: 'secret_writer', zoneTags: [chainId] } // prettier-ignore
+    const { app } = await setup([reader, writer], {
+      db: Db.postgres({ connectionString: 'postgresql://unused@127.0.0.1:1/unused' }),
+    })
+    const inferred = await app.request(`/v1/addresses/${account}/activities?include=zones`, {
+      headers: { 'tempo-api-key': reader.token },
+    })
+    const rpc = (method: string, params: readonly unknown[]) =>
+      app.request(`/rpc/${chainId}`, {
+        body: JSON.stringify({ id: 1, jsonrpc: '2.0', method, params }),
+        headers: { 'content-type': 'application/json', 'tempo-api-key': writer.token },
+        method: 'POST',
+      })
+    const broadcast = await rpc('eth_sendRawTransaction', [`0x${'02'.repeat(8)}`])
+    // A read the write-only key could never perform keeps its 403.
+    const read = await rpc('eth_chainId', [])
+    const codes = await Promise.all([inferred, broadcast, read].map(async (response) => [response.status, (await response.json()).error.code])) // prettier-ignore
+    expect(codes).toEqual([[503, 'zone_access_unavailable'], [503, 'zone_access_unavailable'], [403, 'api_key_forbidden']]) // prettier-ignore
+  })
+
+  test('times the delegation read in Server-Timing', async () => {
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
+    const { app, db } = await setup([reader])
+    await ZoneDelegations.create(db, delegation)
+    const response = await app.request(`/v1/tokenlist?chainId=${chainId}`, {
+      headers: { 'tempo-api-key': reader.token },
+    })
+    expect(response.status).toBe(200)
+    expect(stages(response)).toEqual(expect.arrayContaining(['zone_delegations', 'zone_delegations_cache', 'zone_delegations_query'])) // prettier-ignore
   })
 
   test('records a granted Zone for inferred-Zone requests, never a denied sibling', async () => {
-    const entries: Log.Entry[] = []
     const other = chainId + 1
-    const reader = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`] }
-    const app = TestApp.create({
-      auth: { keys: [reader] },
-      logger: (entry) => void entries.push(entry),
-      zones: [other, chainId].map((id) =>
-        TestApp.zone({
-          chainId: id,
-          rpcUrl: `https://${id}.rpc.test`,
-          tidxUrl: `https://${id}.tidx.test`,
-        }),
-      ),
-    })
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
+    const { app, db, entries } = await setup([reader], { zones: zonesFor([other, chainId]) })
+    await ZoneDelegations.create(db, delegation)
+    await ZoneDelegations.create(db, { ...delegation, chainId: other })
 
     await app.request(`/v1/addresses/0x${'AB'.repeat(20)}/activities?include=zones`, {
       headers: { 'tempo-api-key': reader.token },
@@ -412,153 +649,37 @@ describe('authorize', () => {
             "0xabababababababababababababababababababab",
           ],
           "zoneChainId": 421700001,
-          "zoneGrant": "scope",
+          "zoneGrant": "delegation",
         },
       ]
     `)
   })
-})
 
-describe('settle', () => {
-  const account = `0x${'ab'.repeat(20)}`
-  const token = `0x${'cd'.repeat(20)}`
-  const delegation = {
-    accountsAll: true,
-    chainId,
-    environment: 'production',
-    orgId: TestApp.key.orgId,
-    projects: 'all',
-    tokensAll: true,
-  } as const
+  test('decides each inferred Zone on its own against the request addresses', async () => {
+    const other = chainId + 1
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId, other])
+    const { app, db, entries, tags } = await setup([reader], { zones: zonesFor([other, chainId]) })
+    await ZoneDelegations.create(db, delegation)
+    // The sibling Zone lists another account only, so it drops out of the selection.
+    await ZoneDelegations.create(db, { ...delegation, accounts: [`0x${'ef'.repeat(20)}`], accountsAll: false, chainId: other }) // prettier-ignore
 
-  /** Builds an app whose Zone requests are logged and metered, over a database holding the key's organization. */
-  async function setup(keys: readonly TestApp.kvStore.Key[]) {
-    const db = TestApp.database()
-    await Organizations.create(db, { id: TestApp.key.orgId, name: 'Delegated' })
-    const entries: Log.Entry[] = []
-    const counts: { name: string; tags: Metrics.Tags | undefined }[] = []
-    const app = TestApp.create({
-      auth: { keys },
-      db,
-      logger: (entry) => void entries.push(entry),
-      metrics: Metrics.from({
-        count: (name, _value, tags) => void counts.push({ name, tags }),
-        flush() {},
-        gauge() {},
-        histogram() {},
-      }),
-      zones: [TestApp.zone({ chainId, rpcUrl: `https://${chainId}.rpc.test` })],
+    const response = await app.request(`/v1/addresses/${account}/activities?include=zones`, {
+      headers: { 'tempo-api-key': reader.token },
     })
-    const request = (path: string, key: TestApp.kvStore.Key | undefined) =>
-      app.request(path, key === undefined ? {} : { headers: { 'tempo-api-key': key.token } })
-    const decisions = () =>
-      entries.map(
-        ({
-          status,
-          zoneDecisionAgreement,
-          zoneDelegationDecision,
-          zoneDelegationId,
-          zoneGrant,
-        }) => ({
-          // prettier-ignore
-          agreement: zoneDecisionAgreement,
-          delegation: zoneDelegationDecision,
-          delegationId: zoneDelegationId === undefined ? undefined : 'zd',
-          grant: zoneGrant,
-          status,
-        }),
-      )
-    const tags = () =>
-      counts.filter(({ name }) => name === ZoneAccess.decisionMetric).map(({ tags }) => tags)
-    return { app, db, decisions, request, tags }
-  }
-
-  test('records agreement and disagreement without changing admission', async () => {
-    const reader = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`] }
-    const outsider = { ...TestApp.key, id: 'key_outsider', scopes: ['data:read'], token: 'secret_outsider' } // prettier-ignore
-    const path = `/v1/tokenlist?chainId=${chainId}`
 
-    // Without a delegation the scope grant disagrees and the outsider's denial agrees.
-    const before = await setup([reader, outsider])
-    expect((await before.request(path, reader)).status).toBe(200)
-    expect((await before.request(path, outsider)).status).toBe(403)
-    // A whole-zone delegation agrees with the grant and disagrees with the denial, which stands.
-    // A fresh app, because delegations are cached per colo and client cache directives are ignored.
-    const after = await setup([reader, outsider])
-    await ZoneDelegations.create(after.db, delegation)
-    expect((await after.request(path, reader)).status).toBe(200)
-    expect((await after.request(path, outsider)).status).toBe(403)
-    // Anonymous callers hold no organization, so no delegation decision is made.
-    expect((await after.request(path, undefined)).status).toBe(403)
-
-    expect([...before.decisions(), ...after.decisions()]).toMatchInlineSnapshot(`
-      [
-        {
-          "agreement": false,
-          "delegation": "deny",
-          "delegationId": undefined,
-          "grant": "scope",
-          "status": 200,
-        },
-        {
-          "agreement": true,
-          "delegation": "deny",
-          "delegationId": undefined,
-          "grant": undefined,
-          "status": 403,
-        },
-        {
-          "agreement": true,
-          "delegation": "allow",
-          "delegationId": "zd",
-          "grant": "scope",
-          "status": 200,
-        },
-        {
-          "agreement": true,
-          "delegation": "deny",
-          "delegationId": "zd",
-          "grant": undefined,
-          "status": 403,
-        },
-        {
-          "agreement": undefined,
-          "delegation": undefined,
-          "delegationId": undefined,
-          "grant": undefined,
-          "status": 403,
-        },
-      ]
-    `)
-    expect([...before.tags(), ...after.tags()]).toMatchInlineSnapshot(`
+    expect(response.status).not.toBe(403)
+    expect(entries.map(({ zoneChainId, zoneGrant }) => ({ zoneChainId, zoneGrant }))).toEqual([
+      { zoneChainId: chainId, zoneGrant: 'delegation' },
+    ])
+    expect(tags()).toMatchInlineSnapshot(`
       [
         {
-          "agreement": "disagree",
-          "chain_id": 421700001,
-          "grant": "scope",
-          "outcome": "allow",
-        },
-        {
-          "agreement": "agree",
-          "chain_id": 421700001,
-          "grant": "none",
-          "outcome": "deny",
-        },
-        {
-          "agreement": "agree",
           "chain_id": 421700001,
-          "grant": "scope",
+          "grant": "delegation",
           "outcome": "allow",
         },
         {
-          "agreement": "agree",
-          "chain_id": 421700001,
-          "grant": "none",
-          "outcome": "deny",
-        },
-        {
-          "agreement": "skipped",
-          "chain_id": 421700001,
+          "chain_id": 421700002,
           "grant": "none",
           "outcome": "deny",
         },
@@ -567,68 +688,62 @@ describe('settle', () => {
   })
 
   test('ignores client cache directives when reading delegations', async () => {
-    const reader = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`] }
-    const { app, db, decisions } = await setup([reader])
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
+    const { app, db } = await setup([reader])
     const path = `/v1/tokenlist?chainId=${chainId}`
     const headers = { 'cache-control': 'no-cache', 'tempo-api-key': reader.token }
-    expect((await app.request(path, { headers })).status).toBe(200)
+    expect((await app.request(path, { headers })).status).toBe(403)
     await ZoneDelegations.create(db, delegation)
     // The cached empty read stands for its TTL even though the caller asked for a refresh.
-    expect((await app.request(path, { headers })).status).toBe(200)
-    expect(decisions().map(({ delegation }) => delegation)).toMatchInlineSnapshot(`
-      [
-        "deny",
-        "deny",
-      ]
-    `)
+    expect((await app.request(path, { headers })).status).toBe(403)
   })
 
-  test('narrows by project and account; zone-wide routes need every account', async () => {
-    const scoped = { ...TestApp.key, projectId: 'prj_a', scopes: ['data:read', `zone:${chainId}:read`] } // prettier-ignore
+  test('narrows by account; zone-wide routes need every account', async () => {
+    const scoped = TestApp.zoneReader({ ...TestApp.key, projectId: 'prj_a', scopes: ['data:read'] }, [chainId]) // prettier-ignore
+    // A key of another project reads the same delegation: narrowing is by key tag, never by project.
     const sibling = { ...scoped, id: 'key_b', projectId: 'prj_b', token: 'secret_b' }
-    const organizationWide = { ...TestApp.key, id: 'key_org', scopes: scoped.scopes, token: 'secret_org' } // prettier-ignore
-    const { db, decisions, request } = await setup([scoped, sibling, organizationWide])
-    await Projects.create(db, { id: 'prj_a', name: 'A', orgId: TestApp.key.orgId })
-    await ZoneDelegations.create(db, { ...delegation, accounts: [account], accountsAll: false, projects: ['prj_a'] }) // prettier-ignore
+    const { db, decisions, request } = await setup([scoped, sibling])
+    await ZoneDelegations.create(db, { ...delegation, accounts: [account], accountsAll: false })
     const balances = (address: string) => `/v1/addresses/${address}/balances?chainId=${chainId}`
 
-    // Project narrowing: the named project passes; a sibling project and an organization-wide key do not.
     await request(balances(account), scoped)
     await request(balances(account), sibling)
-    await request(balances(account), organizationWide)
     // Account narrowing: another account fails, and a zone-wide list fails without `all`.
     await request(balances(`0x${'ef'.repeat(20)}`), scoped)
     await request(`/v1/tokenlist?chainId=${chainId}`, scoped)
 
-    expect(decisions().map(({ delegation, status }) => ({ delegation, status })))
-      .toMatchInlineSnapshot(`
+    expect(decisions()).toMatchInlineSnapshot(`
       [
         {
           "delegation": "allow",
+          "delegationId": "zd",
+          "grant": "delegation",
           "status": 502,
         },
         {
-          "delegation": "deny",
-          "status": 502,
-        },
-        {
-          "delegation": "deny",
+          "delegation": "allow",
+          "delegationId": "zd",
+          "grant": "delegation",
           "status": 502,
         },
         {
           "delegation": "deny",
-          "status": 502,
+          "delegationId": "zd",
+          "grant": undefined,
+          "status": 403,
         },
         {
           "delegation": "deny",
-          "status": 200,
+          "delegationId": "zd",
+          "grant": undefined,
+          "status": 403,
         },
       ]
     `)
   })
 
   test('treats a raw RPC batch with any zone-wide read as zone-wide', async () => {
-    const reader = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`] }
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
     const { app, db, decisions } = await setup([reader])
     await ZoneDelegations.create(db, { ...delegation, accounts: [account], accountsAll: false })
     const rpc = (requests: readonly { method: string; params?: unknown[] }[]) =>
@@ -641,17 +756,28 @@ describe('settle', () => {
     // Chain metadata exposes no account, so it keeps the batch account-scoped; logs do not.
     await rpc([{ method: 'eth_getBalance', params: [account, 'latest'] }, { method: 'eth_blockNumber', params: [] }]) // prettier-ignore
     await rpc([{ method: 'eth_getBalance', params: [account, 'latest'] }, { method: 'eth_getLogs', params: [{}] }]) // prettier-ignore
-    expect(decisions().map(({ delegation }) => delegation)).toMatchInlineSnapshot(`
+    // Admitted batches reach body validation (no content type here); refused ones never do.
+    expect(decisions().map(({ delegation, status }) => [delegation, status]))
+      .toMatchInlineSnapshot(`
       [
-        "allow",
-        "allow",
-        "deny",
+        [
+          "allow",
+          415,
+        ],
+        [
+          "allow",
+          415,
+        ],
+        [
+          "deny",
+          403,
+        ],
       ]
     `)
   })
 
   test('narrows by token on token routes', async () => {
-    const reader = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`] }
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
     const { db, decisions, request } = await setup([reader])
     await ZoneDelegations.create(db, { ...delegation, tokens: [token], tokensAll: false })
 
@@ -660,18 +786,31 @@ describe('settle', () => {
     // A list naming no token sees every token, so a token list does not cover it.
     await request(`/v1/tokenlist?chainId=${chainId}`, reader)
 
-    expect(decisions().map(({ delegation }) => delegation)).toMatchInlineSnapshot(`
+    expect(decisions().map(({ delegation, status }) => [delegation, status]))
+      .toMatchInlineSnapshot(`
       [
-        "allow",
-        "deny",
-        "deny",
+        [
+          "allow",
+          404,
+        ],
+        [
+          "deny",
+          403,
+        ],
+        [
+          "deny",
+          403,
+        ],
       ]
     `)
   })
+})
 
-  test('compares against the scope decision, not later refusals, and skips writes', async () => {
-    const reader = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`, `zone:${chainId}:write`] } // prettier-ignore
-    const { app, db, decisions, tags } = await setup([reader])
+describe('settle', () => {
+  test('meters every recorded decision with its final outcome', async () => {
+    const reader = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read', `zone:${chainId}:write`] }, [chainId]) // prettier-ignore
+    const outsider = { ...TestApp.key, id: 'key_outsider', scopes: ['data:read'], token: 'secret_outsider' } // prettier-ignore
+    const { app, db, request, tags } = await setup([reader, outsider])
     await ZoneDelegations.create(db, delegation)
     const rpc = (method: string) =>
       app.request(`/rpc/${chainId}`, {
@@ -679,49 +818,39 @@ describe('settle', () => {
         headers: { 'tempo-api-key': reader.token },
         method: 'POST',
       })
-    // The read scope admits the chain, the method allowlist refuses the call afterwards; the
-    // delegation agrees with the scope grant because the allowlist survives enforcement.
+    expect((await request(`/v1/tokenlist?chainId=${chainId}`, reader)).status).toBe(200)
+    expect((await request(`/v1/tokenlist?chainId=${chainId}`, outsider)).status).toBe(403)
+    // The delegation admits the chain, the method allowlist refuses the call afterwards.
     expect((await rpc('eth_sign')).status).toBe(403)
-    // Broadcasts are user-signed and stay on key scopes, so they are never compared.
-    const broadcast = await rpc('eth_sendRawTransaction')
-    expect(broadcast.status).not.toBe(403)
-    expect([decisions(), tags()]).toMatchInlineSnapshot(`
+    // Broadcasts are user-signed and stay on key scopes.
+    expect((await rpc('eth_sendRawTransaction')).status).not.toBe(403)
+    expect(tags()).toMatchInlineSnapshot(`
       [
-        [
-          {
-            "agreement": true,
-            "delegation": "allow",
-            "delegationId": "zd",
-            "grant": undefined,
-            "status": 403,
-          },
-          {
-            "agreement": undefined,
-            "delegation": undefined,
-            "delegationId": undefined,
-            "grant": "scope",
-            "status": 415,
-          },
-        ],
-        [
-          {
-            "agreement": "agree",
-            "chain_id": 421700001,
-            "grant": "none",
-            "outcome": "deny",
-          },
-          {
-            "agreement": "skipped",
-            "chain_id": 421700001,
-            "grant": "scope",
-            "outcome": "allow",
-          },
-        ],
+        {
+          "chain_id": 421700001,
+          "grant": "delegation",
+          "outcome": "allow",
+        },
+        {
+          "chain_id": 421700001,
+          "grant": "none",
+          "outcome": "deny",
+        },
+        {
+          "chain_id": 421700001,
+          "grant": "none",
+          "outcome": "deny",
+        },
+        {
+          "chain_id": 421700001,
+          "grant": "scope",
+          "outcome": "allow",
+        },
       ]
     `)
   })
 
-  test('skips forwarded Zone tokens and contexts without a database', async () => {
+  test('meters bare contexts, including forwarded Zone tokens and unloaded delegations', async () => {
     const counts: Metrics.Tags[] = []
     const metrics = Metrics.from({
       count: (_name, _value, tags) => void counts.push(tags ?? {}),
@@ -731,15 +860,15 @@ describe('settle', () => {
     })
     const forwarded = context({ scopes: ['data:read'] })
     forwarded.set('metrics' as never, metrics as never)
-    ZoneAccess.authorize(forwarded, { chainId, verb: 'read', zoneToken: true })
-    await ZoneAccess.settle(forwarded)
-    // No database or cache store is wired, so the comparison is unavailable rather than a decision.
-    const bare = context({ scopes: [`zone:${chainId}:read`] })
+    await ZoneAccess.authorize(forwarded, { chainId, verb: 'read', zoneToken: true })
+    ZoneAccess.settle(forwarded)
+    // Nothing loaded the organization's delegations, so the read fails closed.
+    const bare = context({ scopes: ['zone:read'], zoneTags: [chainId] })
     bare.set('metrics' as never, metrics as never)
-    ZoneAccess.authorize(bare, { chainId, verb: 'read' })
-    await ZoneAccess.settle(bare)
+    await ZoneAccess.authorize(bare, { chainId, verb: 'read' })
+    ZoneAccess.settle(bare)
     const silent = context({ scopes: ['data:read'] })
-    await ZoneAccess.settle(silent)
+    ZoneAccess.settle(silent)
 
     expect([
       (forwarded.get('zoneAccess' as never) as ZoneAccess.Access).delegation,
@@ -753,17 +882,14 @@ describe('settle', () => {
         undefined,
         [
           {
-            "agreement": "skipped",
             "chain_id": 421700001,
             "grant": "zone_token",
             "outcome": "allow",
           },
-          {},
           {
-            "agreement": "unavailable",
             "chain_id": 421700001,
-            "grant": "scope",
-            "outcome": "allow",
+            "grant": "none",
+            "outcome": "deny",
           },
         ],
       ]
@@ -771,12 +897,75 @@ describe('settle', () => {
   })
 })
 
+/** Builds an app whose Zone requests are logged and metered, over a database holding the key's organization. */
+async function setup(keys: readonly TestApp.kvStore.Key[], options: setup.Options = {}) {
+  const db = options.db ?? TestApp.database()
+  if (options.db === undefined) await TestApp.delegateZone(db, { chainIds: [] })
+  const entries: Log.Entry[] = []
+  const counts: { name: string; tags: Metrics.Tags | undefined }[] = []
+  const app = TestApp.create({
+    auth: { keys },
+    db,
+    logger: (entry) => void entries.push(entry),
+    metrics: Metrics.from({
+      count: (name, _value, tags) => void counts.push({ name, tags }),
+      flush() {},
+      gauge() {},
+      histogram() {},
+    }),
+    zones: options.zones ?? zonesFor([chainId]),
+  })
+  const request = (path: string, key: TestApp.kvStore.Key | undefined) =>
+    app.request(path, key === undefined ? {} : { headers: { 'tempo-api-key': key.token } })
+  const decisions = () =>
+    entries.map(({ status, zoneDelegationDecision, zoneDelegationId, zoneGrant }) => ({
+      delegation: zoneDelegationDecision,
+      delegationId: zoneDelegationId === undefined ? undefined : 'zd',
+      grant: zoneGrant,
+      status,
+    }))
+  const tags = () =>
+    counts.filter(({ name }) => name === ZoneAccess.decisionMetric).map(({ tags }) => tags)
+  return { app, counts, db, decisions, entries, request, tags }
+}
+
+declare namespace setup {
+  type Options = {
+    db?: Db.Db | undefined
+    zones?: readonly ReturnType<typeof TestApp.zone>[] | undefined
+  }
+}
+
+function stages(response: globalThis.Response) {
+  return (response.headers.get('server-timing') ?? '')
+    .split(', ')
+    .map((metric) => metric.split(';')[0])
+}
+
+function zonesFor(chainIds: readonly number[]) {
+  return chainIds.map(
+    (id) =>
+    TestApp.zone({ chainId: id, rpcUrl: `https://${id}.rpc.test`, tidxUrl: `https://${id}.tidx.test` }), // prettier-ignore
+  )
+}
+
+/** A delegation row as `load` leaves it on the context. */
+function record(options: Partial<ZoneDelegations.Record>): ZoneDelegations.Record {
+  return {
+    ...delegation,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    id: `zd_${options.chainId ?? chainId}`,
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    ...options,
+  }
+}
+
 function request() {
   return new Request('http://tempo-api.test/')
 }
 
-/** Builds a context authenticated as an API key holding `scopes`. */
-function context(options: { scopes: readonly string[] }) {
+/** Builds a context authenticated as an API key, with its organization's delegations preloaded when given. */
+function context(options: context.Options) {
   const c = new Context(request())
   const principal = {
     apiKey: {
@@ -784,12 +973,26 @@ function context(options: { scopes: readonly string[] }) {
       id: 'key_test',
       orgId: 'org_test',
       scopes: options.scopes,
+      ...(options.zoneTags === undefined ? {} : { zoneTags: options.zoneTags }),
     },
     environment: 'production',
     id: 'key_test',
     orgId: 'org_test',
+    ...(options.projectId === undefined ? {} : { projectId: options.projectId }),
     type: 'api_key',
+    ...(options.zoneTags === undefined ? {} : { zoneTags: options.zoneTags }),
   }
   c.set('principal' as never, principal as never)
+  if (options.delegated)
+    c.set('zoneDelegations' as never, { records: options.delegated.map((id) => record({ chainId: id })) } as never) // prettier-ignore
   return c
 }
+
+declare namespace context {
+  type Options = {
+    delegated?: readonly number[] | undefined
+    projectId?: string | undefined
+    scopes: readonly string[]
+    zoneTags?: readonly number[] | undefined
+  }
+}