@ouraihub/aether-worker 0.1.0 → 0.1.2

package/src/search/index.ts

@@ -83,7 +83,12 @@ function parseProvider(value: unknown): ProviderRecord {
       : { basicAuthUsername: string(data.basicAuthUsername, 'basicAuthUsername') }),
   }
 }
-function scope(actor: Actor, capability: SearchCap, provider: string, keyId: string): CredentialScope {
+function scope(
+  actor: Actor,
+  capability: SearchCap,
+  provider: string,
+  keyId: string,
+): CredentialScope {
   return {
     applicationId: actor.applicationId,
     tenantId: actor.tenantId,
@@ -114,7 +119,11 @@ export class SearchService {
     provider: string,
   ): Promise<{ document: StoredDocument | null; value: ProviderRecord }> {
     providerFor(capability, provider)
-    const document = await this.options.documents.get(actor, 'search.providers', partition(capability, provider))
+    const document = await this.options.documents.get(
+      actor,
+      'search.providers',
+      partition(capability, provider),
+    )
     return { document, value: document ? parseProvider(document.value) : { keys: [] } }
   }
   async preferences(actor: Actor): Promise<SearchPreferences> {
@@ -141,11 +150,20 @@ export class SearchService {
     providerFor(capability, provider)
     return provider
   }
-  private async open(actor: Actor, capability: SearchCap, provider: string, key: KeyRecord): Promise<string> {
-    const bytes = await this.options.credentials.open(scope(actor, capability, provider, key.id), key.sealed)
+  private async open(
+    actor: Actor,
+    capability: SearchCap,
+    provider: string,
+    key: KeyRecord,
+  ): Promise<string> {
+    const bytes = await this.options.credentials.open(
+      scope(actor, capability, provider, key.id),
+      key.sealed,
+    )
     try {
       const value = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
-      if (!value.trim() || value.length > 4096) throw new KitFailure('needs_config', 'Search credential unavailable')
+      if (!value.trim() || value.length > 4096)
+        throw new KitFailure('needs_config', 'Search credential unavailable')
       return value
     } finally {
       bytes.fill(0)
@@ -180,7 +198,8 @@ export class SearchService {
         ...(value.baseUrl ? { baseUrl: value.baseUrl } : {}),
         ...(value.basicAuthUsername ? { basicAuthUsername: value.basicAuthUsername } : {}),
         keys,
-        ready: (config.keyMode !== 'required' || readable > 0) && (!value.keys.length || readable > 0),
+        ready:
+          (config.keyMode !== 'required' || readable > 0) && (!value.keys.length || readable > 0),
       })
     }
     return {
@@ -200,13 +219,15 @@ export class SearchService {
       const baseUrl = string(data.baseUrl, 'baseUrl').trim()
       if (new TextEncoder().encode(string(data.baseUrl, 'baseUrl')).length > 8192)
         throw badRequest('baseUrl', 'too_long', 8192)
-      if (provider !== 'fetch' && baseUrl) await this.options.checkTarget(validateTarget(baseUrl), signal)
+      if (provider !== 'fetch' && baseUrl)
+        await this.options.checkTarget(validateTarget(baseUrl), signal)
       delete value.baseUrl
       if (provider !== 'fetch' && baseUrl) value.baseUrl = baseUrl
     }
     if (data.basicAuthUsername !== undefined) {
       const username = string(data.basicAuthUsername, 'basicAuthUsername').trim()
-      if (new TextEncoder().encode(username).length > 200) throw badRequest('basicAuthUsername', 'too_long', 200)
+      if (new TextEncoder().encode(username).length > 200)
+        throw badRequest('basicAuthUsername', 'too_long', 200)
       if (!spec.basicAuth && username) throw badRequest('basicAuthUsername', 'unsupported')
       delete value.basicAuthUsername
       if (spec.basicAuth && username) value.basicAuthUsername = username
@@ -220,12 +241,22 @@ export class SearchService {
     )
     return this.settings(actor, capability)
   }
-  async setDefault(actor: Actor, capability: SearchCap, provider: string): Promise<SearchSettingsDto> {
+  async setDefault(
+    actor: Actor,
+    capability: SearchCap,
+    provider: string,
+  ): Promise<SearchSettingsDto> {
     providerFor(capability, provider)
     const old = await this.options.documents.get(actor, 'search.defaults', capability)
-    await this.options.documents.compareAndSet(actor, 'search.defaults', capability, old?.revision ?? null, {
-      provider,
-    })
+    await this.options.documents.compareAndSet(
+      actor,
+      'search.defaults',
+      capability,
+      old?.revision ?? null,
+      {
+        provider,
+      },
+    )
     return this.settings(actor, capability)
   }
   async saveKey(
@@ -241,7 +272,8 @@ export class SearchService {
     if (!plaintext || plaintext.length > 4096) throw badRequest('value', 'invalid', 4096)
     const { document, value } = await this.stored(actor, capability, provider)
     const existing = keyId === undefined ? undefined : value.keys.find((key) => key.id === keyId)
-    if (keyId !== undefined && !existing) throw new KitFailure('not_found', 'Search key not found', { field: 'key' })
+    if (keyId !== undefined && !existing)
+      throw new KitFailure('not_found', 'Search key not found', { field: 'key' })
     if (!existing && value.keys.length >= 16) throw badRequest('keys', 'too_many', 16)
     const id = keyId ?? crypto.randomUUID()
     const bytes = new TextEncoder().encode(plaintext)
@@ -262,7 +294,12 @@ export class SearchService {
     )
     return this.settings(actor, capability)
   }
-  async removeKey(actor: Actor, capability: SearchCap, provider: string, keyId: string): Promise<SearchSettingsDto> {
+  async removeKey(
+    actor: Actor,
+    capability: SearchCap,
+    provider: string,
+    keyId: string,
+  ): Promise<SearchSettingsDto> {
     const { document, value } = await this.stored(actor, capability, provider)
     if (!value.keys.some((key) => key.id === keyId))
       throw new KitFailure('not_found', 'Search key not found', { field: 'key' })
@@ -298,7 +335,10 @@ export class SearchService {
     const { document, value } = await this.stored(actor, capability, provider)
     if (!document) return
     for (const key of value.keys)
-      key.sealed = await this.options.credentials.rotate(scope(actor, capability, provider, key.id), key.sealed)
+      key.sealed = await this.options.credentials.rotate(
+        scope(actor, capability, provider, key.id),
+        key.sealed,
+      )
     await this.options.documents.compareAndSet(
       actor,
       'search.providers',
@@ -307,7 +347,11 @@ export class SearchService {
       value,
     )
   }
-  async resolve(actor: Actor, capability: SearchCap, explicitProvider?: string): Promise<ResolvedSearchConfig> {
+  async resolve(
+    actor: Actor,
+    capability: SearchCap,
+    explicitProvider?: string,
+  ): Promise<ResolvedSearchConfig> {
     const provider = explicitProvider ?? (await this.selected(actor, capability))
     const { config } = providerFor(capability, provider)
     const { value } = await this.stored(actor, capability, provider)
@@ -339,12 +383,29 @@ export class SearchService {
   }
   async fetch(actor: Actor, rawUrl: string, signal?: AbortSignal): Promise<SearchPage> {
     const url = validateTarget(rawUrl)
-    return fetchPage(await this.resolve(actor, 'fetch'), url, this.options.outbound, this.options.checkTarget, signal)
+    return fetchPage(
+      await this.resolve(actor, 'fetch'),
+      url,
+      this.options.outbound,
+      this.options.checkTarget,
+      signal,
+    )
   }
-  async check(actor: Actor, capability: SearchCap, provider: string, signal?: AbortSignal): Promise<{ count: number }> {
+  async check(
+    actor: Actor,
+    capability: SearchCap,
+    provider: string,
+    signal?: AbortSignal,
+  ): Promise<{ count: number }> {
     const snapshot = await this.resolve(actor, capability, provider)
     if (capability === 'fetch') {
-      await fetchPage(snapshot, 'https://example.com', this.options.outbound, this.options.checkTarget, signal)
+      await fetchPage(
+        snapshot,
+        'https://example.com',
+        this.options.outbound,
+        this.options.checkTarget,
+        signal,
+      )
       return { count: 1 }
     }
     const result = await searchQuery(snapshot, 'web search', this.options.outbound, signal)
@@ -374,7 +435,8 @@ export class SearchService {
       search: 'POST',
       fetch: 'POST',
     }
-    if (!methods[route] || request.method !== methods[route]) throw badRequest('route', 'unsupported')
+    if (!methods[route] || request.method !== methods[route])
+      throw badRequest('route', 'unsupported')
     if (url.search) throw badRequest('query', 'unsupported')
     let raw: unknown
     try {
@@ -403,8 +465,10 @@ export class SearchService {
     const data = input(raw, names)
     const capability = cap(data.capability)
     const provider = string(data.provider, 'provider')
-    if (route === 'default') return Response.json(await this.setDefault(actor, capability, provider))
-    if (route === 'check') return Response.json(await this.check(actor, capability, provider, signal))
+    if (route === 'default')
+      return Response.json(await this.setDefault(actor, capability, provider))
+    if (route === 'check')
+      return Response.json(await this.check(actor, capability, provider, signal))
     if (route === 'keys/reveal')
       return Response.json(
         await this.reveal(
@@ -417,7 +481,9 @@ export class SearchService {
         ),
       )
     if (request.method === 'DELETE')
-      return Response.json(await this.removeKey(actor, capability, provider, string(data.keyId, 'keyId')))
+      return Response.json(
+        await this.removeKey(actor, capability, provider, string(data.keyId, 'keyId')),
+      )
     return Response.json(
       await this.saveKey(
         actor,

package/src/skills/persistence.ts

@@ -1,7 +1,11 @@
 import type { SkillMeta } from '@ouraihub/aether-contracts'
 import { KitFailure } from '@ouraihub/aether-core'
 import { digest, sha256 } from '@ouraihub/aether-core/skills/content'
-import { parseCatalog, type SkillCatalog, type SkillRecord } from '@ouraihub/aether-core/skills/service'
+import {
+  parseCatalog,
+  type SkillCatalog,
+  type SkillRecord,
+} from '@ouraihub/aether-core/skills/service'
 import { exact, object, revision, text } from '@ouraihub/aether-core/skills/validation'
 import type { Actor } from '../context.js'
 import type { FileStore } from '../files.js'
@@ -97,15 +101,23 @@ function decode(value: unknown): number[] {
 }
 export function serializeSkill(skill: SkillRecord): Uint8Array {
   return new TextEncoder().encode(
-    JSON.stringify({ ...skill, files: skill.files.map((file) => ({ ...file, bytes: encode(file.bytes) })) }),
+    JSON.stringify({
+      ...skill,
+      files: skill.files.map((file) => ({ ...file, bytes: encode(file.bytes) })),
+    }),
   )
 }
-export async function loadSkills(files: FileStore, actor: Actor, value: unknown): Promise<LoadedSkills> {
+export async function loadSkills(
+  files: FileStore,
+  actor: Actor,
+  value: unknown,
+): Promise<LoadedSkills> {
   const refs = parseRefs(value)
   const catalog: SkillRecord[] = []
   for (const ref of refs) {
     const blob = await files.get(actor, ref.blobId)
-    if (!blob || blob.mime !== 'application/json') throw new KitFailure('internal', 'Skill package is unavailable')
+    if (!blob || blob.mime !== 'application/json')
+      throw new KitFailure('internal', 'Skill package is unavailable')
     let parsed: unknown
     try {
       parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(blob.data))
@@ -133,7 +145,8 @@ export async function loadSkills(files: FileStore, actor: Actor, value: unknown)
       if ((await sha256(new Uint8Array(file.bytes))) !== file.sha256)
         throw new KitFailure('internal', 'Skill file integrity failure')
     }
-    if ((await digest(skill, skill.files)) !== skill.digest) throw new KitFailure('internal', 'Skill integrity failure')
+    if ((await digest(skill, skill.files)) !== skill.digest)
+      throw new KitFailure('internal', 'Skill integrity failure')
     catalog.push(skill)
   }
   return { catalog, refs }

package/src/skills/service.ts

@@ -2,18 +2,35 @@ import type { ManualSave, SkillRef } from '@ouraihub/aether-contracts'
 import { badRequest, KitFailure } from '@ouraihub/aether-core'
 import { readSkillSource } from '@ouraihub/aether-core/skills/package'
 import * as skills from '@ouraihub/aether-core/skills/service'
-import { exact, object, parseManualSave, revision, strings, text } from '@ouraihub/aether-core/skills/validation'
+import {
+  exact,
+  object,
+  parseManualSave,
+  revision,
+  strings,
+  text,
+} from '@ouraihub/aether-core/skills/validation'
 import type { Actor, WorkerContext } from '../context.js'
 import type { DocumentStore } from '../storage.js'
 import type { FileStore } from '../files.js'
-import { loadSkills, parseRefs, serializeSkill, type LoadedSkills, type SkillBlobRef } from './persistence.js'
+import {
+  loadSkills,
+  parseRefs,
+  serializeSkill,
+  type LoadedSkills,
+  type SkillBlobRef,
+} from './persistence.js'
 
 /** All catalog mutations commit in one actor-scoped CAS; conflicts never overwrite newer content. */
 export class SkillsService {
   private readonly store: DocumentStore
   private readonly blobs: FileStore
   private readonly builtins: readonly skills.BuiltinSkill[]
-  constructor(store: DocumentStore, blobs: FileStore, builtins: readonly skills.BuiltinSkill[] = []) {
+  constructor(
+    store: DocumentStore,
+    blobs: FileStore,
+    builtins: readonly skills.BuiltinSkill[] = [],
+  ) {
     this.store = store
     this.blobs = blobs
     this.builtins = builtins
@@ -35,7 +52,10 @@ export class SkillsService {
           continue
         }
         const blobId = crypto.randomUUID()
-        await this.blobs.put(actor, blobId, { mime: 'application/json', data: serializeSkill(skill) })
+        await this.blobs.put(actor, blobId, {
+          mime: 'application/json',
+          data: serializeSkill(skill),
+        })
         created.push(blobId)
         refs.push({ ...skills.metadata(skill), blobId, digest: skill.digest })
       }
@@ -49,9 +69,15 @@ export class SkillsService {
       throw error
     }
   }
-  private async load(actor: Actor, now: number): Promise<LoadedSkills & { revision: number | null }> {
+  private async load(
+    actor: Actor,
+    now: number,
+  ): Promise<LoadedSkills & { revision: number | null }> {
     const document = await this.store.get(actor, 'skills', 'catalog')
-    const current = document === null ? { catalog: [], refs: [] } : await loadSkills(this.blobs, actor, document.value)
+    const current =
+      document === null
+        ? { catalog: [], refs: [] }
+        : await loadSkills(this.blobs, actor, document.value)
     const synced = await skills.syncBuiltins(current.catalog, this.builtins, now)
     if (synced === current.catalog) return { ...current, revision: document?.revision ?? null }
     const saved = await this.commit(actor, current, synced, document?.revision ?? null)
@@ -71,7 +97,8 @@ export class SkillsService {
     if (this.builtins.length !== 0) return skills.list((await this.load(actor, now)).catalog)
     const document = await this.store.get(actor, 'skills', 'catalog')
     const refs = document === null ? [] : parseRefs(document.value)
-    if (refs.some((ref) => ref.origin === 'builtin')) return skills.list((await this.load(actor, now)).catalog)
+    if (refs.some((ref) => ref.origin === 'builtin'))
+      return skills.list((await this.load(actor, now)).catalog)
     return refs.map((ref) => ({
       id: ref.id,
       name: ref.name,
@@ -101,9 +128,18 @@ export class SkillsService {
     const content = await readSkillSource(source)
     return skills.preview((await this.load(actor, now)).catalog, content)
   }
-  async install(actor: Actor, source: unknown, confirmedDigest: string, replace: boolean, newId: string, now: number) {
+  async install(
+    actor: Actor,
+    source: unknown,
+    confirmedDigest: string,
+    replace: boolean,
+    newId: string,
+    now: number,
+  ) {
     const content = await readSkillSource(source)
-    return this.mutate(actor, now, (catalog) => skills.install(catalog, content, confirmedDigest, replace, newId, now))
+    return this.mutate(actor, now, (catalog) =>
+      skills.install(catalog, content, confirmedDigest, replace, newId, now),
+    )
   }
   async save(actor: Actor, input: ManualSave, newId: string, now: number) {
     const checked = parseManualSave(input)
@@ -132,11 +168,21 @@ export class SkillsService {
       const id = decodeURIComponent(parts[0] ?? '')
       if (parts.length === 1) return Response.json(await this.get(actor, id, now))
       const expected = revision(Number(url.searchParams.get('revision')))
-      if (parts.length === 2 && parts[1] === 'files') return Response.json(await this.files(actor, id, expected, now))
+      if (parts.length === 2 && parts[1] === 'files')
+        return Response.json(await this.files(actor, id, expected, now))
       if (parts.length === 2 && parts[1] === 'file') {
-        const bytes = await this.file(actor, id, expected, text(url.searchParams.get('path'), 'path'), now)
+        const bytes = await this.file(
+          actor,
+          id,
+          expected,
+          text(url.searchParams.get('path'), 'path'),
+          now,
+        )
         return new Response(bytes, {
-          headers: { 'Content-Type': 'application/octet-stream', 'X-Content-Type-Options': 'nosniff' },
+          headers: {
+            'Content-Type': 'application/octet-stream',
+            'X-Content-Type-Options': 'nosniff',
+          },
         })
       }
     }
@@ -149,7 +195,8 @@ export class SkillsService {
       } catch {
         throw badRequest('body', 'invalid_json')
       }
-      if (path === '/save') return Response.json(await this.save(actor, parseManualSave(raw), crypto.randomUUID(), now))
+      if (path === '/save')
+        return Response.json(await this.save(actor, parseManualSave(raw), crypto.randomUUID(), now))
       const body = object(raw, 'body')
       if (path === '/preview') {
         exact(body, ['source'], 'body')

package/src/storage.ts

@@ -13,7 +13,11 @@ export interface DocumentListOptions {
 }
 export interface DocumentStore {
   get(owner: Actor, collection: string, key: string): Promise<StoredDocument | null>
-  list(owner: Actor, collection: string, options?: DocumentListOptions): Promise<readonly StoredDocument[]>
+  list(
+    owner: Actor,
+    collection: string,
+    options?: DocumentListOptions,
+  ): Promise<readonly StoredDocument[]>
   compareAndSet(
     owner: Actor,
     collection: string,
@@ -32,19 +36,34 @@ function revision(value: number): void {
   if (!Number.isSafeInteger(value) || value < 1 || value >= Number.MAX_SAFE_INTEGER)
     throw badRequest('revision', 'invalid')
 }
-function scope(owner: Actor, collection: string): readonly [string, string, string, string, string] {
+function scope(
+  owner: Actor,
+  collection: string,
+): readonly [string, string, string, string, string] {
   identifier(collection)
-  return [owner.applicationId, JSON.stringify(owner.tenantId), owner.subjectId, ownerKey(owner), collection]
+  return [
+    owner.applicationId,
+    JSON.stringify(owner.tenantId),
+    owner.subjectId,
+    ownerKey(owner),
+    collection,
+  ]
 }
 export async function validateD1Schema(database: D1Database): Promise<void> {
   let row: unknown
   try {
     row = await database.prepare('SELECT version FROM aether_schema WHERE singleton = 1').first()
   } catch {
-    throw new KitFailure('incompatible_db', 'Apply the supported Aether public migration before startup')
+    throw new KitFailure(
+      'incompatible_db',
+      'Apply the supported Aether public migration before startup',
+    )
   }
   if (typeof row !== 'object' || row === null || !('version' in row) || row.version !== 1) {
-    throw new KitFailure('incompatible_db', 'Apply the supported Aether public migration before startup')
+    throw new KitFailure(
+      'incompatible_db',
+      'Apply the supported Aether public migration before startup',
+    )
   }
 }
 /** D1 rows stay below its 2,000,000 byte limit. Large functional documents live
@@ -56,7 +75,10 @@ export class D1DocumentStore implements DocumentStore {
   readonly #database: D1Database
   readonly #blobs: R2Bucket | undefined
   readonly #maxBytes: number
-  constructor(database: D1Database, options: { readonly blobs?: R2Bucket; readonly maxDocumentBytes?: number } = {}) {
+  constructor(
+    database: D1Database,
+    options: { readonly blobs?: R2Bucket; readonly maxDocumentBytes?: number } = {},
+  ) {
     this.#database = database
     this.#blobs = options.blobs
     this.#maxBytes = options.maxDocumentBytes ?? 64 * 1024 * 1024
@@ -85,10 +107,14 @@ export class D1DocumentStore implements DocumentStore {
     if (typeof row.value_json === 'string' && row.blob_key === null) json = row.value_json
     else if (row.value_json === null && typeof row.blob_key === 'string' && this.#blobs) {
       const prefix = await this.#blobPrefix(owner)
-      if (!row.blob_key.startsWith(prefix) || !/^[a-f0-9-]{36}$/u.test(row.blob_key.slice(prefix.length)))
+      if (
+        !row.blob_key.startsWith(prefix) ||
+        !/^[a-f0-9-]{36}$/u.test(row.blob_key.slice(prefix.length))
+      )
         throw new KitFailure('internal', 'Stored document is unreadable')
       const blob = await this.#blobs.get(row.blob_key)
-      if (!blob || blob.size > this.#maxBytes) throw new KitFailure('internal', 'Stored document is unreadable')
+      if (!blob || blob.size > this.#maxBytes)
+        throw new KitFailure('internal', 'Stored document is unreadable')
       const bytes = await blob.arrayBuffer()
       if (bytes.byteLength !== blob.size || bytes.byteLength > this.#maxBytes)
         throw new KitFailure('internal', 'Stored document is unreadable')
@@ -113,9 +139,14 @@ export class D1DocumentStore implements DocumentStore {
       .first()
     return row === null ? null : this.#parse(owner, row)
   }
-  async list(owner: Actor, collection: string, options: DocumentListOptions = {}): Promise<readonly StoredDocument[]> {
+  async list(
+    owner: Actor,
+    collection: string,
+    options: DocumentListOptions = {},
+  ): Promise<readonly StoredDocument[]> {
     const limit = options.limit ?? MAX_LIST
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIST) throw badRequest('limit', 'invalid', MAX_LIST)
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIST)
+      throw badRequest('limit', 'invalid', MAX_LIST)
     if (options.after !== undefined) identifier(options.after)
     const result = await this.#database
       .prepare(
@@ -123,7 +154,8 @@ export class D1DocumentStore implements DocumentStore {
       )
       .bind(...scope(owner, collection), options.after ?? '', limit)
       .all()
-    if (!result.success || !Array.isArray(result.results)) throw new KitFailure('internal', 'Document listing failed')
+    if (!result.success || !Array.isArray(result.results))
+      throw new KitFailure('internal', 'Document listing failed')
     const documents: StoredDocument[] = []
     // Sequential hydration bounds R2 concurrency/memory to one document at a time.
     for (const row of result.results) documents.push(await this.#parse(owner, row))
@@ -151,7 +183,8 @@ export class D1DocumentStore implements DocumentStore {
     let inline: string | null = json
     let blobKey: string | null = null
     if (bytes.byteLength > INLINE_BYTES) {
-      if (!this.#blobs) throw new KitFailure('needs_config', 'Large documents require an R2 blob binding')
+      if (!this.#blobs)
+        throw new KitFailure('needs_config', 'Large documents require an R2 blob binding')
       blobKey = `${await this.#blobPrefix(owner)}${crypto.randomUUID()}`
       const written = await this.#blobs.put(blobKey, bytes, {
         httpMetadata: { contentType: 'application/json' },
@@ -184,7 +217,12 @@ export class D1DocumentStore implements DocumentStore {
     const parsed: unknown = JSON.parse(json)
     return { key, revision: row.revision, value: parsed }
   }
-  async remove(owner: Actor, collection: string, key: string, expectedRevision: number): Promise<void> {
+  async remove(
+    owner: Actor,
+    collection: string,
+    key: string,
+    expectedRevision: number,
+  ): Promise<void> {
     identifier(key)
     revision(expectedRevision)
     const row = await this.#database
@@ -196,3 +234,60 @@ export class D1DocumentStore implements DocumentStore {
     if (row === null) throw new KitFailure('conflict', 'Document revision conflict')
   }
 }
+
+export interface RetryOptions {
+  readonly attempts?: number
+  readonly baseMs?: number
+  /** Injected for deterministic tests; defaults to a real timer. */
+  readonly sleep?: (ms: number) => Promise<unknown>
+  readonly random?: () => number
+}
+/** Marks the store call inside a `retryCas` attempt; only its revision conflicts are retried. */
+export type CasCall = <T>(write: () => Promise<T>) => Promise<T>
+class RevisionConflict extends Error {}
+
+/**
+ * Runs `attempt` until its CAS write succeeds. Each attempt must reload and re-apply its change
+ * to the newest revision. Only a conflict raised by the `cas`-wrapped store call is retried;
+ * semantic conflicts from the attempt itself (stale preparation, finished turn) surface at once.
+ * Retries back off exponentially with jitter, so contending writers spread out instead of
+ * exhausting their attempts in lockstep.
+ */
+export async function retryCas<T>(
+  attempt: (cas: CasCall) => Promise<T>,
+  exhausted: () => KitFailure,
+  options: RetryOptions = {},
+): Promise<T> {
+  const attempts = options.attempts ?? 8,
+    baseMs = options.baseMs ?? 5,
+    random = options.random ?? Math.random
+  const sleep =
+    options.sleep ??
+    ((ms: number) => {
+      const { promise, resolve } = Promise.withResolvers<void>()
+      setTimeout(resolve, ms)
+      return promise
+    })
+  const cas: CasCall = async (write) => {
+    try {
+      return await write()
+    } catch (error) {
+      if (
+        error instanceof KitFailure &&
+        error.code === 'conflict' &&
+        error.details?.reason === undefined
+      )
+        throw new RevisionConflict()
+      throw error
+    }
+  }
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await attempt(cas)
+    } catch (error) {
+      if (!(error instanceof RevisionConflict)) throw error
+    }
+    if (i < attempts - 1) await sleep(baseMs * 2 ** i * (0.5 + random()))
+  }
+  throw exhausted()
+}