@ouraihub/aether-worker 0.1.0 → 0.1.2

package/src/coordinator-helpers.ts

@@ -0,0 +1,131 @@
+import {
+  isContract,
+  type EndStatus,
+  type KitError,
+  type RunEvent,
+  type RunSnapshot,
+} from '@ouraihub/aether-contracts'
+import { KitFailure } from '@ouraihub/aether-core'
+import { immutableActor, isActor, type Actor } from './context.js'
+import type { AcceptedHandle } from './conversations/index.js'
+
+export type Phase = 'creating' | 'accepted' | 'running' | EndStatus
+export interface Metadata {
+  phase: Phase
+  runId: string
+  actor: Actor
+  handle: AcceptedHandle | null
+  snapshot: RunSnapshot
+  revision: number
+  acceptedUntil: number | null
+  pending: { callId: string; revision: number } | null
+}
+export interface Pending {
+  callId: string
+  revision: number
+  decision: boolean | undefined
+  resolve: ((decision: boolean) => void) | null
+}
+
+export const storageKey = 'run'
+export const encoder = new TextEncoder()
+export const conflict = (reason: string): KitFailure =>
+  new KitFailure('conflict', 'Run state conflict', { reason })
+export const missing = (): KitFailure => new KitFailure('not_found', 'Run not found')
+export const interrupted = (newId: () => string): KitError => ({
+  code: 'internal',
+  message: 'Run interrupted',
+  details: { reason: 'interrupted', errorId: newId() },
+})
+
+/** No arbitrary messages/details cross this boundary, even from host KitFailures. */
+export function publicError(error: unknown, newId: () => string): KitError {
+  const code =
+    error instanceof KitFailure
+      ? error.code
+      : isContract('KitError', error)
+        ? error.code
+        : 'internal'
+  const messages: Record<KitError['code'], string> = {
+    bad_request: 'Invalid request',
+    not_found: 'Run not found',
+    conflict: 'Run state conflict',
+    unsupported: 'Unsupported operation',
+    cancelled: 'Cancelled',
+    unauthorized: 'Authentication required',
+    forbidden: 'Access denied',
+    rate_limited: 'Rate limit exceeded',
+    upstream: 'Upstream execution failed',
+    timeout: 'Execution timed out',
+    network: 'Network execution failed',
+    needs_config: 'Configuration required',
+    budget_exceeded: 'Execution budget exceeded',
+    incompatible_db: 'Incompatible database',
+    internal: 'Internal execution failure',
+  }
+  // Error IDs are generated here, never copied from a potentially secret-bearing host error.
+  const reason = error instanceof KitFailure ? error.details?.reason : undefined
+  const safeReason =
+    reason === 'event_replay_unavailable' ||
+    reason === 'subscriber_already_active' ||
+    reason === 'approval_not_pending'
+      ? reason
+      : undefined
+  return {
+    code,
+    message: messages[code],
+    ...(code === 'internal' || safeReason
+      ? {
+          details: {
+            ...(safeReason ? { reason: safeReason } : {}),
+            ...(code === 'internal' ? { errorId: newId() } : {}),
+          },
+        }
+      : {}),
+  }
+}
+export function statusCode(error: KitError): number {
+  switch (error.code) {
+    case 'bad_request':
+      return 400
+    case 'unauthorized':
+      return 401
+    case 'forbidden':
+      return 403
+    case 'not_found':
+      return 404
+    case 'conflict':
+      return 409
+    case 'rate_limited':
+      return 429
+    case 'internal':
+    case 'incompatible_db':
+      return 500
+    default:
+      return 422
+  }
+}
+export function actorHeader(request: Request): Actor {
+  try {
+    const encoded = request.headers.get('x-aether-actor')
+    if (!encoded || encoded.length > 131072) throw missing()
+    const bytes = Uint8Array.from(atob(encoded), (character) => character.charCodeAt(0))
+    const value: unknown = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+    if (!isActor(value)) throw missing()
+    return immutableActor(value)
+  } catch {
+    throw missing()
+  }
+}
+export function terminal(phase: Phase): phase is EndStatus {
+  return phase === 'completed' || phase === 'failed' || phase === 'cancelled'
+}
+export function endEvent(snapshot: RunSnapshot): RunEvent {
+  if (snapshot.status === 'running') throw conflict('run_not_terminal')
+  return {
+    kind: 'end',
+    status: snapshot.status,
+    ...(snapshot.error ? { error: snapshot.error } : {}),
+    ...(snapshot.exhausted === undefined ? {} : { exhausted: snapshot.exhausted }),
+  }
+}

package/src/coordinator.ts

@@ -1,125 +1,38 @@
-import { isContract, type EndStatus, type KitError, type RunEvent, type RunSnapshot } from '@ouraihub/aether-contracts'
+import { isContract, type RunEvent, type RunSnapshot } from '@ouraihub/aether-contracts'
 import { KitFailure, type Approver } from '@ouraihub/aether-core'
 import type { DurableObjectState } from './cloudflare.js'
 import { immutableActor, isActor, ownerKey, type Actor, type WorkerContext } from './context.js'
-import type { AcceptedHandle } from './conversations/index.js'
 import type { PreparedExecution, WorkerRuntime } from './runtime.js'
+import {
+  actorHeader,
+  conflict,
+  encoder,
+  endEvent,
+  interrupted,
+  missing,
+  publicError,
+  statusCode,
+  storageKey,
+  terminal,
+  type Metadata,
+  type Pending,
+} from './coordinator-helpers.js'
 
 type Runtime = Pick<WorkerRuntime, 'prepare' | 'execute' | 'abandon' | 'recover'>
-type Phase = 'creating' | 'accepted' | 'running' | EndStatus
-interface Metadata {
-  phase: Phase
-  runId: string
-  actor: Actor
-  handle: AcceptedHandle | null
-  snapshot: RunSnapshot
-  revision: number
-  acceptedUntil: number | null
-  pending: { callId: string; revision: number } | null
-}
-interface Pending {
-  callId: string
-  revision: number
-  decision: boolean | undefined
-  resolve: ((decision: boolean) => void) | null
-}
-const storageKey = 'run'
-const encoder = new TextEncoder()
-const conflict = (reason: string): KitFailure => new KitFailure('conflict', 'Run state conflict', { reason })
-const missing = (): KitFailure => new KitFailure('not_found', 'Run not found')
-const interrupted = (): KitError => ({
-  code: 'internal',
-  message: 'Run interrupted',
-  details: { reason: 'interrupted', errorId: crypto.randomUUID() },
-})
-
-/** No arbitrary messages/details cross this boundary, even from host KitFailures. */
-function publicError(error: unknown): KitError {
-  const code = error instanceof KitFailure ? error.code : isContract('KitError', error) ? error.code : 'internal'
-  const messages: Record<KitError['code'], string> = {
-    bad_request: 'Invalid request',
-    not_found: 'Run not found',
-    conflict: 'Run state conflict',
-    unsupported: 'Unsupported operation',
-    cancelled: 'Cancelled',
-    unauthorized: 'Authentication required',
-    forbidden: 'Access denied',
-    rate_limited: 'Rate limit exceeded',
-    upstream: 'Upstream execution failed',
-    timeout: 'Execution timed out',
-    network: 'Network execution failed',
-    needs_config: 'Configuration required',
-    budget_exceeded: 'Execution budget exceeded',
-    incompatible_db: 'Incompatible database',
-    internal: 'Internal execution failure',
-  }
-  // Error IDs are generated here, never copied from a potentially secret-bearing host error.
-  const reason = error instanceof KitFailure ? error.details?.reason : undefined
-  const safeReason =
-    reason === 'event_replay_unavailable' || reason === 'subscriber_already_active' || reason === 'approval_not_pending'
-      ? reason
-      : undefined
-  return {
-    code,
-    message: messages[code],
-    ...(code === 'internal' || safeReason
-      ? {
-          details: {
-            ...(safeReason ? { reason: safeReason } : {}),
-            ...(code === 'internal' ? { errorId: crypto.randomUUID() } : {}),
-          },
-        }
-      : {}),
-  }
-}
-function statusCode(error: KitError): number {
-  switch (error.code) {
-    case 'bad_request':
-      return 400
-    case 'unauthorized':
-      return 401
-    case 'forbidden':
-      return 403
-    case 'not_found':
-      return 404
-    case 'conflict':
-      return 409
-    case 'rate_limited':
-      return 429
-    case 'internal':
-    case 'incompatible_db':
-      return 500
-    default:
-      return 422
-  }
-}
-function actorHeader(request: Request): Actor {
-  try {
-    const encoded = request.headers.get('x-aether-actor')
-    if (!encoded || encoded.length > 131072) throw missing()
-    const bytes = Uint8Array.from(atob(encoded), (character) => character.charCodeAt(0))
-    const value: unknown = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
-    if (!isActor(value)) throw missing()
-    return immutableActor(value)
-  } catch {
-    throw missing()
-  }
-}
-function terminal(phase: Phase): phase is EndStatus {
-  return phase === 'completed' || phase === 'failed' || phase === 'cancelled'
-}
-function endEvent(snapshot: RunSnapshot): RunEvent {
-  if (snapshot.status === 'running') throw conflict('run_not_terminal')
-  return {
-    kind: 'end',
-    status: snapshot.status,
-    ...(snapshot.error ? { error: snapshot.error } : {}),
-    ...(snapshot.exhausted === undefined ? {} : { exhausted: snapshot.exhausted }),
-  }
+/** Time and identifiers the coordinator uses for leases, request ids and error ids. */
+export interface CoordinatorOptions {
+  /** Milliseconds since the epoch; drives the 30 s subscription lease and alarms. */
+  readonly now?: () => number
+  readonly newId?: () => string
 }
 
 /** The router alone constructs this private protocol after authentication. */
-export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime) {
+export function createRunCoordinator<Env>(
+  createRuntime: (env: Env) => Runtime,
+  options: CoordinatorOptions = {},
+) {
+  const now = options.now ?? Date.now
+  const newId = options.newId ?? (() => crypto.randomUUID())
   return class RunCoordinator {
     private readonly state: DurableObjectState
     private readonly runtime: Runtime
@@ -147,12 +60,16 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
           try {
             await this.runtime.recover(record.handle, this.context(record.actor))
           } catch (error) {
-            if (!(record.phase === 'creating' && error instanceof KitFailure && error.code === 'not_found'))
+            if (!(
+              record.phase === 'creating' &&
+              error instanceof KitFailure &&
+              error.code === 'not_found'
+            ))
               recoveryFailure = error
           }
         }
         record.phase = 'failed'
-        record.snapshot = { ...record.snapshot, status: 'failed', error: interrupted() }
+        record.snapshot = { ...record.snapshot, status: 'failed', error: interrupted(newId) }
         record.pending = null
         record.acceptedUntil = null
         await this.persist()
@@ -162,7 +79,7 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
     }
 
     private context(actor: Actor): WorkerContext {
-      return { actor, signal: this.abort.signal, requestId: crypto.randomUUID(), now: Date.now() }
+      return { actor, signal: this.abort.signal, requestId: newId(), now: now() }
     }
     private serialize<T>(action: () => Promise<T>): Promise<T> {
       const result = this.queue.then(action)
@@ -189,9 +106,12 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
       if (!controller) return
       try {
         // Bound an unread subscriber rather than retaining an unbounded transcript in memory.
-        if (controller.desiredSize !== null && controller.desiredSize <= 0) throw new Error('Subscriber stalled')
+        if (controller.desiredSize !== null && controller.desiredSize <= 0)
+          throw new Error('Subscriber stalled')
         controller.enqueue(
-          encoder.encode(`event: run_event\nid: ${++this.sequence}\ndata: ${JSON.stringify(event)}\n\n`),
+          encoder.encode(
+            `event: run_event\nid: ${++this.sequence}\ndata: ${JSON.stringify(event)}\n\n`,
+          ),
         )
       } catch {
         this.close()
@@ -276,7 +196,7 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
           turnId: record.snapshot.turnId,
           status: snapshot.status,
           cancelRequested: record.snapshot.cancelRequested || snapshot.cancelRequested,
-          ...(snapshot.error ? { error: publicError(snapshot.error) } : {}),
+          ...(snapshot.error ? { error: publicError(snapshot.error, newId) } : {}),
           ...(snapshot.exhausted === undefined ? {} : { exhausted: snapshot.exhausted }),
         }
         record.phase = snapshot.status
@@ -306,7 +226,7 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
             throw recoveryError
         }
       }
-      await this.finish({ ...record.snapshot, status: 'failed', error: publicError(error) })
+      await this.finish({ ...record.snapshot, status: 'failed', error: publicError(error, newId) })
     }
     private async run(prepared: PreparedExecution, execute: boolean): Promise<void> {
       try {
@@ -369,7 +289,13 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
           revision: 0,
           pending: null,
           acceptedUntil: null,
-          snapshot: { runId, conversationId: null, turnId: null, status: 'running', cancelRequested: false },
+          snapshot: {
+            runId,
+            conversationId: null,
+            turnId: null,
+            status: 'running',
+            cancelRequested: false,
+          },
         }
         await this.persist()
       })
@@ -383,7 +309,8 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
         try {
           const prepared = await this.runtime.prepare(runId, input, this.context(actor), (handle) =>
             this.serialize(async () => {
-              if (!this.metadata || this.abort.signal.aborted) throw new KitFailure('cancelled', 'Cancelled')
+              if (!this.metadata || this.abort.signal.aborted)
+                throw new KitFailure('cancelled', 'Cancelled')
               this.metadata.handle = handle
               this.metadata.snapshot.conversationId = handle?.conversationId ?? null
               this.metadata.snapshot.turnId = handle?.turnId ?? null
@@ -401,7 +328,7 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
             this.metadata.phase = 'accepted'
             this.metadata.snapshot.conversationId = prepared.accepted.conversationId
             this.metadata.snapshot.turnId = prepared.accepted.turnId
-            this.metadata.acceptedUntil = Date.now() + 30000
+            this.metadata.acceptedUntil = now() + 30000
             await this.state.storage.setAlarm(this.metadata.acceptedUntil)
             await this.persist()
           })
@@ -477,7 +404,8 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
         // A rejected competing subscriber must never cancel the actual owner stream.
         if (
           this.owns(actor) &&
-          ((this.subscribed && !this.operation) || (this.metadata?.phase === 'accepted' && request.signal.aborted))
+          ((this.subscribed && !this.operation) ||
+            (this.metadata?.phase === 'accepted' && request.signal.aborted))
         ) {
           this.close()
           await this.cancelRun()
@@ -540,7 +468,7 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
         }
         throw missing()
       } catch (error) {
-        const safe = publicError(error)
+        const safe = publicError(error, newId)
         return Response.json(safe, { status: statusCode(safe) })
       }
     }
@@ -548,7 +476,7 @@ export function createRunCoordinator<Env>(createRuntime: (env: Env) => Runtime)
       await this.ready
       const record = this.metadata
       if (record?.phase === 'accepted' && record.acceptedUntil !== null) {
-        if (Date.now() >= record.acceptedUntil) await this.cancelRun()
+        if (now() >= record.acceptedUntil) await this.cancelRun()
         else
           await this.serialize(async () => {
             if (this.metadata?.phase === 'accepted' && this.metadata.acceptedUntil !== null)

package/src/credentials.ts

@@ -28,7 +28,8 @@ function base64(bytes: Uint8Array): string {
   return btoa(text)
 }
 function unbase64(text: string): Uint8Array<ArrayBuffer> {
-  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(text)) throw unreadable()
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(text))
+    throw unreadable()
   const bytes = Uint8Array.from(atob(text), (character) => character.charCodeAt(0))
   if (base64(bytes) !== text) throw unreadable()
   return bytes
@@ -64,7 +65,15 @@ function aad(scope: CredentialScope, keyId: string): Uint8Array<ArrayBuffer> {
   )
     throw badRequest('credentialScope', 'invalid')
   return new TextEncoder().encode(
-    JSON.stringify([1, keyId, scope.applicationId, scope.tenantId, scope.subjectId, scope.purpose, scope.recordId]),
+    JSON.stringify([
+      1,
+      keyId,
+      scope.applicationId,
+      scope.tenantId,
+      scope.subjectId,
+      scope.purpose,
+      scope.recordId,
+    ]),
   )
 }
 /** Supply non-extractable AES-GCM keys from deployment secrets/KMS; old keys are read-only until explicit rotation. */
@@ -100,7 +109,12 @@ export function createCredentialPort(options: {
         key,
         new Uint8Array(value),
       )
-      return { version: 1, keyId: currentKeyId, nonce: base64(nonce), ciphertext: base64(new Uint8Array(ciphertext)) }
+      return {
+        version: 1,
+        keyId: currentKeyId,
+        nonce: base64(nonce),
+        ciphertext: base64(new Uint8Array(ciphertext)),
+      }
     } catch {
       throw unreadable()
     }
@@ -112,7 +126,11 @@ export function createCredentialPort(options: {
       if (!key) throw unreadable()
       const nonce = unbase64(sealed.nonce)
       const ciphertext = unbase64(sealed.ciphertext)
-      if (nonce.byteLength !== 12 || ciphertext.byteLength < 16 || ciphertext.byteLength > MAX_BYTES + 16)
+      if (
+        nonce.byteLength !== 12 ||
+        ciphertext.byteLength < 16 ||
+        ciphertext.byteLength > MAX_BYTES + 16
+      )
         throw unreadable()
       return new Uint8Array(
         await crypto.subtle.decrypt(

package/src/files.ts

@@ -9,7 +9,11 @@ export interface StoredFile {
   readonly data: Uint8Array
 }
 export interface FileStore {
-  put(actor: Actor, id: string, file: { readonly mime: string; readonly data: Uint8Array }): Promise<StoredFile>
+  put(
+    actor: Actor,
+    id: string,
+    file: { readonly mime: string; readonly data: Uint8Array },
+  ): Promise<StoredFile>
   get(actor: Actor, id: string): Promise<StoredFile | null>
   remove(actor: Actor, id: string): Promise<void>
   /** An authenticated application route, never an R2 public/presigned secret URL. */
@@ -55,18 +59,26 @@ export class R2FileStore implements FileStore {
   readonly #bucket: R2Bucket
   readonly #maxBytes: number
   constructor(bucket: R2Bucket, options: { readonly maxBytes: number }) {
-    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0) throw badRequest('fileLimit', 'invalid')
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0)
+      throw badRequest('fileLimit', 'invalid')
     this.#bucket = bucket
     this.#maxBytes = options.maxBytes
   }
   async #key(actor: Actor, id: string): Promise<string> {
     fileId(id)
     const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(ownerKey(actor)))
-    const ownerHash = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
+    const ownerHash = Array.from(new Uint8Array(digest), (byte) =>
+      byte.toString(16).padStart(2, '0'),
+    ).join('')
     return `aether/files/v1/${ownerHash}/${id}`
   }
-  async put(actor: Actor, id: string, file: { readonly mime: string; readonly data: Uint8Array }): Promise<StoredFile> {
-    if (!MIME_TYPES[file.mime] || !matchesMime(file.data, file.mime)) throw badRequest('mime', 'unsupported')
+  async put(
+    actor: Actor,
+    id: string,
+    file: { readonly mime: string; readonly data: Uint8Array },
+  ): Promise<StoredFile> {
+    if (!MIME_TYPES[file.mime] || !matchesMime(file.data, file.mime))
+      throw badRequest('mime', 'unsupported')
     if (file.data.byteLength === 0 || file.data.byteLength > this.#maxBytes)
       throw badRequest('file', 'too_large', this.#maxBytes)
     const key = await this.#key(actor, id)

package/src/host.ts

@@ -1,12 +1,20 @@
 import type { Approval, ModelRef, PermissionMode, RunRequest } from '@ouraihub/aether-contracts'
-import type { AuthorizeContext, ToolCall, ToolExecution, ToolSpec } from '@ouraihub/aether-core/types'
+import type {
+  AuthorizeContext,
+  ToolCall,
+  ToolExecution,
+  ToolSpec,
+} from '@ouraihub/aether-core/types'
 import type { WorkerContext } from './context.js'
 
 /** Business authorization remains the host's responsibility for every actor and resource. */
 export interface WorkerHost {
   selectModel(request: RunRequest, context: WorkerContext): Promise<ModelRef>
   systemPrompt(request: RunRequest, context: WorkerContext): Promise<string | null>
-  context(request: RunRequest, context: WorkerContext): Promise<{ source: string; text: string } | null>
+  context(
+    request: RunRequest,
+    context: WorkerContext,
+  ): Promise<{ source: string; text: string } | null>
   tools(request: RunRequest, runId: string, context: WorkerContext): Promise<readonly ToolSpec[]>
   permissionModes(request: RunRequest, context: WorkerContext): readonly PermissionMode[]
   authorize(call: ToolCall, authorization: AuthorizeContext, context: WorkerContext): Approval

package/src/identity.ts

@@ -1,5 +1,6 @@
 import { badRequest, KitFailure } from '@ouraihub/aether-core'
 import { immutableActor, isActor, ownerKey, type Actor } from './context.ts'
+import { retryCas } from './storage.ts'
 import type { DocumentStore, StoredDocument } from './storage.ts'
 
 export interface IdentityPort {
@@ -12,11 +13,14 @@ export function createIdentityPort(options: {
   readonly resolve: (request: Request) => Promise<Actor | null>
   readonly verifyFresh: (request: Request, actor: Actor) => Promise<boolean>
 }): IdentityPort {
-  if (!options.applicationId) throw new KitFailure('needs_config', 'Identity application is required')
+  if (!options.applicationId)
+    throw new KitFailure('needs_config', 'Identity application is required')
   return Object.freeze({
     async resolve(request: Request): Promise<Actor | null> {
       const actor = await options.resolve(request)
-      return isActor(actor) && actor.applicationId === options.applicationId ? immutableActor(actor) : null
+      return isActor(actor) && actor.applicationId === options.applicationId
+        ? immutableActor(actor)
+        : null
     },
     async verifyFresh(request: Request, actor: Actor): Promise<boolean> {
       if (!isActor(actor) || actor.applicationId !== options.applicationId) return false
@@ -61,10 +65,17 @@ function parseSession(value: unknown): SessionRecord | null {
     value.expiresAt <= value.lastSeenAt
   )
     return null
-  return { actor: value.actor, createdAt: value.createdAt, lastSeenAt: value.lastSeenAt, expiresAt: value.expiresAt }
+  return {
+    actor: value.actor,
+    createdAt: value.createdAt,
+    lastSeenAt: value.lastSeenAt,
+    expiresAt: value.expiresAt,
+  }
 }
 function opaqueToken(): string {
-  return Array.from(crypto.getRandomValues(new Uint8Array(32)), (byte) => byte.toString(16).padStart(2, '0')).join('')
+  return Array.from(crypto.getRandomValues(new Uint8Array(32)), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('')
 }
 async function tokenKey(token: string): Promise<string | null> {
   if (!/^[a-f0-9]{64}$/u.test(token)) return null
@@ -106,8 +117,14 @@ export class OpaqueSessionStore {
     this.#absoluteMs = options.absoluteMs
     this.#now = options.now ?? Date.now
   }
-  async issue(actor: Actor): Promise<{ readonly token: string; readonly actor: Actor; readonly expiresAt: number }> {
-    if (!isActor(actor) || actor.kind !== 'user' || actor.applicationId !== this.#registry.applicationId)
+  async issue(
+    actor: Actor,
+  ): Promise<{ readonly token: string; readonly actor: Actor; readonly expiresAt: number }> {
+    if (
+      !isActor(actor) ||
+      actor.kind !== 'user' ||
+      actor.applicationId !== this.#registry.applicationId
+    )
       throw badRequest('actor', 'invalid_session_owner')
     const token = opaqueToken()
     const key = await tokenKey(token)
@@ -123,9 +140,11 @@ export class OpaqueSessionStore {
     })
     return { token, actor: sessionActor, expiresAt }
   }
-  async #load(
-    token: string,
-  ): Promise<{ readonly key: string; readonly document: StoredDocument; readonly session: SessionRecord } | null> {
+  async #load(token: string): Promise<{
+    readonly key: string
+    readonly document: StoredDocument
+    readonly session: SessionRecord
+  } | null> {
     const key = await tokenKey(token)
     if (key === null) return null
     const document = await this.#store.get(this.#registry, 'opaque_sessions', key)
@@ -146,10 +165,16 @@ export class OpaqueSessionStore {
     const found = await this.#load(token)
     if (!found) return null
     try {
-      await this.#store.compareAndSet(this.#registry, 'opaque_sessions', found.key, found.document.revision, {
-        ...found.session,
-        lastSeenAt: this.#now(),
-      })
+      await this.#store.compareAndSet(
+        this.#registry,
+        'opaque_sessions',
+        found.key,
+        found.document.revision,
+        {
+          ...found.session,
+          lastSeenAt: this.#now(),
+        },
+      )
       return immutableActor(found.session.actor)
     } catch (error) {
       if (error instanceof KitFailure && error.code === 'conflict') return null
@@ -160,17 +185,16 @@ export class OpaqueSessionStore {
     const key = await tokenKey(token)
     if (key === null) return
     // Retry only metadata CAS, never authentication or external side effects.
-    for (let attempt = 0; attempt < 8; attempt++) {
-      const document = await this.#store.get(this.#registry, 'opaque_sessions', key)
-      if (!document) return
-      try {
-        await this.#store.remove(this.#registry, 'opaque_sessions', key, document.revision)
-        return
-      } catch (error) {
-        if (!(error instanceof KitFailure) || error.code !== 'conflict') throw error
-      }
-    }
-    throw new KitFailure('conflict', 'Session revocation conflicted')
+    await retryCas(
+      async (cas) => {
+        const document = await this.#store.get(this.#registry, 'opaque_sessions', key)
+        if (document)
+          await cas(() =>
+            this.#store.remove(this.#registry, 'opaque_sessions', key, document.revision),
+          )
+      },
+      () => new KitFailure('conflict', 'Session revocation conflicted'),
+    )
   }
   async rotate(
     token: string,
@@ -178,7 +202,12 @@ export class OpaqueSessionStore {
     const found = await this.#load(token)
     if (!found) return null
     try {
-      await this.#store.remove(this.#registry, 'opaque_sessions', found.key, found.document.revision)
+      await this.#store.remove(
+        this.#registry,
+        'opaque_sessions',
+        found.key,
+        found.document.revision,
+      )
     } catch (error) {
       if (error instanceof KitFailure && error.code === 'conflict') return null
       throw error