tapimo 0.0.1 → 0.1.0

package/src/index.ts

@@ -1,10 +1,12 @@
 export * as ApiKey from './ApiKey.js'
-export * as ApiKeySource from './ApiKeySource.js'
+export * as ApiKeys from './ApiKeys.js'
 export * as App from './App.js'
 export * as Assets from './Assets.js'
 export * as Auth from './Auth.js'
-export * as Cli from './Cli.js'
+export * as Cli from './cli/Cli.js'
 export * as Client from './Client.js'
+export * as Db from './db/Db.js'
+export * as Handler from './Handler.js'
 export * as Log from './internal/Log.js'
 export * as Metrics from './Metrics.js'
 export * as RateLimit from './internal/RateLimit.js'

package/src/internal/Auth.test.ts

@@ -1,7 +1,7 @@
 import { Hono } from 'hono'
 import { requestId } from 'hono/request-id'
 import { Mppx, tempo } from 'mppx/hono'
-import { RateLimit } from 'cadent'
+import { RateLimit } from 'tapimo'
 import * as ApiKey from '../ApiKey.js'
 import * as Auth from './Auth.js'
 import * as Log from './Log.js'
@@ -96,7 +96,7 @@ describe('require', () => {
       // the downstream validator rejects it as `query_invalid` and the legacy
       // `?key=...` lane breaks on every strict-query endpoint.
       const auth = {
-        apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+        apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
         rateLimit: RateLimit.memory(),
       }
       const app = new Hono<Auth.Environment>()
@@ -241,7 +241,7 @@ describe('require', () => {
       const app = createApp({
         auth: {
           apiKey: {
-            source: TestApp.source({
+            resolve: TestApp.resolver({
               keys: [{ ...key, scopes: [Scope.wildcard], token }],
             }),
           },
@@ -273,7 +273,7 @@ describe('require', () => {
     function createChainApp(options: { public?: boolean } = {}) {
       const auth: Auth.Context = {
         apiKey: {
-          source: TestApp.source({
+          resolve: TestApp.resolver({
             keys: [
               { ...key, scopes: [Scope.wildcard], token },
               {
@@ -399,7 +399,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuota(),
         },
@@ -420,7 +420,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuotaOnce(),
         },
@@ -451,7 +451,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuota(),
         },
@@ -477,7 +477,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuotaOnce(),
         },
@@ -537,7 +537,7 @@ describe('require', () => {
     test('returns rate-limit error without payment context', async () => {
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           rateLimit: overQuota(),
         },
         policy: { public: { rateLimit: { perMinute: 1 } } },
@@ -555,6 +555,64 @@ describe('require', () => {
         }
       `)
     })
+
+    test('fails open when the public rate-limit store errors', async () => {
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+      try {
+        const app = createApp({
+          auth: {
+            apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+            rateLimit: {
+              async consume() {
+                throw new Error('Network connection lost.')
+              },
+            },
+          },
+          policy: { public: { rateLimit: { perMinute: 1 } } },
+        })
+        const response = await app.request('/protected', {
+          headers: { 'x-forwarded-for': '203.0.113.10' },
+        })
+        const body = await response.json()
+
+        expect(response.status).toMatchInlineSnapshot(`200`)
+        expect(response.headers.has('ratelimit-limit')).toMatchInlineSnapshot(`false`)
+        expect(body).toMatchInlineSnapshot(`
+          {
+            "id": "203.0.113.10",
+            "type": "public",
+          }
+        `)
+        expect(error.mock.calls.length).toMatchInlineSnapshot(`1`)
+      } finally {
+        error.mockRestore()
+      }
+    })
+
+    test('fails open when the API-key rate-limit store errors', async () => {
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+      try {
+        const app = createApp({
+          auth: {
+            apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+            rateLimit: {
+              async consume() {
+                throw new Error('Network connection lost.')
+              },
+            },
+          },
+        })
+        const response = await app.request('/protected', {
+          headers: { 'tempo-api-key': token },
+        })
+
+        expect(response.status).toMatchInlineSnapshot(`200`)
+        expect(response.headers.has('ratelimit-limit')).toMatchInlineSnapshot(`false`)
+        expect(error.mock.calls.length).toMatchInlineSnapshot(`1`)
+      } finally {
+        error.mockRestore()
+      }
+    })
   })
 
   describe('rateLimit per-scope', () => {
@@ -574,7 +632,7 @@ describe('require', () => {
       const auth = {
         apiKey: {
           rateLimits: { 'data:read': { perMinute: 1 }, 'webhooks:write': { perMinute: 1 } },
-          source: TestApp.source({
+          resolve: TestApp.resolver({
             keys: [{ ...key, scopes: [Scope.wildcard], token }],
           }),
         },
@@ -628,7 +686,7 @@ describe('require', () => {
       const auth = {
         apiKey: {
           rateLimits: { 'data:read': { perMinute: 1_000 } },
-          source: TestApp.source({
+          resolve: TestApp.resolver({
             keys: [{ ...key, scopes: [Scope.wildcard], token }],
           }),
         },
@@ -652,7 +710,7 @@ describe('require', () => {
     })
 
     test('per-key default overrides config default but not a route cap', async () => {
-      const source = TestApp.source({
+      const resolve = TestApp.resolver({
         keys: [
           {
             ...key,
@@ -665,7 +723,7 @@ describe('require', () => {
 
       const open = createScopedApp({
         auth: {
-          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, source },
+          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, resolve },
           rateLimit: RateLimit.memory(),
         },
         routes: [{ path: '/protected', policy: { apiKey: { scopes: ['data:read'] } } }],
@@ -676,7 +734,7 @@ describe('require', () => {
 
       const capped = createScopedApp({
         auth: {
-          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, source },
+          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, resolve },
           rateLimit: RateLimit.memory(),
         },
         routes: [
@@ -699,7 +757,7 @@ describe('require', () => {
     test('per-key per-scope overrides everything including a route cap', async () => {
       const auth = {
         apiKey: {
-          source: TestApp.source({
+          resolve: TestApp.resolver({
             keys: [
               {
                 ...key,
@@ -732,7 +790,7 @@ describe('require', () => {
       const entries: Log.Entry[] = []
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           rateLimit: overQuota(),
         },
         logger: (entry) => void entries.push(entry),
@@ -759,7 +817,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuota(),
         },
@@ -788,7 +846,7 @@ function createScopedApp(options: {
 }) {
   const auth = options.auth ?? {
     apiKey: {
-      source: TestApp.source({ keys: [{ ...key, scopes: [Scope.wildcard], token }] }),
+      resolve: TestApp.resolver({ keys: [{ ...key, scopes: [Scope.wildcard], token }] }),
     },
     rateLimit: RateLimit.memory(),
   }
@@ -814,7 +872,7 @@ type Options = {
 
 function createApp(options: Options = {}) {
   const auth = options.auth ?? {
-    apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+    apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
     rateLimit: RateLimit.memory(),
   }
   const app = new Hono<Auth.Environment>()
@@ -845,7 +903,7 @@ function createMppServer() {
       }),
     ],
     realm: 'tempo-api-test',
-    secretKey: 'secret_test_key',
+    secretKey: 'secret_test_key_0123456789abcdef',
   })
 }
 

package/src/internal/Auth.ts

@@ -7,8 +7,9 @@ import { findTargetHandler } from 'hono/utils/handler'
 import { Credential, type Method } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
 
-import * as ApiKeySource from '../ApiKeySource.js'
 import * as ApiKey from '../ApiKey.js'
+import * as ApiKeys from '../ApiKeys.js'
+import type * as Store from './Store.js'
 import * as OpenApi from './OpenApi.js'
 import * as RateLimit from './RateLimit.js'
 import * as Response from './Response.js'
@@ -29,8 +30,8 @@ export type Context = {
          * per-key {@link ApiKey.ApiKey.rateLimits} shape.
          */
         rateLimits?: Record<string, RateLimit.Limit> | undefined
-        /** Backing API-key source. */
-        source: ApiKeySource.Source
+        /** Resolves a presented token against the app's KV store on `c`. */
+        resolve: (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null>
       }
     | undefined
   /** MPP payment configuration. */
@@ -217,14 +218,20 @@ export function middleware<
   const { charge = {}, ...mpp } = options.mpp === false ? {} : (options.mpp ?? {})
   const defaults = laneDefaults(options)
   const base = basePolicy(options, defaults)
+  // Keys resolve against the app's KV state store on request context
+  // (`App.create({ kv })`), so the middleware needs no storage wiring; when no
+  // store is configured, every token resolves to `null` (closed).
   // Resolution is cached per isolate by default (positive 60s / negative 10s,
-  // keyed by token sha256 — see `ApiKeySource.cached`) so hot keys skip the
-  // backend read on the auth path of every request. Pass `apiKey.cache: false`
-  // when instant revocation matters more than the per-request read.
-  const source = (() => {
-    if (options.apiKey === false || !options.apiKey?.source) return ApiKeySource.noop
-    if (options.apiKey.cache === false) return options.apiKey.source
-    return ApiKeySource.cached(options.apiKey.source, options.apiKey.cache)
+  // keyed by token sha256) so hot keys skip the backend read on the auth path
+  // of every request. Pass `apiKey.cache: false` when instant revocation
+  // matters more than the per-request read.
+  const resolve = (() => {
+    const uncached = (c: hono_Context, token: string) => {
+      const kv = contextKv(c)
+      return kv ? ApiKeys.resolve(kv.store, token) : Promise.resolve(null)
+    }
+    if (options.apiKey === false || options.apiKey?.cache === false) return uncached
+    return cachedResolve(uncached, options.apiKey?.cache ?? {})
   })()
   const auth: Context = {
     ...(options.apiKey === false
@@ -232,7 +239,7 @@ export function middleware<
       : {
           apiKey: {
             ...(options.apiKey?.rateLimits ? { rateLimits: options.apiKey.rateLimits } : {}),
-            source,
+            resolve,
           },
         }),
     ...(options.mpp === false
@@ -280,16 +287,14 @@ export declare namespace middleware {
     apiKey?:
       | {
           /**
-           * Resolve-cache tuning for the source (per-isolate, positive 60s /
-           * negative 10s by default), or `false` to resolve uncached on every
-           * request — e.g. when instant revocation matters more than the
-           * per-request backend read.
+           * Resolve-cache tuning (per-isolate, positive 60s / negative 10s by
+           * default), or `false` to resolve uncached on every request — e.g.
+           * when instant revocation matters more than the per-request backend
+           * read.
            */
-          cache?: ApiKeySource.cached.Options | false | undefined
+          cache?: Cache | false | undefined
           /** API-key quotas keyed by quota scope (reserved `'*'` is the config default). */
           rateLimits?: Record<string, RateLimit.Limit> | undefined
-          /** Backing API-key source. Defaults to an empty source (rejects all). */
-          source?: ApiKeySource.Source | undefined
           /** Required API-key scopes. */
           scopes?: readonly Scope.Id[] | undefined
         }
@@ -311,6 +316,16 @@ export declare namespace middleware {
     rateLimit?: RateLimit.memory.Options | undefined
   }
 
+  /** Resolve-cache tuning for API-key resolution. */
+  type Cache = {
+    /** Time-to-live for negative (`null`) results in milliseconds. */
+    negativeTtl?: number | undefined
+    /** Clock used for expiry. */
+    now?: (() => number) | undefined
+    /** Time-to-live for positive results in milliseconds. */
+    ttl?: number | undefined
+  }
+
   /** MPP payment options used by auth middleware. */
   type MppOptions = Omit<NonNullable<Parameters<typeof Mppx.create>[0]>, 'methods'> & {
     /** Global Tempo charge options passed to the MPP method instantiator. */
@@ -612,7 +627,7 @@ export function require<environment extends Environment = Environment>(
 
     const hasPayment = hasPaymentCredential(c) && isPaymentEnabled(auth, policy)
     if (credential) {
-      const apiKey = await auth.apiKey?.source.resolve(credential.token)
+      const apiKey = await auth.apiKey?.resolve(c, credential.token)
       if (!apiKey)
         return jsonError(c, {
           code: 'api_key_invalid',
@@ -796,7 +811,12 @@ function consumeRateLimit(
   options: RateLimit.Store.ConsumeOptions,
 ): Promise<RateLimit.Result | null> {
   if (!auth.rateLimit) return Promise.resolve(null)
-  return auth.rateLimit.consume(options)
+  // Fail open: a rate-limit store error (e.g. a lost Durable Object
+  // connection) degrades to unenforced quota instead of failing the request.
+  return auth.rateLimit.consume(options).catch((error) => {
+    console.error('[auth] rate-limit consume failed; failing open', error)
+    return null
+  })
 }
 
 /**
@@ -1005,3 +1025,61 @@ function setRateLimitHeaders(c: hono_Context, result: RateLimit.Result) {
   c.header('RateLimit-Remaining', String(result.remaining))
   c.header('RateLimit-Reset', String(result.reset))
 }
+
+// Reads the app's KV state store from request context (set by `App.create`
+// from its `kv` option); `undefined` leaves API-key auth closed.
+function contextKv(c: hono_Context): { store: Store.State } | undefined {
+  return (c.get as (key: string) => unknown)('kv') as { store: Store.State } | undefined
+}
+
+/** Maximum resolve-cache entries held per isolate before eviction. */
+const cachedMaxEntries = 10_000
+
+/**
+ * Wraps token resolution with a short-TTL per-isolate cache so hot keys skip
+ * the backend read on every request. Positive results cache for `ttl`
+ * (default 60s), negative for `negativeTtl` (default 10s) so a freshly minted
+ * key is usable quickly; concurrent misses for one token are single-flighted.
+ * Entries are keyed by the token's sha256 (`ApiKey.hash`) — never the
+ * plaintext. A revoked key may stay resolvable for up to `ttl` — the accepted
+ * trade-off for removing a backend read from the auth path.
+ */
+function cachedResolve(
+  resolve: (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null>,
+  options: middleware.Cache,
+): (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null> {
+  const { negativeTtl = 10_000, now = Date.now, ttl = 60_000 } = options
+  type Cell = { expiresAt: number; value: ApiKey.ApiKey | null }
+  const cells = new Map<string, Cell>()
+  const flights = new Map<string, Promise<ApiKey.ApiKey | null>>()
+
+  return async (c, token) => {
+    // Versioned so a future record-shape change can't serve stale shapes.
+    const key = `v1:${ApiKey.hash(token)}`
+    const cell = cells.get(key)
+    if (cell && cell.expiresAt > now()) return cell.value
+    if (cell) cells.delete(key)
+
+    const existing = flights.get(key)
+    if (existing) return existing
+
+    const flight = (async () => {
+      const value = await resolve(c, token)
+      // Bound the cache: random invalid tokens each add a (negative) entry,
+      // so sweep expired cells at the cap and then drop the oldest.
+      if (cells.size >= cachedMaxEntries) {
+        const time = now()
+        for (const [name, entry] of cells) if (entry.expiresAt <= time) cells.delete(name)
+        while (cells.size >= cachedMaxEntries) cells.delete(cells.keys().next().value as string)
+      }
+      cells.set(key, { expiresAt: now() + (value ? ttl : negativeTtl), value })
+      return value
+    })()
+    flights.set(key, flight)
+    try {
+      return await flight
+    } finally {
+      flights.delete(key)
+    }
+  }
+}

package/src/internal/RateLimit.test.ts

@@ -1,4 +1,4 @@
-import { RateLimit, Store } from 'cadent'
+import { RateLimit, Store } from 'tapimo'
 
 describe('memory', () => {
   test('tracks fixed-window quota in a store', async () => {

package/src/internal/RpcSchema.ts

@@ -0,0 +1,10 @@
+import type { RpcSchema } from 'ox'
+
+/**
+ * Ox-compatible JSON-RPC schema union used to type the relay handler's incoming
+ * requests (`RpcRequest.RpcRequest<Ox>`). The relay switches on `request.method`
+ * string literals and casts params per method, so a permissive schema whose
+ * `params` is an array is sufficient — the full method-by-method schema union
+ * from the accounts SDK is not needed here.
+ */
+export type Ox = RpcSchema.Generic<string, readonly unknown[]>

package/src/internal/Store.test.ts

@@ -1,4 +1,4 @@
-import { Store } from 'cadent'
+import { Store } from 'tapimo'
 
 describe('from', () => {
   const ops = {
@@ -68,7 +68,89 @@ describe('increment', () => {
   })
 })
 
+describe('update', () => {
+  test('falls back to a get + put read-modify-write without a native swap', async () => {
+    const cells = new Map<string, string>()
+    const store = Store.from({
+      async delete(key) {
+        cells.delete(key)
+      },
+      async get(key) {
+        return cells.get(key) ?? null
+      },
+      async list() {
+        return { keys: [] }
+      },
+      async put(key, value) {
+        cells.set(key, value)
+      },
+    })
+
+    expect(await Store.update(store, 'value', (current) => `${current ?? 'start'}+`)).toMatchInlineSnapshot(`"start+"`) // prettier-ignore
+    expect(await Store.update(store, 'value', (current) => `${current}+`)).toMatchInlineSnapshot(`"start++"`) // prettier-ignore
+  })
+
+  test('retries the transform when the compare-and-swap loses', async () => {
+    const store = Store.memory()
+    await store.put('value', 'a')
+
+    // Interleave a competing write between the read and the swap once.
+    let raced = false
+    const get = store.get.bind(store)
+    store.get = async (key) => {
+      const current = await get(key)
+      if (!raced) {
+        raced = true
+        await store.put('value', 'b')
+      }
+      return current
+    }
+
+    const transforms: (null | string)[] = []
+    const written = await Store.update(store, 'value', (current) => {
+      transforms.push(current)
+      return `${current}c`
+    })
+
+    expect(written).toMatchInlineSnapshot(`"bc"`)
+    expect(transforms).toMatchInlineSnapshot(`
+      [
+        "a",
+        "b",
+      ]
+    `)
+  })
+
+  test('fails after exhausting compare-and-swap attempts', async () => {
+    const store = Store.memory()
+    await store.put('value', 'a')
+
+    // Every read is immediately invalidated by a competing write.
+    const get = store.get.bind(store)
+    store.get = async (key) => {
+      const current = await get(key)
+      await store.put('value', `${current}!`)
+      return current
+    }
+
+    await expect(
+      Store.update(store, 'value', (current) => `${current}c`, { attempts: 2 }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Store.UpdateContentionError: Store update on "value" lost 2 compare-and-swap attempts.]`,
+    )
+  })
+})
+
 describe('memory', () => {
+  test('swaps atomically against the expected value', async () => {
+    const store = Store.memory()
+
+    expect(await store.swap!('value', null, 'first')).toMatchInlineSnapshot(`true`)
+    expect(await store.swap!('value', null, 'clobber')).toMatchInlineSnapshot(`false`)
+    expect(await store.swap!('value', 'first', 'second')).toMatchInlineSnapshot(`true`)
+    expect(await store.get('value')).toMatchInlineSnapshot(`"second"`)
+  })
+
   test('treats expired entries as absent', async () => {
     const store = Store.memory()
 
@@ -193,6 +275,16 @@ describe('cloudflareKv', () => {
 })
 
 describe('durableObject', () => {
+  // The stub contract requires native `increment` and `swap` (our DO class
+  // implements them); derive them for the in-memory fakes.
+  function stubFor(backing: Store.State): Store.durableObject.Stub {
+    return {
+      ...backing,
+      increment: (key, options) => Store.increment(backing, key, options),
+      swap: (key, expected, next, options) => backing.swap!(key, expected, next, options),
+    }
+  }
+
   test('adapts a Durable Object namespace without caching stubs', async () => {
     const calls: string[] = []
     const backing = Store.memory({
@@ -201,12 +293,7 @@ describe('durableObject', () => {
     const namespace = {
       getByName(name) {
         calls.push(name)
-        // The stub contract requires a native `increment` (our DO class
-        // implements it); derive one for the in-memory fake.
-        return {
-          ...backing,
-          increment: (key, options) => Store.increment(backing, key, options),
-        }
+        return stubFor(backing)
       },
     } satisfies Store.durableObject.Namespace
     const store = Store.durableObject(namespace, { name: 'tempo-api' })
@@ -250,6 +337,7 @@ describe('durableObject', () => {
           increment: (key, options) => Store.increment(backing, key, options),
           list: (options) => backing.list(options),
           put: (key, value, options) => backing.put(key, value, options),
+          swap: (key, expected, next, options) => backing.swap!(key, expected, next, options),
         } satisfies Store.durableObject.Stub
         return new Proxy(stub, {
           get(target, method: string) {
@@ -286,6 +374,90 @@ describe('durableObject', () => {
     )
   })
 
+  test('retries a retryable stub error once on a fresh stub', async () => {
+    let stubs = 0
+    let failures = 1
+    const backing = Store.memory()
+    const namespace = {
+      getByName() {
+        stubs += 1
+        return {
+          ...stubFor(backing),
+          increment: (key, options) => {
+            if (failures > 0) {
+              failures -= 1
+              throw Object.assign(new Error('Network connection lost.'), { retryable: true })
+            }
+            return Store.increment(backing, key, options)
+          },
+        }
+      },
+    } satisfies Store.durableObject.Namespace
+    const store = Store.durableObject(namespace, { name: 'tempo-api' })
+
+    expect(await Store.increment(store, 'counter')).toMatchInlineSnapshot(`1`)
+    // One stub per attempt: a stub that threw is disconnected.
+    expect(stubs).toMatchInlineSnapshot(`2`)
+  })
+
+  test('propagates a retryable stub error when the retry also fails', async () => {
+    let attempts = 0
+    const namespace = {
+      getByName() {
+        return {
+          ...stubFor(Store.memory()),
+          increment: () => {
+            attempts += 1
+            throw Object.assign(new Error('Network connection lost.'), { retryable: true })
+          },
+        }
+      },
+    } satisfies Store.durableObject.Namespace
+    const store = Store.durableObject(namespace, { name: 'tempo-api' })
+
+    await expect(Store.increment(store, 'counter')).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Network connection lost.]`,
+    )
+    expect(attempts).toMatchInlineSnapshot(`2`)
+  })
+
+  test('does not retry non-retryable or overloaded stub errors', async () => {
+    let attempts = 0
+    const namespaceFor = (error: Error) =>
+      ({
+        getByName() {
+          return {
+            ...stubFor(Store.memory()),
+            increment: () => {
+              attempts += 1
+              throw error
+            },
+          }
+        },
+      }) satisfies Store.durableObject.Namespace
+
+    const plain = Store.durableObject(namespaceFor(new Error('boom')), { name: 'tempo-api' })
+    await expect(Store.increment(plain, 'counter')).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: boom]`,
+    )
+    expect(attempts).toMatchInlineSnapshot(`1`)
+
+    attempts = 0
+    const overloaded = Store.durableObject(
+      namespaceFor(
+        Object.assign(new Error('Durable Object is overloaded.'), {
+          overloaded: true,
+          retryable: true,
+        }),
+      ),
+      { name: 'tempo-api' },
+    )
+    await expect(Store.increment(overloaded, 'counter')).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Durable Object is overloaded.]`,
+    )
+    expect(attempts).toMatchInlineSnapshot(`1`)
+  })
+
   test('defers missing namespace failures until an operation is attempted', async () => {
     const store = Store.durableObject(undefined as unknown as Store.durableObject.Namespace, {
       name: 'tempo-api',