# IRunScoreStore

> 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.irunscorestore/
> Summary: IRunScoreStore: The store for run and message scores (RunScore).

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

The store for run and message scores ([RunScore](/api/tracon.runscore/)).

```csharp
public interface IRunScoreStore
```

## Remarks

Not added as a member to [IRunStore](/api/tracon.irunstore/): a score follows a
different lifecycle (written rarely, whereas [IRunStore](/api/tracon.irunstore/) is on
the hot path written on every run), and a separate interface fits better
with the rule that every extension point must be replaceable.

**Tenant behavior — EXPECTED tenant, uniformly.** Every
member is scoped by an explicit tenant: [IRunScoreStore.UpsertAsync](/api/tracon.irunscorestore/#Tracon_IRunScoreStore_UpsertAsync_Tracon_RunScore_System_Threading_CancellationToken_) reads it
from [RunScore.TenantId](/api/tracon.runscore/#Tracon_RunScore_TenantId), [IRunScoreStore.ListAsync](/api/tracon.irunscorestore/#Tracon_IRunScoreStore_ListAsync_System_String_System_Guid_System_Threading_CancellationToken_) and
[IRunScoreStore.DeleteAsync](/api/tracon.irunscorestore/#Tracon_IRunScoreStore_DeleteAsync_System_String_System_Guid_System_Threading_CancellationToken_) take it as a parameter. The ambient tenant is
never consulted.

## Methods

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

Deletes a score.

```csharp
ValueTask<bool> DeleteAsync(string tenantId, Guid scoreId, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant.

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

The score 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)<[bool](https://learn.microsoft.com/dotnet/api/system.boolean)\>

[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) if deleted; [false](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) if no such score exists.

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

Lists all of a run's scores.

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

#### Parameters

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

The tenant.

`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)<[RunScore](/api/tracon.runscore/)\>\>

The scores. No order is guaranteed.

### <a id="Tracon_IRunScoreStore_SummarizeAsync_Tracon_RunScoreQuery_System_Threading_CancellationToken_"></a> SummarizeAsync\(RunScoreQuery, CancellationToken\)

Aggregates the scores matching a filter.

```csharp
ValueTask<RunScoreSummary> SummarizeAsync(RunScoreQuery query, CancellationToken cancellationToken = default)
```

#### Parameters

`query` [RunScoreQuery](/api/tracon.runscorequery/)

The filter and breakdown options.

`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)<[RunScoreSummary](/api/tracon.runscoresummary/)\>

The summary. Never [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null); an empty match returns empty lists.

#### Remarks

A query, not a counter: it reads the rows that already exist. The live,
in-memory online evaluation indicator is unchanged by this member — it
keeps resetting when the process restarts. This one
survives a restart because it is computed from [IRunScoreStore.UpsertAsync](/api/tracon.irunscorestore/#Tracon_IRunScoreStore_UpsertAsync_Tracon_RunScore_System_Threading_CancellationToken_)'s
own rows, not a separate running total (no durable counter store is
introduced).

### <a id="Tracon_IRunScoreStore_UpsertAsync_Tracon_RunScore_System_Threading_CancellationToken_"></a> UpsertAsync\(RunScore, CancellationToken\)

Adds or updates a score.

```csharp
ValueTask<RunScore> UpsertAsync(RunScore score, CancellationToken cancellationToken = default)
```

#### Parameters

`score` [RunScore](/api/tracon.runscore/)

The score. If [RunScore.Id](/api/tracon.runscore/#Tracon_RunScore_Id) is empty ([Guid.Empty](https://learn.microsoft.com/dotnet/api/system.guid)), a
new identifier is generated.

`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)<[RunScore](/api/tracon.runscore/)\>

The score written.

#### Remarks

When the same author ([RunScore.Author](/api/tracon.runscore/#Tracon_RunScore_Author)) writes the same
[RunScore.Name](/api/tracon.runscore/#Tracon_RunScore_Name) onto the same target (a run or a message) a
second time, the row is **updated**, not opened as a new
row. A different name from the same author opens a new row. If
[RunScore.Author](/api/tracon.runscore/#Tracon_RunScore_Author) is empty, the rule does not apply; every
call writes a new row.

The score is validated with [RunScoreRules.Validate](/api/tracon.runscorerules/#Tracon_RunScoreRules_Validate_Tracon_RunScore_) before
it is written; every implementation must do the same.

#### Exceptions

 [ArgumentException](https://learn.microsoft.com/dotnet/api/system.argumentexception)

`score` breaks a [RunScoreRules](/api/tracon.runscorerules/) invariant.