@tanstack/ai-persistence 0.2.0 → 0.4.1

package/src/testkit/conformance.ts

@@ -929,24 +929,24 @@ export function runPersistenceConformance(
 
         await store.save(
           artifact({
-            artifactId: 'art-a',
+            artifactId: '\u{10000}',
             blobKey: 'artifacts/run-art/art-a',
             createdAt: 100,
           }),
         )
         await store.save(
           artifact({
-            artifactId: 'art-b',
+            artifactId: '\u{e000}',
             sourceUrl: 'https://provider.example/expiring.png',
-            createdAt: 200,
+            createdAt: 100,
           }),
         )
         await store.save(
           artifact({ artifactId: 'art-c', runId: 'run-art-other' }),
         )
 
-        expect(await store.get('art-a')).toMatchObject({
-          artifactId: 'art-a',
+        expect(await store.get('\u{10000}')).toMatchObject({
+          artifactId: '\u{10000}',
           runId: 'run-art',
           threadId: 'thread-art',
           blobKey: 'artifacts/run-art/art-a',
@@ -955,28 +955,93 @@ export function runPersistenceConformance(
           size: 3,
           createdAt: 100,
         })
-        expect(await store.get('art-b')).toMatchObject({
+        expect(await store.get('\u{e000}')).toMatchObject({
           sourceUrl: 'https://provider.example/expiring.png',
         })
 
         expect((await store.list('run-art')).map((r) => r.artifactId)).toEqual([
-          'art-a',
-          'art-b',
+          '\u{e000}',
+          '\u{10000}',
         ])
 
         // save() is insert-OR-OVERWRITE: re-saving an id corrects the record.
         await store.save(
-          artifact({ artifactId: 'art-a', name: 'renamed.png', size: 9 }),
+          artifact({ artifactId: '\u{10000}', name: 'renamed.png', size: 9 }),
         )
-        const updated = await store.get('art-a')
+        const updated = await store.get('\u{10000}')
         expect(updated).toMatchObject({ name: 'renamed.png', size: 9 })
         expect(updated?.blobKey).toBeUndefined()
         expect((await store.list('run-art')).map((r) => r.artifactId)).toEqual([
-          'art-a',
-          'art-b',
+          '\u{e000}',
+          '\u{10000}',
         ])
       })
 
+      it('lists a thread in deterministic createdAt and artifactId order', async () => {
+        const store = resolveStore('artifacts')
+        if (!store) return
+
+        await store.save(
+          artifact({
+            artifactId: 'thread-b',
+            threadId: 'thread-order',
+            createdAt: 2,
+          }),
+        )
+        await store.save(
+          artifact({
+            artifactId: 'thread-a',
+            threadId: 'thread-order',
+            createdAt: 2,
+          }),
+        )
+        await store.save(
+          artifact({
+            artifactId: 'thread-early',
+            threadId: 'thread-order',
+            createdAt: 1,
+          }),
+        )
+        await store.save(
+          artifact({
+            artifactId: 'other',
+            threadId: 'thread-other',
+            createdAt: 0,
+          }),
+        )
+
+        expect(
+          (await store.listForThread('thread-order')).map((r) => r.artifactId),
+        ).toEqual(['thread-early', 'thread-a', 'thread-b'])
+      })
+
+      it('orders artifact IDs by UTF-8 bytes after createdAt', async () => {
+        const store = resolveStore('artifacts')
+        if (!store) return
+
+        await store.save(
+          artifact({
+            artifactId: '\u{10000}',
+            threadId: 'thread-utf8',
+            createdAt: 1,
+          }),
+        )
+        await store.save(
+          artifact({
+            artifactId: '\u{e000}',
+            threadId: 'thread-utf8',
+            createdAt: 1,
+          }),
+        )
+        await store.save(
+          artifact({ artifactId: 'a', threadId: 'thread-utf8', createdAt: 1 }),
+        )
+
+        expect(
+          (await store.listForThread('thread-utf8')).map((r) => r.artifactId),
+        ).toEqual(['a', '\u{e000}', '\u{10000}'])
+      })
+
       it('deletes one artifact and every artifact for a run', async () => {
         const store = resolveStore('artifacts')
         if (!store) return

package/src/types.ts

@@ -221,6 +221,18 @@ export interface InterruptRecord {
   response?: unknown
 }
 
+/** A terminal interrupt write for {@link InterruptStore.commitBatch}. */
+export type InterruptCommitEntry =
+  | {
+      interruptId: string
+      status: 'resolved'
+      response?: unknown
+    }
+  | {
+      interruptId: string
+      status: 'cancelled'
+    }
+
 /** Durable store for human-in-the-loop interrupts. */
 export interface InterruptStore {
   /**
@@ -249,6 +261,19 @@ export interface InterruptStore {
    * `interruptId` does not exist.
    */
   cancel: (interruptId: string) => Promise<void>
+  /**
+   * Commit terminal writes for a validated resume batch.
+   *
+   * Optional. When present, `withPersistence` calls it once instead of
+   * calling `resolve` and `cancel` for each entry. Apply every entry or none.
+   *
+   * Reject the whole batch (throw, writing nothing) when any entry has a
+   * duplicate `interruptId`, references an `interruptId` that does not exist,
+   * or references an interrupt whose status is not `'pending'`. This is
+   * stricter than `resolve` / `cancel`, which are no-ops for a missing
+   * `interruptId`.
+   */
+  commitBatch?: (entries: ReadonlyArray<InterruptCommitEntry>) => Promise<void>
   /** Return the interrupt for `interruptId`, or `null` if none exists. */
   get: (interruptId: string) => Promise<InterruptRecord | null>
   /**
@@ -388,8 +413,20 @@ export interface ArtifactStore {
   save: (record: ArtifactRecord) => Promise<void>
   /** Return the artifact for `artifactId`, or `null` if none exists. */
   get: (artifactId: string) => Promise<ArtifactRecord | null>
-  /** All artifacts for a run. Returns `[]` when the run has none. */
+  /**
+   * All artifacts for a run in deterministic snapshot order: `createdAt`
+   * ascending, then `artifactId` ascending by the unsigned UTF-8 bytes of
+   * each string (compare bytes left-to-right; shorter equal prefixes first).
+   * Returns `[]` when the run has none.
+   */
   list: (runId: string) => Promise<Array<ArtifactRecord>>
+  /**
+   * All artifacts for a thread in deterministic snapshot order.
+   * Records are ordered by `createdAt` ascending, then by `artifactId` using
+   * the unsigned UTF-8 bytes of each string (compare bytes left-to-right; shorter
+   * equal prefixes first).
+   */
+  listForThread: (threadId: string) => Promise<Array<ArtifactRecord>>
   /**
    * Delete a single artifact by id. A no-op if absent, mirroring
    * {@link BlobStore.delete} — the two are written and deleted as a pair, so