Skip to content

store checks

Checks for application implementations of :class:ThreadStore.

check_thread_store async

check_thread_store(store: ThreadStore[TContext], context: TContext, *, other_context: TContext, peer: ThreadStore[TContext] | None = None) -> None

Check core thread storage, including form claims, retries, and hidden items.

Run against a disposable database with contexts for two distinct users. Supply an independent store instance sharing that database to check concurrent operations across connections. The check writes and deletes a synthetic thread. A failed condition raises an informative AssertionError.

Source code in chatkit/store_checks.py
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
async def check_thread_store[TContext](
    store: ThreadStore[TContext],
    context: TContext,
    *,
    other_context: TContext,
    peer: ThreadStore[TContext] | None = None,
) -> None:
    """Check core thread storage, including form claims, retries, and hidden items.

    Run against a disposable database with contexts for two distinct users.
    Supply an independent store instance sharing that database to check
    concurrent operations across connections. The check writes and deletes
    a synthetic thread. A failed condition raises an informative AssertionError.
    """
    peer = peer if peer is not None else store
    async with _disposable_thread(store, context) as thread:
        created_at = thread.created_at
        try:
            await peer.load_thread(thread.id, other_context)
        except NotFoundError:
            pass
        else:
            raise AssertionError("Another user's context can load this thread")

        async with asyncio.TaskGroup() as patches:
            patches.create_task(
                store.patch_thread(thread.id, {"title": "Renamed"}, context)
            )
            patches.create_task(
                peer.patch_thread(
                    thread.id,
                    {"metadata_set": {"saved": True}, "metadata_delete": ("remove",)},
                    context,
                )
            )
        patched = await store.load_thread(thread.id, context)
        _require(
            patched.title == "Renamed"
            and patched.metadata == {"kept": True, "saved": True},
            "Concurrent field patches must preserve unrelated state",
        )

        older_turn, newer_turn = str(uuid4()), str(uuid4())
        await store.begin_turn(thread.id, older_turn, context)
        await store.start_turn(thread.id, older_turn, context)
        await peer.begin_turn(thread.id, newer_turn, context)
        try:
            await store.patch_thread(
                thread.id, {"title": "Stale title"}, context, turn_id=older_turn
            )
        except ConflictError:
            pass
        else:
            raise AssertionError("A superseded turn can still patch the thread")
        _require(
            await peer.load_turn_state(thread.id, older_turn, context)
            == TurnState.SUPERSEDED,
            "The older turn must retain its superseded state",
        )
        _require(
            await store.finish_turn(
                thread.id, newer_turn, TurnOutcome.CANCELLED, context
            )
            == TurnState.ABANDONED,
            "Closing an accepted turn must record that it never started",
        )

        item_ids = set()
        for text in ("First message", "Second message", "Third message"):
            message = UserMessageItem(
                id=store.generate_item_id("message", thread, context),
                thread_id=thread.id,
                created_at=created_at,
                content=[UserMessageTextContent(text=text)],
                inference_options=InferenceOptions(),
            )
            await store.add_thread_item(thread.id, message, context)
            item_ids.add(message.id)
        _require(len(item_ids) == 3, "Item ID generation returned a duplicate")

        ascending = await peer.load_thread_items(thread.id, None, 3, "asc", context)
        ascending_ids = [item.id for item in ascending.data]
        _require(
            len(ascending_ids) == len(item_ids) and set(ascending_ids) == item_ids,
            "Pagination must return each item with a tied timestamp once",
        )

        form = StructuredInputItem(
            id=store.generate_item_id("task", thread, context),
            thread_id=thread.id,
            created_at=created_at + timedelta(seconds=2),
            inputs=[],
        )
        await store.add_thread_item(thread.id, form, context)
        active_turn = str(uuid4())
        await store.begin_turn(thread.id, active_turn, context)
        answered = form.model_copy(update={"status": "answered"})
        for active_state in (TurnState.ACCEPTED, TurnState.RUNNING):
            if active_state == TurnState.RUNNING:
                await store.start_turn(thread.id, active_turn, context)
            try:
                await peer.claim_pending_item(
                    thread.id, form, answered, context, next_turn_id=str(uuid4())
                )
            except ConflictError:
                pass
            else:
                raise AssertionError(f"A form claim replaced the {active_state} turn")
            _require(
                await peer.load_turn_state(thread.id, active_turn, context)
                == active_state
                and await peer.load_item(thread.id, form.id, context) == form,
                "A rejected form claim must preserve the active turn and pending form",
            )
        await store.finish_turn(thread.id, active_turn, TurnOutcome.COMPLETED, context)
        _, result = await _race_claims(
            store,
            peer,
            context,
            form,
            answered,
            form.model_copy(update={"status": "skipped"}),
        )
        _require(result is None, "A form claim must return no private invocation")

        app_note = HiddenContextItem(
            id=str(uuid4()),
            thread_id=thread.id,
            created_at=created_at + timedelta(seconds=1),
            content="App context",
        )
        sdk_note = SDKHiddenContextItem(
            id=store.generate_item_id("sdk_hidden_context", thread, context),
            thread_id=thread.id,
            created_at=created_at + timedelta(seconds=3),
            content="SDK context",
        )
        last_message = UserMessageItem(
            id=store.generate_item_id("message", thread, context),
            thread_id=thread.id,
            created_at=created_at + timedelta(seconds=4),
            content=[UserMessageTextContent(text="Last message")],
            inference_options=InferenceOptions(),
        )
        for item in (app_note, sdk_note, last_message):
            await store.add_thread_item(thread.id, item, context)
        stored_ids = [
            *ascending_ids,
            app_note.id,
            form.id,
            sdk_note.id,
            last_message.id,
        ]
        await _check_item_pagination(peer, thread.id, context, stored_ids)
        await _check_item_pagination(
            peer,
            thread.id,
            context,
            stored_ids,
            exclude_ids=frozenset({app_note.id, sdk_note.id}),
        )
        await _check_retry(
            store,
            peer,
            context,
            thread.id,
            ascending_ids[0],
            stored_ids[1:],
        )

check_client_tool_store async

check_client_tool_store(store: ThreadStore[TContext], context: TContext, *, other_context: TContext, peer: ThreadStore[TContext] | None = None) -> None

Check the optional browser-tool store contract using a disposable thread.

Run this alongside check_thread_store for stores that support browser callbacks. Pass two distinct users and, optionally, a second connection to the same database.

Source code in chatkit/store_checks.py
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
async def check_client_tool_store[TContext](
    store: ThreadStore[TContext],
    context: TContext,
    *,
    other_context: TContext,
    peer: ThreadStore[TContext] | None = None,
) -> None:
    """Check the optional browser-tool store contract using a disposable thread.

    Run this alongside check_thread_store for stores that support browser callbacks.
    Pass two distinct users and, optionally, a second connection to the same database.
    """
    peer = peer if peer is not None else store
    async with _disposable_thread(store, context) as thread:
        anchor = UserMessageItem(
            id=store.generate_item_id("message", thread, context),
            thread_id=thread.id,
            created_at=thread.created_at,
            content=[UserMessageTextContent(text="Start a tool call")],
            inference_options=InferenceOptions(),
        )
        await store.add_thread_item(thread.id, anchor, context)

        async def register_tool() -> tuple[ClientToolCallItem, ClientToolInvocation]:
            owner = str(uuid4())
            await store.begin_turn(thread.id, owner, context)
            await store.start_turn(thread.id, owner, context)
            item = ClientToolCallItem(
                id=store.generate_item_id("tool_call", thread, context),
                thread_id=thread.id,
                created_at=thread.created_at + timedelta(seconds=1),
                name="store_check",
                arguments={},
            )
            invocation = ClientToolInvocation(
                item_id=item.id,
                thread_id=thread.id,
                turn_id=owner,
                call_id=f"call_{owner}",
            )
            await store.register_client_tool_call(thread.id, item, invocation, context)
            return item, invocation

        tool, invocation = await register_tool()
        _require(
            await peer.load_client_tool_status(thread.id, tool.id, context) == "pending"
            and await peer.load_client_tool_invocation(thread.id, tool.id, context)
            == invocation,
            "A pending callback and its private invocation must be readable across store instances",
        )
        try:
            await peer.load_client_tool_invocation(thread.id, tool.id, other_context)
        except NotFoundError:
            pass
        else:
            raise AssertionError("Another user can read the private invocation")

        hidden = SDKHiddenContextItem(
            id=store.generate_item_id("sdk_hidden_context", thread, context),
            thread_id=thread.id,
            created_at=thread.created_at + timedelta(seconds=2),
            content="Internal store check",
        )
        await peer.add_thread_item(thread.id, hidden, context)
        winner_id, claimed = await _race_claims(
            store,
            peer,
            context,
            tool,
            tool.model_copy(update={"status": "completed", "output": "one"}),
            tool.model_copy(update={"status": "completed", "output": "two"}),
        )
        _require(
            claimed == invocation.model_copy(update={"continuation_turn_id": winner_id})
            and await peer.load_client_tool_invocation(thread.id, tool.id, context)
            == claimed,
            "The winning callback must bind the same private invocation and turn",
        )
        _require(
            await peer.load_client_tool_status(thread.id, tool.id, context)
            == "completed",
            "The callback lifecycle must complete with the winning claim",
        )
        cancelled, _ = await register_tool()
        await _check_retry(
            store,
            peer,
            context,
            thread.id,
            anchor.id,
            [tool.id, hidden.id, cancelled.id],
        )
        _require(
            await peer.load_client_tool_status(thread.id, cancelled.id, context)
            == "cancelled",
            "Retry must close active callbacks and retain their lifecycle",
        )

        await store.add_thread_item(thread.id, hidden, context)
        explicitly_cancelled, _ = await register_tool()
        await peer.cancel_client_tool_call(thread.id, explicitly_cancelled.id, context)
        visible = await peer.load_thread_items(
            thread.id, None, 1, "desc", context, include_hidden=False
        )
        _require(
            [item.id for item in visible.data] == [anchor.id]
            and not visible.has_more
            and visible.after is None,
            "Visible history must exclude hidden and cancelled items before applying the page limit",
        )