basalt-ui 1.12.0 → 1.13.0

package/src/agent/adapter.test.ts

@@ -134,6 +134,21 @@ describe('threadsStoreAdapterContract', () => {
     expect(new Set(cases.map((c) => c.name)).size).toBe(cases.length)
   })
 
+  test("the contract suite itself does not depend on crypto.randomUUID — it still runs to completion via the getRandomValues fallback (mintThreadId, since every id it mints here is a THREAD id, never appendMessage's idempotency key)", async () => {
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', {
+      value: { getRandomValues: originalCrypto.getRandomValues.bind(originalCrypto) },
+      configurable: true,
+    })
+    try {
+      for (const conformanceCase of threadsStoreAdapterContract(() => createMemoryAdapter())) {
+        await conformanceCase.run()
+      }
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
+
   test('FAILS an adapter whose appendMessage is not idempotent on message.id', async () => {
     const cases = threadsStoreAdapterContract(() => {
       const memory = createMemoryAdapter()
@@ -417,6 +432,228 @@ describe('createAdapterThreadsStore', () => {
     expect(result.current.threads[0]?.read).toBe(true)
   })
 
+  // ── rolled-back create() and its dependent writes ───────────────────────────
+
+  test('a rolled-back create surfaces its own error, not a cascade from the writes queued behind it', async () => {
+    const calls: string[] = []
+    const memory = createMemoryAdapter()
+    const useThreads = createAdapterThreadsStore<AgentPart>({
+      ...memory,
+      createThread: async () => {
+        calls.push('createThread')
+        throw new Error('create-boom')
+      },
+      // Mirrors the real finding: a real backend REJECTS a write against a row that was never
+      // created, it does not silently no-op the way the permissive reference `memory` adapter
+      // does — so these reproduce the exact "unknown thread" cascade from the console trace.
+      markRead: async (id) => {
+        calls.push('markRead')
+        if ((await memory.loadThread(id)) === null)
+          throw new Error(`markRead: unknown thread ${id}`)
+        await memory.markRead(id)
+      },
+      appendMessage: async (i) => {
+        calls.push('appendMessage')
+        if ((await memory.loadThread(i.threadId)) === null) {
+          throw new Error(`appendMessage: unknown thread ${i.threadId}`)
+        }
+        await memory.appendMessage(i)
+      },
+      setStatus: async (i) => {
+        calls.push('setStatus')
+        if ((await memory.loadThread(i.threadId)) === null) {
+          throw new Error(`setStatus: unknown thread ${i.threadId}`)
+        }
+        await memory.setStatus(i)
+      },
+    })
+
+    const { result } = renderHook(() => useThreads())
+    await waitFor(() => {
+      expect(result.current.hydrated).toBe(true)
+    })
+
+    // Exactly the observed sequence: create() -> markRead() -> appendMessage() -> setStatus() in
+    // one synchronous block, every dependent write chained behind the same rejected createThread.
+    let id = ''
+    act(() => {
+      id = result.current.create()
+      result.current.markRead(id)
+      result.current.appendMessage(id, makeMessage('m-first'))
+      result.current.setStatus(id, 'streaming')
+    })
+
+    await waitFor(() => {
+      expect(result.current.error).toBeInstanceOf(Error)
+    })
+    await settle()
+
+    // The surfaced error names the create, not one of the three cascade rejections that would
+    // otherwise overwrite it in issue order.
+    expect((result.current.error as Error).message).toBe('create-boom')
+    // The dependent writes never reached the adapter at all — dropped, not run-and-failed.
+    expect(calls).toEqual(['createThread'])
+    // Rollback semantics are untouched: the thread is gone, both locally and server-side.
+    expect(result.current.threads).toHaveLength(0)
+    expect(await memory.loadThread(id)).toBeNull()
+  })
+
+  test('a rolled-back create does not stall or spoil the write queue for a different thread', async () => {
+    const memory = createMemoryAdapter()
+    const calls: string[] = []
+    let createCalls = 0
+    const useThreads = createAdapterThreadsStore<AgentPart>({
+      ...memory,
+      createThread: async (i) => {
+        createCalls += 1
+        if (createCalls === 1) {
+          calls.push('createThread:doomed')
+          throw new Error('create-boom')
+        }
+        calls.push('createThread:healthy')
+        await memory.createThread(i)
+      },
+      markRead: async (id) => {
+        calls.push(`markRead:${id}`)
+        await memory.markRead(id)
+      },
+    })
+
+    const { result } = renderHook(() => useThreads())
+    await waitFor(() => {
+      expect(result.current.hydrated).toBe(true)
+    })
+
+    let doomed = ''
+    let healthy = ''
+    act(() => {
+      doomed = result.current.create()
+      result.current.markRead(doomed)
+      healthy = result.current.create()
+      result.current.markRead(healthy)
+    })
+
+    await waitFor(() => {
+      expect(result.current.error).toBeInstanceOf(Error)
+    })
+    await waitFor(async () => {
+      expect(await memory.loadThread(healthy)).not.toBeNull()
+    })
+    await settle()
+
+    expect((result.current.error as Error).message).toBe('create-boom')
+    // doomed's markRead was dropped; healthy's own write for a DIFFERENT thread ran normally.
+    expect(calls).toEqual(['createThread:doomed', 'createThread:healthy', `markRead:${healthy}`])
+    expect((await memory.loadThread(healthy))?.read).toBe(true)
+    expect(await memory.loadThread(doomed)).toBeNull()
+  })
+
+  test('a genuine failure that arrives after a rolled-back create still surfaces', async () => {
+    const memory = createMemoryAdapter()
+    let createCalls = 0
+    const useThreads = createAdapterThreadsStore<AgentPart>({
+      ...memory,
+      createThread: async (i) => {
+        createCalls += 1
+        if (createCalls === 1) throw new Error('create-boom')
+        await memory.createThread(i)
+      },
+      markRead: async () => {
+        // A genuine, unrelated failure against a HEALTHY thread — not a cascade of the rollback.
+        throw new Error('markRead-boom')
+      },
+    })
+
+    const { result } = renderHook(() => useThreads())
+    await waitFor(() => {
+      expect(result.current.hydrated).toBe(true)
+    })
+
+    act(() => {
+      result.current.create()
+    })
+    await waitFor(() => {
+      expect(result.current.error).toBeInstanceOf(Error)
+    })
+    expect((result.current.error as Error).message).toBe('create-boom')
+
+    let healthy = ''
+    act(() => {
+      healthy = result.current.create()
+    })
+    await waitFor(async () => {
+      expect(await memory.loadThread(healthy)).not.toBeNull()
+    })
+
+    act(() => {
+      result.current.markRead(healthy)
+    })
+
+    await waitFor(() => {
+      expect((result.current.error as Error).message).toBe('markRead-boom')
+    })
+  })
+
+  test('a rolled-back create keeps dropping its thread’s writes after the queue drains', async () => {
+    // The run's COMPLETION path (useAgentThreadRuns: appendMessage(assistant) -> setOutcome ->
+    // setStatus -> setResumeToken) lands when the stream ends, long after the create's own
+    // rollback has drained the per-thread chain. Those writes target the same rolled-back row, so
+    // they are the same cascade as the synchronous send-path trio — just later. If the failed-id
+    // record is cleared when the chain drains, the fix above covers the first ~200ms and then the
+    // cascade returns at stream end, which is precisely when the user is looking at the thread.
+    const calls: string[] = []
+    const memory = createMemoryAdapter()
+    const useThreads = createAdapterThreadsStore<AgentPart>({
+      ...memory,
+      createThread: async () => {
+        calls.push('createThread')
+        throw new Error('create-boom')
+      },
+      appendMessage: async (i) => {
+        calls.push('appendMessage')
+        if ((await memory.loadThread(i.threadId)) === null) {
+          throw new Error(`appendMessage: unknown thread ${i.threadId}`)
+        }
+        await memory.appendMessage(i)
+      },
+      setStatus: async (i) => {
+        calls.push('setStatus')
+        if ((await memory.loadThread(i.threadId)) === null) {
+          throw new Error(`setStatus: unknown thread ${i.threadId}`)
+        }
+        await memory.setStatus(i)
+      },
+    })
+
+    const { result } = renderHook(() => useThreads())
+    await waitFor(() => {
+      expect(result.current.hydrated).toBe(true)
+    })
+
+    let id = ''
+    act(() => {
+      id = result.current.create()
+    })
+    await waitFor(() => {
+      expect(result.current.error).toBeInstanceOf(Error)
+    })
+    // Drain fully: the create's chain entry is gone by the time the completion writes arrive.
+    await settle()
+    await settle()
+    expect((result.current.error as Error).message).toBe('create-boom')
+
+    // The completion path fires now, against the row that was never materialized.
+    act(() => {
+      result.current.appendMessage(id, makeMessage('m-assistant'))
+      result.current.setStatus(id, 'done')
+    })
+    await settle()
+    await settle()
+
+    expect(calls).toEqual(['createThread'])
+    expect((result.current.error as Error).message).toBe('create-boom')
+  })
+
   test('setResumeToken(undefined) clears the key through the adapter', async () => {
     const memory = createMemoryAdapter()
     const useThreads = createAdapterThreadsStore<AgentPart>(memory)

package/src/agent/adapter.ts

@@ -168,7 +168,11 @@ type ThreadPatch<TPart> = {
  * - **Roll back on rejection.** A rejected write's patch is discarded, the rejection is surfaced
  *   on `error`, and the store re-lists to converge on whatever the server really did. Patches are
  *   tracked individually, so a failing write rolls back only itself and not whatever else was in
- *   flight beside it.
+ *   flight beside it. A rejected `create()` additionally drops every later single-thread write for
+ *   that id (`markRead`/`appendMessage`/`setStatus`/… — both the ones chained directly behind it and
+ *   the run's completion writes at stream end) instead of letting each fail independently against a
+ *   row that no longer exists — see `failedCreateIds`. Without that, the create's own error is
+ *   overwritten by a run of "unknown thread" rejections that name nothing a caller can act on.
  * - **`hydrated` means "a `listThreads` has succeeded"**, not "a load has been attempted". A
  *   store that is `!hydrated` with a non-undefined `error` failed to load; check both.
  * - **`error` latches the most recent failure until something disproves it.** A successful
@@ -412,6 +416,31 @@ export function createAdapterThreadsStore<TPart = AgentPart>(
    */
   const chains = new Map<string, Promise<void>>()
 
+  /**
+   * Thread ids whose `createThread` has rejected and been rolled back. The send path issues
+   * `create()` → `markRead()` → `appendMessage()` → `setStatus()` in one synchronous block, all
+   * chained behind the same per-thread queue above — so when `createThread` rejects, the three
+   * dependent writes queued right behind it are guaranteed to reach the adapter next, each against
+   * a row that was never materialized. Left alone, each of those independently rejects with its own
+   * "unknown thread" error and overwrites the one that actually explains what happened (the
+   * create's), so the user ends up staring at the last cascade error instead of the root cause.
+   *
+   * Recording the id here lets `mutate` recognize a single-thread write against a rolled-back
+   * create and drop it silently instead of running a doomed commit — see `mutate`'s `isCreate`
+   * guard.
+   *
+   * Entries are NEVER removed, deliberately. The cascade is not confined to the synchronous block:
+   * `useAgentThreadRuns`' COMPLETION path (`appendMessage(assistant)` → `setOutcome` → `setStatus`
+   * → `setResumeToken`) fires when the stream ends, long after this thread's write chain has
+   * drained — same rolled-back row, same "unknown thread" rejections, and landing at exactly the
+   * moment the user is watching the thread. Clearing the entry when the chain drains would fix the
+   * first few hundred milliseconds and hand the cascade straight back at stream end. Retaining it
+   * is safe and bounded: `create()` always mints its own id (`mintThreadId`, never caller-supplied),
+   * so an id in here can never be re-created and the set only grows by one per FAILED create in a
+   * session.
+   */
+  const failedCreateIds = new Set<string>()
+
   /** `task` must never reject, so a failed write cannot poison the chain behind it. */
   function enqueue(threadIds: readonly string[], task: () => Promise<void>): void {
     const ids = [...new Set(threadIds)]
@@ -421,6 +450,7 @@ export function createAdapterThreadsStore<TPart = AgentPart>(
     for (const id of ids) chains.set(id, run)
     void run.finally(() => {
       // Only the tail clears its own entry, so a later write chained behind it is not orphaned.
+      // `failedCreateIds` is deliberately NOT cleared here — see its doc.
       for (const id of ids) if (chains.get(id) === run) chains.delete(id)
     })
   }
@@ -438,6 +468,12 @@ export function createAdapterThreadsStore<TPart = AgentPart>(
     readonly apply: ThreadPatch<TPart>['apply']
     readonly applyActive?: (activeId: string | null) => string | null
     readonly commit: () => Promise<void>
+    /**
+     * True only for `create()`'s own write. On rejection, marks its thread id as failed so the
+     * dependent writes chained behind it in the same synchronous send-path block recognize the row
+     * was rolled back — see `failedCreateIds`.
+     */
+    readonly isCreate?: boolean
   }): void {
     const patch: ThreadPatch<TPart> = {
       apply: memoizeApply(i.apply),
@@ -448,9 +484,30 @@ export function createAdapterThreadsStore<TPart = AgentPart>(
     const tokenAtIssue = errorToken
     recompute()
     enqueue(i.threadIds, async (): Promise<void> => {
+      // A single-thread write against a create that already rolled back cannot succeed — the row
+      // was never materialized, and running it only manufactures a second "unknown thread" error
+      // that would bury the create's own. This covers both the writes chained directly behind the
+      // create and the run's later completion writes (see `failedCreateIds`). Scoped to
+      // single-thread writes deliberately:
+      // `clear()`'s multi-id commit already has its own per-id fan-out (`Promise.allSettled`) and
+      // `removeThread` is contractually a no-op on an unknown id anyway, so folding this check into
+      // a multi-id write would risk dropping legitimate deletes for OTHER, healthy threads in the
+      // same batch just because one id in it happened to be orphaned.
+      const [soleThreadId] = i.threadIds
+      if (
+        !i.isCreate &&
+        i.threadIds.length === 1 &&
+        soleThreadId !== undefined &&
+        failedCreateIds.has(soleThreadId)
+      ) {
+        drop(patch)
+        recompute()
+        return
+      }
       try {
         await i.commit()
       } catch (cause) {
+        if (i.isCreate) for (const threadId of i.threadIds) failedCreateIds.add(threadId)
         // Roll back: discard THIS patch only, leaving any other in-flight patch applied.
         drop(patch)
         error = cause
@@ -540,6 +597,7 @@ export function createAdapterThreadsStore<TPart = AgentPart>(
     mutate({
       threadIds: [id],
       apply: (threads) => (threads.some((t) => t.id === id) ? [...threads] : [thread, ...threads]),
+      isCreate: true,
       commit: () =>
         adapter.createThread({
           id,
@@ -738,7 +796,7 @@ export function threadsStoreAdapterContract<TPart>(
 
   return [
     define('createThread then listThreads returns the thread with empty defaults', async (a) => {
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id })
       const threads = await a.listThreads()
       const found = threads.filter((t) => t.id === id)
@@ -754,19 +812,19 @@ export function threadsStoreAdapterContract<TPart>(
     }),
 
     define('createThread persists meta', async (a) => {
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id, meta: { source: 'contract' } })
       const thread = await loadOrThrow(a, id)
       assert(thread.meta?.['source'] === 'contract', 'meta did not round-trip')
     }),
 
     define('loadThread returns null for an unknown id', async (a) => {
-      const thread = await a.loadThread(crypto.randomUUID())
+      const thread = await a.loadThread(mintThreadId())
       assert(thread === null, 'loadThread must return null (not throw, not undefined) when absent')
     }),
 
     define('appendMessage is idempotent on message.id', async (a) => {
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id })
       const msg = message<TPart>('contract-msg-1')
       await a.appendMessage({ threadId: id, message: msg })
@@ -780,7 +838,7 @@ export function threadsStoreAdapterContract<TPart>(
     }),
 
     define('appendMessage preserves order for distinct ids', async (a) => {
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id })
       await a.appendMessage({ threadId: id, message: message<TPart>('contract-msg-1') })
       await a.appendMessage({ threadId: id, message: message<TPart>('contract-msg-2') })
@@ -792,7 +850,7 @@ export function threadsStoreAdapterContract<TPart>(
     }),
 
     define('setStatus round-trips', async (a) => {
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id })
       await a.setStatus({ threadId: id, status: 'streaming' })
       assert((await loadOrThrow(a, id)).status === 'streaming', "status did not become 'streaming'")
@@ -801,7 +859,7 @@ export function threadsStoreAdapterContract<TPart>(
     }),
 
     define('setOutcome round-trips', async (a) => {
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id })
       const outcome: AgentOutcome = { title: 'Title', summary: 'Summary', status: 'done' }
       await a.setOutcome({ threadId: id, outcome })
@@ -812,7 +870,7 @@ export function threadsStoreAdapterContract<TPart>(
     }),
 
     define('setResumeToken round-trips and clears with undefined', async (a) => {
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id })
       await a.setResumeToken({ threadId: id, token: 'tok-1' })
       assert((await loadOrThrow(a, id)).resumeToken === 'tok-1', 'resumeToken did not round-trip')
@@ -824,7 +882,7 @@ export function threadsStoreAdapterContract<TPart>(
     }),
 
     define('markRead marks the thread read', async (a) => {
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id })
       assert((await loadOrThrow(a, id)).read === false, 'a new thread must start unread')
       await a.markRead(id)
@@ -835,7 +893,7 @@ export function threadsStoreAdapterContract<TPart>(
       // The store keeps a write's optimistic patch applied until a listThreads STARTED after that
       // write resolved lands in the confirmed base. An eventually-consistent list (a stale read
       // replica, a cached response) breaks that and flashes the pre-write state back into the UI.
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id })
       await a.appendMessage({ threadId: id, message: message<TPart>('contract-msg-raw') })
       await a.setStatus({ threadId: id, status: 'streaming' })
@@ -856,7 +914,7 @@ export function threadsStoreAdapterContract<TPart>(
       async (a) => {
         // The store serializes writes per thread id, so this exact sequence — the send path's
         // create-then-first-message — is what a real adapter receives. Each write must find the row.
-        const id = crypto.randomUUID()
+        const id = mintThreadId()
         await a.createThread({ id })
         await a.markRead(id)
         await a.appendMessage({ threadId: id, message: message<TPart>('contract-msg-dep') })
@@ -872,7 +930,7 @@ export function threadsStoreAdapterContract<TPart>(
     ),
 
     define('removeThread removes the thread', async (a) => {
-      const id = crypto.randomUUID()
+      const id = mintThreadId()
       await a.createThread({ id })
       await a.removeThread(id)
       assert(await a.loadThread(id).then((t) => t === null), 'loadThread must be null after remove')
@@ -881,7 +939,7 @@ export function threadsStoreAdapterContract<TPart>(
     }),
 
     define('removeThread of an unknown id does not throw', async (a) => {
-      await a.removeThread(crypto.randomUUID())
+      await a.removeThread(mintThreadId())
     }),
   ]
 }

package/src/agent/ai-sdk-transport.test.ts

@@ -592,3 +592,67 @@ describe('aiSdkTransport — deterministic ids and replay idempotency', () => {
     )
   })
 })
+
+describe('aiSdkTransport — id minting under degraded crypto', () => {
+  test('the fixed chatId (mintThreadId, low collision cost) mints fine with no usable crypto at all — construction never throws', () => {
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    try {
+      expect(() =>
+        aiSdkTransport({
+          api: '/api/chat',
+          fetch: mockFetch(() => {
+            throw new Error('must not be called')
+          }),
+        }),
+      ).not.toThrow()
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
+
+  test('the outbound user message id (mintMessageId, an idempotency key on the AI SDK backend) works via getRandomValues when randomUUID is unavailable', async () => {
+    const chunks: UIMessageChunk[] = [
+      { type: 'text-start', id: 't1' },
+      { type: 'text-end', id: 't1' },
+    ]
+    const transport = aiSdkTransport({
+      api: '/api/chat',
+      fetch: mockFetch(async () => scriptedResponse(chunks)),
+    })
+
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', {
+      value: { getRandomValues: originalCrypto.getRandomValues.bind(originalCrypto) },
+      configurable: true,
+    })
+    try {
+      const parts = await collect(transport.stream('hi'))
+      expect(parts[0]?.type).toBe('start')
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
+
+  test('the outbound user message id THROWS on a host with no usable crypto at all, rather than silently colliding', async () => {
+    const transport = aiSdkTransport({
+      api: '/api/chat',
+      fetch: mockFetch(() => {
+        throw new Error('must not be called — must throw before any network call')
+      }),
+    })
+    const gen = transport.stream('hi')
+
+    // The synthesized StartPart is yielded first, before mintMessageId is ever reached.
+    const start = await gen.next()
+    expect(start.value).toMatchObject({ type: 'start' })
+
+    const originalCrypto = globalThis.crypto
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    try {
+      await expect(gen.next()).rejects.toThrow(/idempotency key/)
+    } finally {
+      Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+    }
+  })
+})

package/src/agent/ai-sdk-transport.ts

@@ -48,6 +48,7 @@
  * })
  */
 import { assertNever } from '../register'
+import { mintMessageId, mintThreadId } from './id'
 import { TERMINAL_TOOL_STATES } from './parts'
 import type { AgentPart, AgentPartDraft } from './parts'
 import type { ResumableAgentTransport } from './transport'
@@ -401,7 +402,10 @@ export function aiSdkTransport<TPart = AgentPart>(
 
         const { httpTransport, readUIMessageStream: readStream } = await resolveAiSdk()
         const userMessage: UIMessage = {
-          id: crypto.randomUUID(),
+          // This id is what AI SDK's own backend persistence/dedup keys turns hang off — the same
+          // idempotency-key cost as basalt's own ChatMessage.id (see mintMessageId's doc), so
+          // mintMessageId, not mintThreadId, is the right helper here.
+          id: mintMessageId(),
           role: 'user',
           parts: [{ type: 'text', text: input }],
         }
@@ -425,7 +429,9 @@ export function aiSdkTransport<TPart = AgentPart>(
     }
   }
 
-  const fixedChatId = crypto.randomUUID()
+  // Client-side conversation namespace, not an idempotency key — a collision here would merge two
+  // conversations' index-addressed part ids, the same low collision cost `mintThreadId` covers.
+  const fixedChatId = mintThreadId()
   return {
     ...makeTransport(fixedChatId),
     forThread: (chatId: string) => makeTransport(chatId),

package/src/agent/id.test.ts

@@ -1,9 +1,15 @@
 /**
  * withPartIds — stamps `${runId}#${n}` onto any draft part arriving without an id; idempotent for
  * drafts that already have one (untouched, and doesn't advance the counter).
+ *
+ * mintThreadId/mintMessageId — the two id-minting helpers behind every unguarded
+ * `crypto.randomUUID()` call site this file's siblings used to have. Both share rungs 1
+ * (`crypto.randomUUID`) and 2 (`crypto.getRandomValues`, hand-assembled into a UUIDv4); they
+ * deliberately diverge on rung 3 (no crypto at all) — `mintThreadId` degrades, `mintMessageId`
+ * throws. See each function's own doc for why.
  */
 import { describe, expect, test } from 'bun:test'
-import { withPartIds } from './id'
+import { mintMessageId, mintThreadId, withPartIds } from './id'
 import type { AgentPartDraft } from './parts'
 
 async function* gen<T>(values: T[]): AsyncGenerator<T> {
@@ -16,6 +22,33 @@ async function collect<T>(source: AsyncGenerator<T>): Promise<T[]> {
   return out
 }
 
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/** Rung 2: randomUUID absent, getRandomValues present (a real, non-secure-context host). */
+function withRung2Crypto<T>(run: () => T): T {
+  const originalCrypto = globalThis.crypto
+  Object.defineProperty(globalThis, 'crypto', {
+    value: { getRandomValues: originalCrypto.getRandomValues.bind(originalCrypto) },
+    configurable: true,
+  })
+  try {
+    return run()
+  } finally {
+    Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+  }
+}
+
+/** Rung 3: no usable crypto at all. */
+function withRung3Crypto<T>(run: () => T): T {
+  const originalCrypto = globalThis.crypto
+  Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+  try {
+    return run()
+  } finally {
+    Object.defineProperty(globalThis, 'crypto', { value: originalCrypto, configurable: true })
+  }
+}
+
 describe('withPartIds', () => {
   test('stamps a sequential id on every draft missing one', async () => {
     // Annotated: all three literals uniformly omit `id`, so without this TS infers an `id`-less
@@ -73,3 +106,64 @@ describe('withPartIds', () => {
     ])
   })
 })
+
+describe('mintThreadId', () => {
+  test('rung 1 (crypto.randomUUID): returns a valid UUIDv4 string', () => {
+    const id = mintThreadId()
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 1: many mints are distinct', () => {
+    const ids = Array.from({ length: 1000 }, () => mintThreadId())
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 2 (getRandomValues only): assembles a valid UUIDv4 — version/variant bits set', () => {
+    const id = withRung2Crypto(() => mintThreadId())
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 2: many mints are distinct', () => {
+    const ids = withRung2Crypto(() => Array.from({ length: 1000 }, () => mintThreadId()))
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 3 (no usable crypto at all): does NOT throw, still returns distinct non-empty strings', () => {
+    const ids = withRung3Crypto(() => Array.from({ length: 50 }, () => mintThreadId()))
+    for (const id of ids) {
+      expect(typeof id).toBe('string')
+      expect(id.length).toBeGreaterThan(0)
+    }
+    // Weak (Date.now() + Math.random()), not cryptographically random — but still distinct across
+    // this many mints in one tick, since Math.random() varies even when Date.now() doesn't.
+    expect(new Set(ids).size).toBe(50)
+  })
+})
+
+describe('mintMessageId', () => {
+  test('rung 1 (crypto.randomUUID): returns a valid UUIDv4 string', () => {
+    const id = mintMessageId()
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 1: many mints are distinct', () => {
+    const ids = Array.from({ length: 1000 }, () => mintMessageId())
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 2 (getRandomValues only): assembles a valid UUIDv4 — version/variant bits set', () => {
+    const id = withRung2Crypto(() => mintMessageId())
+    expect(id).toMatch(UUID_V4_RE)
+  })
+
+  test('rung 2: many mints are distinct', () => {
+    const ids = withRung2Crypto(() => Array.from({ length: 1000 }, () => mintMessageId()))
+    expect(new Set(ids).size).toBe(1000)
+  })
+
+  test('rung 3 (no usable crypto at all): THROWS rather than minting a non-random id', () => {
+    // Diverges from mintThreadId's rung 3 on purpose — appendMessage's idempotency key must never
+    // silently degrade to a non-collision-resistant id. See mintMessageId's own doc.
+    expect(() => withRung3Crypto(() => mintMessageId())).toThrow(/idempotency key/)
+  })
+})