Concurrency

Concurrency control in Chronicle ensures that multiple operations don’t interfere with each other when appending events to the same event source. Chronicle provides a sophisticated concurrency control mechanism through the ConcurrencyScope concept, which allows you to define precisely how concurrency should be handled based on formalized event metadata tags.

Understanding ConcurrencyScope

A ConcurrencyScope defines the boundaries and constraints for concurrent operations when appending events. It uses formalized, well-known event metadata tags that are indexed by Chronicle to scope concurrency control to specific aspects of your events, providing fine-grained control over when concurrency violations should be detected. These tags are separate from any user-controlled event tags you may add for categorization. See Event Metadata Tags for details.

Formalized Metadata Tags for Concurrency

Chronicle uses the following formalized, indexed metadata tags to scope concurrency:

• EventSourceId: Unique identifier for the event source
• EventSourceType: Overarching, binding concept (e.g., Account)
• EventStreamType: A concrete process related to event source type (e.g., Onboarding, Transactions)
• EventStreamId: A marker to separate independent streams for a stream type (e.g., Monthly, Yearly)
• EventTypes: Specific event types to scope concurrency to

Basic Usage

Simple Concurrency Scope

The most basic form of concurrency control scopes to a specific sequence number for an event source:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

[EventType]
public record ConcurrencyAccountOpened(string AccountName);

public class ConcurrencyBankAccountService(IEventLog eventLog)
{
    public async Task OpenAccount(EventSourceId accountId, string accountName)
    {
        var concurrencyScope = new ConcurrencyScope(
            SequenceNumber: 42,
            EventSourceId: accountId);

        await eventLog.Append(
            accountId,
            new ConcurrencyAccountOpened(accountName),
            concurrencyScope: concurrencyScope);
    }
}

Kotlin

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.eventSequences.AppendOptions
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder
import io.cratis.chronicle.events.EventType

@EventType
data class ConcurrencyStockReserved(val sku: String = "", val quantity: Int = 0)

/**
 * Appends only if the event source is still at the expected sequence number — the kernel
 * rejects the append with a concurrency violation if another writer got there first.
 */
suspend fun reserveStockIfUnchanged(store: IEventStore, sku: String, expectedSequenceNumber: Long) {
    val scope = ConcurrencyScopeBuilder()
        .withSequenceNumber(EventSequenceNumber(expectedSequenceNumber))
        .withEventSourceId()
        .build()

    val result = store.eventLog.append(sku, ConcurrencyStockReserved(sku, 1), AppendOptions(concurrencyScope = scope))
    val violation = result.concurrencyViolation
    if (!result.isSuccess && violation != null) {
        println("Concurrency violation: expected ${violation.expectedSequenceNumber}, actual ${violation.actualSequenceNumber}")
    }
}

Java

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.AppendOptions;
import io.cratis.chronicle.eventSequences.AppendResult;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScope;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyViolation;

import io.cratis.chronicle.java.ConcurrencyScopeBuilderJavaBridge;
import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
record ConcurrencyStockReserved(String sku, int quantity) {}

class EventsConcurrencyBasic {
    // Appends only if the event source is still at the expected sequence number — the kernel
    // rejects the append with a concurrency violation if another writer got there first.
    void reserveStockIfUnchanged(EventStore store, String sku, long expectedSequenceNumber) {
        ConcurrencyScope scope = ConcurrencyScopeBuilderJavaBridge
            .withSequenceNumber(new ConcurrencyScopeBuilder(), expectedSequenceNumber)
            .withEventSourceId()
            .build();

        AppendResult result = EventLogJavaBridge.append(
            store.getEventLog(), sku, new ConcurrencyStockReserved(sku, 1), new AppendOptions(null, scope));

        ConcurrencyViolation violation = result.getConcurrencyViolation();
        if (!result.isSuccess() && violation != null) {
            System.out.println("Concurrency violation for event source: " + violation.getEventSourceId());
        }
    }
}

Elixir

defmodule MyApp.Events.ConcurrencyAccountOpened do
  use Chronicle.Events.EventType, id: "concurrency-account-opened"

  defstruct [:account_name]
end

defmodule MyApp.ConcurrencyBankAccountService do
  alias Chronicle.Events.ConcurrencyScope
  alias MyApp.Events.ConcurrencyAccountOpened

  def open_account(account_id, account_name) do
    scope = ConcurrencyScope.for_event_source(42)

    Chronicle.append(account_id, %ConcurrencyAccountOpened{account_name: account_name},
      concurrency_scope: scope
    )
  end
end

TypeScript

import { eventType, IEventStore } from '@cratis/chronicle';

@eventType()
class ConcurrencyAccountOpened {
    constructor(readonly accountName: string) {}
}

class ConcurrencyBankAccountService {
    constructor(private readonly store: IEventStore) {}

    async openAccount(accountId: string, accountName: string): Promise<void> {
        await this.store.eventLog.append(accountId, new ConcurrencyAccountOpened(accountName), {
            concurrencyScope: {
                sequenceNumber: 42n,
                eventSourceId: true
            }
        });
    }
}

Using ConcurrencyScopeBuilder

For more complex scenarios, use the ConcurrencyScopeBuilder to fluently construct concurrency scopes:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

[EventType]
public record ConcurrencyMoneyDeposited(decimal Amount);

[EventType]
public record ConcurrencyMoneyWithdrawn(decimal Amount);

public class ConcurrencyAccountTransactionService(IEventLog eventLog)
{
    public async Task ProcessTransaction(EventSourceId accountId, decimal amount)
    {
        var concurrencyScope = new ConcurrencyScopeBuilder()
            .WithEventSourceId(accountId)
            .WithSequenceNumber(15)
            .WithEventStreamType("Transactions")
            .WithEventType<ConcurrencyMoneyDeposited>()
            .WithEventType<ConcurrencyMoneyWithdrawn>()
            .Build();

        await eventLog.Append(
            accountId,
            new ConcurrencyMoneyDeposited(amount),
            concurrencyScope: concurrencyScope);
    }
}

Kotlin

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.eventSequences.AppendOptions
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder

@EventType
data class ConcurrencyMoneyDeposited(val amount: Double = 0.0)

/**
 * Uses [ConcurrencyScopeBuilder] to fluently narrow a concurrency scope to this account's own
 * event source id and a specific event stream type.
 */
suspend fun processTransaction(store: IEventStore, accountId: String, amount: Double) {
    val concurrencyScope = ConcurrencyScopeBuilder()
        .withEventSourceId()
        .withSequenceNumber(EventSequenceNumber(15))
        .withEventStreamType("Transactions")
        .build()

    store.eventLog.append(
        accountId,
        ConcurrencyMoneyDeposited(amount),
        AppendOptions(eventStreamType = "Transactions", concurrencyScope = concurrencyScope)
    )
}

Java

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.AppendOptions;
import io.cratis.chronicle.eventSequences.AppendResult;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScope;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder;

import io.cratis.chronicle.java.AppendOptionsBuilder;
import io.cratis.chronicle.java.ConcurrencyScopeBuilderJavaBridge;
import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
record ConcurrencyMoneyDeposited(double amount) {}

class EventsConcurrencyBuilder {
    // Uses ConcurrencyScopeBuilder to fluently narrow a concurrency scope to this account's own
    // event source id and a specific event stream type.
    AppendResult processTransaction(EventStore store, String accountId, double amount) {
        ConcurrencyScope concurrencyScope = ConcurrencyScopeBuilderJavaBridge
            .withSequenceNumber(new ConcurrencyScopeBuilder(), 15)
            .withEventSourceId()
            .withEventStreamType("Transactions")
            .build();

        AppendOptions options = new AppendOptionsBuilder()
            .eventStreamType("Transactions")
            .concurrencyScope(concurrencyScope)
            .build();

        return EventLogJavaBridge.append(store.getEventLog(), accountId, new ConcurrencyMoneyDeposited(amount), options);
    }
}

Elixir

defmodule MyApp.Events.ConcurrencyMoneyDeposited do
  use Chronicle.Events.EventType, id: "concurrency-money-deposited"

  defstruct [:amount]
end

defmodule MyApp.Events.ConcurrencyMoneyWithdrawn do
  use Chronicle.Events.EventType, id: "concurrency-money-withdrawn"

  defstruct [:amount]
end

defmodule MyApp.ConcurrencyAccountTransactionService do
  alias Chronicle.Events.ConcurrencyScope
  alias MyApp.Events.{ConcurrencyMoneyDeposited, ConcurrencyMoneyWithdrawn}

  def process_transaction(account_id, amount) do
    scope =
      ConcurrencyScope.for_event_source(15,
        event_stream_type: "Transactions",
        event_types: [ConcurrencyMoneyDeposited, ConcurrencyMoneyWithdrawn]
      )

    Chronicle.append(account_id, %ConcurrencyMoneyDeposited{amount: amount},
      concurrency_scope: scope
    )
  end
end

TypeScript

import { eventType, getEventTypeFor, IEventLog } from '@cratis/chronicle';

@eventType()
class ConcurrencyMoneyDeposited {
    constructor(readonly amount: number) {}
}

@eventType()
class ConcurrencyMoneyWithdrawn {
    constructor(readonly amount: number) {}
}

class ConcurrencyAccountTransactionService {
    constructor(private readonly eventLog: IEventLog) {}

    async processTransaction(accountId: string, amount: number): Promise<void> {
        await this.eventLog.append(accountId, new ConcurrencyMoneyDeposited(amount), {
            concurrencyScope: {
                sequenceNumber: 15n,
                eventStreamType: 'Transactions',
                eventTypes: [getEventTypeFor(ConcurrencyMoneyDeposited), getEventTypeFor(ConcurrencyMoneyWithdrawn)]
            }
        });
    }
}

Scoping by Event Metadata Tags

EventSourceType and EventStreamType

You can scope concurrency to specific event source types and stream types:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

[EventType]
public record ConcurrencyAccountSettingsUpdated(string Settings);

public class ConcurrencyAccountManagementService(IEventLog eventLog)
{
    public async Task UpdateAccountSettings(EventSourceId accountId, string settings)
    {
        var concurrencyScope = new ConcurrencyScopeBuilder()
            .WithEventSourceId(accountId)
            .WithEventSourceType("BankAccount")
            .WithEventStreamType("AccountManagement")
            .WithSequenceNumber(10)
            .Build();

        await eventLog.Append(
            accountId,
            new ConcurrencyAccountSettingsUpdated(settings),
            eventSourceType: "BankAccount",
            eventStreamType: "AccountManagement",
            concurrencyScope: concurrencyScope);
    }
}

Kotlin

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.eventSequences.AppendOptions
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder

@EventType
data class ConcurrencyAccountSettingsUpdated(val settings: String = "")

/**
 * Scopes concurrency to a specific event source type and event stream type, in addition to the
 * event source id.
 */
suspend fun updateAccountSettings(store: IEventStore, accountId: String, settings: String) {
    val concurrencyScope = ConcurrencyScopeBuilder()
        .withEventSourceId()
        .withEventSourceType("BankAccount")
        .withEventStreamType("AccountManagement")
        .withSequenceNumber(EventSequenceNumber(10))
        .build()

    store.eventLog.append(
        accountId,
        ConcurrencyAccountSettingsUpdated(settings),
        AppendOptions(eventSourceType = "BankAccount", eventStreamType = "AccountManagement", concurrencyScope = concurrencyScope)
    )
}

Java

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.AppendOptions;
import io.cratis.chronicle.eventSequences.AppendResult;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScope;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder;

import io.cratis.chronicle.java.AppendOptionsBuilder;
import io.cratis.chronicle.java.ConcurrencyScopeBuilderJavaBridge;
import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
record ConcurrencyAccountSettingsUpdated(String settings) {}

class EventsConcurrencySourceAndStreamType {
    // Scopes concurrency to a specific event source type and event stream type, in addition to
    // the event source id.
    AppendResult updateAccountSettings(EventStore store, String accountId, String settings) {
        ConcurrencyScope concurrencyScope = ConcurrencyScopeBuilderJavaBridge
            .withSequenceNumber(new ConcurrencyScopeBuilder(), 10)
            .withEventSourceId()
            .withEventSourceType("BankAccount")
            .withEventStreamType("AccountManagement")
            .build();

        AppendOptions options = new AppendOptionsBuilder()
            .eventSourceType("BankAccount")
            .eventStreamType("AccountManagement")
            .concurrencyScope(concurrencyScope)
            .build();

        return EventLogJavaBridge.append(store.getEventLog(), accountId, new ConcurrencyAccountSettingsUpdated(settings), options);
    }
}

Elixir

defmodule MyApp.Events.ConcurrencyAccountSettingsUpdated do
  use Chronicle.Events.EventType, id: "concurrency-account-settings-updated"

  defstruct [:settings]
end

defmodule MyApp.ConcurrencyAccountManagementService do
  alias Chronicle.Events.ConcurrencyScope
  alias MyApp.Events.ConcurrencyAccountSettingsUpdated

  def update_account_settings(account_id, settings) do
    scope =
      ConcurrencyScope.for_event_source(10,
        event_source_type: "BankAccount",
        event_stream_type: "AccountManagement"
      )

    Chronicle.append(
      account_id,
      %ConcurrencyAccountSettingsUpdated{settings: settings},
      event_source_type: "BankAccount",
      event_stream_type: "AccountManagement",
      concurrency_scope: scope
    )
  end
end

TypeScript

import { eventType, IEventLog } from '@cratis/chronicle';

@eventType()
class ConcurrencyAccountSettingsUpdated {
    constructor(readonly settings: string) {}
}

class ConcurrencyAccountManagementService {
    constructor(private readonly eventLog: IEventLog) {}

    async updateAccountSettings(accountId: string, settings: string): Promise<void> {
        await this.eventLog.appendMany([{
            eventSourceId: accountId,
            event: new ConcurrencyAccountSettingsUpdated(settings),
            eventSourceType: 'BankAccount',
            eventStreamType: 'AccountManagement'
        }], {
            concurrencyScope: {
                sequenceNumber: 10n,
                eventSourceType: 'BankAccount',
                eventStreamType: 'AccountManagement'
            }
        });
    }
}

EventStreamId

Use event stream IDs to scope concurrency to specific streams within a stream type:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

[EventType]
public record ConcurrencyMonthlyReportGenerated(string Month);

public class ConcurrencyMonthlyReportService(IEventLog eventLog)
{
    public async Task GenerateMonthlyReport(EventSourceId accountId, DateTime month)
    {
        var monthKey = month.ToString("yyyy-MM");

        var concurrencyScope = new ConcurrencyScopeBuilder()
            .WithEventSourceId(accountId)
            .WithEventStreamType("Reporting")
            .WithEventStreamId(monthKey)
            .WithSequenceNumber(5)
            .Build();

        await eventLog.Append(
            accountId,
            new ConcurrencyMonthlyReportGenerated(monthKey),
            eventStreamType: "Reporting",
            eventStreamId: monthKey,
            concurrencyScope: concurrencyScope);
    }
}

Kotlin

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.eventSequences.AppendOptions
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder

@EventType
data class ConcurrencyMonthlyReportGenerated(val month: String = "")

/**
 * Scopes concurrency to a specific event stream id within a stream type, so reports for
 * different months don't contend with each other.
 */
suspend fun generateMonthlyReport(store: IEventStore, accountId: String, monthKey: String) {
    val concurrencyScope = ConcurrencyScopeBuilder()
        .withEventSourceId()
        .withEventStreamType("Reporting")
        .withEventStreamId(monthKey)
        .withSequenceNumber(EventSequenceNumber(5))
        .build()

    store.eventLog.append(
        accountId,
        ConcurrencyMonthlyReportGenerated(monthKey),
        AppendOptions(eventStreamType = "Reporting", eventStreamId = monthKey, concurrencyScope = concurrencyScope)
    )
}

Java

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.AppendOptions;
import io.cratis.chronicle.eventSequences.AppendResult;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScope;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder;

import io.cratis.chronicle.java.AppendOptionsBuilder;
import io.cratis.chronicle.java.ConcurrencyScopeBuilderJavaBridge;
import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
record ConcurrencyMonthlyReportGenerated(String month) {}

class EventsConcurrencyStreamId {
    // Scopes concurrency to a specific event stream id within a stream type, so reports for
    // different months don't contend with each other.
    AppendResult generateMonthlyReport(EventStore store, String accountId, String monthKey) {
        ConcurrencyScope concurrencyScope = ConcurrencyScopeBuilderJavaBridge
            .withSequenceNumber(new ConcurrencyScopeBuilder(), 5)
            .withEventSourceId()
            .withEventStreamType("Reporting")
            .withEventStreamId(monthKey)
            .build();

        AppendOptions options = new AppendOptionsBuilder()
            .eventStreamType("Reporting")
            .eventStreamId(monthKey)
            .concurrencyScope(concurrencyScope)
            .build();

        return EventLogJavaBridge.append(store.getEventLog(), accountId, new ConcurrencyMonthlyReportGenerated(monthKey), options);
    }
}

Elixir

defmodule MyApp.Events.ConcurrencyMonthlyReportGenerated do
  use Chronicle.Events.EventType, id: "concurrency-monthly-report-generated"

  defstruct [:month]
end

defmodule MyApp.ConcurrencyMonthlyReportService do
  alias Chronicle.Events.ConcurrencyScope
  alias MyApp.Events.ConcurrencyMonthlyReportGenerated

  def generate_monthly_report(account_id, month_key) do
    scope =
      ConcurrencyScope.for_event_source(5,
        event_stream_type: "Reporting",
        event_stream_id: month_key
      )

    Chronicle.append(
      account_id,
      %ConcurrencyMonthlyReportGenerated{month: month_key},
      event_stream_type: "Reporting",
      event_stream_id: month_key,
      concurrency_scope: scope
    )
  end
end

TypeScript

import { eventType, IEventLog } from '@cratis/chronicle';

@eventType()
class ConcurrencyMonthlyReportGenerated {
    constructor(readonly month: string) {}
}

class ConcurrencyMonthlyReportService {
    constructor(private readonly eventLog: IEventLog) {}

    async generateMonthlyReport(accountId: string, month: Date): Promise<void> {
        const monthKey = `${month.getFullYear()}-${String(month.getMonth() + 1).padStart(2, '0')}`;

        await this.eventLog.appendMany([{
            eventSourceId: accountId,
            event: new ConcurrencyMonthlyReportGenerated(monthKey),
            eventStreamType: 'Reporting',
            eventStreamId: monthKey
        }], {
            concurrencyScope: {
                sequenceNumber: 5n,
                eventStreamType: 'Reporting',
                eventStreamId: monthKey
            }
        });
    }
}

Event Types

Scope concurrency to specific event types to allow concurrent operations on different types of events:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

[EventType]
public record ConcurrencyPaymentProcessed(decimal Amount);

[EventType]
public record ConcurrencyPaymentFailed(decimal Amount);

[EventType]
public record ConcurrencyPaymentRefunded(decimal Amount);

public class ConcurrencyAccountService(IEventLog eventLog)
{
    public async Task ProcessPayment(EventSourceId accountId, decimal amount)
    {
        // Only check concurrency for payment-related events
        var concurrencyScope = new ConcurrencyScopeBuilder()
            .WithEventSourceId(accountId)
            .WithSequenceNumber(20)
            .WithEventType<ConcurrencyPaymentProcessed>()
            .WithEventType<ConcurrencyPaymentFailed>()
            .WithEventType<ConcurrencyPaymentRefunded>()
            .Build();

        await eventLog.Append(
            accountId,
            new ConcurrencyPaymentProcessed(amount),
            concurrencyScope: concurrencyScope);
    }
}

Kotlin

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.events.EventTypeDescriptor
import io.cratis.chronicle.events.EventTypeId
import io.cratis.chronicle.eventSequences.AppendOptions
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder

@EventType
data class ConcurrencyPaymentProcessed(val amount: Double = 0.0)

@EventType
data class ConcurrencyPaymentFailed(val amount: Double = 0.0)

@EventType
data class ConcurrencyPaymentRefunded(val amount: Double = 0.0)

/**
 * Narrows the concurrency scope to only the payment-related event types, so other event types
 * appended for the same account don't affect this check.
 */
suspend fun processPayment(store: IEventStore, accountId: String, amount: Double) {
    val concurrencyScope = ConcurrencyScopeBuilder()
        .withEventSourceId()
        .withSequenceNumber(EventSequenceNumber(20))
        .withEventType(EventTypeDescriptor(EventTypeId("ConcurrencyPaymentProcessed")))
        .withEventType(EventTypeDescriptor(EventTypeId("ConcurrencyPaymentFailed")))
        .withEventType(EventTypeDescriptor(EventTypeId("ConcurrencyPaymentRefunded")))
        .build()

    store.eventLog.append(
        accountId,
        ConcurrencyPaymentProcessed(amount),
        AppendOptions(concurrencyScope = concurrencyScope)
    )
}

Java

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.events.EventTypeDescriptor;
import io.cratis.chronicle.eventSequences.AppendOptions;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScope;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder;

import io.cratis.chronicle.java.ConcurrencyScopeBuilderJavaBridge;
import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
record ConcurrencyPaymentProcessed(double amount) {}

@EventType
record ConcurrencyPaymentFailed(double amount) {}

@EventType
record ConcurrencyPaymentRefunded(double amount) {}

class EventsConcurrencyEventTypes {
    /**
     * Narrows the concurrency scope to only the payment-related event types, so other event types
     * appended for the same account don't affect this check.
     */
    void processPayment(EventStore store, String accountId, double amount) {
        ConcurrencyScope concurrencyScope = ConcurrencyScopeBuilderJavaBridge
            .withSequenceNumber(new ConcurrencyScopeBuilder(), 20)
            .withEventSourceId()
            .withEventType(EventTypeDescriptor.parse("ConcurrencyPaymentProcessed"))
            .withEventType(EventTypeDescriptor.parse("ConcurrencyPaymentFailed"))
            .withEventType(EventTypeDescriptor.parse("ConcurrencyPaymentRefunded"))
            .build();

        EventLogJavaBridge.append(
            store.getEventLog(),
            accountId,
            new ConcurrencyPaymentProcessed(amount),
            new AppendOptions(null, concurrencyScope));
    }
}

Elixir

defmodule MyApp.Events.ConcurrencyPaymentProcessed do
  use Chronicle.Events.EventType, id: "concurrency-payment-processed"

  defstruct [:amount]
end

defmodule MyApp.Events.ConcurrencyPaymentFailed do
  use Chronicle.Events.EventType, id: "concurrency-payment-failed"

  defstruct [:amount]
end

defmodule MyApp.Events.ConcurrencyPaymentRefunded do
  use Chronicle.Events.EventType, id: "concurrency-payment-refunded"

  defstruct [:amount]
end

defmodule MyApp.ConcurrencyAccountService do
  alias Chronicle.Events.ConcurrencyScope
  alias MyApp.Events.{ConcurrencyPaymentFailed, ConcurrencyPaymentProcessed, ConcurrencyPaymentRefunded}

  def process_payment(account_id, amount) do
    # Only check concurrency for payment-related events
    scope =
      ConcurrencyScope.for_event_source(20,
        event_types: [ConcurrencyPaymentProcessed, ConcurrencyPaymentFailed, ConcurrencyPaymentRefunded]
      )

    Chronicle.append(account_id, %ConcurrencyPaymentProcessed{amount: amount},
      concurrency_scope: scope
    )
  end
end

TypeScript

import { eventType, getEventTypeFor, IEventLog } from '@cratis/chronicle';

@eventType()
class ConcurrencyPaymentProcessed {
    constructor(readonly amount: number) {}
}

@eventType()
class ConcurrencyPaymentFailed {
    constructor(readonly amount: number) {}
}

@eventType()
class ConcurrencyPaymentRefunded {
    constructor(readonly amount: number) {}
}

class ConcurrencyAccountService {
    constructor(private readonly eventLog: IEventLog) {}

    async processPayment(accountId: string, amount: number): Promise<void> {
        // Only check concurrency for payment-related events
        await this.eventLog.append(accountId, new ConcurrencyPaymentProcessed(amount), {
            concurrencyScope: {
                sequenceNumber: 20n,
                eventTypes: [
                    getEventTypeFor(ConcurrencyPaymentProcessed),
                    getEventTypeFor(ConcurrencyPaymentFailed),
                    getEventTypeFor(ConcurrencyPaymentRefunded)
                ]
            }
        });
    }
}

AppendMany with Concurrency Scopes

When appending multiple events, you can specify different concurrency scopes for different event sources:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

[EventType]
public record ConcurrencyMoneyWithdrawnForTransfer(decimal Amount);

[EventType]
public record ConcurrencyMoneyDepositedForTransfer(decimal Amount);

public class ConcurrencyTransferService(IEventLog eventLog)
{
    public async Task TransferMoney(EventSourceId fromAccount, EventSourceId toAccount, decimal amount)
    {
        var events = new[]
        {
            new EventForEventSourceId(fromAccount, new ConcurrencyMoneyWithdrawnForTransfer(amount)),
            new EventForEventSourceId(toAccount, new ConcurrencyMoneyDepositedForTransfer(amount))
        };

        var concurrencyScopes = new Dictionary<EventSourceId, ConcurrencyScope>
        {
            [fromAccount] = new ConcurrencyScopeBuilder()
                .WithEventSourceId(fromAccount)
                .WithSequenceNumber(50)
                .WithEventType<ConcurrencyMoneyWithdrawnForTransfer>()
                .Build(),

            [toAccount] = new ConcurrencyScopeBuilder()
                .WithEventSourceId(toAccount)
                .WithSequenceNumber(25)
                .WithEventType<ConcurrencyMoneyDepositedForTransfer>()
                .Build()
        };

        await eventLog.AppendMany(events, concurrencyScopes: concurrencyScopes);
    }
}

Kotlin

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.events.EventTypeDescriptor
import io.cratis.chronicle.events.EventTypeId
import io.cratis.chronicle.eventSequences.AppendResult
import io.cratis.chronicle.eventSequences.EventForEventSourceId
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder

@EventType
data class ConcurrencyMoneyWithdrawnForTransfer(val amount: Double = 0.0)

@EventType
data class ConcurrencyMoneyDepositedForTransfer(val amount: Double = 0.0)

/**
 * Appends to two event sources as one atomic batch, each checked against its own expected
 * sequence number and narrowed to the event type it produces.
 */
suspend fun transferMoney(store: IEventStore, fromAccount: String, toAccount: String, amount: Double): List<AppendResult> {
    val events = listOf(
        EventForEventSourceId(fromAccount, ConcurrencyMoneyWithdrawnForTransfer(amount)),
        EventForEventSourceId(toAccount, ConcurrencyMoneyDepositedForTransfer(amount))
    )

    val concurrencyScopes = mapOf(
        fromAccount to ConcurrencyScopeBuilder()
            .withEventSourceId()
            .withSequenceNumber(EventSequenceNumber(50))
            .withEventType(EventTypeDescriptor(EventTypeId("ConcurrencyMoneyWithdrawnForTransfer")))
            .build(),
        toAccount to ConcurrencyScopeBuilder()
            .withEventSourceId()
            .withSequenceNumber(EventSequenceNumber(25))
            .withEventType(EventTypeDescriptor(EventTypeId("ConcurrencyMoneyDepositedForTransfer")))
            .build()
    )

    return store.eventLog.appendMany(events, concurrencyScopes)
}

Java

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.AppendResult;
import io.cratis.chronicle.eventSequences.EventForEventSourceId;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScope;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder;

import java.util.List;
import java.util.Map;

import io.cratis.chronicle.java.ConcurrencyScopeBuilderJavaBridge;
import io.cratis.chronicle.java.EventSequenceJavaBridge;

@EventType
record ConcurrencyMoneyWithdrawnForTransfer(double amount) {}

@EventType
record ConcurrencyMoneyDepositedForTransfer(double amount) {}

class EventsConcurrencyAppendMany {
    // Appends to two event sources as one atomic batch, each checked against its own expected
    // sequence number.
    List<AppendResult> transferMoney(EventStore store, String fromAccount, String toAccount, double amount) {
        List<EventForEventSourceId> events = List.of(
            new EventForEventSourceId(fromAccount, new ConcurrencyMoneyWithdrawnForTransfer(amount)),
            new EventForEventSourceId(toAccount, new ConcurrencyMoneyDepositedForTransfer(amount)));

        ConcurrencyScope fromScope = ConcurrencyScopeBuilderJavaBridge
            .withSequenceNumber(new ConcurrencyScopeBuilder(), 50)
            .withEventSourceId()
            .build();
        ConcurrencyScope toScope = ConcurrencyScopeBuilderJavaBridge
            .withSequenceNumber(new ConcurrencyScopeBuilder(), 25)
            .withEventSourceId()
            .build();

        Map<String, ConcurrencyScope> concurrencyScopes = Map.of(fromAccount, fromScope, toAccount, toScope);

        return EventSequenceJavaBridge.appendMany(store.getEventLog(), events, concurrencyScopes, null);
    }
}

Elixir

defmodule MyApp.Events.ConcurrencyMoneyWithdrawnForTransfer do
  use Chronicle.Events.EventType, id: "concurrency-money-withdrawn-for-transfer"

  defstruct [:amount]
end

defmodule MyApp.Events.ConcurrencyMoneyDepositedForTransfer do
  use Chronicle.Events.EventType, id: "concurrency-money-deposited-for-transfer"

  defstruct [:amount]
end

defmodule MyApp.ConcurrencyTransferService do
  alias Chronicle.Events.ConcurrencyScope
  alias Chronicle.Transactions.UnitOfWork
  alias MyApp.Events.{ConcurrencyMoneyDepositedForTransfer, ConcurrencyMoneyWithdrawnForTransfer}

  def transfer_money(from_account, to_account, amount) do
    unit_of_work = UnitOfWork.begin()

    try do
      :ok =
        Chronicle.append(
          from_account,
          %ConcurrencyMoneyWithdrawnForTransfer{amount: amount},
          concurrency_scope: ConcurrencyScope.for_event_source(50)
        )

      :ok =
        Chronicle.append(
          to_account,
          %ConcurrencyMoneyDepositedForTransfer{amount: amount},
          concurrency_scope: ConcurrencyScope.for_event_source(25)
        )

      :ok = UnitOfWork.commit(unit_of_work)
    rescue
      exception ->
        UnitOfWork.rollback(unit_of_work)
        reraise exception, __STACKTRACE__
    end
  end
end

TypeScript

import { eventType, EventForEventSourceId, getEventTypeFor, IEventLog } from '@cratis/chronicle';

@eventType()
class ConcurrencyMoneyWithdrawnForTransfer {
    constructor(readonly amount: number) {}
}

@eventType()
class ConcurrencyMoneyDepositedForTransfer {
    constructor(readonly amount: number) {}
}

class ConcurrencyTransferService {
    constructor(private readonly eventLog: IEventLog) {}

    async transferMoney(fromAccount: string, toAccount: string, amount: number): Promise<void> {
        const events: EventForEventSourceId[] = [
            { eventSourceId: fromAccount, event: new ConcurrencyMoneyWithdrawnForTransfer(amount) },
            { eventSourceId: toAccount, event: new ConcurrencyMoneyDepositedForTransfer(amount) }
        ];

        await this.eventLog.appendMany(events, {
            concurrencyScopes: {
                [fromAccount]: {
                    sequenceNumber: 50n,
                    eventTypes: [getEventTypeFor(ConcurrencyMoneyWithdrawnForTransfer)]
                },
                [toAccount]: {
                    sequenceNumber: 25n,
                    eventTypes: [getEventTypeFor(ConcurrencyMoneyDepositedForTransfer)]
                }
            }
        });
    }
}

Event Source Operations with Concurrency

You can also use concurrency scopes with event source operations:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Operations;

[EventType]
public record ConcurrencyAccountValidated;

[EventType]
public record ConcurrencyAccountProcessed;

public class ConcurrencyBatchAccountProcessor(IEventLog eventLog)
{
    public async Task ProcessAccountBatch(EventSourceId accountId)
    {
        await eventLog
            .ForEventSourceId(accountId, source => source
                .WithConcurrencyScope(scope => scope
                    .WithSequenceNumber(30)
                    .WithEventType<ConcurrencyAccountProcessed>()
                    .WithEventType<ConcurrencyAccountValidated>())
                .Append(new ConcurrencyAccountValidated())
                .Append(new ConcurrencyAccountProcessed()))
            .Perform();
    }
}

Kotlin

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.events.EventTypeDescriptor
import io.cratis.chronicle.events.EventTypeId
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.operations.forEventSourceId

@EventType
class ConcurrencyAccountValidated

@EventType
class ConcurrencyAccountProcessed

/**
 * Composes two events against the same event source, with a shared concurrency scope narrowed
 * to the event types this operation produces.
 */
suspend fun processAccountBatch(store: IEventStore, accountId: String) {
    store.eventLog
        .forEventSourceId(accountId) {
            withConcurrencyScope {
                withSequenceNumber(EventSequenceNumber(30))
                withEventType(EventTypeDescriptor(EventTypeId("ConcurrencyAccountProcessed")))
                withEventType(EventTypeDescriptor(EventTypeId("ConcurrencyAccountValidated")))
            }
            append(ConcurrencyAccountValidated())
            append(ConcurrencyAccountProcessed())
        }
        .perform()
}

Java

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.AppendResult;
import io.cratis.chronicle.eventSequences.operations.EventSequenceOperations;

import java.util.List;

import io.cratis.chronicle.java.ConcurrencyScopeBuilderJavaBridge;
import io.cratis.chronicle.java.EventSequenceOperationsJavaBridge;
import io.cratis.chronicle.java.EventSourceOperationsJavaBridge;

@EventType
record ConcurrencyAccountValidated() {}

@EventType
record ConcurrencyAccountProcessed() {}

class EventsConcurrencyForEventSourceOperations {
    // Composes two events against the same event source, with a shared concurrency scope.
    List<AppendResult> processAccountBatch(EventStore store, String accountId) {
        EventSequenceOperations operations = EventSequenceOperationsJavaBridge.operationsFor(store.getEventLog());

        EventSequenceOperationsJavaBridge.forEventSourceId(operations, accountId, source -> {
            EventSourceOperationsJavaBridge.withConcurrencyScope(
                source,
                scope -> ConcurrencyScopeBuilderJavaBridge.withSequenceNumber(scope, 30).withEventSourceId());
            EventSourceOperationsJavaBridge.append(source, new ConcurrencyAccountValidated());
            EventSourceOperationsJavaBridge.append(source, new ConcurrencyAccountProcessed());
        });

        return EventSequenceOperationsJavaBridge.perform(operations);
    }
}

Elixir

Elixir does not support this workflow yet.

TypeScript

TypeScript does not support this workflow yet.

Handling Concurrency Violations

When a concurrency violation occurs, Chronicle will return a ConcurrencyViolation in the append result:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

[EventType]
public record ConcurrencySafeAccountOpened(string AccountName);

public class ConcurrencySafeAccountService(IEventLog eventLog)
{
    public async Task<bool> TryOpenAccount(EventSourceId accountId, string accountName)
    {
        var concurrencyScope = new ConcurrencyScope(
            SequenceNumber: EventSequenceNumber.BeforeFirst, // Expect no event for this account yet
            EventSourceId: accountId);

        var result = await eventLog.Append(
            accountId,
            new ConcurrencySafeAccountOpened(accountName),
            concurrencyScope: concurrencyScope);

        if (result.HasConcurrencyViolations)
        {
            // result.ConcurrencyViolation describes the expected vs actual sequence number
            return false;
        }

        // False would mean nothing was compared against the event store
        return result.IsSuccess && result.ConcurrencyCheckPerformed;
    }
}

Kotlin

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.eventSequences.AppendOptions
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder

@EventType
data class ConcurrencySafeAccountOpened(val accountName: String = "")

/**
 * Handles a concurrency violation reported on [io.cratis.chronicle.eventSequences.AppendResult.concurrencyViolation]
 * by comparing the expected and actual sequence numbers the kernel found.
 */
suspend fun tryOpenAccount(store: IEventStore, accountId: String, accountName: String): Boolean {
    val concurrencyScope = ConcurrencyScopeBuilder()
        .withEventSourceId()
        .withSequenceNumber(EventSequenceNumber.first)
        .build()

    val result = store.eventLog.append(
        accountId,
        ConcurrencySafeAccountOpened(accountName),
        AppendOptions(concurrencyScope = concurrencyScope)
    )

    val violation = result.concurrencyViolation
    if (violation != null) {
        println("Expected sequence ${violation.expectedSequenceNumber.value}, actual was ${violation.actualSequenceNumber.value}")
        return false
    }

    return result.isSuccess
}

Java

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.AppendOptions;
import io.cratis.chronicle.eventSequences.AppendResult;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScope;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyViolation;

import io.cratis.chronicle.java.AppendOptionsBuilder;
import io.cratis.chronicle.java.ConcurrencyScopeBuilderJavaBridge;
import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
record ConcurrencySafeAccountOpened(String accountName) {}

class EventsConcurrencyHandlingViolations {
    // Handles a concurrency violation reported on AppendResult.getConcurrencyViolation() - the
    // event source id it was reported for is enough to tell which account lost the race.
    boolean tryOpenAccount(EventStore store, String accountId, String accountName) {
        ConcurrencyScope concurrencyScope = ConcurrencyScopeBuilderJavaBridge
            .withSequenceNumber(new ConcurrencyScopeBuilder(), 0)
            .withEventSourceId()
            .build();

        AppendOptions options = new AppendOptionsBuilder().concurrencyScope(concurrencyScope).build();
        AppendResult result = EventLogJavaBridge.append(
            store.getEventLog(), accountId, new ConcurrencySafeAccountOpened(accountName), options);

        ConcurrencyViolation violation = result.getConcurrencyViolation();
        if (violation != null) {
            System.out.println("Concurrency violation for event source " + violation.getEventSourceId());
            return false;
        }

        return result.isSuccess();
    }
}

Elixir

defmodule MyApp.Events.ConcurrencySafeAccountOpened do
  use Chronicle.Events.EventType, id: "concurrency-safe-account-opened"

  defstruct [:account_name]
end

defmodule MyApp.ConcurrencySafeAccountService do
  alias Chronicle.EventSequences.EventLog
  alias Chronicle.Events.ConcurrencyScope
  alias MyApp.Events.ConcurrencySafeAccountOpened

  def try_open_account(account_id, account_name) do
    with {:ok, tail} <- EventLog.get_tail_sequence_number(account_id) do
      # Expect no event for this account yet
      scope = ConcurrencyScope.for_event_source(tail)

      case Chronicle.append(
             account_id,
             %ConcurrencySafeAccountOpened{account_name: account_name},
             concurrency_scope: scope
           ) do
        :ok ->
          true

        {:error, {:append_errors, _errors}} ->
          # A concurrency violation surfaces as an append error — retry against
          # the state the winner produced, or surface the conflict.
          false

        {:error, _reason} ->
          false
      end
    end
  end
end

TypeScript

TypeScript does not support this workflow yet.

Concurrency Strategies

Chronicle provides built-in concurrency strategies:

Optimistic Concurrency Strategy

This strategy gets the current tail sequence number and uses it as the expected sequence number:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

[EventType]
public record ConcurrencyAccountNameChanged(string NewName);

// Configured automatically when using dependency injection
public class ConcurrencyOptimisticAccountService(IEventLog eventLog, IConcurrencyScopeStrategies strategies)
{
    public async Task UpdateAccount(EventSourceId accountId, string newName)
    {
        var strategy = strategies.GetFor(eventLog);
        var concurrencyScope = await strategy.GetScope(accountId);

        await eventLog.Append(
            accountId,
            new ConcurrencyAccountNameChanged(newName),
            concurrencyScope: concurrencyScope);
    }
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule MyApp.Events.ConcurrencyStrategyAccountNameChanged do
  use Chronicle.Events.EventType, id: "concurrency-strategy-account-name-changed"

  defstruct [:new_name]
end

defmodule MyApp.ConcurrencyOptimisticAccountService do
  alias Chronicle.EventSequences.EventLog
  alias Chronicle.Events.ConcurrencyScope
  alias MyApp.Events.ConcurrencyStrategyAccountNameChanged

  def update_account(account_id, new_name) do
    # The optimistic strategy: read the current tail for this event source and
    # expect nothing to have been appended since.
    {:ok, tail} = EventLog.get_tail_sequence_number(account_id)
    scope = ConcurrencyScope.for_event_source(tail)

    Chronicle.append(
      account_id,
      %ConcurrencyStrategyAccountNameChanged{new_name: new_name},
      concurrency_scope: scope
    )
  end
end

TypeScript

TypeScript does not support this workflow yet.

Note: [EventStreamType] on a reactor or reducer scopes which events an observer receives (see Filter by event stream type) — it does not set the EventStreamType used for concurrency scoping on an append call. Set eventStreamType explicitly on Append/AppendMany, or through ConcurrencyScopeBuilder.WithEventStreamType(...), when you need concurrency scoped to a specific stream type.

The First Append Into a Scope Is Not Checked by Default

A concurrency check needs something to compare against, and the optimistic strategy gets one by reading the tail through the scope’s own narrowing. When nothing matching that narrowing has been appended yet there is no tail to read, so the strategy reports EventSequenceNumber.Unavailable — the same value that means “no expected sequence number was supplied at all”. The kernel cannot act on that, so it skips the check, notes it in a debug-level log line, and lets the append through — the skip is the designed default, so it is not logged as a warning.

This is not limited to narrow scopes — it is every first append into a scope:

• The first event on a new event source has no tail, so its append is not checked.
• The first event carrying a new EventSourceType, EventStreamType, or EventStreamId is not checked either, even when the event source itself already has plenty of events under a different narrowing.

The second case is the one to watch. It is the append most exposed to a race — it opens a new partition on a stream that other writers are already using — and by default it is the one the check does not cover.

Checking It — Opt In

Turn the check on and the strategy stops saying “no sequence number” for an empty narrowing and starts saying what a first append actually expects: no event matching this narrowing may exist. The kernel checks that, and rejects the append with a ConcurrencyViolation if a matching event turned up between the scope being resolved and the append arriving.

There are two levels, and you can use either or both:

C#

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

public static class ConcurrencyFirstAppendCheckSetup
{
    // Application-wide: every first append into a scope the optimistic strategy resolves is checked.
    public static void ConfigureChronicle(ChronicleOptions options) =>
        options.ConcurrencyOptions.CheckFirstAppendIntoAScope = true;
}

[EventType]
public record ConcurrencyFirstAppendPartitionOpened(string Name);

public class ConcurrencyFirstAppendPartitionService(IEventLog eventLog)
{
    // Per append: ask for the same check on one behavior, without turning it on everywhere.
    public async Task<bool> TryOpenPartition(EventSourceId accountId, string name)
    {
        var concurrencyScope = new ConcurrencyScopeBuilder()
            .ExpectingNoMatchingEvent()
            .WithEventSourceId(accountId)
            .WithEventType<ConcurrencyFirstAppendPartitionOpened>()
            .Build();

        var result = await eventLog.Append(
            accountId,
            new ConcurrencyFirstAppendPartitionOpened(name),
            concurrencyScope: concurrencyScope);

        return result.IsSuccess;
    }
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

Elixir does not support this workflow yet.

TypeScript

TypeScript does not support this workflow yet.

• Application-wide — ConcurrencyOptions.CheckFirstAppendIntoAScope. Every scope the optimistic strategy resolves gets the check.
• Per append — ConcurrencyScopeBuilder.ExpectingNoMatchingEvent(). One behavior asks for the check without changing the default for everything else.

This rejects appends that succeed with it off

That is the point — it is the race the check exists to catch — but adopt it per behavior and be ready to handle ConcurrencyViolation on appends that never produced one before. Treat it like any other violation: retry against the state the winner produced, or surface the conflict. See Handling Concurrency Violations.

The default is scheduled to change

CheckFirstAppendIntoAScope defaults to false so that upgrading within this major version changes nothing. It is planned to become true in the next major version, where the first append into a scope will be checked unless you opt out. Turning it on now — one behavior at a time — is how you get there without a surprise at the major boundary. To keep the unchecked behavior past that point, ask for no check explicitly with ConcurrencyScope.None.

Expressing “This Must Not Exist Yet”

By default a concurrency scope protects a sequence you are extending. With the check opted into, EventSequenceNumber.BeforeFirst means before the first event, so a scope can also say “no event matching this narrowing may exist” — which makes “only one writer may open this partition” expressible as a concurrency concern.

Reach for a constraint instead when the rule has to hold for every writer forever, regardless of what any client asked for: a unique event type constraint permits exactly one event of a given type per event source, and the kernel enforces it whether or not the append declared a scope.

Telling a Skipped Check From a Passing One

A skipped concurrency check and a passing one produce the same successful append, so the append result says which happened. IAppendResult.ConcurrencyCheckPerformed is true when the scope was actually compared against the event store, and false when nothing was:

• the append asked for no check (ConcurrencyScope.None), or carried no scope at all;
• the append was a first append into a scope and the check is not turned on — the default;
• the append declared a scope that narrows but names no expectation, built by hand without resolving one. That is always skipped, because EventSequenceNumber.Unavailable is the same value ConcurrencyScope.None carries and cannot be read as an expectation.

Assert on it in a test when a command’s correctness depends on the check running. It is also how you confirm an opt-in actually took effect.

Mixed-Version Deployments

A scope declares “I expect no matching event” in a field of its own on the wire, and sends EventSequenceNumber.Unavailable as its sequence number. EventSequenceNumber.BeforeFirst is an in-process value and never crosses the wire. That is what makes a client/kernel version mismatch safe in both directions when the check is opted into:

Client	Kernel	First append into a narrowed scope, with the check on
current	current	Checked. Rejected if a matching event arrived in between
current	older	Skipped, with the SkippingIncompleteConcurrencyScope warning — the older behavior. The older kernel does not know the field, reads Unavailable, and declines to validate exactly as it always did
older	current	Skipped, same log line — at debug level, since for a current kernel this is the designed default. The older client never sets the field, so the kernel has no expectation to check

A skew therefore degrades to the same skip you get with the check off, and says so in the log — it never produces a check that reports success without running. Both directions are pinned by specs under for_ConcurrencyScopeConverters/when_a_client_and_kernel_version_disagree.

One caveat on the diagnostic itself: IAppendResult.ConcurrencyCheckPerformed is sent by the kernel, so a current client against an older kernel always reads false — the older kernel does not send the field. That is correct for a skipped first append and conservative for every other append (it under-reports a check that did run). It never over-reports.

Best Practices

1. Use specific scoping: Scope concurrency as narrowly as possible to avoid unnecessary blocking — but note that the narrower the scope, the more scopes there are, and the first append into each one is not checked unless you ask for it
2. Event type scoping: When possible, scope to specific event types to allow concurrent operations on different event types
3. Handle violations gracefully: Always check for concurrency violations and implement appropriate retry or fallback logic
4. Use builders for complex scopes: The ConcurrencyScopeBuilder provides a clear, fluent API for complex concurrency requirements
5. Use concurrency scope strategies: Inject IConcurrencyScopeStrategies to get a built-in strategy (such as optimistic concurrency) instead of hand-rolling sequence-number lookups
6. Assert the check ran: Read IAppendResult.ConcurrencyCheckPerformed when a behavior depends on serialization — a skipped check looks exactly like a passing one
7. Adopt the first-append check per behavior: Turn on the first-append check where two writers must not both open the same partition, ahead of it becoming the default in the next major version