Plan an upgrade

Upgrading across one major is usually small. Upgrading across several is the union of every boundary between them — and the part you cannot defer is the boundaries that touch data you have already written.

Pick where you are and where you are going.

Showing every boundary from 6 to 19.

1. 6 → 7Stored state2023-01-10

   Stored observer state

   migrate that stored state before starting 7.x, or accept that inbox observers restart from their default position.

2. 7 → 8Compile-time, transport2023-01-23

   Namespaces, transport and several APIs

   expect compile errors across the codebase and work through them; update `cratis.json` / `cluster.json`, where single-cluster mode changed from `local` to `single`.

3. 8 → 9Compile-time2023-07-19

   Repository split and startup

   Startup and configuration only; wire-compatible both directions

4. 9 → 10Unknown2024-07-30

   No recorded change

   No release notes exist for this major

5. 10 → 11Stored state2025-03-12

   Stored job state

   expect in-flight job state from 10.x to be unreliable. Drain jobs before upgrading if their completion matters.

6. 11 → 12Compile-time2025-06-04

   Internalized APIs and a renamed package

   rename the package reference; stop using anything from `Cratis.Chronicle.Contracts` or `Cratis.Chronicle.Infrastructure` that you were reaching into.

7. 12 → 13Compile-time2025-06-23

   One method became async

   `await` it. Opt out with `AutoDiscoverAndRegister = false` on `ChronicleOptions` or the `skipDiscovery` argument if you were managing discovery yourself.

8. 13 → 14Stored state, compile-time2025-08-15

   Read-model formalization and stored layout

   this one touches stored layout as well as APIs. Read the release notes in full, and go to **14.0.1**, not 14.0.0.

9. 14 → 15Compile-time, config2026-02-03

   Rules retired, TLS, content type

   replace Rules usage; fix code that treated `Content` as `ExpandoObject`; configure TLS for production; rename the testing package reference.

10. 15 → 16Config, endpoints2026-07-09

    One port, always TLS

    remove management-port configuration, point tooling and bookmarks at the single TLS port, and configure a certificate for production.

11. 16 → 17Wire2026-08-25

    The generated wire contract

    take a matching client. Go to **17.0.1** — 17.0.0 is the accidental release described above and carries a pre-migration contract.

12. 17 → 18Wire2026-09-08

    Append content back to a string

    nothing, if you use a published client at a matching version. A client built directly against the raw gRPC contracts must send and receive `Content` as a string.

13. 18 → 19Compile-time2026-09-17

    A .NET signature

    rebuild.

How to read this

Compile-time boundaries accumulate without interacting. However many you cross, you fix them once against the version you land on.

Stored state boundaries are ordered. They concern data already written, and skipping past one does not skip its consequence. Where your path crosses one, take a backup you have restored from at least once before, and rehearse against a copy.

Wire boundaries mean the kernel and its clients must move together. Chronicle verifies compatibility across every released minor of a major; that guarantee stops at a major boundary, which is what a major means.

Each entry links to the full account in the product’s own upgrade guide, which is where this list comes from — nothing here is maintained separately from the prose it summarizes.