Reference

IPersistedOperationStore

Package Trax.Api.GraphQL.PersistedOperationsNamespace Trax.Api.GraphQL.PersistedOperations.StorageSource IPersistedOperationStore.cs, UpsertOptions.cs, DbPersistedOperationStorage.cs

Programmatic reads and writes of trax.persisted_operation. The request path does not use it: HotChocolate reads documents through IOperationDocumentStorage.TryReadAsync.

Registered as a singleton when UsePersistedOperations is called. For the surface the GraphQL fields and the dashboard share, which returns refusals as payload errors instead of throwing, use IPersistedOperationsService.

A host without a GraphQL server registers it with AddPersistedOperationStore. The store reads and writes through the Trax data context registered by AddEffects(e => e.UsePostgres(...)).

Signature

public interface IPersistedOperationStore
{
    Task<PersistedOperation?> GetAsync(string id, string? tenantKey, CancellationToken ct);
 
    Task<IReadOnlyList<PersistedOperation>> ListAsync(string? tenantKey, CancellationToken ct);
 
    Task<PersistedOperation> UpsertAsync(
        string id,
        string document,
        UpsertOptions? options,
        CancellationToken ct);
 
    Task DeactivateAsync(string id, string? tenantKey, string reason, CancellationToken ct);
 
    Task RestoreAsync(string id, string? tenantKey, CancellationToken ct);
}

Members

UpsertOptions is a sealed record with init-only properties:

PropertyTypePurpose
TenantKeystring?Tenant scope for multi-tenant deployments. Null targets the single-tenant row set.
Descriptionstring?Operator-facing note recorded on the row.
BypassShapeDiffboolWhen true, skips the shape-diff guardrail on an edit.
VersionintOperator-controlled metadata stored on the row. Not used for request routing. Defaults to 0.

Behavior

  • GetAsync returns null for missing or deactivated rows.
  • ListAsync returns active and deactivated rows for the tenant.
  • UpsertAsync runs the document through IPersistedOperationValidator (HotChocolate-backed when UsePersistedOperations is wired in), extracts the GraphQL operation name from the document's operation definition, computes the response-shape fingerprint, writes both the live row and a history row in a single transaction, invalidates the local caches, and publishes a broadcast event when the broadcaster is configured.
  • Changes to one id are applied one at a time. Each write takes a transaction-scoped lock on the id (a PostgreSQL advisory lock; SQLite's write transaction) before it reads the row, so two first uploads of one id do not collide, and every upload's shape-diff check sees the row the previous change left.
  • Once a change is committed it is applied to this node's caches and broadcast whether or not the caller's token is still live. When the broker does not confirm the broadcast, the call throws PersistedOperationNotBroadcastException (CHANGE_NOT_BROADCAST): the change is saved and in force here, and other nodes pick it up when their cached entry reaches its maximum age. Repeat the change to send it again.
  • A document with no operation, or more than one, throws PersistedOperationInputException (INVALID_INPUT).
  • Validation throws one of the structured PersistedOperationException subclasses. No row is written and no broadcast fires when validation rejects the document.
  • DeactivateAsync and RestoreAsync throw InvalidOperationException when the id does not exist. Both act on a row in either state, so repeating one sends the change again.
  • All mutations append a row to trax.persisted_operation_history.
  • UpsertAsync, DeactivateAsync and RestoreAsync refuse an id starting with trax_machine_, trax_train_, trax_progress_, trax_view_, trax_client_ or trax_console_ with PersistedOperationInputException (INVALID_INPUT): those ids are the documents the host registers itself, or registered in an earlier version (trax_train_).

Examples

Manifest uploader:

var store = serviceProvider.GetRequiredService<IPersistedOperationStore>();
 
foreach (var (id, document) in manifest)
{
    await store.UpsertAsync(id, document, options: null, ct);
}

Soft-delete with reason:

var store = serviceProvider.GetRequiredService<IPersistedOperationStore>();
 
await store.DeactivateAsync(
    "userProfile_v1",
    tenantKey: null,
    reason: "broken filter in 2026-05-08 release",
    ct
);

See also