That rule decided most of the design, so this post goes through the decisions it made for me.

What gets stored

A snapshot is the account’s state at a version:

public sealed record AccountSnapshot(
    AccountId AccountId,
    Iban Iban,
    Currency Currency,
    AccountStatus Status,
    FreezeReason? FreezeReason,
    long Version);

Version is the number of events it covers. Loading reads the snapshot, then the events with a higher version, and replays only those. The aggregate base class has one method for this, RestoreVersion, and it refuses to run on an aggregate that already has events, so a snapshot can only start a fresh instance.

The account refuses to produce a snapshot while it has unsaved events:

// a snapshot of unsaved changes could outlive a failed append and claim events that never got stored
public AccountSnapshot ToSnapshot() =>
    PendingEvents.Count == 0
        ? new AccountSnapshot(Id, Iban, Currency, Status, FreezeReason, Version)
        : throw new InvalidOperationException("Save the pending events before taking a snapshot.");

If the append fails and the snapshot had already been written, the next load would start from a state that includes events the store never got. The cache would be ahead of the source of truth, which is the one thing a cache must never be.

When it is taken

The policy is one line, and the line is not the obvious one:

// crossing a multiple, not landing on it, since one append can add several events
public bool IsDue(long versionBefore, long versionAfter) => versionAfter / Every > versionBefore / Every;

My first version was versionAfter % Every == 0. A save can append several events in one call, so a stream can go from version 98 to 103 and never land on 100. With the modulo check that account would skip its snapshot and the next chance is version 200, if that one is hit. Dividing both versions and comparing catches every crossing. The test table says it in numbers, with Every set to 5:

The default interval is 100. Reading 99 events after a snapshot costs well under a millisecond on the benchmark numbers, and a smaller interval would just mean more snapshot writes.

Where it lives

The snapshot goes into a second PostgreSQL table next to the events, one row per stream, with the aggregate serialized as jsonb:

insert into snapshots (stream_category, stream_id, version, data)
values (@category, @id, @version, @data)
on conflict (stream_category, stream_id) do update
set version = excluded.version, data = excluded.data, taken_at = now()
where snapshots.version < excluded.version

The where on the update is the part that matters. Two saves of the same account can run close together, and the slower one may carry the older state. Without the guard, the older snapshot would overwrite the newer one. The result would still be correct, because the events after version 2 get replayed either way, but the cache would get worse for no reason, and it is cheap to prevent. The contract test for it saves version 5, then version 2, and checks that version 5 is still there.

The in-memory store, used by the unit tests, has the same rule in AddOrUpdate, and both stores run the same abstract test class.

When it fails

Three things can go wrong with a cache, and each one gets the cache-miss treatment.

A stored snapshot that no longer deserializes, because the snapshot shape changed in a release:

// a snapshot from an older shape is just a cache miss, the events still rebuild the state
try
{
    return JsonSerializer.Deserialize(data, _json);
}
catch (JsonException)
{
    return null;
}

A null here means “no snapshot”, and the repository replays from the first event. The next save past a threshold writes a fresh snapshot in the new shape, and the stream heals on its own. Events need upcasters when their shape changes, because they are forever. Snapshots don’t, because they can be thrown away.

A snapshot write that fails after the events were stored:

// the events are stored by now, so a failed snapshot must not look like a failed save
private async Task TrySnapshotAsync(StreamId stream, Account account, CancellationToken cancellationToken)
{
    try
    {
        await snapshots.SaveAsync(stream, account.Version, account.ToSnapshot(), cancellationToken);
    }
    catch (Exception e) when (e is not OperationCanceledException)
    {
        LogSnapshotFailed(logger, e, stream, account.Version);
    }
}

By the time this runs, the append has committed. If the snapshot threw, the caller would see the save as failed and retry a command that has already succeeded, and the account would get a second deposit. So it logs a warning and moves on. Cancellation is the exception to the exception: if the caller cancelled, it should hear about it.

And a snapshot store that is down entirely: LoadAsync on the Postgres store will throw in that case, and I left it that way. The events table is in the same database, so if one is down the other is too. A separate cache server would be a different conversation.

The test that pins the rule

The one test I’d keep if I had to delete the others loads an account with snapshots on, wipes the snapshot store, loads it again, and compares:

[Fact]
public async Task Loading_with_or_without_snapshots_gives_the_same_account()
{
    var repository = Repository(every: 2);
    var account = await OpenAndFlip(repository, flips: 5);

    var withSnapshots = await repository.LoadAsync(account.Id, Token);
    _snapshots.Clear();
    var fromEventsOnly = await repository.LoadAsync(account.Id, Token);

    Assert.Equal(fromEventsOnly!.ToSnapshot(), withSnapshots!.ToSnapshot());
    Assert.Equal(6, withSnapshots.Version);
}

With an interval of 2 and six events, the loaded account went through snapshots at versions 2, 4 and 6. If FromSnapshot restored a field wrongly, or Apply and the snapshot disagreed on what a freeze does to the state, this test fails. Everything else about snapshots is an optimisation; this test is the correctness.

I haven’t benchmarked the snapshot path itself yet. The current numbers are for raw appends and stream reads, and they’re in docs/performance.md. The snapshot code is in LedgerCore.Application/Snapshots and LedgerCore.Infrastructure/Snapshots.

What the store has to do

The interface has three operations:

• append events to one stream, but only if the stream is still at the version the caller loaded;
• read one stream, for rebuilding an aggregate;
• read all events from every stream in order, starting after a position, for projections.

The first two are the classic event sourcing part. The third one is where the trouble is. A projection (balances, statements) reads everything after the last position it processed, handles it, saves the new position, and repeats. That only works if, once it has seen position 8, nothing with a lower position can show up later.

The table

create table if not exists events (
    position bigint generated always as identity primary key,
    stream_category text not null,
    stream_id uuid not null,
    version bigint not null check (version > 0),
    event_type text not null,
    data jsonb not null,
    recorded_at timestamptz not null default now(),
    constraint events_stream_version_key unique (stream_category, stream_id, version)
);

version is the event’s place in its own stream, starting at 1. position is its place in the whole store. The unique key on (category, stream, version) means two writers can never both store version 3 of the same account.

Positions are handed out before commit

An identity column is backed by a sequence. PostgreSQL takes the next value when the row is inserted, not when the transaction commits, and sequences ignore rollbacks.

Take two appends to different accounts running at the same time:

Position 7 is now in the table, and the projection will never read it. Nothing fails. A balance is just wrong, and the event store itself looks fine if you query it.

Gaps from rollbacks are a separate thing. An append that inserts and then rolls back burns its position, and that hole never fills. That one is harmless: the reader skips a number that will never exist. The interface says so in its comment: positions only grow, may have gaps, and readers keep the last one they saw instead of counting.

The fix I picked

Every append takes a transaction-level advisory lock before it does anything else:

// one append at a time, so ReadAll never sees position 8 commit before position 7
await using (var lockCommand = new NpgsqlCommand("select pg_advisory_xact_lock(@key)", connection, transaction))
{
    lockCommand.Parameters.AddWithValue("key", AppendLockKey);
    await lockCommand.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
}

pg_advisory_xact_lock is held until the transaction ends, by commit or rollback, so nobody has to remember to release it. With it, transaction B in the table can’t insert until A has committed. Positions are handed out in commit order, and a reader that sees 8 has already been able to see 7.

The same lock makes the version check simple. Under it, the append reads the current version of the stream and compares it with what the caller expected:

var actualVersion = await CurrentVersionAsync(connection, transaction, stream, cancellationToken)
    .ConfigureAwait(false);
if (actualVersion != expectedVersion)
{
    throw new ConcurrencyConflictException(stream, expectedVersion, actualVersion);
}

In READ COMMITTED each statement gets a fresh snapshot, so this query sees whatever the previous lock holder committed. The unique key is still there as a backstop if something ever writes to the table without going through this code.

A conflict is an exception and not a Result, which is what the domain uses for business rule failures. Nobody broke a rule here. The command handler has to reload the account and try again, and that’s a retry loop, not a message for the user.

What it costs

All appends now go one at a time, across every stream. Two deposits to two unrelated accounts wait for each other. Each append is short (one lock, one select, one batch of inserts, commit), but it’s still a single queue for the whole ledger.

I haven’t measured it yet. A BenchmarkDotNet run of single appends and small batches is next on the list for this repo, and I’ll put the numbers in the docs.

The other option I looked at lets appends run in parallel and makes the reader careful instead: store the transaction id on each row, and have the global reader only return rows written by transactions older than the oldest one still running (pg_snapshot_xmin). Writers never wait, but the read side gets more complicated, and one long-running transaction holds back every projection until it ends. For a ledger that isn’t anywhere near its write limits, I’d rather keep the reader simple and change this when a benchmark tells me to.

Testing it

The in-memory store and the PostgreSQL store run the same abstract test class, EventStoreContract. The PostgreSQL run uses Testcontainers with postgres:18-alpine, so CI tests the real thing. One of the tests fires ten appends at the same new stream at once:

[Fact]
public async Task Only_one_of_several_racing_appends_wins()
{
    var stream = NewStream();

    var attempts = Enumerable.Range(1, 10)
        .Select(n => Task.Run(() => _store.AppendAsync(stream, 0, Events(n), Token), Token));
    var outcome = await Task.WhenAll(attempts.Select(Succeeded));

    Assert.Single(outcome, won => won);
    Assert.Single(await ReadStream(stream));
}

Exactly one wins and the other nine get a ConcurrencyConflictException.

This test doesn’t prove the read ordering from the table above, because that needs two transactions held open at the right moments. I want a test for that before the projection runner exists, probably by holding a transaction open on a second connection and checking that a ReadAll after it never skips.

The store is in LedgerCore.Infrastructure/EventStore, and the design of the ledger’s money movements is in ADR-0004.

decimal.Round rounds half to even

decimal.Round uses MidpointRounding.ToEven unless you pass a mode. It’s usually called banker’s rounding: a value exactly halfway between two neighbours goes to the one whose last digit is even.

With round half up, every midpoint goes up, so over many postings the rounding error builds up in one direction. With half to even, midpoints go up about half the time and down the rest, and the error mostly cancels out.

The mode is a parameter

Half to even isn’t right everywhere. Some products and some tax rules specify half up. So Multiply takes the mode as a parameter, with ToEven as the default:

public Money Multiply(decimal factor, MidpointRounding rounding = MidpointRounding.ToEven) =>
    new(decimal.Round(Amount * factor, Currency.MinorUnits, rounding), Currency);

Code that needs another rule has to say it: Multiply(0.5m, MidpointRounding.AwayFromZero). That way the choice shows up in code review.

The number of decimals comes from Currency.MinorUnits, not a hard-coded 2. The yen has no minor unit and the Bahraini dinar has three.

Rejecting amounts that are too precise

Rounding after a multiplication can’t be avoided. Input is another matter. If 10.005 EUR arrives, storing it as 10.00 or 10.01 creates half a cent of difference that nobody will be able to trace later. So Money.Of refuses it:

public static Money Of(decimal amount, Currency currency)
{
    ArgumentNullException.ThrowIfNull(currency);

    // a ledger that silently rounds on the way in loses cents nobody can explain later
    if (decimal.Round(amount, currency.MinorUnits) != amount)
    {
        throw new ArgumentException(
            $"{amount} has more than {currency.MinorUnits} decimal places for {currency}.", nameof(amount));
    }

    return new Money(amount, currency);
}

Money.Of(1.5m, Currency.FromCode("JPY")) and Money.Of(0.001m, Currency.Eur) both throw. Trailing zeros are accepted: 1.2000m passes, and it compares equal to 1.20m.

Other checks in Money

• Adding EUR to USD throws a CurrencyMismatchException.
• Comparing amounts in different currencies throws too. Converting needs a rate and a date, and a value object has neither.
• The amount is a decimal, because double can’t represent 0.1 exactly.

The code and tests are in LedgerCore.Domain/Monetary.

I’m writing an open-source matcher for .NET, payee-match. Before any fuzzy matching, both names have to be brought to the same form, so that “João Conceição” typed by the payer and “JOAO CONCEICAO” in the bank’s records compare as equal. This post is about that step.

Removing accents

.NET does most of it. string.Normalize(NormalizationForm.FormKD) decomposes an accented letter into the base letter followed by a combining mark. Skip everything in the NonSpacingMark category and the accents are gone:

foreach (var c in name.Normalize(NormalizationForm.FormKD))
{
    if (CharUnicodeInfo.GetUnicodeCategory(c) == UnicodeCategory.NonSpacingMark)
    {
        continue;
    }
    // ...
}

That covers ã, ç, ü, é and ñ, and Czech letters like ř and ť too. “Dvořák Šťastný” becomes “dvorak stastny”.

I used KD rather than D. The compatibility form also turns the fi ligature into f and i, and full-width ＡＢＣ into ABC. You won’t see either often in a payment form, but a name pasted from a PDF can bring them in.

Letters with no accent to remove

The first German, Nordic and Polish names in the tests failed:

ß, ø, ł, æ and þ are letters of their own, not a base letter with an accent, so Unicode has no decomposition for them. Lower-casing doesn’t touch them either: "ß".ToLowerInvariant() is still "ß".

They go through a lookup table instead:

// letters that NFKD leaves alone because they aren't an accent on a base letter
private static readonly FrozenDictionary<char, string> Folds = new Dictionary<char, string>
{
    ['ß'] = "ss", ['æ'] = "ae", ['œ'] = "oe", ['ø'] = "o", ['ł'] = "l",
    ['đ'] = "d", ['ð'] = "d", ['þ'] = "th", ['ı'] = "i", ['ŀ'] = "l",
}.ToFrozenDictionary();

I kept it as an explicit list. A VoP result may have to be explained to a customer or an auditor, and with ten entries anyone can check exactly what was replaced.

Splitting into words

Next the name is split into tokens. Most punctuation just ends a word: hyphens, commas, &, repeated spaces. “Silva-Santos, Ana” becomes silva santos ana.

Apostrophes are different. O’Neill and D’Almeida should stay one word, and people type them with a straight quote, a curly one or nothing at all. Dropping the apostrophe gives oneill and dalmeida in every case.

At first I wanted dots to behave the same way, but then “J.M. Silva” becomes jm silva and the two initials are lost. A later step compares initials with full given names (“J. M. Silva” against “João Manuel Silva”), so dots split: j m silva.

Titles and company forms

The normaliser knows nothing about names. After it runs, titles like “Dr” and company forms like “Lda” or “GmbH” are still there. A separate step removes them, and it keeps the legal form to one side instead of throwing it away, because “Silva Lda” and “Silva SA” are two different companies. I’ll write about that one when the matcher uses it.

The normaliser and its tests are in NameNormaliser.cs. If a name in your language comes out wrong, please open an issue with it.