# IWorkflowCheckpointStore

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.iworkflowcheckpointstore/
> Summary: IWorkflowCheckpointStore: The store for workflow checkpoints.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

The store for workflow checkpoints.

```csharp
public interface IWorkflowCheckpointStore
```

## Remarks

The contract deliberately **carries no** Microsoft Agent
Framework type: the state is expressed as a [JsonElement](https://learn.microsoft.com/dotnet/api/system.text.json.jsonelement).
This way, `Tracon.PostgreSql` stores checkpoints without binding
to the workflow engine's 130-type API surface. Adapting to MAF's
`ICheckpointStore<JsonElement>` interface happens inside
`Tracon.Workflows`.

**Every read is scoped by the tenant filter.** A
checkpoint carries the entire execution state; another tenant's
checkpoint returns *not found* — not even "unauthorized" is said, its existence is not leaked.

**Delivery guarantee — AT-LEAST-ONCE.** [IWorkflowCheckpointStore.CreateAsync](/api/tracon.iworkflowcheckpointstore/#Tracon_IWorkflowCheckpointStore_CreateAsync_Tracon_WorkflowCheckpointRecord_System_Threading_CancellationToken_)
can be called more than once for what is logically the SAME super-step: when
`IWorkflowRunner.ResumeStreamingAsync` resumes from an EARLIER checkpoint
(a real crash-recovery resume, not the "already completed" case), every
super-step from that point forward is replayed and each one writes a new
checkpoint record again. This store does not deduplicate those writes — each
call to [IWorkflowCheckpointStore.CreateAsync](/api/tracon.iworkflowcheckpointstore/#Tracon_IWorkflowCheckpointStore_CreateAsync_Tracon_WorkflowCheckpointRecord_System_Threading_CancellationToken_) is a plain append, and a caller reading the
list back via [IWorkflowCheckpointStore.ListAsync](/api/tracon.iworkflowcheckpointstore/#Tracon_IWorkflowCheckpointStore_ListAsync_System_String_System_String_System_Threading_CancellationToken_)/[IWorkflowCheckpointStore.ListByRunAsync](/api/tracon.iworkflowcheckpointstore/#Tracon_IWorkflowCheckpointStore_ListByRunAsync_System_String_System_Guid_System_Threading_CancellationToken_) sees every
one of them, including ones written by a step that has now run twice.

## Methods

### <a id="Tracon_IWorkflowCheckpointStore_CreateAsync_Tracon_WorkflowCheckpointRecord_System_Threading_CancellationToken_"></a> CreateAsync\(WorkflowCheckpointRecord, CancellationToken\)

Writes a new checkpoint.

```csharp
ValueTask<WorkflowCheckpointRecord> CreateAsync(WorkflowCheckpointRecord record, CancellationToken cancellationToken = default)
```

#### Parameters

`record` [WorkflowCheckpointRecord](/api/tracon.workflowcheckpointrecord/)

The record to write.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[WorkflowCheckpointRecord](/api/tracon.workflowcheckpointrecord/)\>

The written record.

### <a id="Tracon_IWorkflowCheckpointStore_DeleteAsync_System_String_System_String_System_Threading_CancellationToken_"></a> DeleteAsync\(string, string, CancellationToken\)

Deletes all of a session's checkpoints.

```csharp
ValueTask<int> DeleteAsync(string tenantId, string sessionId, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant identifier.

`sessionId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The execution session identifier.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[int](https://learn.microsoft.com/dotnet/api/system.int32)\>

The number of records deleted.

### <a id="Tracon_IWorkflowCheckpointStore_ListAsync_System_String_System_String_System_Threading_CancellationToken_"></a> ListAsync\(string, string, CancellationToken\)

Lists a session's checkpoints, oldest to newest. The state payload is
**not read**; only metadata is returned.

```csharp
ValueTask<IReadOnlyList<WorkflowCheckpointRecord>> ListAsync(string tenantId, string sessionId, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant identifier.

`sessionId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The execution session identifier.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[WorkflowCheckpointRecord](/api/tracon.workflowcheckpointrecord/)\>\>

The records. Each record's [WorkflowCheckpointRecord.State](/api/tracon.workflowcheckpointrecord/#Tracon_WorkflowCheckpointRecord_State) is an
empty JSON object (`{}`), which marks the payload as not read; use
[IWorkflowCheckpointStore.ReadAsync](/api/tracon.iworkflowcheckpointstore/#Tracon_IWorkflowCheckpointStore_ReadAsync_System_String_System_String_System_String_System_Threading_CancellationToken_) for the payload itself.

### <a id="Tracon_IWorkflowCheckpointStore_ListByRunAsync_System_String_System_Guid_System_Threading_CancellationToken_"></a> ListByRunAsync\(string, Guid, CancellationToken\)

Lists the checkpoints a single run produced, oldest to newest. The
state payload is **not read**.

```csharp
ValueTask<IReadOnlyList<WorkflowCheckpointRecord>> ListByRunAsync(string tenantId, Guid runId, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant identifier.

`runId` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The run identifier.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[WorkflowCheckpointRecord](/api/tracon.workflowcheckpointrecord/)\>\>

The records, each with an empty JSON object (`{}`) as its
[WorkflowCheckpointRecord.State](/api/tracon.workflowcheckpointrecord/#Tracon_WorkflowCheckpointRecord_State).

#### Remarks

Separate from the session-based list: a session can carry multiple
runs (resuming opens a new run each time), and the UI asks "where can
this run be resumed from."

### <a id="Tracon_IWorkflowCheckpointStore_ReadAsync_System_String_System_String_System_String_System_Threading_CancellationToken_"></a> ReadAsync\(string, string, string, CancellationToken\)

Reads a single checkpoint's state.

```csharp
ValueTask<JsonElement?> ReadAsync(string tenantId, string sessionId, string checkpointId, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant identifier.

`sessionId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The execution session identifier.

`checkpointId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The checkpoint identifier.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[JsonElement](https://learn.microsoft.com/dotnet/api/system.text.json.jsonelement)?\>

The opaque state; [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) if the record does not exist or belongs to another tenant.