Cratis Blog | Blog

The assembly language of the business

Mon, 05 Oct 2026 00:00:00 GMT

Let’s face it, nobody gets excited about intermediate languages. Hardly anyone writes IL by hand, and I’ve yet to meet someone who reads JVM bytecode for fun. Yet I would argue they’re among the most important ideas our industry ever had.

Think about what IL actually did for .NET. C#, F# and VB all compile down to the same thing. The runtime only has to understand that one thing. And every tool that came after, debuggers, decompilers, profilers, analyzers, obfuscators, got to work on every language for free, because they only had to read IL. The JVM got the exact same superpower from bytecode, which is why Kotlin and Scala could show up years later and inherit an entire ecosystem on day one. Languages above, tools below, and a small, stable, well-defined format in the middle that both sides agree on.

The thing is, the business side of software has never had that. We’ve had whiteboards, sticky notes, Miro boards, Word documents, Jira epics and a lot of very good intentions. None of them are something a compiler can check, a tool can read, or a pull request can diff. So the moment the code exists, the model starts drifting away from it.

That’s what Screenplay is for, and over the last couple of weeks it really clicked for me what it has become: the assembly language of the business.

A quick recap of what Screenplay is

Screenplay is a small, indentation-based language for writing down an event model: modules and features, slices, commands, events, read models, screens, policies, personas and the specifications that say what should happen. It lives in .play files next to your code, it has a compiler with stable diagnostic codes, and it prints back to the same text it read. It’s young, so expect it to keep moving.

This is a slice from the Library sample that ships with Screenplay:

slice StateChange AddBook
  description "The librarian adds a newly bought book to the catalog"

  command AddBook
    bookId BookId identifier
    isbn   Isbn
    title  BookTitle
    author AuthorName

    authorize IsLibrarian

    validate
      isbn matches "^[0-9]{13}$"  message "An ISBN has 13 digits"
      title not empty             message "A book needs a title"

    produces BookAdded
      for bookId
      isbn   = isbn
      title  = title
      author = author

  event BookAdded
    isbn   Isbn
    title  BookTitle
    author AuthorName

If you want the language tour, Sindre did a great job with that in Screenplay: an event model you can compile. What I want to talk about here is not the language itself. It’s everything that now sits around it.

That picture is the whole point of this post. On the left are all the ways a Screenplay document comes into existence. A person writes it in an editor. An AI assistant proposes it through the Screenplay MCP server. Cratis Studio exports it from the board you’ve been modeling on together. The Cratis CLI generates it from Arc, Marten or Wolverine source code with cratis screenplay generate. And Prologue interprets one from what an existing system is observed doing. On the right are the things that read it. Same file format in the middle, every single time.

Exactly like IL. Nobody on the left has to know who’s on the right.

One board, extracted out of Studio

The first piece of the puzzle was making sure that whatever reads Screenplay can show it, and show it the same way everywhere.

Studio has had a very nice event model board for a while. The problem was that it lived inside Studio. So we pulled it out. @cratis/event-models is now a published, MIT-licensed npm package containing the exact board Studio draws, both the read-only viewer and the editor. It’s released together with Studio and carries Studio’s version number, which is still 0.x, so pin a minor version and expect the API to move a bit.

Rendering a board in your own React app is pretty much this:

import { createRoot } from 'react-dom/client';
import { EventModelBoard, readEventModelDocument } from '@cratis/event-models';
import '@cratis/components/tokens';
import '@cratis/components/styles';
import '@cratis/components/theme';
import '@cratis/event-models/theme';
import '@cratis/event-models/styles';
import '@cratis/scene/styles';
import 'primeicons/primeicons.css';
import json from './library-model.json';

const model = readEventModelDocument(json.eventModel);

createRoot(document.getElementById('root')!).render(
    <div style={{ height: '100vh' }}>
        <EventModelBoard document={model} readOnly />
    </div>
);

That’s the snippet I ran in a throwaway Vite app to take the screenshot below, with @cratis/event-models and @cratis/scene at 0.117.3 and @cratis/components at 4.25.0. The JSON it reads is the board model of a small library application, which I’ll get to in a moment.

The board from @cratis/event-models, in a page that contains nothing else.

Once the board was a package, it could go anywhere. And it went to a lot of places in a short amount of time.

Open a .play file, get a board

The Screenplay VS Code extension now opens .play files on the event model board by default. It’s the same board as Studio, with modules and features across the top, a column per slice, the personas as rows with screens drawn as small prototypes in them, and the Given/When/Then specifications hanging underneath each slice.

code --install-extension cratis.screenplay

The text is still the source of truth. Run Show Source from the command palette and you get the .play file side by side with the board, with highlighting, completion, hover and diagnostics, and the board redraws as you type.

The Library sample in VS Code: the board on the left, the Screenplay it’s drawn from on the right.

Zoom out and you get the whole application in one picture. A picture of the system is something I’ve wanted for every system I’ve built, and this one is drawn from the very file the rest of the tooling reads.

Your AI assistant gets a whiteboard

This is the one that made me smile the most.

The Screenplay MCP server has been around for a bit, letting an assistant explore a model, find declarations, find gaps in your specifications and propose changes that a person reviews and applies. Over the last week it gained a bunch of new capabilities. It now picks its workspace by itself (from the folder you name, the folder your client offers, or the folder you started it in), it ships as desktop bundles for Claude Desktop and a local plugin for ChatGPT Desktop, and the CLI can install and update those for you with cratis screenplay mcp install. It guides the assistant towards valid models before it proposes anything, and it can propose typed repairs for some diagnostics instead of just complaining about them.

And it can draw.

The server now offers the board as an MCP App, a view the host renders right inside the conversation, through a tool called visualize-model. In hosts that render MCP Apps, like Claude Desktop and GitHub Copilot in VS Code, you can just say “Show me the application as an event model board” and there it is. While it’s on screen it follows the files on disk, so when the assistant applies a change or you edit a file by hand, the board catches up on its own.

The part I find really powerful is the what-if. Ask the assistant to sketch something without changing anything:

Without changing anything, sketch what a Reservations feature could look like next
to the existing Lending module, and show it on the board. Do not propose it yet.

The board then shows the application as the sketch would leave it, with a Current and Proposed switch in the toolbar. Whatever both share stays in place, so the only thing that moves is the difference.

A sketch of a Reservations feature drawn over the Library sample. Nothing is written to disk.

To be honest about how I took that one: I didn’t screenshot Claude Desktop. The capture is the actual ui:// view served by cratis screenplay mcp (Screenplay 4.60.1, as bundled in Cratis CLI 3.27.0), rendered in a minimal MCP Apps host I put together with the official @modelcontextprotocol/ext-apps bridge, so I could drive it from a script. The sketch it draws is a real .play document. I compiled it together with the sample with cratis screenplay validate first, and the server’s own summary of it read “which would have 10 slice(s), 6 event(s), 0 error(s)”.

This changes the conversation with an assistant quite a bit. Instead of reading a wall of generated text and trying to imagine what it does to the model, you look at what it would do, before anything is written. And since the board is the same board you’d see in Studio or VS Code, there’s nothing new to learn.

Your running application already knows its model

Now for the other direction. Everything so far is about a Screenplay someone, or something, wrote. But what about the code you already have?

In Arc, we’ve added Cratis.Arc.Screenplay.Embedded. During compilation it analyzes your commands, events, read models, projections and reactors, generates Screenplay documents from them, one for the assembly and one per module and feature, and embeds them in your assembly. Generation errors fail the build rather than embedding something the Screenplay compiler would reject. The Cratis metapackage includes it, and UseCratis() maps a read-only explorer at /.cratis/event-model/ for a Debug-built application. You don’t have to do anything.

I verified that with a fresh application from the template (dotnet new cratis, Cratis 22.50.3), where I replaced the sample feature with a small library (adding books, borrowing and returning them, registering members and a reactor welcoming them), ran it with dotnet run, and opened the explorer.

The explorer in a running Arc application, with the View options open.

A few things worth calling out here.

This is source-derived documentation, not a view of live data. It shows what your code says the model is, not what’s in the event store. It’s also read-only, of course, since the code is the source.

The board is honest about what it can’t draw. See those warnings at the top? The analysis found things a board card can’t express, like a reaction whose body is code, or property mappings on a produced event, and instead of quietly dropping them it tells you. The Source tab always gives you the full generated Screenplay.

And debug detection isn’t authorization. The explorer exposes your application’s structure, so the docs cover turning it off or putting a policy on it if a debug build is reachable by anyone but you.

One thing I ran into while writing this: a project that pulls in Microsoft.CodeAnalysis.Analyzers transitively can hit an MSBuild target cycle with the embedded generation in Debug (Arc#2979). Our own Library showcase in the Samples repository turns the generation off for that reason until it’s fixed. The template app doesn’t have the problem.

No need to run anything: cratis view

Now, starting an application just to look at its model is a bit much. Especially when the model is the thing you wanted to look at before you set up its database.

So the Cratis CLI got cratis view. Run it in the folder of a .csproj and it serves the very same explorer from your machine and opens a browser on it.

cratis view

If the built assembly embeds Screenplay documents, those are what you see. If it doesn’t, or you pass --from-source, it generates them from the project’s source in memory with the same Arc generator the build uses, without writing a single file. None of your application’s code runs, the assembly isn’t locked so you can keep rebuilding, and it only listens on loopback.

The same application through cratis view (Cratis CLI 3.27.0), without starting it. Board on top, the generated Screenplay below.

That last screenshot is the one I keep coming back to. That’s C# code, compiled down to the business’s assembly language, and then drawn as an event model. It’s ILDASM for your domain.

Why the format in the middle matters

Let me get back to the IL thing, because I think it’s the real story here and not just a cute analogy.

None of what I’ve shown you required the tools to know about each other. VS Code doesn’t know about Arc. The MCP server doesn’t know about the CLI’s view command. Arc doesn’t know about Studio. They all speak Screenplay, and they all draw it with the same board package. Every new thing that can produce a .play file gets every viewer for free, and every new viewer works for every producer. That’s exactly the leverage IL gave .NET.

It goes the other way too. Screenplay is what cratis run boots into a live sandbox, and what cratis render turns into an application. The more things that can read and write the format, the more valuable each .play file becomes.

Which is also why so much of the last couple of weeks went into the language itself. Applications composed from many files through imports, events declared inline where they’re produced, optional values written as Type optional, deterministic clocks, reactions, triggers and captures. On top of that you can now write down event sources and streams, external systems and command operations, and handler implementation intent, although those are syntax only for now: the compiler and the editors understand them, but nothing executes them yet. Studio exports more of its model to Screenplay and says out loud what it couldn’t carry. An intermediate language is only as good as what it can express, and every one of those makes it a little more complete.

Wrapping up

I’ve spent most of my career building platforms for developers, and the one thing I’ve always wanted is for the model the business talks about and the code we ship to be the same thing. Not two things we try to keep in sync. Screenplay is not there yet, and there are still things the board can’t draw. But for the first time I can point at a single format that people, AI assistants, Studio and our C# code all write, and that VS Code, an MCP host, a running Arc application and the CLI all read and draw the same way.

If you want to give it a go:

Install the VS Code extension and open a .play file. The Screenplay samples are a good start, Library in particular.
Run cratis view in one of your Arc projects and look at the model you’ve already written.
Connect the Screenplay MCP server to Claude Desktop or Copilot in VS Code, and ask it to show you the board.

And if you build something that reads or writes Screenplay, I’d love to hear about it. That’s kind of the whole point.

Tested with: .NET SDK 10.0.400, Cratis CLI 3.27.0 (bundling Screenplay 4.60.1), the cratis.screenplay VS Code extension 4.62.1, Cratis 22.50.3 from Cratis.Templates, and @cratis/event-models 0.117.3, on October 5, 2026.

From script to stage · Part 26: Getting started with Cratis, and the tools around it

Wed, 30 Sep 2026 09:26:00 GMT

Cratis: from script to stage, and the long run · Part 26 of 26

dotnet new cratis -n MyStore writes a command that registers a name, a projection that lists the names, a reactor that logs each one and a React page for all of it, before you’ve written a line of your own. Three more commands start Chronicle, the backend and the frontend. The name you register on that page is an event you can open in the Workbench.

The first hour

The C# path needs the .NET 10 SDK, because every .NET template targets net10.0 and nothing else. It also needs Docker with the Compose plugin, and Node.js ^20.19.0 or >=22.12.0 with yarn, pnpm or npm. The Kotlin and Java variants build with JDK 17 instead of the .NET SDK. The getting started guide goes from an empty folder to the first event:

dotnet new install Cratis.Templates
dotnet new cratis -n MyStore
cd MyStore
docker compose up -d
dotnet run
yarn dev

dotnet run and yarn dev each want a terminal of their own.

Creating the project runs post-creation actions that add the Cratis NuGet packages at their current release and install the frontend dependencies. The template source leaves its package versions open on purpose, and the generated .csproj records the versions it resolved, so two projects scaffolded a week apart can differ. dotnet new asks before it runs the frontend install. In a script or a dev container nobody is there to answer, and Cratis.Templates 1.7.2 keeps re-prompting instead of moving on, so pass --allow-scripts yes. Add --packageManager none as well to pin the packages and skip the install.

--Database picks MongoDB, the default, or PostgreSQL, SQL Server or SQLite. Any choice other than MongoDB swaps Arc’s MongoDB package for its Entity Framework Core one and points Chronicle’s sink at SQL.

docker compose up -d starts the Chronicle development image, which bundles MongoDB, and an Aspire dashboard. The compose file is for development. It publishes its ports on every network interface and the Chronicle image uses well-known development credentials, so keep it on a machine you trust. With the default MongoDB setup, events and read models live inside the Chronicle container. docker compose stop keeps them and docker compose down deletes them.

The backend listens on http://localhost:5000, with Swagger at /swagger. Vite serves the frontend on http://localhost:9000 and forwards /api, /.cratis and /swagger to the backend. Port 5000 has to be free because the Vite proxy is fixed to it, and so does 27017, because the Chronicle image advertises its MongoDB replica-set member as localhost:27017. Register a name on the Demo page and three things happen. The backend logs Registered: <name> from the sample reactor, the name appears in the list, and the event shows up in the Chronicle Workbench at https://localhost:35000, once you’ve accepted the self-signed development certificate and signed in with the development account.

A registered name, opened as an event in the Workbench.

From an empty folder to an event you can open.

What the template writes

The cratis template puts its sample under SomeModule/SomeFeature/, in two vertical slices.

SomeModule/SomeFeature/
├── Listing/
│   ├── index.ts
│   ├── Listing.cs
│   ├── Listing.ts
│   └── ListingPage.tsx
├── Registration/
│   ├── index.ts
│   ├── RegisterDialog.tsx
│   ├── Registration.cs
│   └── Registration.ts
├── index.ts
├── SomeFeature.tsx
├── SomeId.cs
└── SomeName.cs

src/main/kotlin/com/example/somemodule/somefeature/
├── listing/
│   └── Listing.kt
├── registration/
│   └── Registration.kt
├── SomeId.kt
└── SomeName.kt

SomeModule/SomeFeature/
├── Listing/
│   ├── index.ts
│   └── ListingPage.tsx
├── Registration/
│   ├── index.ts
│   └── RegisterDialog.tsx
├── index.ts
└── SomeFeature.tsx

src/main/java/com/example/somemodule/somefeature/
├── listing/
│   ├── Listing.java
│   └── ListingReducer.java
├── registration/
│   ├── Register.java
│   ├── Registered.java
│   └── RegistrationReactor.java
├── SomeId.java
└── SomeName.java

SomeModule/SomeFeature/
├── Listing/
│   ├── index.ts
│   └── ListingPage.tsx
├── Registration/
│   ├── index.ts
│   └── RegisterDialog.tsx
├── index.ts
└── SomeFeature.tsx

No TypeScript template: --language takes csharp, kotlin or java.

No Elixir template: --language takes csharp, kotlin or java.

Registration/ holds a [Command] record, a Registered event, a reactor and a dialog, and Listing/ a read model built from that event, a query and a list page. C# projects the read model with [FromEvent<Registered>] behind an observable query. Kotlin and Java use a reducer and a plain query, and keep the backend under src/main, apart from the frontend. The command is short:

[Command]
public record Register(SomeName Name)
{
    public (SomeId, Registered) Handle()
    {
        var eventSourceId = SomeId.New();

        return (eventSourceId, new(Name));
    }
}

@Command
@AllowAnonymous
data class Register(
    @CommandKey val id: SomeId,
    val name: SomeName
) {
    fun handle(): Registered = Registered(name)
}

@Command
@AllowAnonymous
public record Register(@CommandKey SomeId id, SomeName name) {
    public CompletionStage<Registered> handle() {
        return CompletableFuture.completedFuture(new Registered(name()));
    }
}

There is no TypeScript template. This is the equivalent command in the source-only Arc for TypeScript preview, not generated template output.

@command()
export class Register {
    @field(SomeName) name!: SomeName;

    handle() {
        const someId = SomeId.create();

        return tuple(
            eventSourceIdResponse(someId.value.toString()),
            new Registered(this.name));
    }
}

In C# and TypeScript, Handle() returns the identity it chose and the event to append, and Arc appends it. The Kotlin and Java templates take the identity as the command’s @CommandKey, return only the event, and Arc appends it to that key. The project has no controller and registers no route. Arc derives the route from the namespace, and the build generates the TypeScript proxy the dialog calls, next to its C# source. The route settings live in appsettings.json and have matching CratisProxies* properties in the .csproj, and the two have to change together. Arc gotchas: where a convention decides for you shows what happens when they don’t, and why a project laid out like this one should leave CratisProxiesSkipOutputDeletion at true.

For the author feature, Register becomes RegisterAuthor, SomeName becomes a concept for the author’s name, and the listing becomes the list of authors. RegisterAuthor takes the author’s id from the caller, as the Kotlin and Java templates do, instead of creating it in Handle(). Uniqueness within the organization is the part the template leaves out. That’s a Chronicle constraint, covered in Rules that hold when you write, and the tenant comes from the edge, as Tenancy and identity end to end explains.

`cratis new`: the same templates from the CLI

cratis new creates the same full-stack skeleton from the Cratis templates, in C# or on Spring Boot with Kotlin or Java, for the database you pick, with proxy generation configured:

cratis new
cratis new list
cratis new cratis --language csharp -n MyStore -o MyStore

The first line starts a wizard that asks for the project, the language and the database. The second lists what’s available, and the third scaffolds directly. The CLI carries its own template engine, which reads the format dotnet new uses, so scaffolding doesn’t need a .NET SDK installed. Building the generated C# still does, and the CLI restores packages only when it finds a build toolchain.

A few differences from dotnet new matter on the first run. --language (csharp, kotlin or java) is required when you scaffold directly. -o is the output directory here, while everywhere else in the CLI it selects the output format. --allow-scripts defaults to no, so pass yes to get the frontend install. An unknown option is an error that names the valid set, --dry-run reports what it would create and writes nothing, and --force lets it write into a folder that isn’t empty. --database takes mongodb, postgresql, mssql or sqlite.

When it’s done, cratis new synchronizes the project’s AI configuration, the same work cratis ai update does. Every template ships a .cratis/ai.json that selects the Cratis AI profiles, languages and assistant integrations, so after dotnet new you run cratis ai update yourself, and after cratis new there’s nothing left to run. AI across the Cratis stack goes into what that installs, and The Cratis CLI, from diagnose to llm-context covers the rest of the CLI.

The package holds four .NET templates. cratis is the web application above, and cratis-aspire is the same application orchestrated with .NET Aspire. A minimal AppHost that runs Chronicle for a project looks like this:

var builder = DistributedApplication.CreateBuilder(args);

var chronicle = builder.AddCratisChronicle();

builder.AddContainer("api", "my-org/my-api")
    .WithReference(chronicle);

builder.Build().Run();

The template’s AppHost also sets Cratis__Chronicle__ConnectionString on the backend, because the client reads Cratis:Chronicle:ConnectionString, not Aspire’s ConnectionStrings. cratis-chronicle-console and cratis-chronicle-web connect a console app and an ASP.NET Core app to Chronicle, for when you want the event store without Arc. The Kotlin and Java variants of cratis generate their proxies through the Arc Gradle plugin, and Beyond .NET covers how they differ from the .NET stack.

One feature, one folder

Arc recommends a vertical slice, with the command, the read model, the screen and the specs in one feature folder, so one change is one diff. Arc doesn’t enforce it. We still recommend it, because when a feature is spread across five layer folders, reviewing one change means opening all five. The C# template’s Registration/ and Listing/ folders are already laid out that way.

In the author feature, the registration slice keeps the command and its event, with the rule that names are unique, side by side:

Authors/Registration/Registration.cs

[Command]
public record RegisterAuthor(AuthorId Id, AuthorName Name)
{
    public AuthorRegistered Handle() => new(Name);
}

[EventType]
public record AuthorRegistered([property: Unique(name: "UniqueAuthorName")] AuthorName Name);

Authors/Registration/Registration.kt

@Command
data class RegisterAuthor(@CommandKey val id: AuthorId, val name: AuthorName) {
    fun handle(): AuthorRegistered = AuthorRegistered(name)
}

@EventType
data class AuthorRegistered(@Unique(id = "UniqueAuthorName") val name: AuthorName)

Java keeps one public type per file, all in the same folder:

Authors/Registration/RegisterAuthor.java

@Command
public record RegisterAuthor(@CommandKey AuthorId id, AuthorName name) {
    public AuthorRegistered handle() { return new AuthorRegistered(name); }
}

// Authors/Registration/AuthorRegistered.java
@EventType
public record AuthorRegistered(@Unique(id = "UniqueAuthorName") AuthorName name) { }

From Arc for TypeScript, an early source preview whose packages aren’t on npm yet:

Authors/Registration/Registration.ts

@command()
export class RegisterAuthor {
    @key() @field(AuthorId) id!: AuthorId;
    @field(AuthorName) name!: AuthorName;

    handle(): AuthorRegistered { return new AuthorRegistered(this.name); }
}

@eventType()
export class AuthorRegistered {
    @unique('UniqueAuthorName') @field(AuthorName) name: AuthorName;

    constructor(name = new AuthorName('')) {
        this.name = name;
    }
}

One feature, one folder, one diff.

Samples, and what each one leaves out

The template is a starting point for your own application. The samples are for learning one idea at a time. A catalog file in the Samples repository drives the roster on the site, and each entry lists its level, the products it uses, its prerequisites, the exact commands that verify it and what it doesn’t cover. The tracks run from getting started, event processing and full-stack CQRS to boundaries and isolation, operations, model-first work and full applications.

What a sample leaves out is part of its design. Chronicle Backend appends a fact and reads one event source’s history over HTTP, without projections or a frontend, and its specs run without external infrastructure. Idea Loom shows generated contracts, model-bound commands, an observable query and a CommandDialog on Arc and React, and it deliberately doesn’t use Chronicle, keeping its current state in memory. Chronicle Operations Diagnosis creates one failed partition on purpose, for you to find with the CLI and the Workbench. Model-First Library compiles one .play file and runs its accepted and rejected examples through Stage. It needs locally built Screenplay and Stage checkouts, and it checks the model without running a live Chronicle command. Library is the larger one, with lending and membership. Full-stack author registration is the author feature from the hub as a sample: RegisterAuthor returns AuthorRegistered, a projection keeps an observable author list, and a React screen calls the generated proxies. It covers registration and listing only, so the uniqueness constraint isn’t in it, and it runs on the template’s development credentials.

Neither the samples nor the templates are production templates. The Samples repository has no release tags, so there’s no sample version to match against your packages. If a sample doesn’t build against the version you have installed, report it in the Samples repository. One loop works for any of them: read the README, run the happy path, open the Workbench when Chronicle is involved, and change one thing.

Fundamentals, underneath everything

Five smaller tools, each doing one thing around the feature folder.

Fundamentals holds the shared building blocks beneath the Cratis stack. For .NET that means concepts, serialization, convention-based dependency injection and type discovery. For TypeScript it means GUIDs, serialization of derived types, property-path proxies and decorators. Chronicle, Arc and Components build on it, and you can use it on its own. Parity between the two isn’t a goal, because the environments offer different things.

Most people meet it through a concept. ConceptAs<T> wraps a primitive so the compiler stops you passing an author’s ID where a book’s ID belongs, and a personal value such as a social security number also carries Chronicle’s [PII] marker. In .NET, services are registered by convention:

[PII]
public record SocialSecurityNumber(string Value) : ConceptAs<string>(Value);

@Pii
data class SocialSecurityNumber(private val rawValue: String) : ArcConceptAs<String>, ChronicleConceptAs<String> {
    override fun value(): String = rawValue
    override val value: String get() = rawValue
}

@Pii
public record SocialSecurityNumber(String value) implements ConceptAs<String>, io.cratis.chronicle.concepts.ConceptAs<String> {
    @Override
    public String getValue() {
        return value;
    }
}

@pii()
export class SocialSecurityNumber extends ConceptAs<string> {
    static readonly valueType = String;
}

defmodule MyApp.SocialSecurityNumber do
  use Chronicle.Concept, type: :string
  pii()
end

services.AddBindingsByConvention();

public interface IUserDirectory { }
public class UserDirectory : IUserDirectory { } // Registered as Transient

Arc for TypeScript registers services explicitly:

export class UserDirectory { }

const builder = ArcApplication.createBuilder();
builder.services.addTransient(UserDirectory);

A concept wraps exactly one value. The serializers and converters Fundamentals provides unwrap it to the primitive, so a property you add to a concept is ignored and lost. C# gives you an implicit conversion from the concept to the primitive but not back, so you add that one yourself. AddBindingsByConvention() pairs IUserDirectory with UserDirectory only when both sit in the same namespace and the interface has one implementation. Registrations are transient unless the class says [Singleton], and [IgnoreConvention] opts a type out. Arc: commands and queries without the plumbing shows what Arc does with concepts, from validation to the TypeScript types.

The shape every spec takes

Specifications brings specification by example to xUnit and NUnit, in the style of Machine.Specifications. Establish() is the given, Because() the when, each [Fact] or [Test] method a then, and Destroy() the cleanup. The lifecycle methods are found by convention, take no arguments, can return void or Task, and run across the inheritance chain, so a context you reuse lives in a given/ folder.

The folder and class names carry the meaning. A for_<unit> folder, a when_<behavior> class and should_<fact> methods read as a sentence, and a spec at for_RegisterAuthor/when_registering/and_the_name_is_taken.cs says what it checks before you open it. The specs run on the standard test runners, so IDE, editor and CI tooling work unchanged. The packages are Cratis.Specifications, Cratis.Specifications.XUnit and Cratis.Specifications.NUnit, and the naming style triggers compiler warnings you switch off in the test projects. How the shape combines with Arc’s command scenarios and Chronicle’s in-memory tests is in Testing with Arc and Chronicle.

Reading the specs back with Synopsis

Synopsis reads the executable examples a repository already has and writes them out as one searchable HTML page, organized by module and feature, with every statement linked back to the code it came from. It turns recognized specification shapes in C#, JavaScript, TypeScript, Gherkin and Screenplay into that page. On the C# side that covers Cratis Specifications and six other frameworks, xUnit, NUnit and MSTest among them, and on the JavaScript side runners from Vitest and Jest to Playwright.

A spec written with Cratis Specifications:

public class when_borrowing_an_available_book : given.a_registered_member
{
    void Because() => _receipt = _checkout.Borrow(_book, _member);

    [Fact] void should_confirm_the_loan() => _receipt.Confirmed.ShouldBeTrue();
}

becomes a card on the page:

FOR  Checkout                           Backend - C#
     Borrowing an available book
GIVEN  A registered member
WHEN   Borrowing an available book
THEN   Confirm the loan

It works from static analysis. C# goes through Roslyn syntax trees without a semantic compilation, JavaScript and TypeScript through a scanner, and it never loads or runs code from the repository it reads, so there’s no restore and no test run. That also sets its limit. The page says what the specs describe, not whether they pass, and it doesn’t judge whether they’re good specs. Install it with dotnet tool install --global Cratis.Synopsis.Tool and run synopsis . --open. The output is one file with full-text search and no server or external assets, and --format both writes a JSON model beside it. Module and feature names come from folder conventions, and a synopsis.json handles other layouts.

Synopsis is a standalone tool and library today. There’s no cratis synopsis command and no Studio view of it yet. Its README is the documentation.

Narrator and Lens: two windows onto a running system

Workbench ships with Chronicle, and the same running system is also visible from a terminal with cratis chronicle workbench and from VS Code with Narrator, which we still treat as experimental.

Narrator is a VS Code extension for browsing Chronicle artifacts and event history. From the activity bar you browse event stores and namespaces down to event types, read models, observers and projections, and page through the event sequence with each event’s sequence number, type, event source, time and payload. You can open an event type’s or a read model’s schema, or a projection’s declaration, and switch between servers. It reads the same ~/.cratis/config.json the CLI uses and picks up changes to it:

{
  "activeContext": "default",
  "contexts": {
    "default": {
      "server": "chronicle://localhost:35000"
    }
  }
}

It reads the log and the schemas and changes nothing in the store. That config file can hold client credentials and an access token in plain text, so treat it like any other file with a secret in it. Chronicle Workbench, screen by screen covers the browser tool.

Lens is a browser extension for the Arc side, and its current release is 0.0.1. It detects a running Arc application in the current tab, lists its commands and queries by namespace, runs them from a form built from their schema and shows diagnostics for observable queries. It also switches the active user and tenant, which it adds as request headers when the application calls its backend. That makes it a development tool for exercising an Arc application as different users and tenants. It needs an Arc application it can detect, and it doesn’t replace testing your authorization.

cratis.io, and where each page comes from

cratis.io is a Starlight site built from many repositories. Most pages are written in the owning product’s repository, in its Documentation/ folder, and the site build copies them in. The edit link on a page therefore points at the product, where a fix belongs. Site-level pages, such as the front page, the scenarios, the AI section, the samples and the tools, live in the Documentation repository. A few tools, Synopsis among them, have no page on the site yet.

A newcomer usually wants one of a handful of pages. The Cratis stack shows how the products fit, Build a full app is a guided journey through Arc, Chronicle, generated contracts and React, and learning paths order the rest. What’s new and compatibility matter once you’ve picked versions. Parts of the model-first layer are experimental and in early development.

For an assistant, the site publishes llms.txt, llms-full.txt and an llms.txt for each product. The bulk archives aren’t the best default context for one question.

Where to start

The whole life cycle, by the moment you’re in:

When	What you reach for	What you stop writing
Model it	Cratis Studio, event modeling, Screenplay, Screenplay MCP	A design document that drifts from the code
Start it	`cratis new` or `dotnet new cratis`, `cratis ai install`	Project wiring and proxy setup
Build it	AuthProxy, Ante, Arc for .NET, JVM or TypeScript, Components, Chronicle	Controllers, DTOs, fetch wrappers, uniqueness lookups before the write
Test it	Cratis Specifications, Arc’s `CommandScenario`, Chronicle’s in-memory scenarios, Stage’s specification runner	A fake event log, and a running server for every spec
Protect it	`[PII]`, `[NotAudited]`, `[Encrypted]`	Per-field encryption code
Run it	A namespace per tenant, outbox and inbox subscriptions	Tenant filters in every event query, relays between stores
Debug it	`cratis chronicle`, the terminal workbench, Workbench, Narrator	Ad-hoc queries against the storage
Evolve it	Generations, replay, revision, redaction	One-off scripts that rewrite the store
Automate it	Cratis Direct, the AI corpus and its hooks, the CLI’s command catalog, Chronicle MCP, Screenplay MCP	Your conventions, retyped into every assistant

Ante, in the Build it row, is the separate invitation and onboarding lobby for users who have signed in but belong to no tenant yet, from Tenancy and identity end to end.

Not everything in that table is at the same stage. Stage, Scene and Prologue are experimental, and so are Narrator and Prompter, which answers questions about the docs in Discord, so their syntax and behavior can still change. Arc for TypeScript is an early preview, available as source only. The Cratis AI corpus and its hooks are in preview. Cratis Studio is live and in beta. Cratis Direct is a control plane for agentic engineering. We run our own engineering on it today. For everyone else it’s coming soon at cratis.direct.

Starting fresh, scaffold with cratis new or dotnet new cratis, then follow Build a full app.

To learn by example, start with Full-stack author registration, or pick one of the samples that matches what you want to understand, and read what it leaves out first.

For the event history on its own, follow Get started with Chronicle, append a few events and open the Workbench. To operate it, brew tap cratis/cratis && brew install cratis, then run cratis chronicle diagnose, and keep retry-partition ahead of replay in your runbook.

To model first, sketch one slice with event modeling, write it as a .play file and run cratis screenplay validate on the folder. At the edge, put AuthProxy in front of an Arc app and set Arc’s tenant header to Tenant-ID. For personal data, mark one value’s type [PII], then read The log remembers.

With an assistant, run cratis ai install for the harnesses, profiles and languages you use, keep cratis screenplay validate and your build in the assistant’s loop, and review its work as a proposal, a model, a spec and the event log.

Earlier posts on the blog go deeper on single decisions. Choosing an event sourcing stack for .NET is about whether event sourcing fits your stack, and Event sourcing in any language about how the clients share one kernel. Event sourcing in .NET with Chronicle builds a runnable first slice, and From zero to first projection with an AI assistant has an assistant do the same.

The series

Events are facts. A message is gone once it’s sent, and a recorded fact can still feed next year’s view.
Inside Chronicle. What the kernel does during an append, and why no projection has run yet when the call returns.
From event to read model. One attribute turns AuthorRegistered into a read model, and a reducer takes over when attributes can’t say it.
Reacting to facts. Reactors, webhooks and outbox-to-inbox subscriptions, each of which has to cope with running twice.
Rules that hold when you write. Constraints, concurrency scopes, decision reads and aggregates, and which one we’d reach for first.
Arc: commands and queries without the plumbing. Arc gives a record with a Handle method its route, validation, authorization and the TypeScript your frontend compiles against.
Validation all the way down. Every place a rule can live, from the rules copied into the browser to Chronicle’s append, what each layer can’t guarantee, and which rejections find their way back to a form field.
Live UIs. Queries that push updates to React, and forms that keep their button disabled until the backend’s shared rules pass.
Cratis Components, the React layer. The author list and the register dialog built with Components 4, how a field binds to a generated command, how a taken name gets back to the Name field, and where the library stops.
Tenancy and identity end to end. A tenant picked at AuthProxy travels as a header Arc reads, and Arc’s Chronicle integration turns it into a Chronicle namespace. Membership is still yours to check.
Testing with Arc and Chronicle. The ladder from a direct method call to a real Chronicle, and the ways a green spec proves nothing.
Beyond .NET. Arc and Chronicle in other languages, four storage providers, and where each still differs from .NET.
Personal data in an event log. Making a person’s data unreadable in an append-only log, and exactly where that stops.
Year two. Why a new event shape, a new view, a correction and a stopped processor are four kinds of change, none of them a script against the store.
Arc gotchas: where a convention decides for you. Validation that runs in two places, a proxy folder that gets cleared, and names that do the mapping for you until they don’t.
Chronicle Workbench, screen by screen. The browser tool that ships with Chronicle.
The Cratis CLI, from diagnose to llm-context. From diagnose to a full-screen terminal workbench, and a command catalog that tells an agent which commands change the server.
Running Chronicle and a Cratis application in production. What the production image won’t start without, what a client trusts until you tell it otherwise, where a trace stops today, and the order a restore has to follow.
Chronicle jobs, scale and performance. Replays you can stop and resume, and the clustering default that, with two servers, quietly gives you two clusters.
Screenplay: an event model you can compile. An event model written as text that a compiler can check in CI before the application has ever started.
Stage and Scene: what happens after a model compiles. A model rendered into an Arc and Chronicle application by a renderer that refuses what it can’t express.
Prologue: a first model of the system you already have. A first model drafted from a running system that nobody ever modeled.
Cratis Studio: one event model for the whole team. A team and its AI agents on one event model, and a slice’s code generated into your repository.
Cratis Direct and our agentic development life cycle. How a person admits agent work, what each gate records and who merges.
AI across the Cratis stack. The AI corpus, its hooks and the MCP servers, what each lets an assistant read or change, and the checks that run whether it listened or not.
Getting started with Cratis, and the tools around it. cratis new, the samples, and the supporting pieces, from Fundamentals and Specifications to Synopsis and Narrator.

The hub, Cratis: from script to stage, and the long run, follows the author feature through all of them once, briefly.

Previous: Part 25 — AI across the Cratis stack
Next: back to the start of the series, Cratis: from script to stage, and the long run

From script to stage · Part 25: AI across the Cratis stack

Wed, 30 Sep 2026 09:25:00 GMT

Cratis: from script to stage, and the long run · Part 25 of 26

In Claude Code and Pi, the Cratis store-mutation guard can stop an assistant’s cratis chronicle observers replay before the shell runs it, even with --yes. It reads the command text, so a call hidden in a script file or made through MCP is outside what it sees.

That guard is one of seven places an assistant meets the Cratis stack. The others run from the corpus in your repository to an MCP server on a running Chronicle. Most of them let an assistant read something, and a few let it propose or change something. The corpus states the principle behind all of them in one of its rules: “A tool grant is not authority. A configured token, an installed CLI, a writable branch, or an MCP server in the session says only that the action is mechanically possible.”

Seven touchpoints, from the repository to the running store.

A spec the compiler reads

Cratis Direct and our agentic development life cycle covers deciding what an agent works on and checking what comes back. The event model gives that work an intent a compiler can read.

The most useful critique we’ve read comes from the spec-driven development side. In her look at three spec-driven tools on martinfowler.com, Birgitta Böckeler separates three levels. Spec-first writes a spec to guide one change. Spec-anchored keeps the spec and evolves it with the feature. Spec-as-source makes the spec the only thing people edit. She finds the markdown these tools produce can be harder to review than the code, and she wonders whether spec-as-source, and even spec-anchored, could end up with the downsides of both model-driven development and language models: inflexibility and non-determinism.

We sit at spec-anchored, with a spec a compiler reads. The event model is the spec and the .play file is its text. Its commands, events and projections are the concepts Arc and Chronicle run, so the spec and the running system share one vocabulary. For the narrow part Stage can render, it moves a step toward spec-as-source. A textual model with a code generator is the model-driven shape she warns about. The renderer is deterministic, so that step adds no unpredictability of its own, but the rigidity risk does apply to us, and it’s why hand-written code has its own place.

For the narrow backend vertical Stage supports, cratis render writes the code. Code written by hand, by a person or an agent, belongs in Customizations/, and an edit to a generated file shows up as a refused render instead of a silent overwrite, unless someone passes --force. Stage and Scene goes through it.

Guidance in the repository

The Cratis AI corpus is a free, MIT-licensed set of rules, skills, agents and prompts for building with Cratis, and it’s still in preview. It lives in one folder, .cratis/ai/, and each supported assistant gets a thin adapter that points back to it, so the guidance is installed once instead of being copied into each tool’s instructions. cratis ai install puts it into your repository:

cratis ai install \
  --harnesses claude,codex,copilot,cursor,opencode,pi \
  --profiles cratis/application/csharp,cratis/documentation \
  --languages csharp,typescript
cratis ai status

It records the selection in .cratis/ai.json and every file with its hash in .cratis/ai.manifest.json, refuses to overwrite files you own, and cratis ai status tells you when a managed file was edited locally. Profiles choose the scope, such as a C# application or documentation, and rules are scoped by language, so only the languages you list install theirs. In a terminal it asks for the harnesses, profiles and languages, and in a script or an agent’s own terminal you pass them as above. The Cratis templates preselect it. cratis new runs the sync itself, and dotnet new prints a reminder to run cratis ai update.

That gives an assistant context about how Cratis is meant to be used, with dozens of skills for commands, projections, reactors, concepts and specs. It doesn’t give it access to anything, and it doesn’t make its output correct. The corpus’s own checks are static and don’t run anything through a model. The CLI installs the corpus from its current main unless you give it a local source.

An assistant that hasn’t read your conventions guesses at your framework, and the result is plausible code that’s subtly wrong. Each layer of Cratis also gives an assistant something concrete to read so it doesn’t have to guess. AuthProxy’s configuration is declarative JSON, the generated TypeScript proxies are typed contracts the frontend compiles against, registered event types have schemas it can look up, and a .play file is text a compiler checks.

One folder of guidance, and an adapter for each assistant that points back to it.

Checks that run whether the agent listened or not

Böckeler also notes that agents often ignore the instructions they’re given, and asks whether all those files and checklists give a “false sense of control”. A rules file is advice. What holds is a check that runs either way, and the author feature meets several:

cratis screenplay validate rejects a broken model before any code exists, and the Stage specification runner checks the model’s Given/When/Then examples against the model.
The compiler and the generated TypeScript proxies turn a renamed field into a compile error on both sides.
Arc and Chronicle’s .NET client ship Roslyn analyzers that report some misuses of their APIs as build diagnostics. They aren’t specific to agents, and they treat an agent’s code like anyone else’s.
The corpus ships hooks that run inside the assistant’s own tool.

The hooks are the part written with agents in mind. Each one runs on an event in the assistant’s tool:

Pattern pass   PostToolUse on a write   appends a one-line reminder to context, never blocks
Hard block     PreToolUse on a write    exits 2 - the write does not happen
Hard block     PreToolUse on Bash       exits 2 - the store-changing cratis chronicle command does not run
Quality gate   Stop (Claude)            exits 2 - the turn does not end

The write guard blocks edits to a file whose header marks it as Cratis-generated output, such as the proxies Arc writes, and to package-management files, lock files and .env files. Arc gotchas explains why the generated files matter.

Take the store-mutation guard. Say an assistant working on the author feature decides the Authors read model is stale and reaches for a replay:

cratis chronicle observers replay <observer-id> --yes

With --yes, the CLI doesn’t stop to ask first. In Claude Code and Pi, the hook runs before the shell does. It finds every cratis in command position, including after && or |, inside $( ), behind wrappers such as env, sudo or timeout, and in the script of bash -c, and checks each cratis chronicle command against a read-only allowlist. observers replay is on its list of known mutations, so the hook exits 2 and the command never runs. A command on neither list, including one a newer CLI adds, is blocked as unknown, so the allowlist fails closed.

The block message is written for the agent. It lists each refused command path and what it changes, tells the agent not to retry or work around the guard, and asks it to report the exact command, the target context or server, what it changes and why, and to ask the user. From there the replay is a person’s decision. If they want it, they set CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1 in the environment the assistant was started from. The hook reads its own environment, so an agent that writes the assignment into the command changes nothing.

The guard is there to stop an agent reaching for --yes, and it isn’t a sandbox. It reads the command text, so cratis reached through a variable, an alias or a script file is invisible to it, and it doesn’t see MCP tool calls.

In Claude Code, when the assistant tries to finish and relevant files have changed, a quality gate runs one build and test pass, and a failure goes back to the assistant instead of letting it stop. In Pi the gate doesn’t run on its own. It’s a tool called at a verification checkpoint, it stops after 300 seconds by default, and a gate that times out or is cancelled reports that nothing was verified, never a pass. The gates are data a repository can override. Today the hooks are wired for Claude Code and Pi, and other assistants get the rules and skills without them.

None of this proves the author feature does what was asked. A green build says the code has the right shape, and a spec checks one example of the behavior, as Testing with Arc and Chronicle goes into.

The CLI catalog is how an assistant learns which commands change state; The Cratis CLI, from diagnose to llm-context covers effect labels, confirmation and the fields stable enough for scripts.

Chronicle MCP: an assistant at a running store

Chronicle MCP connects an assistant to a running Chronicle server, whatever client language the application uses. It ships as a container, and an editor can start it like this:

{
    "servers": {
        "Chronicle": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-eCratis__Chronicle__Mcp__ConnectionString=chronicle://host.docker.internal:35000",
                "cratis/chronicle-mcp"
            ]
        }
    }
}

Configuration is optional. It takes explicit options first, then CHRONICLE_CONNECTION_STRING, then the active CLI context, and falls back to development defaults, which means the development client ID and secret when no credentials are set. Don’t rely on those.

It has two sets of tools. The operate side reads what the server holds, from event types and observers to failed partitions, events and read-model instances. The design-time side describes the system, lists event types that nothing consumes and explains a causal trace, the ordered history of one event source with its correlation and causation chains. For the author feature, an assistant can read the trace behind one author and say which command appended which event. The design-time tools introspect the store before generating anything, take field names from the schema registered with each event type, and say so when the store can’t answer. They never change the store, and the code they return is a proposal to review.

The only tools that change anything are three for stopping, resuming and deleting jobs. The server marks that through MCP tool annotations, so a client can let the read-only tools run and ask before the others. It can’t append, redact or replay.

An assistant connected to it can read event payloads, including personal data. Don’t treat it as read-only, scope what you connect it to, and treat anything it reads as data, not instructions.

The corpus is more careful than the server. Its Chronicle MCP skill doesn’t admit any of these tools for an agent’s use yet, and tells an agent not to invoke or configure them, so installing the corpus doesn’t teach an assistant to call them. A person wires the server in.

Screenplay MCP: proposals a person applies

An assistant works on the event model through the Screenplay MCP server, which cratis screenplay mcp starts over stdio for one application’s folder. It can read the model, list the slices that have no then assertion or prepare a model-aware rename. The assertion check looks at the examples people wrote, which isn’t the same as executed coverage. Proposals are tied to the revision they were made against, and a stale revision means proposing again. Only an explicit apply (or workspace recovery) writes files, which is exactly where your client’s approval prompt belongs. None of its tools run specifications, and a proposal can be valid as source while still marked as not ready to execute.

For a system that already exists, a Prologue draft enters at the same point, as a proposal a person corrects.

cratis ai install registers it for your assistants when the profiles you pick include cratis/screenplay. The corpus declares it like this:

{
  "id": "screenplay",
  "profiles": ["cratis/screenplay"],
  "transport": "stdio",
  "command": "cratis",
  "args": ["screenplay", "mcp"],
  "defaultRoot": ".cratis/screenplay",
  "description": "Understand and safely author one Screenplay application through typed AST operations, reviewed proposals, durable identities, and explicit recovery."
}

The install never creates .play files, and it leaves MCP servers you added yourself alone.

Cratis Studio and Cratis Direct

Cratis Studio and Cratis Direct are applications you use in the browser, and assistants meet them as well. Cratis Studio has an MCP server that lets external AI agents read and change an organization’s event models and brainstorming boards. Scope it like any tool that can write. Inside Studio, a slice of the author feature can be assigned to an AI agent and, where the application has code generation switched on, rendered through Stage into your connected Git repository. Cratis Direct’s issue admission and gates are covered in Cratis Direct and our agentic development life cycle.

The docs, for an assistant that asks or reads

Prompter, still experimental, answers questions about the Cratis docs in Discord. It grounds each answer in cratis.io with citations you can follow, or declines when it can’t ground an answer. Its /issue command files a GitHub issue only when the person asking says so, and the question text goes to two outside providers, as its privacy page explains. For an assistant that reads instead of asking, cratis.io publishes llms.txt, llms-full.txt and an llms.txt for each product, and the index says the bulk archives aren’t the best default context for one question.

A person reviews, or sets who merges

Reviewing a pull request an agent wrote is a different job from reviewing a colleague’s. One recent piece on it makes two points we agree with. The intent sits in a prompt that rarely travels with the pull request, and tests the same agent wrote tend to share its blind spots.

The Cratis pieces give the reviewer the intent as a diff of its own. A change to the author feature can arrive as a .play change that states the command, its rules and its event, a render manifest that says which files are generated, and code in one feature folder. The reviewer reads the intent first, then checks the code against it. The second point applies here too. A spec an agent wrote next to its code can miss what the code misses, so read the model’s examples as intent.

A proposal, a declared model, a passing specification and a recorded event each answer a different question, and a passing spec neither approves a proposal nor proves deployed behavior. An assistant’s diff that stops two authors in tenant Acme registering under the same name is a proposal. The rule written into the event model is a declaration. A spec that registers the same name twice and expects a rejection checks one example. The event log in Acme’s namespace shows what was actually recorded. Someone writes the first three, and the fourth is what happened. In a review, it helps to say which of the four you’re looking at.

With the public pieces, however a pull request was produced, whether it merges is a person’s decision. The corpus’s own pull-request rule lets an assistant take a change through to merge only when a person asks it to ship, and even then it stops before a major release until a person explicitly confirms the break. That rule is about an assistant working in your repository. The separate repository merge policy is covered in Cratis Direct and our agentic development life cycle.

Read, propose, change

Put side by side, the touchpoints form a ladder. On the lowest rung an assistant reads, through Chronicle MCP’s list and get tools, Screenplay’s understanding tools, the CLI’s read-only commands and llms.txt. One rung up it proposes, with Screenplay’s proposal tools and Chronicle’s design-time code. Above that it can change state, but the tools don’t all enforce confirmation. The CLI’s add commands don’t prompt, and --yes bypasses the prompt on commands that do. In Claude Code and Pi, the store-mutation guard blocks those cratis chronicle commands unless a person set the variable. Chronicle MCP’s three job tools carry annotations; whether to ask for approval is up to the client. Writing model files takes Screenplay’s apply behind your client’s approval, and the write guard keeps it out of generated files. None of these tools merges or releases.

Each rung up asks more of a person.

Run it, read the log, start again

The loop closes at the event log. The model says what the system is meant to record, and the log says what it did record. An event type nothing consumes, a partition that keeps failing, or a causal trace that surprises someone is the input to the next change. None of the public tools here turns that finding into work on its own. An agent can read it, and a person decides what starts.

For the alert-to-backlog path and where it stops, see Cratis Direct and our agentic development life cycle.

The rendered vertical is narrow, and taking a second model change through to a running application isn’t proven yet, so the model anchors the code without replacing it. The hooks cover two assistants, and nothing here makes an agent’s code correct. Whether agents working this loop ship faster or with fewer defects is unmeasured. The AI assistant walkthrough shows one of these tools on a real task, including where the assistant was told not to use one.

To start, run cratis ai install in your repository for the corpus and its hooks, and cratis init to write the command catalog into your assistant’s context files.

From script to stage · Part 24: Cratis Direct and our agentic development life cycle

Wed, 30 Sep 2026 09:24:00 GMT

Cratis: from script to stage, and the long run · Part 24 of 26

Since the Cratis Direct GitHub app was created on 26 August 2026, it has opened 320 pull requests across 20 Cratis repositories, 238 of them merged, and filed 412 issues (as of 29 September 2026). They count what the app opened and filed. How many went through a full journey, and what the work cost or saved, isn’t in them. The work itself is ordinary engineering: bug fixes, dependency alignment across repositories, fixes for flaky integration tests, and, through its content journeys, blog posts and a weekly digest.

Cratis Direct is a control plane for agentic engineering. It turns repository signals into one prioritized queue of bounded AI work, checks each stage against recorded evidence, and brings the results back as pull requests. The agents do the work. Cratis Direct owns what they’re allowed to start, how far each piece of work may go, what counts as done, and the evidence of what happened.

Cratis runs its own engineering on Cratis Direct today. For everyone else it’s coming soon: access opens in stages at cratis.direct. The login there admits only accounts we’ve enabled.

The author feature arrives in Cratis Direct as an issue: two authors in one organization ended up with the same name.

The hard part moved

Once agents can write code, the hard part moves. Cratis Direct’s page puts it this way: “It becomes deciding what they work on, proving what they did, and noticing when the world changed underneath them.” That was our problem. Agents could investigate an issue, write the change and open a pull request, across many repositories, faster than anyone could decide what they should be doing or check what they had done. So we built the system around them.

An agentic development life cycle

Once agents write much of the code, people have started calling the resulting life cycle an agentic development life cycle, or ADLC. DataKnobs and one open version disagree on the stages, and IBM uses the same letters for something else, the life cycle of building AI agents as products. The shape they share is that the familiar stages stay, and each one has to hand the next something an agent can read and a person can check. Ours is the issue journey in Cratis Direct. It runs Intake, Investigation, Plan, Implementation and Release, with a gate after each stage.

In ours, the work waits for a person at several points. A person admits the work and sets how far it may go. After reading the plan, a person can raise that ceiling or leave a comment that steers the next stage. A gate can hand its result to a person for review, and when remediation has failed twice, a person decides. Only a person activates a new version of the rules, and by default a person merges.

The work waits for a person at each marked point.

Who it’s for

Teams that already use coding agents, or are about to, and have more repositories, issues and alerts than people to look at them. That means engineering leads who decide what agents work on, platform teams who own the rules the work has to pass, and maintainers who review what comes back.

What it’s for

An agent that starts on everything spends on everything. In Cratis Direct, classifying an issue describes it and never starts work. No work on it starts until a person admits the issue into a journey and sets a ceiling: stop after the investigation, after the plan, after the implementation, or go through to release. AI capacity is shared within a concurrency limit, with usage tracked per provider and model, so issue work spends only on what a person chose to start.

A merged pull request doesn’t tell anyone what was checked. Every stage ends at a gate that evaluates recorded evidence against versioned rules, and keeps the verdict, the evidence and the rule version.

The gate that lets an agent proceed is the same evidence a reviewer reads later. Behind each pull request is its journey, with the plan, the verdicts of the gates and the evidence they read, and each repository decides how much a person has to review at all.

The world also changes under a running agent. An issue is closed mid-journey, a pull request is merged early, a worker fails, the rules change. Cratis Direct checks each journey against reality every 15 minutes and whenever something changes, stops a journey that no longer matches, and asks a person.

In Cratis Direct an alert is deduplicated and an agent investigates it straight away, so a person gets findings instead of a bare notification.

One issue, through one journey

Cratis Direct takes in GitHub issues, pull requests and builds, plus alerts from running systems. It classifies and screens each issue without starting any work, keeps one prioritized backlog that people order, and starts work only when a person admits an issue into a journey and sets how far it may go.

The signal

Someone files the issue in the repository that holds the author feature. GitHub issues, pull requests and builds arrive through webhooks, with a daily reconciliation to catch anything missed. Alerts from running systems arrive by webhook too, and resource probes check what’s running. It works only with GitHub.

Screened and classified

Every issue and comment is screened for spam, conduct and other content problems. Every issue is classified by its kind, how feasible it is, how critical it is, a guess at its semantic-versioning impact and which model tier suits it. A person’s classification is recorded beside the machine’s. Issues from people outside the team are kept from agents until someone decides. None of this starts work on the issue.

One queue

The backlog is one ordered list across repositories. You drag to rank and drop to group, and a group is scheduled only when all its issues are ready. Triage reads the repository’s vision documents. A roadmap plan can be generated from selected issues, and it stays a proposal until someone applies it. A chained issue waits until the release of the one before it exists.

Admitted with a ceiling

A person picks the duplicate-names issue and sets how far it may go, for example “stop after the plan”. That’s the only way issue work starts.

Investigation and plan

The agent does one unit of work at a time in a worker Cratis Direct launches for it, while Cratis Direct keeps the state, the sequence and the capacity. Each journey is a stream of events in Chronicle, the event store the rest of this series is about, so its history is the record. No screen can set a stage directly, and what happened can be read back in order.

With the ceiling at the plan, the journey stops once the plan has passed its gate. That’s where a person finds out what the agent intends to change for the duplicate names, before any code exists. They can raise the ceiling to implementation, or leave a comment, and the comment steers the next stage. A running worker can also be watched in a live console and talked to.

A journey’s history is the record, in the order it happened.

The implementation gate

Each Cratis Direct journey moves an issue through investigation, plan, implementation and release, and each stage ends at a gate that evaluates versioned rules against recorded evidence. Unknown is never a pass: an inconclusive result goes to a person.

The stage view of a journey, from one of our own issues rather than the author feature. This journey started at the implementation stage and is held at that gate.

The most restrictive outcome wins.

A gate collects the rules bound to it and evaluates each against recorded evidence. The evaluators range from deterministic checks and Roslyn analysis to a decision engine, external checks and an LLM’s judgment, and the gate takes the most restrictive of five outcomes: allow, requires human review, requires explanation, requires remediation, or block. A low-confidence result counts as unknown. An unknown result can’t map to allow, and by default it goes to human review.

For the duplicate-names fix, the implementation gate’s evidence includes the build, the specs, static analysis and an LLM check that the tests weren’t weakened. That last one is judgment, not proof, and a low-confidence answer from it counts as unknown. A failing build, test coverage or static analysis rule sends the work back for remediation, and after two attempts a person decides. A failing check that the tests weren’t weakened goes to human review instead.

The rule that checks the tests weren’t weakened: a failure and an unknown result both go to human review.

The rules are versioned. A new version is drafted, validated, simulated, reviewed and approved, only a person activates it, and a journey keeps the version it started with.

The pull request, and who merges

Results come back as pull requests. Who merges is a per-repository setting: a person by default, or, for a repository that opts in, an agent once the change is classified as safe to merge, optionally limited to paths the repository allows.

Each pull request is on its own branch, linked to its issue and marked for review. The default is called Human, and in it a person reviews and merges. The opt-in comes in two forms. Either Cratis Direct merges a pull request on its own when a language model reads the change as safe to merge, or it first hands the uncertain ones to an agent for a full review. The classification behind each automatic merge decision is recorded with its reason. We use both the default and the opt-in on our own repositories. The release gate passes only once the pull request is merged.

A person by default. An agent only where the repository opts in.

From production back to the backlog

Cratis Direct can deduplicate an alert from a running system, have an agent investigate it, and hand a person the findings or turn the alert into a tracked issue. Turning an alert into a full journey isn’t built yet, and some watchdog checks are paused while we harden them.

Alerts are deduplicated by their fingerprint, and production access is opt-in. An issue made from an alert lands back at the start of the queue, where a person decides whether it starts, like any other. That line from production back to the backlog is the step that’s easiest to leave out, and it’s how what the running system says becomes work someone can admit.

Content goes through it too

The same machinery runs content. A blog journey goes Brief, Draft, Editorial review, Publish, with editorial gates, and publishing is a button a person presses. Cratis Direct’s page describes the whole as five loops: deliver, assure, operate, publish and steer. The first, the issue journey, is what we mean by an agentic development life cycle.

Where it stops

It works only with GitHub. Agents are only as good as the rules the gates hold them to, and an LLM rule is judgment, not proof. Production access is opt-in. Some watchdog checks are paused while we harden them. It isn’t generally available, and access opens in stages. We’re building MCP access to Cratis Direct.

Nothing else in Cratis needs it. It isn’t in a request’s path. Cratis Direct works on the issues, pull requests and alerts around the application. It earns its place when agent work outgrows what one person can watch. For one repository and one assistant, the AI corpus and the checks in AI across the stack, plus your CI, may well be enough.

Previous: Part 23 — Cratis Studio: one event model for the whole team
Next: Part 25 — AI across the Cratis stack

From script to stage · Part 23: Cratis Studio: one event model for the whole team

Wed, 30 Sep 2026 09:23:00 GMT

Cratis: from script to stage, and the long run · Part 23 of 26

An event-modeling workshop usually ends as a photo of sticky notes. In Cratis Studio it ends as a model the whole team edited, with the AI agents working on the same one.

Cratis Studio is a collaborative workspace where people and AI agents design, visualize and edit the same event model. It runs in the browser, and it’s built on Chronicle and Arc. Cratis Studio is live and in beta. Open signup is coming soon at cratis.studio, with a 14-day free trial.

In Cratis Studio, a slice a team sketched together can be assigned to an AI agent, rendered into C# for Arc and Chronicle and committed to your connected Git repository, with the event model beside it as Screenplay text. Code generation is opt-in for each application. It works on one slice at a time, and it only goes from the model to the code.

In Studio, the author feature starts as a handful of sticky notes and can end as a commit.

The wall ends up as a photo

Event modeling happens in a room, or on a call, with a product owner, someone who knows the domain and a couple of developers arguing about what actually happens in the business. Someone photographs the wall of sticky notes that comes out of it and retypes part of it into a tool, and by the time the first slice is built, the model, the conversation and the code have started to drift apart.

The author feature shows where it goes wrong. Someone at the wall asks whether two organizations can each have an author with the same name. The answer, that names are unique within an organization, is the rule the whole feature turns on, and on the wall it’s a yellow note with a question mark. It’s hard to read in the photo and easy to lose in the retyping, and it tends to come back later as a bug report.

Coding agents widen the gap. An assistant can write the RegisterAuthor command, its projection and its spec in a few minutes, and the reviewer then compares that code with what they remember of a workshop.

Studio moves the conversation onto the model itself, where people and AI agents edit the same thing, and what the team agrees on can be exported as text you commit.

Who it’s for

Studio is for the people who have to agree on what a system should do: developers, domain experts and product owners, in one room or in a remote workshop. We also build it for whoever runs the workshop, and for whoever has to turn the result into a system afterwards.

Each of them uses a different part of it. A domain expert starts on the board and names what happens in the business in its own words, such as AuthorRegistered and AuthorRenamed. A product owner can follow the model after the workshop ends, because every slice can be assigned to a teammate or an AI agent, and the project’s progress board shows where each one is. A developer gets the model as Screenplay to review as a diff and, where the application has code generation switched on, a slice’s code in the repository. Someone who joins the team half a year later can ask Studio to explain a feature at the level they need.

In a remote workshop everyone’s cursor is on the same board, so the facilitator isn’t the only person who can point at a note.

Why we built it

We think the model and the code belong together. A model nothing is generated from goes stale, and code nobody can trace back to a model is hard to review, whether a person or an agent wrote it. Studio keeps the two coupled. The team works on one model, the model is text you can diff, and the code for a slice is generated from it into your repository.

The commands, events and read models on the canvas are the concepts Arc and Chronicle run. The text form is Screenplay, the event-modeling language covered in Screenplay, and Play and code generation go through Stage, which Stage and Scene takes apart. Studio is where those pieces meet for a whole team.

The author feature, from board to commit

On a shared board

Open a brainstorming board, and everyone adds events and sticky notes at once: AuthorRegistered, AuthorRenamed, and a note asking “same name in two organizations?”. Group them by theme, and transfer the events that hold up into the event model.

Everyone sees who else is on the board and where their cursor is while they work, so a remote session doesn’t depend on one person’s shared screen. The events are what you transfer. The yellow note stays on the board as the question the slice will have to answer.

On the canvas

On the event-modeling canvas, the author feature becomes a module, a feature and a slice on a timeline with swimlanes, with the RegisterAuthor command, the AuthorRegistered event and a read model as color-coded cards. Assign the slice to a teammate or to an AI agent, and follow it on the project’s progress board.

The author feature on the canvas: two slices, with a command, an event and a read model.

The answer to the yellow note belongs to this slice. Registering a name that’s already taken in the organization is rejected, and that’s the behavior the specification on the slice writes down.

The same feature on the board and on the canvas. Events transfer; the question stays on the board.

A specification on the slice

Add a given/when/then specification to the slice, such as “registering the same name twice is rejected”. It’s an example against the model, and not against a running system, like the ones the Stage specification runner in Stage and Scene checks.

This is where the question from the board ends up, as an example with a given, a when and a then that a domain expert can read as easily as a developer.

Two specifications on the Register author slice. The second is the duplicate-name rule, written as an example.

AI agents on the same model

Cratis Studio’s AI agents can generate modules, features and slices from a prompt, explain a domain, feature or module, and answer in chat on the model. They run on a model provider your organization configures, and AI stays off until one is set up.

For the author feature, ask Studio to generate the missing slices of a feature from a prompt, such as renaming an author, and they appear on the canvas as cards the team reviews like any other change to the model. Ask it to explain the feature to someone new, at the level they need, and read aloud if they want. Dictate instead of typing, let predictive modeling suggest the next cards, or mention an agent in a slice’s chat and let it answer there.

Studio doesn’t ship a language model. Every AI feature runs on a provider your organization configures, such as OpenAI, Azure OpenAI or Anthropic, and until one is configured the AI features stay switched off and say why. The choice of provider, and the terms that come with it, stay yours.

Play

Press Play, and Studio starts a disposable Stage session for the model, so you can try the application it describes before anyone has written it. The session is for exploring the model. Don’t host the application there.

A Play session: the register form generated from the model.

From the canvas to a Play session. The wait for the session to start is shortened.

Screenplay out, and back in

Export the model as Screenplay, as one .play document or a folder of them, or as Mermaid or JSON. Commit the Screenplay next to the code and review it as a diff. Importing it back shows a preview of what will change and warns about anything it can’t bring in.

Screenplay reads well as a diff. This one, written by hand as an illustration and not exported from Studio, adds a rule to the RegisterAuthor slice of the author feature:

slice StateChange RegisterAuthor
  command RegisterAuthor
    authorId AuthorId identifier
    name     AuthorName
    authorize IsSignedIn
    validate
      name not empty  message "A name is required"
    produces AuthorRegistered
      for authorId
      name = name

The rule sits beside the command it guards, so a change to the author feature can be reviewed in a pull request before anyone writes code for it, and the reviewer reads the intent in a few changed lines.

Code for one slice

When a slice is assigned to an AI agent, Cratis Studio can render it through Stage into C# for Arc and Chronicle in a connected Git repository, commit the result, and optionally let the agent refine it. Code generation is opt-in for each application.

In practice, generation starts when the author slice, assigned to an AI agent, is marked ready for implementation. Studio renders it through Stage’s Cratis renderer into a working copy of your connected Git repository, commits the code and the .play files separately, lets the agent refine the result if the application is set up for that, and pushes. What arrives is a change in your repository, and it goes through the same review as any other.

Code generation is a setting on each application, and every path runs from the model to the repository.

Everyone on the same model

Collaboration is live. You see who else is on the board and where their cursor is, and a change one person makes shows up on everyone’s screen. Comments and chat sit on features and slices, and agents take part in them as well as people.

A project holds several applications, so each bounded context keeps its own model, and each organization has its own projects. For the author feature, that means the registration context can have its own model without sharing a canvas with, say, billing.

Where code generation stops

Code generation is opt-in for each application, with three settings: no code generation, Screenplay only, or Screenplay with an agent on top. It goes through Stage’s Cratis renderer, but through its older direct-write path, and not the planned render that cratis render uses in Stage and Scene. The output is C# on Arc and Chronicle, and not every construct becomes rendered code. What the renderer can’t express is marked with a TODO and a diagnostic instead of being refused, and the refusal and Customizations/ guarantees of cratis render don’t apply here. What the renderer leaves out is for the agent pass, or a person, to write.

Coupled doesn’t mean synchronized. Generation goes one way, one slice at a time. Nothing reads the code back into the model, and Studio doesn’t detect when code and model have drifted apart. What the coupling gives you is code that starts from the model, in the model’s own vocabulary, with the model sitting in the repository as Screenplay beside it. Review what comes out like any other change.

The Screenplay round trip has the same kind of limit. It’s tested for the constructs Studio models, and the import warns where it can’t carry something, so it isn’t lossless in every case. It’s the rule from Screenplay: expose what you can’t represent instead of dropping it.

Assistants outside Studio

Cratis Studio has an MCP server that lets external AI agents read and change an organization’s event models and brainstorming boards. That’s the route for an assistant in your editor or terminal to work on the author feature’s model without anyone copying it out of Studio first.

Scope it like any tool that can write. AI across the stack puts it next to the other places an assistant meets Cratis.

How it fits with the rest of Cratis

Studio isn’t in a request’s path. It works on the model and generates code into your repository. It uses the pieces the rest of this series describes. Its text form is Screenplay, Play and code generation run through Stage, and the generated code runs on Arc and Chronicle. You don’t need Studio to use any of them, and modeling in Studio doesn’t require adopting the rest of the stack. Stage is experimental, and some features inside Studio are labeled preview or experimental.

Prologue, which drafts a model from a running system, has a place in Studio too for systems that already exist, and it’s experimental there as well. Prologue covers what it does and what it can’t know.

When signup opens, the author feature makes a good first board: brainstorm it with the people who know the domain, transfer the events that hold up into the event model, add the example about duplicate names, and export it as Screenplay.

From script to stage · Part 22: Prologue: a first model of the system you already have

Wed, 30 Sep 2026 09:22:00 GMT

Cratis: from script to stage, and the long run · Part 22 of 26

Prologue can stand beside a running system, watch what it does, and hand back a .play file describing it, without recording a single row value or request body. What it does record is metadata: which endpoint was called, which tables and columns changed, which spans the system emitted. That metadata can still be sensitive, and the model it produces is a draft for a person to correct.

Prologue is an experimental assisted-discovery tool that captures approved metadata signals and proposes a Cratis event model for human correction. Most systems exist long before anyone models them, and those are the ones it’s for. The model it proposes is written in Screenplay, the language from Screenplay, so the first model of an old system starts from a draft instead of a blank page.

Picture the author feature already running in an ASP.NET application with a SQL database and no event model anywhere. Prologue can see a POST reach it and the write to an authors table that follows. Whether that pair of observations is called RegisterAuthor, and that names are unique per organization, is for a person to settle.

Evidence instead of memory

A system that predates any event model has two usual sources for one. The code says what the authors wrote, and the people who remember the system say what they think it does. Why Prologue proposes a third: watch the system run. Prologue observes three things the system already does, without a change to its code. It sees the state-changing HTTP requests that reach it, which tables and columns changed in each database transaction right after a command, and the telemetry it already emits.

The output is an ExtractionResult, a structured tree, and a generated .play file. That file is the way into everything else in the modeling layer. cratis screenplay validate checks it, cratis run starts it in a Stage sandbox, and a person edits it. Prologue itself is self-contained. It needs no Cratis Studio, no Orleans and no Chronicle, and runs as three ordinary containers, the Extractor, the Interpreter and an optional Receiver, with shared contract packages on NuGet.

What the Extractor watches

The Extractor runs next to the system and is the only piece that runs all the time, as the cratis/prologue-extractor image or a downloadable binary. It has four capture sources.

For SQL Server it uses change data capture, and it enables CDC itself unless you set enableChangeDataCapture to false. A tables allowlist narrows what it watches, and an empty list means every user table. It records which tables and columns changed in each transaction.

For PostgreSQL it uses logical replication. The Extractor creates its own publication and replication slot. The server has to run with wal_level = logical, and that’s a setting you make, because the Extractor can’t.

For HTTP it runs a YARP reverse proxy in front of the system, on port 8080 by default. Every request passes through unchanged. For POST, PUT and DELETE it records the method, the path, the response status, and the trace ID from a W3C traceparent header when there is one. GET requests pass through and leave nothing in the captures, since reads don’t change state. Traffic that goes around the proxy produces nothing.

For OpenTelemetry it runs an OTLP proxy over HTTP and gRPC. It records the metadata of spans, metrics and logs: the service name, filtered by serviceNames or all services when that’s empty, and the values of the attribute keys you allowlist in attributeKeys. Telemetry is forwarded unchanged to your collector, and with no upstream configured the Extractor is the last stop.

The Extractor watches from the side, and the Interpreter turns what it recorded into a draft.

What it records, and why that still matters

None of the four sources records the content of what passes through. There are no row values from the database, and no request or response bodies from HTTP. That boundary is deliberate.

Metadata is still information about the system and sometimes about people. An HTTP path can carry an identifier, such as a customer number in /customers/{id}. Table and column names describe the data model. The values of allowlisted telemetry attributes are recorded exactly as sent, so an attribute that holds an email address ends up in a capture file. And captures are written to disk as files, or posted to a Receiver that stores them in MongoDB. Choose the allowlists and the place captures go the way you’d choose them for a log that contains personal data, because it might.

One capture is a command and what it caused

A single HTTP call is rarely the whole fact. The call plus the database transactions it caused usually is. Prologue’s correlator groups observations into captures. A capture is an HTTP command plus every database transaction, span or log observed within correlation.windowMilliseconds after it, 2,000 milliseconds by default, or that shares the command’s trace ID.

Telemetry that carries a trace ID but has no command in front of it becomes one capture per trace, which is how background work shows up. Anything else becomes a capture of its own. A schema change, a table or column appearing or disappearing, is recorded but never used as evidence to group other observations. A capture is written only once nothing newer than the window could still join it, so one capture never ends up split across two runs.

This is a heuristic, and it links events by when they happened. Two requests that arrive inside the same window can share database transactions, and one of them can get credit for the other’s writes. Every relationship in the resulting model is provisional, and a person should read it that way.

From captures to a first model

The Interpreter turns a folder of capture files into a model. By default it runs to completion: it reads every .jsonl file, rebuilds the correlated captures, and writes extraction-result.json and a .play file. It also has a service mode that keeps running as a resumable session backed by MongoDB. The Receiver is an optional HTTP endpoint that stores captures in MongoDB when the Extractor posts them to it instead of writing files.

The first step is deterministic. Each capture becomes one or more provisional slice drafts, the drafts are grouped into modules, features and slices, and drafts that describe the same behavior are merged by name. The merge keeps the first item it finds for each name. Only projections combine their source events, so a property that appears only in a later capture of the same command or event is dropped. The result has the right structure and mechanical names, CRUD placeholders derived from HTTP verbs and database operations.

The extraction result follows the module, feature and slice structure of a Screenplay model. A system has modules, a module has features that can nest, and a feature has slices of type StateChange, StateView, Automation or Translation. A slice holds commands (at most one for a StateChange), events, read models, projections and constraints. For a library system it looks like this, trimmed:

{
  "systemName": "Library",
  "modules": [ { "name": "Catalog", "features": [ { "name": "Books", "slices": [ {
    "name": "Reservation", "type": "StateChange",
    "commands": [ { "name": "ReserveBook",
      "properties": [{ "name": "Isbn", "type": "string", "isRequired": true, "maxLength": 0 }],
      "validations": [] } ],
    "events": [ { "name": "BookReserved",
      "properties": [{ "name": "Isbn", "type": "string", "isRequired": false, "maxLength": 0 }] } ],
    "readModels": [], "projections": [], "constraints": [] } ] } ] } ]
}

A command’s validations come from rejected requests, as Required, MaxLength, MinLength or Pattern with an argument and the rejection’s message. Constraints are uniqueness and invariant rules inferred from rejected requests too. For the author feature, that’s where the unique-name rule could show up, if registering a duplicate name produced a distinct rejection while Prologue was watching. A rule the system enforces without a distinguishing HTTP response or database write leaves no evidence, and a person has to add it.

A language model may rename, never restructure

The second step is optional. With a language model configured in the llm section of cratis-prologue.json, or in the CLI’s ~/.cratis/config.json via cratis llm use, the Interpreter asks it to refine the draft. Refinement is off until you configure it. In cratis-prologue.json the kinds are Ollama (the default kind, self-hosted, no token), OpenAI, Azure OpenAI (where the model ID is the deployment name), any OpenAI-compatible /v1 endpoint, and Anthropic. cratis llm use offers anthropic, openai and local, an OpenAI-compatible endpoint such as Ollama’s.

The refinement prompt is in the public repository. These three lines set its contract.

The structure of the model is fixed - you never add, remove, or move anything.
Commands are imperative and express business intent (for example RegisterAuthor, PlaceOrder, ReserveBook) - name the intent, not the HTTP verb (not CreateAuthor).
Events are past-tense facts naming what happened in the domain (for example AuthorRegistered, OrderPlaced, BookReserved) - name the fact, not the database operation (not AuthorCreated).

The language model gets to return renames, keyed on the provisional names it was given, a description for each module, feature, slice and command, a system name in PascalCase, and questions. It infers intent from request paths, the tables and columns that changed, span names and the observed schema. The structure it was handed is the structure that comes back. For the author feature, that’s the difference between a placeholder named after the insert and RegisterAuthor.

Questions are meant to be rare. The prompt asks for one only when the model is unsure about a decision that would change the result materially, and zero is the normal case. An interactive run asks them one at a time, with choices and always a free-text answer. A non-interactive run, in CI, with piped output or with -y, never asks and finishes with its best effort. Without a configured model, the Interpreter doesn’t go beyond the heuristics.

The heuristics decide the structure, a language model can only name it, and a person decides the rest.

With a hosted provider, the prompt leaves your network. It carries the provisional outline of the model, the provisional names, the observed behavior, including request paths, and the observed database schema. That’s metadata again, and a path can carry an identifier. Nothing is sent anywhere unless you enable refinement, and Ollama runs wherever you host it.

Running it

The getting-started guide runs everything in Docker. A minimal configuration that watches only HTTP writes captures to a folder and forwards requests to the system on port 5000:

{
  "prologue": {
    "output": { "kind": "Json", "json": { "directory": "/captures", "maxEntriesPerFile": 10000 } },
    "correlation": { "windowMilliseconds": 2000 },
    "sqlServer": [],
    "postgres": [],
    "openTelemetry": { "enabled": false }
  },
  "reverseProxy": {
    "routes": { "monitored": { "clusterId": "monitored", "match": { "path": "{**catch-all}" } } },
    "clusters": { "monitored": { "destinations": { "primary": { "address": "http://host.docker.internal:5000/" } } } }
  }
}

Create the captures and output folders first, so Docker doesn’t create them as root. Then the Extractor runs with that file and the captures folder mounted, you send state-changing requests through port 8080, and the Interpreter reads the captures and writes to output:

mkdir captures output

docker run --rm -p 8080:8080 \
  -v "$(pwd)/cratis-prologue.json:/config/cratis-prologue.json:ro" \
  -v "$(pwd)/captures:/captures" \
  cratis/prologue-extractor

docker run --rm \
  -v "$(pwd)/captures:/captures" \
  -v "$(pwd)/output:/output" \
  cratis/prologue-interpreter

The CLI wraps the same steps:

cratis prologue start
cratis prologue interpret ./captures --file MySystem.play

cratis prologue start is an interactive wizard that writes cratis-prologue.json, with the sources, the allowlists, any upstream collectors, and an output folder or Receiver endpoint. It needs a terminal and fails with -y or piped input, so in CI you write the file yourself. cratis prologue interpret reads the .jsonl files, prints the path it wrote, the system name it derived and the counts of modules, features and slices, and suggests cratis run as the next step. For the language model it uses the llm section of a cratis-prologue.json it finds, when that’s enabled, then ~/.cratis/config.json, and otherwise runs on heuristics alone and says so.

Every capture carries a prologueId. When a folder holds captures from several runs, --prologue-id picks the one to interpret. The Library sample in the Prologue repository is an ordinary ASP.NET and EF Core application with no Cratis code in it, and its Aspire composition wires up the whole pipeline, with the Receiver storing captures in MongoDB. It’s a demonstration, and not a pattern for production.

Two ways into a model

cratis screenplay generate is the other way to get a model you didn’t write. It reads a .sln, .slnx or .csproj with Roslyn, for Arc, Marten, and Marten with Wolverine. It doesn’t start the application or connect to Chronicle or PostgreSQL, its output is byte-identical for unchanged source, and whatever it can’t express is reported with a stable diagnostic code. Generation reads what the code declares, and needs the source. Prologue records what the system did, and needs the system running with traffic going through it, though no source.

Two ways to a first model, and both end with a person reviewing it.

Neither one replaces the person who reviews the model, and neither is a migration tool.

What the draft is for

A Prologue draft is a provisional model built from evidence. It isn’t the system’s recovered intent, and it isn’t a lossless reconstruction. It shows only the traffic you sent through the proxy, the database changes on SQL Server or PostgreSQL, and the telemetry you allowed. Reads, message queues with no database effect, and requests that went around the proxy are absent, and so is any path nobody exercised while it was watching. Its names stay mechanical until a language model or a person renames them.

For the author feature, the draft gets you a slice with a command, an event and the tables behind them, maybe with a sensible name. It won’t know that names are unique per organization unless the system rejected a duplicate while Prologue was watching, and it can’t know what an author means in your domain. That’s what the review is for. The draft enters the loop at the same point a hand-written model does, as a proposal a person corrects, then validates with cratis screenplay validate. A corrected model can go on to cratis run, and Stage and Scene covers what Stage will and won’t do with it. Stage renders a narrow vertical, so don’t expect a draft of an old system to render unchanged.

Prologue is the wrong tool for a system that doesn’t exist yet, for moving data out of an old database, and for a system with neither an HTTP surface nor database access to watch.

From script to stage · Part 21: Stage and Scene: what happens after a model compiles

Wed, 30 Sep 2026 09:21:00 GMT

Cratis: from script to stage, and the long run · Part 21 of 26

A Screenplay model in which one event declares two generations passes cratis screenplay validate. Hand the same model to cratis render, and it reports STAGE-ESM-016, explains it with CLI-RENDER-003, and publishes nothing. The model is valid, and the renderer can’t turn it into code faithfully, so it doesn’t turn it into code at all.

Stage is the experimental part of the Cratis modeling layer that takes a compiled model somewhere. It renders the part of the model it supports into a C# application on Arc and Chronicle, boots a disposable sandbox, and runs the model’s Given/When/Then examples. Scene, also experimental, describes a user interface without describing a platform, and it’s how a screen in the model reaches React. Both are in early development.

Screenplay introduced the slice model using BorrowBook; the author feature follows the same pattern with RegisterAuthor. What happens to that slice next depends on which of Stage’s jobs you ask for, and on whether the slice stays inside what Stage supports.

One input, three jobs

Stage reads Screenplay source, either one .play file or a folder compiled as one application. Its own JSON contracts are internal seams produced from that compile, and it doesn’t depend on Cratis Studio. Any tool can hand it the same source. It does three things with it:

The renderer turns the compiled model into a reviewable C# application on Arc and Chronicle. It’s the job Stage puts first.
The cratis/stage image is a disposable sandbox: the Stage host plus an in-memory Chronicle kernel, for poking at the modeled backend behavior Stage understands.
The cratis/stage-specrunner job compiles the model, checks its specifications, writes a results file and exits.

One model, three uses, and a gate that fails closed.

Rendering is planning

The renderer keeps planning apart from writing. CratisRendering.Plan(...) returns an ArtifactRenderPlan with normalized paths, the exact bytes of every file, a SHA-256 hash for each, and typed diagnostics. Planning reads no file system, process, network, environment, clock or random source. A plan that fails carries its diagnostics and no files, and only a plan whose Success is true is published.

The CLI does the publishing:

cratis render ./plays \
  --target cratis \
  --destination ./out \
  --name MyApplication

cratis render publishes new files only after the model compiles, binds to an executable model, is admitted for execution, plans for the target and passes artifact validation. If an earlier publication was interrupted, it recovers that first. The output is deterministic, down to a manifest that records the model’s semantic revision and the hash of every file. It refuses to overwrite a generated file you’ve edited unless you pass --force, and it never overwrites a file it didn’t generate, with or without --force. It runs no Git command. --name sets the application’s identity, while --project-name and --root-namespace change only how it’s rendered.

cratis is the only target that ships, and the renderer-target guide describes how another one would be built. A plan for a whole application holds the generated C# for concepts, commands, events, projections and specifications, a frontend shell, and eight backend scaffold files. With cli 3.21.0, an author model renders to this, scaffold files marked:

out/
├── .frontend/
│   ├── index.css
│   ├── index.html
│   ├── main.tsx
│   ├── tsconfig.json
│   ├── tsconfig.node.json
│   └── vite.config.ts
├── Authors/
│   └── Registration/
│       ├── AuthorList/
│       │   └── AuthorList.cs
│       └── RegisterAuthor/
│           ├── RegisterAuthor.cs
│           ├── UniqueAuthorName.cs
│           └── when_registering_an_author.cs
├── Common/
│   ├── AuthorId.cs
│   └── AuthorName.cs
├── GeneratedPolicies/
│   └── Policies.cs
├── src/
│   └── bindings.ts
├── .cratis-render.json
├── .gitignore
├── appsettings.json                           # scaffold
├── Directory.Build.props                      # scaffold
├── Directory.Build.targets                    # scaffold
├── Directory.Packages.props                   # scaffold
├── docker-compose.yml                         # scaffold
├── GeneratedPolicyRegistration.cs
├── MyApplication.csproj                       # scaffold
├── MyApplication.slnx                         # scaffold
├── package.json
├── Program.cs                                 # scaffold
├── scene.json
└── tsconfig.json

Stage 4.22.1 renders for .NET 10 and pins Arc 22.25.0 and Chronicle 19.8.1, with Components 4.14.0, Scene 4.2.0 and Fundamentals 7.19.6 for the frontend. cli 3.21.0 renders with, and cratis run starts, Stage 4.20.0, which has the same pins. The specification runner described below is the 4.22.1 image, which you pull by tag. Those versions belong to those Stage releases, and they say nothing about which other versions work.

The generated code follows the model closely. A command implements ICanProvideEventSourceId from the property the model marks as identifier, its event is appended through the value Handle() returns, and the generated acceptance specs check both the event source ID and the payload.

What the renderer admits

The cratis target covers a narrow backend vertical. It admits concepts and composite types, one command-to-event production path with not empty validation, the event with its mappings, a one-instance projection, an optional by-key query over a snapshot, and the model’s specifications. Anything reachable outside that is a blocking diagnostic. The renderer doesn’t leave behavior out, and it doesn’t generate TODOs.

The refusals have codes. An event with more than one declared generation gets STAGE-ESM-016. Code validations, named rule predicates and code validations on concepts get STAGE-ESM-005, because Arc doesn’t give a generated validator the received-at time in RuleContext.Occurred. A guarded production gets STAGE-ESM-006. Through cratis render, bodied reducers and opaque policies are refused as well, for now.

The renderer also admits declarative unique constraints, rendered as named Chronicle constraints, and policies whose expression requires a signed-in caller. The author feature’s unique name and its sign-in rule are both inside. A policy that checks only a role or claim, or one written as code, gets STAGE-ESM-015. For that vertical you stop typing the concepts, command, event, constraint, policy, projection, query and specs by hand, and everything outside it is still code somebody writes.

Valid Screenplay is the first gate. The renderer adds its own, and a refusal publishes nothing.

A successful render is a plan that validated. Building and running the generated code is still your step. Taking a second model change through to a running application isn’t proven yet.

Hand-written code goes in Customizations/

Every render plans Program.cs, the project file, appsettings.json and the frontend shell again, so an edit to one of them is either lost or blocks the next render. The customization guide gives hand-written code an unmanaged folder at the application root, Customizations/. The generated Program.cs ends like this:

ConfigureServices(builder);

var app = builder.Build();
app.UseDefaultFiles();
app.UseStaticFiles();
app.UseCratis();
app.MapHealthChecks("/healthz");
app.MapFallbackToFile("/index.html");
ConfigureApplication(app);

await app.RunAsync();

// Optional partial methods disappear when Customizations/Program.cs supplies no implementation.
public partial class Program
{
    static partial void ConfigureServices(WebApplicationBuilder builder);
    static partial void ConfigureApplication(WebApplication app);
}

Customizations/Program.cs supplies either partial method, or both. The generated project imports Customizations/Dependencies.props when it exists, and the frontend loads Customizations/styles.css after its own tokens and styles. No plan contains a path under Customizations/, and the planner never reads one. A model that would generate a file there is rejected with STAGE-CRATIS-005, whatever the capitalization.

That makes the folder a seam for agents too. Code written by hand, by a person or an assistant, goes in Customizations/, and an edit to a generated file shows up as a refused render, unless someone passes --force.

A sandbox to poke at

cratis run starts the model before anyone renders it. It needs Docker, mounts the file or folder read-only, and starts the cratis/stage image, pulled on first use at the Stage version the CLI renders with, 4.20.0 for cli 3.21.0:

cratis run [PATH]

  Stage API           http://localhost:9090
  API reference       http://localhost:9090/scalar/v1
  Chronicle Workbench https://localhost:35000
                      HTTPS only

  Ready - event model 'Invoicing' as event store 'gentle-zephyr'
  Press Ctrl+C to stop

The sandbox serves an API, a generated frontend and Chronicle Workbench. The Workbench port only speaks HTTPS, because Kestrel serves gRPC and HTTP/1.1 on it through ALPN, so a plain http:// request gets no reply. The certificate is a self-signed development one. The kernel stores everything in memory, so each run starts empty, and --rm removes the container afterwards. The image is built on the Chronicle kernel image, pinned to the exact development tag the host’s client was built against, because the gRPC contract changes between versions.

Calling a command appends the events its produces block maps to Chronicle and echoes the payload back. A projection translation that could be read more than one way fails at registration, and the sandbox doesn’t pick one. The sandbox doesn’t yet enforce the model’s command validation or authorization, and it doesn’t evaluate query authorization. For the author feature, that means a blank name and an anonymous caller both get through. It isn’t a production host. cratis run publishes both ports on every interface. On a machine other people can reach, run the image yourself with -p 127.0.0.1:9090:9090 -p 127.0.0.1:35000:35000, as Stage’s own Docker examples do.

Running the model’s examples

The specification runner is for a build pipeline. It compiles the model, checks its specifications and writes a results file, and it starts no server and needs no event store. Exit code 0 means the run completed and the file was written. A failing specification still completes the run, so a pipeline has to read the outcomes.

The model-first Library model in Cratis Samples has a specification of this kind:

slice StateChange AddBook
  command AddBook
    bookId     BookId identifier
    title      BookTitle
    authorName AuthorName

    validate
      title not empty       message "A title is required"
      authorName not empty  message "An author name is required"

    produces BookAddedToCatalog
      title      = title
      authorName = authorName

  event BookAddedToCatalog
    title      BookTitle
    authorName AuthorName

  specification RejectingABookWithoutATitle
    when AddBook
      bookId     = "69064f39-6a76-458a-8a34-088eb4752650"
      title      = ""
      authorName = "Mara North"
    then error "A title is required"

There are two engines. The default one is structural, and it works on the model: it checks that the events and commands a specification names resolve to its slice and that the rules and expected errors agree. Each result is Passed, Failed or Inconclusive (when that kind of slice can’t be verified yet), with a note saying what was and wasn’t checked. The structural engine is deprecated, stays the default for existing users, and goes away in the next major version.

The semantic engine is opt-in with --engine semantic. It executes admitted commands through Arc’s in-memory command pipeline, with a fresh in-memory Chronicle event log for each specification. It handles Given events with an explicit source, direct when append, unconditional production, event assertions, and command authorization checked before dispatch with given caller and then denied. It also checks command rules, and unique-value and unique-event constraints before the append, which is where the author feature’s “same name twice” example belongs. Flat and event-source-keyed projections and snapshot queries by identifier are covered too.

Each semantic result is Passed, Failed, Unsupported or Cancelled. Given read models, conditional production, implicit identity allocation and external effects come back as Unsupported, with the kind, the construct and the reason, and an unsupported case never counts as a pass. It all runs in memory. Nothing in a released Stage runs a .play specification against the generated application on a live Chronicle.

Scene: a screen that isn’t React

Scene separates what a screen is from how it’s drawn. It has three layers, and a blueprint around them:

Scene.Model holds screens, layouts, forms, contribution points, UI profiles and themes (NuGet Cratis.Scene.Model, npm @cratis/scene.model).
Scene.Engine walks that graph and resolves its data, action, form and navigation bindings, and drives whichever renderer is plugged in (@cratis/scene.engine).
Scene.React is one renderer (@cratis/scene.react).
A blueprint supplies the application around the screens, meaning layouts, screen and dialog templates, shell components and themes, built from declared packages, and an application selects one.

Each layer knows only the one above it. The model has no URL, CSS class, React type or HTTP verb in it. The engine imports no UI framework and never touches window, so “entering this screen runs that query once” can be a unit test instead of a browser test. The renderer is the only place a URL is built, and the model only says “navigate to” a screen. Only Stage knows what an Arc endpoint is. React is the only renderer today. Native and desktop renderers are reserved positions, and vendor component packages are adapters to the renderer contract.

Each layer knows only the one above it.

In a .play file, a screen lives in a StateView slice. The lending example from Screenplay declares its screen at the level of intent, with the data and the query it comes from:

      screen OnLoan
        data OnLoanReadModel[] via query BooksOnLoan

A screen can add named sections, tables and summaries that fill a screen template’s slots, or drop down to a template with inline code. It never names the layout. A UI profile picks the shell once per build, which keeps the screen portable between targets.

Stage resolves a render plan for each target from the UI profile, using Scene.Engine’s own rules, so the plan and the running application can’t disagree about what a screen resolves to. When a target doesn’t fully resolve, the plan says so with IsComplete set to false.

In the sandbox, the host serves a browser bundle at /, fetches the Scene translation from /stage/scene (produced from the same compile as the runtime model) and draws it with @cratis/scene.react. A model without screens gets query views and command forms built from the Arc routes. Commands with string or GUID values get inputs named after the proxy’s properties and a submit action, and a combination the sandbox can’t handle shows a diagnostic instead of a partial form. Screens you’ve written take precedence. Layout and template composition, data from queries and command forms are all still growing.

The model is checked for the wire shape of its screens. Nothing verifies that every component and binding resolves, and a native build doesn’t prove that a browser can submit a command and read the result back. Live UIs covers the React side you write by hand today.

Stage inside Cratis Studio

Cratis Studio, live and in beta, uses Stage in two places. Play runs the model in a disposable Stage session, which is for exploring and not for hosting. When a slice is assigned to an AI agent, Cratis Studio can render it through Stage into C# for Arc and Chronicle in a connected Git repository, commit the result, and optionally let the agent refine it. Code generation is opt-in for each application. It goes one slice at a time, through Stage’s older direct-write path instead of the planned render cratis render uses. Cratis Studio goes through both.

Stage’s vertical covers the author feature’s basic command with its validation and sign-in policy, event, unique-name constraint, projection and by-key query. The executable model refuses compliance-marked concepts (PLAY0268), so the name’s personal-data handling stays outside that vertical and its [PII] marking is still yours to write. The C# for anything Stage refuses still goes in Customizations/ or beside it, written by a person or an agent.

From script to stage · Part 20: Screenplay: an event model you can compile

Wed, 30 Sep 2026 09:20:00 GMT

Cratis: from script to stage, and the long run · Part 20 of 26

cratis screenplay validate compiles an event model on a machine where the application has never started. It reads a folder of .play files, merges them into one application, and reports each problem with a code that stays the same from one release to the next. Screenplay is the language those files are written in.

In a model, the author feature is a RegisterAuthor command, the AuthorRegistered event it produces, and a list of authors built from those events. The code below uses the library example from the Screenplay docs, where a member borrows a book. It has the same shape, with one command, one event and one list.

Write the intent down first

Event modeling draws a feature as a timeline of screens, commands, events, read models and automations. For the author feature that timeline is short. A librarian fills in a form, the system records that an author was registered, and a list shows the authors. Drawing it first lets the people involved argue about cause and information flow while changing their minds is still cheap.

One slice as an event model, and the file that holds it.

An event model on a whiteboard stops matching the code soon after the code exists. Screenplay writes the model down as a versioned .play file next to the code it describes, so a change to the model turns up in the same pull request as the change to the code. The language reaches from the concepts a value is made of to the policy that decides who may run a command. It doesn’t make any one runtime the authority on what those mean, which is why several tools can read the same file.

The slice is the unit

A .play file is indented like Python and has no braces. Nesting is decided by spaces, so a tab gets a warning (PLAY0006), and comments start with //. A file declares a domain, the concepts and policies it needs, and then a module that holds features and slices. Features nest as deep as the domain needs them to.

The slice is the smallest thing a model is made of, and its four types follow event modeling:

Slice type	What it models
`StateChange`	a command that produces events
`StateView`	a query, its projection and a screen
`Automation`	a reaction or a reducer that runs when something happens
`Translate`	external data captured as events

The author feature is one StateChange slice and one StateView slice. In a lending version adapted from Getting started, a member borrows a book:

    slice StateChange BorrowBook
      command BorrowBook
        bookId     BookId identifier
        borrowedBy MemberId
        authorize  IsMember
        validate
          bookId not empty  message "A book is required"
        produces BookBorrowed
          for bookId
          borrowedBy   = borrowedBy

      event BookBorrowed
        borrowedBy MemberId

A reviewer sees the whole write in one diff. authorize IsMember names the policy that decides who may run the command. The validate block holds the rules, each with the message a user gets back. identifier makes the book the command’s event source, produces appends the event to it with for bookId and maps the command’s values onto the event. An event never carries its event source ID, so bookId isn’t on BookBorrowed, and marking one of an event’s properties as the identifier is a compile error (PLAY0019). When it happened travels in the event’s context.

For the author feature, RegisterAuthor sits where BorrowBook is. The rule that names are unique goes in a constraint, another construct a slice can hold:

      constraint UniqueAuthorName
        unique name on AuthorRegistered
        message "An author with this name is already registered."

A constraint covers one event sequence in one namespace, and a namespace per tenant makes that one organization. A declared event is a statement of intent. AuthorRegistered in the model says the system is meant to be able to record it, and only the event log says it did.

An event can also declare a generation. Generations have to be in range and contiguous within a slice (PLAY0446 to PLAY0448), and Year two goes through what they’re for.

The read side in the same file

The same page adds the read side of lending to the file:

    slice StateView OnLoan
      query BooksOnLoan => OnLoanReadModel[]

      projection OnLoan => OnLoanReadModel
        from BookBorrowed
          borrowedBy = borrowedBy
          borrowedAt = $eventContext.occurred

      screen OnLoan
        data OnLoanReadModel[] via query BooksOnLoan

BooksOnLoan returns a list of OnLoanReadModel. The projection block is written in PDL, the projection language, embedded in the model: for each BookBorrowed, keyed by the book it happened to, copy who borrowed it and when onto the read model. The screen names the data it shows and where that data comes from, and says nothing about how it looks. Stage and Scene picks up from that screen, and From event to read model goes deeper on projections. PDL and CDL, a language for change data capture, are both built in and can be used on their own.

A model means something without any code in it. A few points in the language accept a short inline block in csharp, typescript, react, html or sql, or a file reference to one, and Screenplay treats that as realization metadata. None of it is required. The construct keywords themselves are a closed set. An editor extension can highlight a keyword of its own, and the compiler discards it.

Personal data is declared on the value

Concepts are the typed values a model is built from, and they’re where personal data is marked:

concept EmailAddress     : String   @pii
concept NationalIdNumber : String   @pii @sensitive
concept BankAccount : String @pii @sensitive
  pii reason "Partner payout bank account - financial data. Lawful basis: contract performance / legal obligation."
  sensitive reason "Fraud-sensitive - a leaked account number enables direct financial harm."

EmailAddress is marked @pii once, and every command, event and read model property of that type inherits the mark. In the model, the decision about an email address is made in one place. Nothing released carries it into a running application yet: the executable model behind Stage refuses a concept with compliance attributes (PLAY0268), so in code the [PII] marking is still yours to write. The indented reason lines record why, and a reason for an attribute the concept doesn’t declare is a compile error (PLAY0012). What Chronicle does with personal data, including encryption per subject and erasure, is the subject of Personal data in an event log.

Examples live in the slice

A slice can carry specifications, written as Given/When/Then over facts. given sets up earlier events, a read model’s state, or the caller with their roles and claims. when runs a command or appends an event directly. then expects events, a read model, a query result, an error with its message, or denied.

then denied expects the typed unauthorized rejection, which is a different outcome from a failed validation. A scenario for a command with an authorize line has to say who the caller is with given caller, and without it binding fails with PLAY0389. Values in an executable specification are concrete literals, objects and lists. A null in a command or event value is rejected (PLAY0350), because in Chronicle an optional fact is a separate event.

For the author feature, “registering the same name twice is rejected” would have an earlier AuthorRegistered under given, the same name under when, and then error with the message a user sees. The compiler checks that the specification fits the model. Running it is a different job, done by the Stage specification runners in Stage and Scene.

One folder is one application

A folder of .play files compiles as a single application. The files are merged before any name is resolved, so an event declared in one file and produced in another resolves. Compile the same files one at a time and you get false warnings about unknown types, policies and events (PLAY0165 to PLAY0167). Compile the folder and you get none. A folder can hold at most one domain, and two files that each declare one get PLAY0172: “a folder compiles to one application, which can have at most one”. Unrelated applications need separate folders.

Checking the model needs nothing running:

cratis screenplay validate ./plays --warnings-as-errors

The CLI compiles every .play file under the folder as one application and prints compiler-style errors, so it fits in CI on a machine where the application has never started. By default warnings and information don’t fail the run, and an error does. --warnings-as-errors makes a warning fail it too. In CI that’s usually what you want, since a warning almost always means an undeclared name. Piped output is JSON, and -o plain or -o table prints something for a person. Validation checks the model only. Whether a renderer can build it is a separate question, and Stage and Scene answers it.

The compiler is also a .NET global tool, Cratis.Screenplay.Tool, which puts a screenplay command on the path, and a NuGet library, Cratis.Screenplay, for tools of your own.

Diagnostics you can match on

Every problem is a diagnostic with a severity, a code, a message and a line and column. The screenplay tool prints them like a compiler:

nested/broken.play(3,5): error PLAY0028: Unknown slice type 'Wat' - expected StateChange, StateView, Automation or Translate
    3 |     slice Wat DoIt
      |     ^

2 file(s) compiled - 1 error(s), 0 warning(s)

cratis screenplay validate reports the same code and message, as JSON when piped. Match on the code. A message can be reworded between releases, and a code is never reused or renumbered. New codes are appended at the end whatever area they belong to, so a number tells you when a code was added, and says nothing about where it belongs. Two constructs that hit the same condition share a code. The library declares every code as a named constant in DiagnosticCodes, so a misspelled code in your own tool is a compile error. At Screenplay 4.44.1 the catalogue has 391 codes.

The prefix is PLAY. Arc has a generator that writes a .play file from C# source, and its codes use SP. The two can run one after the other and land in the same build log, so the prefixes share nothing on purpose. An SP code describes what the generator couldn’t express, and a PLAY code what the compiler couldn’t read.

Editors get part of the catalogue. The Monaco language service (@cratis/screenplay-language) and the VS Code extension (cratis.screenplay) check a subset of the conditions and report the compiler’s own code for each, so the squiggle under an unknown type and the CLI both say PLAY0165. A few structural editor checks in captures and projections have no code, because the compiler has no matching diagnostic. The full set runs only in the compiler.

A folder compiles as one application, and every finding carries a code that doesn’t change.

A tree that prints back to the same text

As a library, new ScreenplayCompiler().Compile(source) returns a result with Success, the syntax tree in Value, and Diagnostics. PlayFileCompiler compiles a file or a folder. The nodes of the tree are immutable records, and each carries its location in the source. ScreenplaySyntaxWalker is the supported way to traverse the tree, and a new kind of node arrives as a new Visit method whose default keeps walking.

New node kinds can be added, and an unknown form never throws. Enum members keep their numeric values, and public constants, every diagnostic code among them, never change. A node grows by an init-only property, never by a new constructor parameter. The positional parameter list, an exhaustive switch over a base type and the element types of collections are outside those promises, so tools shouldn’t depend on them.

ScreenplayPrinter turns a tree back into .play text, with two spaces per level, escaped strings and numbers that print the same in every culture. Printing a compiled document gives an equivalent tree, and printing that again gives identical text. Comments survive and surrounding whitespace is normalized. That round trip keeps a generated .play file readable as a diff, whichever tool wrote it.

Valid and runnable are two verdicts

A document that compiles is valid Screenplay. Whether it can execute is decided separately. An executable semantic model is bound from the checked model and versioned on its own, and handler code blocks executable admission (PLAY0268). The reference executor can’t run inline or file-backed code, so anything that depends on it comes back as unsupported. The standalone tool and PlayFileCompiler compile syntax only and don’t read attached files. cratis screenplay validate gives the first verdict. The Stage renderer, its sandbox and its specification runners each give part of the second, for the constructs they support.

An assistant on the model

The Screenplay MCP server lets an assistant work on the same files a person does. It ships in the .NET tool and in the native CLI as cratis screenplay mcp, which needs no separate .NET install. The CLI embeds its own copy of the server, so it can trail the newest Screenplay release. cli 3.21.0 embeds server 4.43.0, while the newest Screenplay release is 4.44.1. For VS Code, the install guide points the tool at a folder:

{
  "servers": {
    "screenplay": {
      "type": "stdio",
      "command": "screenplay",
      "args": ["mcp", "${workspaceFolder}/specifications"]
    }
  }
}

With the CLI, it’s cratis screenplay mcp .cratis/screenplay. cratis ai install registers that form, with .cratis/screenplay as the default root, when the profile you pick includes Screenplay. Installing creates the root folder if it’s missing and never creates a .play file. Starting the server creates nothing, and a missing root is an error.

At cli 3.21.0 the server lists 27 tools, and most of them read. describe-application, find-references, dependencies and find-assertion-gaps navigate the model, and diagnostics returns the compiler’s findings. On a small library model with two slices, describe-application reports one file, 13 declarations, one module, one feature, two slices and no diagnostics, with a hash of the source revision. find-assertion-gaps lists both slices as having no specifications, and notes that a gap isn’t proof of missing runtime test coverage.

Changes go through proposals. propose-ast takes a typed edit whose shape comes from syntax-schema, propose-rename renames with the whole model in view, and read-proposal shows the exact bytes that would be written. A proposal is tied to the revision it was made against, so one made before somebody else’s edit is rejected when it’s applied. Only two tools write files, apply and recover-workspace, which is where your client’s approval prompt belongs. Keep approval on for both.

One root is one application, and symlinks are rejected. Paging and oversize results fail loudly instead of truncating. Identities live in .screenplay/identities.json, which belongs in source control. An interrupted apply leaves a pending.json that blocks reads and edits until someone inspects it and recovers the workspace explicitly, since rollback isn’t crash-atomic. None of the tools runs specifications, so an assertion being present says nothing about runtime coverage.

Most tools read. Only apply and recover-workspace write, so that’s where your client’s approval prompt belongs.

The server checks what reaches the files. It doesn’t make an assistant’s model correct. AI across the stack puts it next to Chronicle MCP and the Cratis AI corpus.

What reads a .play file

A .play file is an input for several tools. cratis render and cratis run hand it to Stage (at cli 3.21.0, Stage 4.20.0), which renders a narrow backend vertical into C# on Arc and Chronicle, starts a disposable sandbox and checks the model’s specifications. A .play file is a good home for a model once someone has written it down. Getting there is usually a conversation between several people. A Cratis Studio event model can be exported as Screenplay text, Mermaid or JSON and imported back from Screenplay with a preview. That round trip isn’t lossless, and Studio is live and in beta. cratis screenplay generate goes from Arc, Marten or Critter Stack source in C# to a .play file, and Prologue drafts one from a running system. Stage and Scene, Prologue and Cratis Studio each take one of those. Everything above works without any of them, because validate only reads files. And outside what Stage renders, nothing checks hand-written code against the model.

There’s one rule in this layer we care about more than any single feature. Producers and consumers of a model have to declare what they can handle and expose what they can’t represent, instead of dropping it silently. A tool that quietly loses part of your model is worse than one that refuses it, so Stage publishes nothing when a model reaches past what it supports, and Studio’s import warns about anything it can’t bring in.

From script to stage · Part 19: Chronicle jobs, scale and performance

Wed, 30 Sep 2026 09:19:00 GMT

Cratis: from script to stage, and the long run · Part 19 of 26

Replaying a projection in Chronicle runs as a job, and a job can be stopped halfway and resumed later from where it stopped, as long as the application that owns the observer is connected. If the server crashes instead, the replay picks up from its last checkpoint, and the batches it processed since that checkpoint are delivered a second time.

Change the projection behind the Author read model and deploy it, and Chronicle decides whether the change needs a replay. The job’s progress and the cost of restarting it matter once that author list has a long history.

What runs as a job

A job is long-running work the kernel does in the background, split into steps. These are the kinds it runs as of Chronicle 19.23.1:

Job	What it does
Replay observer	Reprocesses an observer from the start of the log
Replay observer partition	Reprocesses one partition of an observer
Catch up observer, catch up partition	Brings an observer or one partition up to the tail, after downtime, a new subscription or a full queue
Retry failed partition	Makes one more attempt at a failed partition
Migrate existing events for type	Back-fills a new generation of an event type across the stored events
Reindex constraints	Rebuilds a constraint’s index after its definition changed

A replay isn’t split the same way for every observer. A projection’s replay is a single step that reads the log in global order, from the first event to the last. A reducer’s or reactor’s replay is one step per event source, taken from the observer’s index of keys, so for the author feature that’s one step per author.

A projection replays in one ordered step; a reducer or reactor replays one event source per step.

Two operations that sound like background work aren’t jobs. Erasing a person’s key is a synchronous call from the client, and webhooks are delivered by an observer.

A job’s life

A job moves through PreparingJob, PreparingSteps, StartingSteps and Running, and ends as CompletedSuccessfully, CompletedWithFailures, Stopped or Failed. Removing is the state it passes through on its way out. Each step has a status of its own, from Scheduled and Running through to completed, stopped or failed.

The controls are stop and resume. Stopping keeps the job’s progress, and resuming a stopped job continues where it left off. A job that ended as Failed doesn’t resume.

Stop and resume have two rules for replays. Resuming a replay needs the observer to be subscribed, so a replay you stopped can’t continue while the application is down. And starting a replay deletes the observer’s other jobs, so a stopped replay doesn’t survive the next one.

The kernel cleans up after itself on a schedule. A job stuck in preparation with no steps is removed after an hour. Every 60 seconds a watchdog checks that running replay and catch-up jobs are still making progress, and an observer that stays stuck preparing a catch-up is quarantined after five recovery attempts.

Jobs belong to an event store and a namespace, like the observers they work for.

What a crash delivers twice

A replay or catch-up step doesn’t write its position after every event. It makes a checkpoint durable every 100 batches or every five seconds, whichever comes first, and on every status change. After a crash, the step resumes from its last checkpoint and reads forward again, so everything between that checkpoint and the crash is delivered a second time.

For a projection that only sets values, a second delivery writes the same values again. For one that accumulates, such as a count, it would change the result. Chronicle narrows that in two ways. For read models keyed by the event source ID, the sink write is guarded by a watermark by default, so a batch that was already applied isn’t applied again. A projection that combines several event sources into one document, through a join, a constant key or a parent, can’t be guarded that way. Its per-partition steps checkpoint after every batch, which keeps what’s read again to the batch in flight, and that doesn’t make it idempotent.

Reactors have no such guard, and they don’t need a special case either. Chronicle can deliver an event to an observer more than once. A timeout, a retry and a replay can all deliver an event again, so a reactor has to cope with running twice regardless, and a crash during a job is one more way that happens. For the author feature, a reactor that sends a welcome email needs to know whether it already sent one. Reacting to facts goes through delivery identity and [OnceOnly].

How many steps run at once

Job throttling caps the number of job steps running in parallel. Each step takes a slot before it runs, waits in a queue when none is free, and gives the slot back when it finishes, successfully or not. The default is the processor count minus one, with a minimum of one, so an 8-core machine runs up to seven steps at a time.

In chronicle.json it goes at the top level:

{ "Jobs": { "MaxParallelSteps": 4 } }

As an environment variable, it’s Cratis__Chronicle__Jobs__MaxParallelSteps=4. Don’t nest the section under Cratis and Chronicle inside chronicle.json. Chronicle already publishes that file under the Cratis:Chronicle: path, so a nested copy binds to the wrong path and is silently ignored.

There’s a second ceiling in the kernel’s own code. The effective cap is the smaller of MaxParallelSteps and Observers.MaxConcurrentPartitions, which defaults to 32 and isn’t in the configuration reference. On a machine with 34 or more cores the default stops tracking the processor count, and a configured value above 32 is capped at 32 as well.

For the author feature, that cap matters for reducers and reactors, whose replays are made of many small steps. A projection’s replay is one step, so the cap doesn’t speed it up.

Watching and steering jobs

The Workbench’s Jobs page shows each job’s type, status and progress, with Stop, Resume and Delete. The terminal workbench has a Jobs view where S and U stop and resume. From the CLI:

cratis chronicle jobs list
cratis chronicle jobs get <JOB_ID> -o json
cratis chronicle jobs stop <JOB_ID>      # progress is preserved; needs --yes non-interactively

jobs get shows each step with its own progress and any error. The CLI has no command to delete a job. Chronicle MCP has three tools for stopping, resuming and deleting jobs, and they’re the only tools in it that change anything on the server. Chronicle MCP can read personal data and isn’t read-only, so scope what you connect it to. The jobs API lists jobs and their steps, stops, resumes and deletes them, and the .NET client exposes it as IJobs.

Replays Chronicle recommends instead of running

The classification and definitionEvolution policy in From event to read model determine whether a changed definition starts a job or leaves a recommendation. To let partial replays run while reserving full ones for a person:

{ "observers": { "maxRetryAttempts": 10, "definitionEvolution": "PartialOnly" } }

As of Chronicle 19.23.1, a recommendation is always a replay candidate. It’s filed for a projection or reducer definition change the policy didn’t apply, for a reactor or webhook definition change when replayOnDefinitionChange is off, and for a retired projection that wrote to the same container as the one replacing it. Performing a recommendation replays the observer server-side and removes the recommendation when the replay succeeds. Ignoring it drops it.

We’d set PartialOnly or Manual on a store where a full replay of a large projection is expensive, so that a deploy doesn’t start one on its own and a person decides when it runs.

How events reach observers

An append doesn’t wait for observers. Once an event is in the log, it’s handed to observers through queues, and the number of queue loops is events.queues, 2 by default. It’s the setting to raise for higher expected event throughput, and it comes without a sizing rule.

Each queue is a bounded channel, 2,000 batches by default, set by Events.QueueBoundedCapacity in the kernel’s configuration code. When a channel is full, the append still doesn’t wait. The observers on that queue are moved to their catch-up path, which reads the log again from each observer’s persisted position, and catching up is a job like the others. Setting the capacity to 0 makes the channel unbounded, and then nothing is ever moved. The setting isn’t in the configuration reference, so treat it as an internal.

A full queue sends observers to catch up from the log; the append doesn’t block.

The append path does one related piece of housekeeping. The kernel looks for changed constraint definitions at most once a second per sequence, because checking on every append would tie append throughput to how fast one cluster-wide grain can take its turns.

On the observer side, order is per event source. Live delivery hands events over in sequence order, one partition’s batch at a time, to every observer that wants it at once. Partitions run side by side only inside jobs, where a reducer’s or reactor’s replay or catch-up is one step per event source under the step cap. A failed partition stops alone and retries with backoff while the rest continue. Across partitions there’s no order. An event can reach an observer more than once, and projections always run asynchronously, which is Chronicle’s eventual consistency model.

When several instances of one application connect, the observer fans delivery out across them. The default, round-robin, assigns each partition to one instance by its key, so a partition stays with the same instance and keeps its order. random picks an instance per delivery. When an instance disconnects, it’s dropped at once and its partitions go to the others.

subscriberTimeout, 30 seconds by default, bounds how long an observer waits for a subscriber to answer a batch. Giving up abandons the wait, and the subscriber may still be working on the batch when it’s delivered again on retry. A partition whose last attempt was a Timeout doesn’t count toward the quarantine thresholds, because a timeout says the system was congested, and congestion clears.

Read cost

A read model is materialized by default. The projection writes it as events arrive, a read is a lookup, and the read is eventually consistent. A passive read model computes its state from the log on every read instead, so it’s always current, and its cost grows with the history of the key being read. For the Author list, materialized is the obvious fit. A passive read suits something read rarely, over a short history, where being current matters more than the cost.

Running more than one node

Inside Chronicle covers the kernel architecture and why two servers on default clustering don’t form one cluster. That architecture makes no scale or throughput guarantee.

The server logs a warning when it sees localhost clustering against storage that isn’t local, and it starts anyway. Every node in a multi-node deployment has to set the clustering type to MongoDB, with the same cluster ID and service ID:

Cratis__Chronicle__Clustering__Type=MongoDB
Cratis__Chronicle__Clustering__ClusterId=chronicle
Cratis__Chronicle__Clustering__ServiceId=chronicle

There are only two clustering types, Localhost and MongoDB, and the second keeps cluster membership in the configured MongoDB storage. MongoDB has to run as a replica set, because appends use transactions. The nodes share the same encryption certificate and storage, the Orleans ports, 11111 and 30000 by default, are open between them, and port 35000 sits behind a load balancer. Nodes on one host need different silo and gateway ports and an explicitly set advertised address. The production guide has a two-node Compose example. In-memory storage doesn’t share state across a cluster.

Nodes can take roles. roles.eventSequences and roles.observers, both on by default, let you separate the nodes that take appends from the nodes that run observers. Role placement is best-effort today. A node only sees its own role settings, so a grain can still land on another node whose role is switched off. Treat the roles as a scheduling hint, and run every node with every role when every node must accept every grain.

The default gives two servers two clusters; a shared cluster needs the MongoDB type on every node.

What’s been shown about a cluster is limited. Chronicle’s integration tests run an Orleans cluster of two silos in one process, with event sequences on one and observers on the other, and check that a reactor, a reducer and a projection work across it. A clustering benchmark suite compares one silo, two silos and two silos with split roles, and it runs on demand with no published results. Its silos share one machine, so it wouldn’t show ideal scaling even when it runs. Chronicle can run as a multi-node Orleans cluster, and what a second node adds in throughput hasn’t been measured and published.

What the benchmarks measure

A single-node benchmark suite runs every night on a GitHub-hosted Ubuntu runner, against the development container with MongoDB inside it. The series on the benchmarks page ends at a run from August 2026, and the nightly runs since then haven’t been added to it. Each benchmark runs one to three warmups and five or ten measured iterations. The last entry in that series gives these mean times:

Benchmark	Mean
Append one event	8.98 ms
Append 10 / 100 / 1,000 events in one `AppendMany`	12.9 / 34.1 / 239.9 ms
Read a materialized instance, 10 / 100 events of history	4.30 / 3.49 ms
Read a passive instance, 10 / 100 events of history	7.77 / 11.67 ms
Replay a projection over 1,000 / 10,000 events	328.9 / 1,508.0 ms

One AppendMany of ten events takes 12.9 ms, against 8.98 ms for a single append. In these runs a materialized read didn’t grow with the history, and a passive read did.

The limits are as specific as the numbers. It’s one runner type on shared hosted hardware, and per-commit numbers from hosted runners are noisy. The observer benchmarks, projecting, reducing and reacting to events, append everything to one event source, so they never exercise partitions running in parallel, and their window includes the append and a completion poll that puts a floor of roughly 60 to 70 ms under every result. None of it is an events-per-second figure, and there are no benchmarks for comparing storage providers, for job step parallelism, or for what happens when a queue fills up.

Tuning a production deployment

Start with the deployment and restore requirements in Running Chronicle and a Cratis application in production, and make every observer idempotent before tuning delivery.

The tuning knobs are observers.subscriberTimeout, observers.maxRetryAttempts, events.queues and jobs.maxParallelSteps. None of them comes with a sizing rule. Chronicle’s configuration examples show 8 queues and a 5-second subscriber timeout as illustrations, and the right values for a given system come from measuring that system.

Watch the Author replay as a job, allow for the batches a crash can repeat, and measure what a second server adds before relying on it.

From script to stage · Part 18: Running Chronicle and a Cratis application in production

Wed, 30 Sep 2026 09:18:00 GMT

Cratis: from script to stage, and the long run · Part 18 of 26

A Compose file that runs Chronicle happily on cratis/chronicle:latest-development stops at startup when you change the tag to latest. The development images generate their own TLS certificate and fall back to throwaway keys for the built-in OAuth authority, and latest-development bundles a database as well. The production image does none of that, and no environment variable changes it back, because the production code paths are chosen by a compile-time symbol that only the development builds define.

On a laptop, the author feature ran on one development container. In production it runs on a kernel that someone configures and keeps running, next to an application that has to trust the right server and report what it does.

What the production image won’t start without

The production guide names three settings the production path needs, and a missing certificate stops it at startup. Every setting can come from /app/chronicle.json or from an environment variable with the Cratis__Chronicle__ prefix, and the environment variable wins when both are set:

docker run -d \
  --name chronicle \
  -p 35000:35000 \
  -v /path/to/chronicle.json:/app/chronicle.json:ro \
  -v /path/to/certs:/certs:ro \
  -e Cratis__Chronicle__Storage__ConnectionDetails='mongodb://mongodb:27017/?directConnection=true' \
  -e Cratis__Chronicle__Tls__CertificatePath=/certs/chronicle.pfx \
  -e Cratis__Chronicle__Tls__CertificatePassword="$CHRONICLE_CERTIFICATE_PASSWORD" \
  -e Cratis__Chronicle__EncryptionCertificate__CertificatePath=/certs/encryption-cert.pfx \
  -e Cratis__Chronicle__EncryptionCertificate__CertificatePassword="$ENCRYPTION_CERTIFICATE_PASSWORD" \
  cratis/chronicle:19.23.1

The storage connection defaults to an empty string, so there’s nothing to fall back to. An unset storage type means MongoDB. The TLS certificate is for port 35000, where gRPC for the clients and HTTP/1.1 for the REST API, the Workbench, OAuth and the health endpoint share one TLS port. The encryption certificate protects the signing and encryption keys of the internal OAuth authority. You can do without it only when that authority isn’t in use, either because you’ve pointed Chronicle at an external authority or turned the oAuthAuthority feature off, and encrypting a value later still needs a certificate. A certificate path that points at a missing file stops startup with EncryptionCertificateFileNotFound, so a typo can’t leave you running without one.

Pin the version, as above. latest floats, and so does the image Aspire picks for you. In publish mode, AddCratisChronicle() selects the production image whatever else you configure, so it needs WithTlsCertificate and WithEncryptionCertificate before it’ll start, and WithImageTag to stop two deployments of the same AppHost from landing on different versions.

The production image is built on a chiseled .NET base with no shell, curl or wget. A Docker HEALTHCHECK runs inside the container, so it fails every time and reports a healthy Chronicle as unhealthy. Probe /health from your orchestrator instead. If the prober can’t handle the TLS certificate, Cratis__Chronicle__Health__Port=8080 and Cratis__Chronicle__Health__Tls=false give it a plain HTTP health port. That port serves the other HTTP/1.1 endpoints as well unless you set health.exclusive, so keep it internal.

Choosing where the events live

Chronicle has pluggable storage providers: MongoDB, which is the default, PostgreSQL, SQL Server and SQLite. The kernel creates and migrates its own tables on the SQL databases, so there’s no schema for you to run. What changes with the choice:

Storage type	What to know
`MongoDB`	Must run as a replica set, a single-node one included, because appends use transactions. Read models are documents. The only storage that multi-node clustering keeps its membership in.
`PostgreSql`	Read models become tables, one per read model type, with a typed column per scalar property and a `jsonb` column for each collection or nested object.
`MsSql`	The same table layout, with `nvarchar(max)` for the JSON columns.
`Sqlite`	Separate database files for stores and namespaces, with read models in their own files. Each uses WAL mode with a 30-second busy timeout because many grains write to it at once. The JSON columns are `TEXT`.
`InMemory`	Not durable, and scoped to one process. For tests and throwaway environments.

The MongoDB in the production guide’s Compose file has no authentication and is published on loopback only. Authentication and TLS for the database, or a managed replica set, are yours to add.

On the SQL databases, the SQL sink creates each read model’s table on first use and updates only the columns that changed. It doesn’t create the indexes a read model declares with [Index]. Only the MongoDB sink does that today, so an [Index] on the Author read model isn’t created on PostgreSQL, and you add that index to the table yourself.

The sink is chosen by the client, separately from the kernel’s storage, and every Chronicle client registers read models against the MongoDB sink unless you tell it otherwise. With the kernel on PostgreSQL, SQL Server or SQLite, set the default sink to SQL in the application as well:

using Cratis.Chronicle.Sinks;

builder.AddCratisChronicle(configureOptions: options =>
{
    options.DefaultSinkTypeId = WellKnownSinkTypes.SQL;
});

import io.cratis.chronicle.ChronicleOptions
import io.cratis.chronicle.connection.ChronicleConnectionString
import io.cratis.chronicle.sinks.WellKnownSinkTypes

fun optionsWithSqlSink(): ChronicleOptions = ChronicleOptions(
    connectionString = ChronicleConnectionString.parse("chronicle://my-server:35000"),
    defaultSinkTypeId = WellKnownSinkTypes.SQL
)

import io.cratis.chronicle.ChronicleOptions;
import io.cratis.chronicle.connection.ChronicleConnectionString;
import io.cratis.chronicle.sinks.WellKnownSinkTypes;

class ChronicleSqlSinkOptions {
    ChronicleOptions create() {
        return new ChronicleOptions(ChronicleConnectionString.Companion.parse("chronicle://my-server:35000"), "Unknown", WellKnownSinkTypes.SQL);
    }
}

import { ChronicleOptions, WellKnownSinks } from '@cratis/chronicle';

function createChronicleOptionsSqlSink(): ChronicleOptions {
    return ChronicleOptions.fromConnectionString('chronicle://my-server:35000', {
        defaultSinkTypeId: WellKnownSinks.SQL
    });
}

defmodule MyApp.ChronicleSqlSink do
  @moduledoc false

  def start_link do
    children = [
      {Chronicle.Client,
       connection_string: "chronicle://my-server:35000", default_sink_type_id: :sql}
    ]

    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

The storage choice also decides whether you can add a second node. The clustering types are Localhost, the default, and MongoDB, which keeps cluster membership in MongoDB storage. PostgreSQL, SQL Server and SQLite have no clustering type of their own, so a cluster of more than one node needs MongoDB storage. The default has a trap of its own, two servers pointed at one database forming two clusters without an error, and Chronicle jobs, scale and performance walks through it.

We’d pick MongoDB, since both a second node and declared indexes need it, unless your organization already runs one of the SQL databases and doesn’t run MongoDB. SQLite fits one kernel on one machine.

Who gets to connect

Authentication is on by default, served by Chronicle’s built-in OAuth authority unless you configure an external one. The production image creates the administrator without a password and lets the first person to open the Workbench set it. Keep port 35000 unreachable until that’s done, or supply the password from your secret store through the Cratis__Chronicle__Authentication__AdminUser__* settings.

Services connect as applications, which are OAuth clients with a client ID and secret. You can create them in the Workbench, with cratis chronicle applications add, or declare them in the clients section of the configuration, where the secret is hashed when it loads. A declared application whose client ID already exists is skipped, so changing its secret in the configuration doesn’t change the one Chronicle holds. Removing it in the Workbench or with the CLI lasts until the next restart, when the kernel creates it again from the configuration, so to revoke a declared application, take it out of the configuration as well.

The application puts its own credentials in the connection string, chronicle://author-service:<secret>@chronicle.internal:35000. Leave them out and the .NET, Java, Kotlin and TypeScript clients fill in the well-known development credentials, chronicle-dev-client and chronicle-dev-secret. The development images create an application with those credentials in storage at startup and the production image doesn’t, so a production kernel refuses them, unless its storage was used by a development image before and still holds that application. If it does, remove chronicle-dev-client from the production store. In the Workbench it’s on the Applications page under System, and from a terminal you pass its ID from cratis chronicle applications list to cratis chronicle applications remove. If the clients section of the configuration declares it, take it out there too, or the kernel creates it again at the next restart. The Elixir client fills nothing in and connects without authentication, and a kernel with authentication on accepts that connection but never lets the client finish registering.

Chronicle has no operator roles. The kernel’s authorization asks one question, whether the caller is authenticated, so every user and every application you create can do everything the API and the Workbench allow. Create a user for each person and an application for each service, so you can revoke one without touching the rest.

The client side has a default to change too. Every Chronicle client uses TLS unless told otherwise, and by default it accepts any server certificate, which is what lets a development client talk to the self-signed certificate of the development image. Against a production kernel, turn validation on with skipTlsValidation=false:

using Cratis.Chronicle;

public static class ChronicleTlsOptions
{
    public static ChronicleOptions Create() =>
        ChronicleOptions.FromConnectionString(
            "chronicle://my-server:35000?skipTlsValidation=false");
}

import io.cratis.chronicle.ChronicleOptions

fun optionsWithTlsValidationEnabled(): ChronicleOptions =
    ChronicleOptions.fromConnectionString("chronicle://my-server:35000?skipTlsValidation=false")

import io.cratis.chronicle.ChronicleOptions;

class ChronicleTlsOptions {
    ChronicleOptions create() {
        return ChronicleOptions.fromConnectionString("chronicle://my-server:35000?skipTlsValidation=false");
    }
}

import { ChronicleOptions } from '@cratis/chronicle';

function createOptionsWithTlsValidation(): ChronicleOptions {
    return ChronicleOptions.fromConnectionString('chronicle://my-server:35000?skipTlsValidation=false');
}

defmodule MyApp.TlsValidationEnabled do
  @moduledoc false

  def connection_string do
    Chronicle.Connections.ConnectionString.parse(
      "chronicle://my-server:35000?skipTlsValidation=false"
    )
  end
end

Two settings look like shortcuts and aren’t meant for a network. auth=none in a .NET connection string only works against a server with authentication turned off, and a server like that answers every call from anyone who can reach its port, with every event and every read model. It exists for a kernel embedded next to its own client in one throwaway process. TLS on the server can be switched off only for a private backend behind an HTTPS proxy that forwards everything as cleartext HTTP/2, and that setup needs an external authority, because the internal one doesn’t serve its token endpoint over cleartext. The .NET client’s client-credentials mode can’t use an external authority, so it doesn’t work behind such a proxy.

Values in events that are secret without being personal, such as a partner’s API key, get [Encrypted], which encrypts them at rest under keys that no erasure can reach. Security explains how it differs from [PII], and Personal data in an event log covers the personal side.

What you can watch

The kernel is instrumented whether or not anything collects it. Set OTEL_EXPORTER_OTLP_ENDPOINT and it exports OpenTelemetry metrics, traces and logs over OTLP, with OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_HEADERS and OTEL_SERVICE_NAME (default Chronicle) for the rest. Without the endpoint, nothing leaves the process.

The metrics come from four meters: Cratis.Chronicle, Microsoft.Orleans, Grpc.AspNetCore.Server and the .NET runtime. The server also records further internal counters that the configuration reference doesn’t list.

The application has telemetry of its own. In .NET, Arc publishes command, query and identity spans under the Cratis.Arc source, and the Chronicle client publishes its append, unit-of-work, reactor and reducer spans under Cratis.Chronicle.Client. Neither reaches an exporter until the application subscribes to it. The Chronicle client’s ASP.NET Core package, Cratis.Chronicle.AspNetCore, has one helper for this, AddCratisChronicleInstrumentation(), which registers the client’s source on the tracer. Arc has no counterpart and no single call sets up both, so the application names Cratis.Arc itself. One that registers only Cratis.Arc never exports a client append span:

using Cratis.Chronicle.AspNetCore.OpenTelemetry;
using OpenTelemetry;
using OpenTelemetry.Trace;

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource("Cratis.Arc")
        .AddCratisChronicleInstrumentation()
        .AddAspNetCoreInstrumentation())
    .UseOtlpExporter();

Arc for Kotlin and Java reports through Micrometer once you add its observability starter. The Chronicle client for the JVM reports spans under the io.cratis.chronicle scope through whatever OpenTelemetry the application registered globally, with no setup of its own.

dependencies {
    implementation("io.cratis:arc-observability-spring-boot-starter:7.7.0")
}

dependencies {
    implementation("io.cratis:arc-observability-spring-boot-starter:7.7.0")
}

The Chronicle TypeScript client reports spans and metrics under @cratis/chronicle through the OpenTelemetry API, so starting the Node SDK before the client is enough.

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({ traceExporter: new OTLPTraceExporter() });
sdk.start();

Arc’s pipelines in .NET emit spans and no counters, so command and query rates come from the spans. Its Cratis.Arc meter records MongoDB client metrics.

Where a trace stops

Follow a RegisterAuthor command through a trace in .NET and it stops at the append. The HTTP request, Arc’s cratis.arc.command.execute span and the client’s client.event_sequence.append span nest in one trace, and the kernel receives the append through ASP.NET Core, which reads the trace context the call carries. From there the event is stored, and nothing that carries it on to observers carries the trace with it. The kernel’s cratis.chronicle.observer.handle span runs in a separate trace, and client.reactor.handle and client.reducer.handle start with no parent and no link back to the command. The correlation ID travels with the event, but it’s an ID, and a tracing backend can’t join spans on it. The JVM client’s tracing guide says the same of its own spans. The gap is Cratis/Chronicle#4416.

In .NET, the command, the client append and the kernel append share a trace; observers start new ones.

For the author feature, that means a slow registration shows up in a trace up to the append, and the projection that updates the Author list shows up on its own. The design discussion about carrying the trace past the append, and about a one-line setup and domain-named spans, is open in Cratis/Chronicle#4417, Cratis/Arc#2914 and Cratis/Arc#2915. None of it has shipped.

Backups that can be restored

A Chronicle deployment can’t be restored from a database backup alone. The database carries the event store’s data, the Data Protection key ring, webhook definitions with their encrypted credentials, and OAuth applications and tokens. It can’t carry the certificates that decrypt the key ring, and those have to be the ones that were in use when the backup was taken.

A database backup is the second of three things to restore.

Restore the certificate ring first, in the shape it had at backup time, including every previous certificate that was live then. Restore the storage second. The compliance key store comes third, when one is configured, restored to the storage’s point in time and never to an earlier one. The fence that records an erasure is kept in the key store beside the keys, so a key store restored from earlier than the storage still holds the key of anyone erased in between, with no fence to refuse it. Their personal data reads again, and an erasure already reported as complete is undone. The same key store is missing the keys of subjects created since its backup, and their personal data reads back as empty strings, the same as a completed erasure. Restored from later than the storage, it keeps the deletions and fences of the erasures made in between, and those erasures hold. Personal data in an event log covers the key store itself. Then start one node and read GET /diagnostics/encryption-certificates. A key reported with the role Retired means the ring is missing a certificate the restored data needs.

Nothing about a wrong order reports itself at restore time. The data is there, and nothing can read it. So a certificate stays in the backup set for as long as the oldest backup you’d still restore, which is longer than it stays in the ring. Losing the certificates can’t be recovered from.

Rotating the certificate is forward only. You make the new certificate active, list the old one under previous, restart every node with the same ring, and remove the old entry once the diagnostic shows nothing depends on it. Overwriting the file at the certificate path with a new key pair isn’t a rotation, and it makes everything the old one protected unreadable.

Upgrades

Chronicle raises its major version for a breaking change to any published surface, whether the wire contract, a .NET API or observable behavior, and Every major version lists what each boundary changed. Most boundaries are compile-time changes you fix once. Three concerned data already written, 6 to 7, 10 to 11 and 13 to 14, and skipping past one doesn’t skip its consequence. Before crossing one, take a backup of a kind you’ve already restored from once, and rehearse the upgrade on a copy. Two releases are there to step over, 14.0.0 and 17.0.0, where the .0.1 is the real start of the major.

Within a major, each build is checked against every released minor of that major, so a .NET client and a kernel that differ only in minor are expected to work together. The Java, Kotlin, TypeScript and Elixir clients have version numbers of their own. Across a major, upgrade the kernel and the clients together. The .NET, Java, Kotlin and TypeScript clients check at connect that their wire contract and the server’s are compatible, and a mismatch fails the connection. The Elixir client runs the check before it sends an append, and a mismatch fails the append. In .NET, skipCompatibilityCheck=true turns the check off, as a temporary escape hatch that trades a clear failure at connect for a less obvious one later.

The kernel upgrades its own stored state with patches it applies at startup, in version order, and only forward. Starting an older kernel against patched storage doesn’t undo them, so rolling back means restoring the backup you took before the upgrade. Upgrading doesn’t rewrite the events you’ve already appended.

Two operations don’t mix with a rolling upgrade. Finish the upgrade before you rotate the encryption certificate or change webhook credentials, because a credential written by an upgraded node can’t be read by one that isn’t. And while an erasure of personal data is in force, upgrade every node together, since a node from before the erasure fence can provision a key over it.

The author feature’s first day

Acme registers Jane Austen in the morning. Contoso registers her too, and both succeed, because the uniqueness constraint holds per event sequence and namespace, and each organization has its own namespace, as Tenancy and identity end to end sets up. When a second Acme librarian tries the same name, the kernel refuses the append.

The number to watch is failed partitions. If the projection behind the Author list throws for one author, that author’s partition stops and is retried, and every other author keeps updating. From a terminal, for Acme:

cratis chronicle diagnose -n acme
cratis chronicle failed-partitions list -n acme

Leave out -n and these commands look at the active context’s namespace, or Default when the context doesn’t set one, and Acme’s authors aren’t in Default. The Cratis CLI, from diagnose to llm-context follows a failed partition from diagnose to the retry, and Chronicle Workbench, screen by screen shows the same partition in the Workbench, labelled with the author’s ID.

The operator can’t go from that failed partition to the trace of the command that registered the author, because that trace stopped at the append.

From script to stage · Part 17: The Cratis CLI, from diagnose to llm-context

Wed, 30 Sep 2026 09:17:00 GMT

Cratis: from script to stage, and the long run · Part 17 of 26

cratis chronicle diagnose exits nonzero when the server is unreachable or when a failed partition exists. An observer that’s far behind the tail leaves the exit code at zero, and that’s deliberate.

The Cratis CLI inspects and diagnoses Chronicle from a terminal, full-screen workbench included, and it also hosts cratis new, cratis ai, cratis screenplay and cratis render.

Installing it

The release binaries for macOS and Linux, on arm64 and x64, are self-contained and need no runtime. The .NET tool needs the runtime its package declares, .NET 10 or later.

brew tap cratis/cratis && brew install cratis   # macOS and Linux
dotnet tool install -g Cratis.Cli                # or, with .NET 10+
cratis completions install

Against a Chronicle on your own machine there’s nothing to configure. The first run writes a default context pointing at chronicle://localhost:35000, and the first chronicle command asks which event store to use by default and remembers the answer. Other servers get contexts of their own, with cratis context create and cratis context set.

Completion asks the running server. cratis completions install sets it up for bash, zsh, fish or PowerShell, and pressing Tab after a command that takes an observer, a read model or an event type asks the live server what it has registered right now.

When a view stops updating

We built the CLI so you can ask the running system instead of comparing sequence numbers by hand. Start with diagnose. Run against a bookshop store (the sample is from an older server), it prints this:

❯ cratis chronicle diagnose

── Chronicle Diagnostics  14:18:21 ─────────────────────────────────────────────
  server:      chronicle://chronicle-dev-client:***@localhost:35100/
  event store: Bookshop  /  Default

  ✓  Connection            connected
  ✓  Server version        16.7.0
  ✓  Event stores          2 stores: System, Bookshop
  ✓  Observers             9 active
  ✗  Failed partitions     1 need attention  → cratis chronicle failed-partitions list
  ✓  Recommendations       none
  ✓  Event sequence        tail: 22

  ✗ Issues detected — review items above

The same summary from a current server, with the author feature’s store. The exit code is 3 while a partition has failed.

The failing row names the next command, and diagnose exits nonzero when failed partitions exist, so it works as a check in a script too. failed-partitions show then gives the exception and a short stack trace for each attempt, shown here trimmed:

FailedPartition: caadc869-1251-41d0-9063-6947eaf74043
Observer:        Bookshop.OverdueNotices
Partition:       978-0131177055
Attempts:        5

  --- Attempt at 2026-07-28T12:17:56.6680000+00:00 (Seq# 22) ---
  Exception has been thrown by the target of an invocation.
  smtp.bookshop.local: connection refused
  StackTrace:
    at System.Reflection.MethodBaseInvoker.InvokeWithFewArgs(…)
    at System.Reflection.RuntimeMethodInfo.Invoke(…)
    at Cratis.Chronicle.Reactors.ReactorInvoker.Invoke(Object content, EventContext eventContext)

The partition is a book’s ISBN, because that’s the event source ID the application uses. For us it would be the author’s ID. Failures are addressed by your own keys, so you can go straight from “this author is missing” to “this author’s partition failed, and here’s why”.

Behind that is Chronicle’s failure model. When one partition fails, it stops and is retried with backoff while every other partition keeps going. After the configured number of attempts it’s quarantined until someone looks. For a failed partition that isn’t quarantined, fix the cause, then ask the observer commands for exactly one more attempt:

cratis chronicle observers retry-partition Bookshop.OverdueNotices 978-0131177055 -y

A quarantined partition refuses an ordinary retry, as Year two explains. A quarantined observer also blocks retries, and the CLI exits nonzero with a suggestion when the kernel refuses. Even a success only says the retry started, so run diagnose again.

Retry the partition before you replay anything. observers replay is the bigger hammer. It reprocesses the observer from sequence zero and rebuilds its read model, and on a large store that takes time and costs something.

Inspect, fix the cause, retry one partition, inspect again.

The same loop in a terminal. The fix itself isn’t shown; a comment stands in for it.

The rest of the debugging kit depends on where you are:

In a terminal on a server. cratis chronicle workbench opens a full-screen terminal dashboard over the same connection. Ctrl+P searches observers, event types, projections, read models and failed partitions at once, which helps because “author” isn’t a name in one list. It’s a thread through five of them. Actions such as replaying an observer or retrying a partition sit in place, behind a confirmation dialog. Tab completion asks the live server for observer and read-model names.
In a browser. Chronicle Workbench, screen by screen covers the browser tool’s views, projection preview and permissions.
In your editor. Narrator, a VS Code extension we still treat as experimental, browses event stores, event types, read models and observers, and pages through events. It only reads.

Reading an observer row

cratis chronicle observers list is the table you’ll spend the most time in. From the same bookshop store:

Id                       Type        State   Quarantined  Next#  LastHandled#  Subscribed
Bookshop.Members         Reducer     Active  False        23     2             False
Bookshop.Books           Reducer     Active  False        23     10            False
Bookshop.BorrowedBooks   Projection  Active  False        23     18            False
Bookshop.OverdueBooks    Projection  Active  False        23     22            False
Bookshop.OverdueNotices  Reactor     Active  False        23     22            False

Two of its columns are easy to misread. Next# is the next sequence number the observer will look at, and LastHandled# is the last event it actually processed. The tail here is 22, so every observer with Next# 23 has read everything there is. Members last handled sequence 2 because nobody has registered as a member since, and nothing between 3 and 22 was addressed to it. Next# is how far an observer has read. LastHandled# is the last thing it cared about.

One more event moves the tail, Next# and LastHandled# by one. The register line stands in for registering a name in the app.

State is one of Active, Replaying, Suspended, Disconnected, Quarantined or Unknown. Disconnected means no client is attached, which usually means the application isn’t running. For a store whose application is stopped, that’s the normal state.

Past the first retry

Two flags go further than the loop above. failed-partitions show --detailed prints the full stack trace for every attempt, and failed-partitions list --observer narrows the list to one observer. The stuck-observer scenario puts them in order:

cratis chronicle diagnose
cratis chronicle failed-partitions show <OBSERVER_ID> <PARTITION> --detailed
cratis chronicle observers retry-partition <OBSERVER_ID> <PARTITION>

Inside Chronicle explains failure kinds, retry defaults and quarantine thresholds. failed-partitions show in CLI 3.21.0 prints the messages and stack trace, not the kind. Workbench shows the same failed partitions from the browser.

A quarantined observer needs observers clear-quarantine, or Clear quarantine on the browser Workbench’s Observers page. The terminal workbench has no key for it.

When the partition’s state is wrong and not merely stuck, observers replay-partition discards that partition’s state and rebuilds it, and leaves every other partition alone. It’s the step between one retry and a full replay.

Retry one partition, rebuild one partition, or rebuild the observer.

The loop is finished when diagnose shows no failed partitions and the observer’s Next# has reached the tail plus one. diagnose --watch --interval <seconds> keeps the summary refreshing while you wait, and diagnose -o json gives a pipeline the same summary with the exit code intact.

Every command that asks for confirmation defaults to No. In a script or another non-interactive shell, it fails with a validation error unless you pass --yes, so nothing in a pipeline replays an observer because a prompt went unanswered.

After changing a projection

A deployment can leave a replay recommendation, depending on the definition change and policy described in From event to read model.

A filed recommendation appears in recommendations list, in the Recommendations row of diagnose and on the Workbench’s Recommendations page. recommendations perform carries it out, which means replaying the observer, and recommendations ignore drops it. You can also replay directly, following Replay a projection:

cratis chronicle observers list --type projection -q
cratis chronicle observers replay <OBSERVER_ID>      # asks for confirmation
cratis chronicle diagnose --watch

The replay runs as a job, and jobs list and jobs get follow it. When it’s done, read-models instances, occurrences and snapshots show what the rebuilt Author read model holds. Jobs, scale and performance covers what the replay does in between.

The terminal workbench

cratis chronicle workbench exists for one situation in particular. The browser Workbench is served by the server, behind the server’s authentication, and you’re on a box you reached over SSH.

It has fifteen views: Overview on its own, then Observation (Observers, Failures, Jobs, Recommendations), Events (Event Sequences, Event Types), Projections (Projections, Read Models) and Server (Event Stores, Namespaces, Applications, Users, Identities, Subscriptions). The views refresh on an interval, and it reopens on the view you left.

The terminal workbench, from Overview to the palette.

The actions sit on keys in the view where they apply. R replays the selected observer, T retries and P replays a failed partition, S and U stop and resume a job, and A and I apply or ignore a recommendation. F filters the current view, and Ctrl+E and Ctrl+N switch event store and namespace.

The Failures view, with the retry and replay keys on its toolbar.

For the author feature, typing “author” into the Ctrl+P palette would bring up the projection’s observer, the AuthorRegistered event type, the projection declaration and the Author read model in one list, and picking one jumps to its view with the filter already applied.

Ctrl+P with “author”: five kinds of result in one list.

Each action opens a confirmation dialog that shows only its target. The event store and namespace are in the status bar, so read them and the target before confirming, because the dialog confirms whatever is selected. The terminal workbench covers observation and jobs. It has no screens for appending, revising or redacting events, and no projection editor.

Output for scripts

The CLI picks its output format from where it’s running. An interactive terminal gets a table, redirected output gets JSON, and NO_COLOR gets tab-separated plain text. -o table|plain|json|json-compact chooses explicitly, and -q prints only identifiers, for piping into the next command.

For anything automated, pick the format with -o and pin the CLI version the script was written against. The output formats are current behavior, and they aren’t declared as a stable machine contract between versions.

A command catalog for agents

Once the feature runs, an assistant that helps operate it needs to know which of its actions change anything. cratis llm-context prints the CLI’s command catalog as JSON, and every command states its effect, read-only, local, mutating or destructive, and whether it requires confirmation. An agent can tell observing commands from state-changing ones without keeping its own list. cratis init writes that catalog into context files for the tools you use, and you refresh it after upgrading. When the CLI recognizes it’s running under an agent tool, it defaults to compact JSON. Only the effect and confirmation fields are meant to stay stable between versions, so pin the CLI version if you rely on anything else.

The catalog marks each command’s effect, so an agent can tell observing from changing.

Besides the effects, the catalog lists every group, command, argument and option, with connection details and guidance on output formats. An effect is the strongest change a command can make, and an option such as --dry-run can lower it for one run but never raise it. The Chronicle commands in CLI 3.21.0 carry these effects:

Group	`read-only`	`mutating`	`destructive`
`observers`	`list`, `show`	`retry-partition`, `clear-quarantine`	`replay`, `replay-partition`, `remove`
`failed-partitions`	`list`, `show`
`jobs`	`list`, `get`	`stop`, `resume`
`recommendations`	`list`	`ignore`	`perform`
`events`	`get`, `tail`
`read-models`	`list`, `get`, `instances`, `occurrences`, `snapshots`
`users`, `applications`, `subscriptions`	`list`	`add`	`remove`
`diagnose`	`diagnose`

Every mutating and destructive command in that table also requires confirmation, except add. recommendations perform is classed destructive because it replays an observer. local covers commands that change only your machine, such as context set, login, init and ai install. cratis chronicle workbench is classed destructive as a whole, because actions can be run from inside it, and it confirms each one in its own dialog.

Some things aren’t in the catalog because the CLI can’t do them. No CLI command appends, revises or redacts an event, and there’s no jobs delete. cratis llm-context --schema prints the JSON Schema for the catalog itself, and effect should be parsed as a string, with any value an agent doesn’t recognize treated as a state change.

The label informs an agent, and it enforces nothing. An agent that can run cratis in a shell with production credentials can run observers replay there, whatever the catalog says. The confirmation default helps, since a non-interactive replay needs an explicit --yes. The Cratis AI corpus adds a guard that blocks the store-changing cratis chronicle commands it can see in an assistant’s shell commands, in Claude Code and Pi, the two assistants its hooks are wired for. AI across the stack covers the hooks, and Chronicle MCP, a separate way for an assistant to reach a running Chronicle.

cratis ai and the other groups

cratis ai installs the Cratis AI corpus, rules, skills, agents, prompts and hooks for building with Cratis, into a repository. The corpus is still in preview. It goes into .cratis/ai/ once, and each supported assistant (Claude Code, Codex, Copilot, Cursor, OpenCode and pi) gets a thin adapter that links back to that one copy. The selection is recorded in .cratis/ai.json and the installed files in a manifest with hashes. cratis ai install runs once per repository, cratis ai update re-synchronizes the recorded choice after that, and cratis ai uninstall removes the managed content you haven’t changed.

The profile is the choice that matters. cratis/application/* is for building an application on Cratis, and cratis/engineering/* is for working on a Cratis framework repository itself. install and update never touch a file you own, and they leave a managed file you’ve edited alone unless you pass --force. cratis ai status exits nonzero when managed files were modified locally, which makes it usable as a CI check. Getting started has the full selection.

The CLI doesn’t call a language model itself. cratis llm use stores model-provider settings, for Anthropic, OpenAI or a local model, that tools such as Prologue read.

Several other groups live in the same binary. cratis new scaffolds a project from the Cratis templates, in C#, Kotlin or Java, without a .NET SDK installed, and Getting started with Cratis, and the tools around it walks through it. cratis screenplay, cratis render and cratis run work on .play models and belong to the modeling tools in Screenplay and the experimental Stage and Scene. cratis prologue belongs to Prologue, experimental as well. cratis arc inspects the commands and queries a running Arc application has registered, and it doesn’t need Chronicle.

After fixing the missing author’s partition, use retry-partition for one more attempt and inspect the result. The catalog decides nothing about who runs that command. It tells a person or an agent, before they run it, that it changes the server.

From script to stage · Part 16: Chronicle Workbench, screen by screen

Wed, 30 Sep 2026 09:16:00 GMT

Cratis: from script to stage, and the long run · Part 16 of 26

Chronicle Workbench has nothing to install. The Chronicle server serves it on port 35000, the same TLS port your clients connect to, so starting Chronicle starts the Workbench with it.

Chronicle Workbench ships with Chronicle and runs locally in your browser. Once you’re authorized, it shows what the running Chronicle is doing, and previews how a projection will behave for the projection features it supports.

Say an author registers without an error and never appears in the list of authors. The command succeeded, so the event should be in the log, and the interesting part is what happened after the append. Most of the Workbench’s screens answer a piece of that.

Starting one locally

The quickest Workbench is the development image on your own machine, published on localhost only:

docker run --pull=always --rm -d --name chronicle \
  -p 127.0.0.1:35000:35000 \
  cratis/chronicle:latest-development
curl --insecure --fail --retry 30 --retry-all-errors --retry-delay 1 \
  https://localhost:35000/health

When the health check prints Healthy, open https://localhost:35000. The development image generates a self-signed certificate in memory, so the browser warns about it the first time. Log in as Admin with the password ChangeMeNow!. That account is built into the development images for local use, and a development image with those credentials shouldn’t be reachable from a staging or production network.

A production image behaves differently at exactly this point. It needs a real TLS certificate, or the server throws at startup. It also creates the administrator without a password, and the first person to open the Workbench sets one. Supply the initial password from your secret store through Authentication:AdminUser, or keep port 35000 unreachable until setup is done. The production guide covers the certificates and the rest of what that image needs.

Authentication is on by default, with Chronicle’s built-in OAuth authority unless you configure an external one. Setting authentication.enabled to false removes it altogether. There’s no login and no token endpoint, and every gRPC service and HTTP endpoint answers anonymously. That suits an instance embedded in one container or process, talking to its own client over loopback and thrown away with it, and nothing reachable as a server.

Store first, then namespace

Most screens belong to one event store and one namespace, and the address carries both. A few belong to the store as a whole, among them event types, projections and the list of namespaces. User and application management sits above any single store.

With Arc’s Chronicle integration, each tenant maps to its own namespace. The author who’s missing for tenant Acme is visible only in Acme’s namespace, so pick the store and the namespace before you read anything else. An empty page in the wrong namespace looks exactly like an empty page in the right one.

Is the event there?

The Sequences page is a query editor over an event sequence, with filters, saved queries and a detail view for each event. For the author feature, filter on AuthorRegistered and look for the author’s ID.

The event log of one namespace.

One event’s context, with a Content tab beside it.

If the event isn’t in the log, the problem sits on the write side, and the command result or the append result carries the reason. If it is there, the next question is who should have handled it.

Event types is one store-level list. Selecting a type opens a side panel with its schema and an Observers tab that lists the observers reading it, in every namespace. For AuthorRegistered, that list should include the projection behind the Author read model. An event type that no observer reads is recorded and then ignored, which is sometimes the intent and sometimes the bug.

Who should have handled it

The Observers page lists every observer in the namespace, projections, reducers and reactors alike. Each row has the observer’s ID, type, owner and state, the next sequence number it will look at and how many events it has handled.

Both rows read Active. The reactor has a failed partition, and the list doesn’t show it.

An observer’s position doesn’t say whether it’s healthy, because one that has stopped consuming looks exactly like one with nothing to do. The Failed partitions page answers that.

The observer’s detail view has a connected clients section in its Summary tab, with each client’s connection, type, version, machine, process ID and process. When a client was last seen is on the Connected Clients page. An observer with no connected client has nobody to deliver events to. That’s the normal state while the application is stopped, and the first thing to check when it’s supposed to be running.

Why it failed

When a partition fails, Chronicle stops that partition and retries it with backoff, and the observer’s other partitions carry on. A partition is the events of one event source, so for the author feature it’s one author, and the failed partition is labelled with the author’s ID. You can go straight from “this author is missing” to the partition that holds the reason.

The Failed partitions page lists each one with its status, the partition, the number of attempts and the last attempt, and it has a detail panel per partition. Status says whether the partition has been quarantined. When the status value is missing, the page shows Unknown, and that’s a gap in what the page knows about the partition. It doesn’t mean the partition is fine.

Inside Chronicle explains the failure kinds that separate a handler bug from congestion. The detail panel lists each attempt’s time, sequence number, messages and stack trace. As of Chronicle 19.23.1 it doesn’t show the kind.

A failed partition’s detail: one entry per attempt, with its messages and stack trace.

The kind of an attempt separates a bug from congestion.

The retry policy and the timeout exception to observer quarantine are covered in Inside Chronicle.

The page itself has one action, Retry, which asks for one more attempt at that partition. Fixing the cause comes first, because a retry against the same bug fails the same way.

Fix the cause, press Retry, and the partition leaves the list.

What the view actually holds

The Read models page lists the read-model definitions in the namespace, their occurrences by generation, and a paged list of the instances in each. For the missing author, look for the author’s ID among the Author instances. When an instance exists but holds old content, the time machine shows the snapshots of that one instance, so you can see how its state got to where it is.

The instances of a read model in one namespace.

From one event to the read-model instance built from it.

Projection definitions live at store level, on the projections page, with an editor and a preview. The preview shows how a projection will behave for the features it supports, so a change to the Author projection can be tried there first, within what the preview covers. What happens when a changed definition is deployed, and why Chronicle sometimes replays and sometimes only recommends it, is in Jobs, scale and performance.

A projection’s declaration in the editor.

Around the edges

The dashboard gives key figures, a distribution of events by type and a breakdown by namespace. The Jobs page shows replays, catch-ups, migrations and failed-partition retries with their type, status and progress. The Recommendations page shows the replays Chronicle has filed for a person to decide on, each with a name, a description and when it occurred.

The other store-level pages aren’t on the missing author’s route: read-model types, known identities, webhooks, external services, captures and a page that seeds events into a store.

Above the stores, the Servers page lists each server’s address, status, CPU and memory. It’s where a cluster with more than one node shows up, and it doesn’t show which node runs which partition. The other system screens list users, OAuth applications and connected clients, and development builds add a page of development tools.

The Workbench’s main screens, and which ones carry actions.

Screens that change things

Several screens have buttons that change the store. On Sequences you can append an event, revise one, or redact a single event or every event of one event source. Observers has Replay, Clear quarantine and Remove. Jobs has Stop, Resume and Delete. On Recommendations, Perform replays the observer the recommendation names, and Ignore drops it. The seed-data page writes events, the projections page saves definitions, the system screens add and remove users and OAuth applications, and the store-level pages remove webhooks and external services and stop or delete captures.

Some of those buttons reach further than they look. Removing an observer is refused while any client is subscribed to it in any namespace. Once it goes through, it applies to every namespace and leaves the read-model data where it is, and if the observer registers again later, it replays from the start of the log. A replay rebuilds from sequence zero, which on a large store takes time. A revision keeps the original next to the correction, and redaction replaces an event’s content with a marker in the same slot. Year two goes through what each kind of correction means.

The Workbench is built for looking at a running Chronicle and previewing projections. It isn’t a full administration console, and nothing about its buttons makes a change on a production store reviewed or safe. Behind the screens there’s also no role model. Anyone who can sign in gets every screen, the ones that change things included, and the password-change prompt on first login doesn’t restrict anything else they can call. Workbench has screens for revising and redacting events. Being able to open a tool or run a command isn’t permission to use it on a production system.

The browser or the terminal

The Workbench is served by the server, behind the server’s authentication. On a machine you reached over SSH, cratis chronicle workbench opens a full-screen terminal dashboard over the CLI’s connection instead. It has views for observers, failed partitions, jobs, recommendations, event sequences, event types, projections and read models, plus the server-level lists, and each action goes through a confirmation dialog. It has no screens for appending, revising or redacting events, and no projection editor. The Cratis CLI covers it with the rest of the CLI.

The CLI’s cratis chronicle diagnose reports failed partitions in one summary and names the next command to run. The two work well side by side. The terminal says that a partition failed, and the Workbench shows the observer, its clients and the instance it was supposed to update.

From VS Code, Narrator, which we still treat as experimental, browses the same stores and only reads.

Follow the missing author from the event on the Sequences page to the observers listed on its event type, then to the failed partition labeled with the author’s ID and the error its attempts recorded. The Author instance on the Read models page shows what the list was actually reading. The fix goes into the code, and whether anyone presses Retry afterwards, on a production system, is a decision for whoever runs that system.

From script to stage · Part 15: Arc gotchas: where a convention decides for you

Wed, 30 Sep 2026 09:15:00 GMT

Cratis: from script to stage, and the long run · Part 15 of 26

A validation rule that applies only sometimes on the server can apply every time in the browser. Arc’s proxy generator copies the rules it recognizes from a C# validator into the generated TypeScript, and it doesn’t copy When or Unless conditions. A rule that sat inside a condition can arrive on the client without it, and a form will then refuse input the server would have accepted.

Most of what Arc saves you comes from conventions. A namespace becomes a route, a validator becomes browser rules, a property becomes a field in the generated TypeScript. Each convention makes one decision in the place that owns it, and each has an edge that’s documented but easy to miss until it costs an afternoon.

Arc: commands and queries without the plumbing covers the pipeline and the proxies in general, and Validation all the way down follows a rule through every layer it can live in.

Validation that runs in two places

The server is where validation counts. For a command, Arc runs authorization first, then validation, from data annotations, FluentValidation validators and concept validators, and only then Provide() and Handle(). POST <command-route>/validate runs the same authorization and validation without calling the handler.

The browser gets a copy. At build time the proxy generator loads the compiled assembly, finds the validator for each command, creates an instance and inspects its rules, then writes the ones it can express into the generated TypeScript. In the Arc and React sample the idea title is a concept with a validator of its own:

public class IdeaTitleValidator : ConceptValidator<IdeaTitle>
{
    public IdeaTitleValidator() => RuleFor(_ => _.Value).NotEmpty().MaximumLength(72);
}

These rules run on the server only. Unlike the .NET generator described on this page, Arc for Kotlin doesn’t copy them into the generated TypeScript.

@Component
class IdeaTitleValidator : ConceptValidator<IdeaTitle> {
    override val conceptType: Class<IdeaTitle> = IdeaTitle::class.java

    override fun validate(concept: IdeaTitle): List<ValidationResult> = buildList {
        if (concept.value().isBlank()) add(ValidationResult.error("A title is required."))
        if (concept.value().length > 72) add(ValidationResult.error("A title can be at most 72 characters."))
    }
}

These rules run on the server only. Unlike the .NET generator described on this page, Arc for Kotlin doesn’t copy them into the generated TypeScript.

@Component
public final class IdeaTitleValidator implements ConceptValidator<IdeaTitle> {
    @Override
    public Class<IdeaTitle> getConceptType() {
        return IdeaTitle.class;
    }

    @Override
    public List<ValidationResult> validate(IdeaTitle concept) {
        var results = new ArrayList<ValidationResult>();
        if (concept.value().isBlank()) results.add(ValidationResult.error("A title is required."));
        if (concept.value().length() > 72) results.add(ValidationResult.error("A title can be at most 72 characters."));
        return results;
    }
}

@validator(IdeaTitle)
export class IdeaTitleValidator extends ConceptValidator<IdeaTitle> {
    constructor() {
        super();
        this.ruleFor(title => title.value).notEmpty().maxLength(72);
    }
}

and the generated command proxy carries one statement per rule:

this.ruleFor(c => c.title).notEmpty();
this.ruleFor(c => c.title).maxLength(72);

The copy covers a fixed set. From FluentValidation that’s NotEmpty, NotNull, EmailAddress, the length rules, Matches and the four numeric comparisons against constants. From data annotations it’s [Required], [EmailAddress], the length attributes, [Range], [RegularExpression], [Url] and [Phone]. Per member, an explicit FluentValidation validator wins, a concept validator’s rules add to it, and data annotations fill in only where neither contributed anything.

Everything else stays on the server. Must, MustAsync, custom validators and any check that needs a service are never turned into browser logic. The author feature’s name-uniqueness rule never reaches the browser either, because it’s a Chronicle constraint checked when the event is appended, as Rules that hold when you write explains. Comparisons between two properties and comparisons against a constant that isn’t a number, a date for example, aren’t projected. A .NET regular expression is copied as it is, so it has to mean the same thing in JavaScript.

Conditions are the sharp edge. When, Unless, rule sets, cascade behavior and severity that depends on runtime values aren’t reproduced. Say the author feature lets people register under a pen name, and the validator says PenName must not be empty When the author chose to use one. The browser can receive the notEmpty() rule without its condition and block every registration that leaves the pen name blank. A blocking result in the browser can stop the request, so the server never gets to say otherwise.

A few quieter cases pass the .NET build:

The generator runs the validator’s constructor. It prefers a parameterless one, and otherwise passes null for reference dependencies and defaults for values. If construction or reflection fails, it can extract no FluentValidation rules at all, and a green build is not proof that the rules were emitted.
A message built with a .WithMessage(x => ...) factory isn’t evaluated, so the browser shows its default message for that rule. A literal message is copied.
Rules at Error severity block in the browser by default. Warning and Info block only with [BlockOnValidationSeverity], and a severity decided at runtime is left out of the client so it can’t block by mistake. Extraction happens at build time, so a change to FluentValidation’s global default severity isn’t seen.
[CreditCard] emits a creditCard() call the client rule builder doesn’t implement, so the generated file fails TypeScript checking. Required.AllowEmptyStrings isn’t projected, and messages from resource files aren’t resolved.
On a positional record, the server’s data-annotations filter reads property attributes, not constructor-parameter ones. Write [property: Required].

After changing a validator, open the generated file, then try one accepted and one rejected value against both the form and the server. Never patch the generated validator. When a rule must stay server-only, write it in a form the generator doesn’t translate, a Must predicate for example. The browser rules are a convenience copy, and the server decides. Live UIs shows how forms use them, and the proxy boundary explains what crosses from C# into TypeScript.

One validator, two programs.

A folder the generator owns

Every generated TypeScript file starts with a header in the form // @generated by Cratis. Source: <type>. Time: <utc>. Hash: <sha256>, followed by a DO NOT EDIT banner. In incremental mode, that header decides what the generator may delete.

There are two ways to run the generator, and their defaults differ. The MSBuild integration keeps the output directory, updates it incrementally and skips a write when the content hash matches. The generator executable run directly deletes the output directory first, unless you pass --skip-output-deletion. You can make the build do the same:

<PropertyGroup>
    <CratisProxiesSkipOutputDeletion>false</CratisProxiesSkipOutputDeletion>
</PropertyGroup>

With that output behavior, the generator recursively deletes the entire output directory, handwritten files and indexes included, before it writes the proxies. Never point it at your frontend source root.

Incremental mode deletes too. After each run the generator scans the .ts files below its output path, finds the ones with valid generated metadata that this run didn’t produce, and removes them. That’s how renaming UpdateOrder to ModifyOrder gets rid of the old file. The scan covers the whole output tree, not one input assembly, so two independent generation runs writing into the same tree can each take the other’s proxies for orphans. CratisProxiesSkipFileIndexTracking is still forwarded by the build package, and the executable ignores it. There’s no supported way to turn orphan cleanup off.

Only files with the header are eligible for that cleanup, so a handwritten file in the same folder isn’t swept by it. Even so, incremental mode doesn’t guarantee to preserve a mixed source tree, and a separate cleanup phase for emptied directories can remove an index.ts. The generator treats index.ts differently from its other files. It never carries the header, because it’s a file you edit. The generator adds exports for the files it generated and removes exports whose target is gone, and it leaves exports for your own files for you to write.

Two side effects follow from the header. It embeds the generation time, so a full regeneration that deletes files defeats the hash check and can produce Git diffs for contracts that didn’t change. And tools can recognize generated files by it. The skip-generated-proxies processor in @cratis/eslint-plugin-arc skips linting them, and the Cratis AI write guard refuses to let an assistant edit them, as AI across the Cratis stack describes.

Arc’s recommendation is to “use a dedicated, generated-only directory with one generation owner.” The cratis template, from Getting started with Cratis, and the tools around it, and the Arc and React sample both do the opposite on purpose. They set CratisProxiesOutputPath to the project directory, write each proxy beside its C# source, run in incremental mode and rely on the header. It works, and it isn’t the recommended arrangement. In a project set up that way, full regeneration would delete the project folder, so leave CratisProxiesSkipOutputDeletion at true.

Give the generator a folder of its own.

Names that do the mapping

Several things in Arc and Chronicle are resolved by name, with defaults that are usually right. Each default is a decision made somewhere you may not be looking.

Routes are computed twice

A conventional route is the API prefix, the artifact’s namespace with a configured number of leading segments skipped, in kebab case, and the artifact’s name. A query uses its method name, not its read-model type, as the last segment. For namespace MyApp.Orders.Registration and command CreateOrder, with one segment skipped, the route is /api/orders/registration/create-order.

The generator and the server each compute that route from their own settings. The Arc and React sample sets both sides, in the project file and in Program.cs, and the generated client for its CaptureIdea command in Arc.React.Ideas.Board carries route = '/api/ideas/board':

<CratisProxiesSegmentsToSkip>2</CratisProxiesSegmentsToSkip>
<CratisProxiesSkipCommandNameInRoute>true</CratisProxiesSkipCommandNameInRoute>

cratisArc {
    endpoints {
        segmentsToSkip.set(2)
        includeCommandNames.set(false)
    }
}

cratisArc {
    endpoints {
        segmentsToSkip.set(2)
        includeCommandNames.set(false)
    }
}

arc-proxygenerator --project tsconfig.json --artifacts src --output src \
  --use-proxy-file-suffix --segments-to-skip 2 --skip-command-name-in-route

builder.AddCratisArc(options =>
{
    options.GeneratedApis.RoutePrefix = "api";
    options.GeneratedApis.IncludeCommandNameInRoute = false;
    options.GeneratedApis.SegmentsToSkipForRoute = 2;
});

cratis.arc.endpoints.route-prefix=api
cratis.arc.endpoints.include-command-name-in-route=false
cratis.arc.endpoints.segments-to-skip-for-route=2

cratis.arc.endpoints.route-prefix=api
cratis.arc.endpoints.include-command-name-in-route=false
cratis.arc.endpoints.segments-to-skip-for-route=2

const builder = ArcApplication.createBuilder({
    generatedApis: {
        routePrefix: 'api',
        includeCommandNameInRoute: false,
        segmentsToSkipForRoute: 2
    }
});

The build properties configure the generator only and don’t change the running application’s endpoints. IncludeCommandNameInRoute and IncludeQueryNameInRoute are the inverse of the generator’s skip properties, and both sides default to skipping no segments. The templates skip one and put the server side in appsettings.json. Change one side without the other and the generated client calls a route the backend doesn’t map.

With command-name skipping on, the generator restores command names when more than one command shares a namespace after skipping. A namespace with one command gets a route without the command’s name. Add a second command to that namespace and the first one’s generated route moves, from /api/orders/registration to /api/orders/registration/create-order. An explicit [Path] pins a route, and the generator uses it as written, without the API prefix.

The generator and the server have to agree.

Which stream a command appends to

A command that appends through Arc’s Chronicle integration needs an event source ID. ICanProvideEventSourceId wins if the command implements it. Otherwise Arc takes the first property that is an EventSourceId, derives from EventSourceId<T> or carries [Key], with no preference for the typed one, so a command should have exactly one candidate. If no property matches, a new EventSourceId is created so the append still succeeds. A command meant to add to an existing author’s stream then starts a new stream, and nothing reports an error.

Returning the identity with the event, as the cratis template’s Register command does with (SomeId, Registered), works only for a type that derives from EventSourceId. A raw Guid in the same tuple is just a response value, and the event goes to the fallback stream. The ARCCHR0010 analyzer flags that shape, and ARCCHR0002 flags a command with more than one candidate property.

An event’s name is its identity

[EventType] takes an optional ID, and without one the event type is identified by its type name:

/// <param name="id">Optional identifier of the event type, if not used it will default to the type name.</param>
/// <param name="generation"><see cref="EventTypeGeneration"/> represented as <see cref="uint"/>.</param>
public sealed class EventTypeAttribute(string id = "", uint generation = EventTypeGeneration.FirstValue) : Attribute

/**
 * @property id The UUID string identifier for this event type. If empty, the class simple name is used.
 * @property generation The generation number of this event type. Defaults to 1.
 */
annotation class EventType(
    val id: String = "",
    val generation: Int = 1
)

Java uses the Kotlin client’s @EventType annotation, and the class’s simple name is the identity when id is empty.

/**
 * - `@eventType()` -> uses class name as id, generation 1, tombstone false.
 */
export function eventType(): ChronicleClassDecorator;
export function eventType(id: string): ChronicleClassDecorator;
export function eventType(id: string, generation: number): ChronicleClassDecorator;

The Elixir client has no default: id: is required in use Chronicle.Events.EventType.

Rename AuthorRegistered and the events you append from then on carry the new identity, while the ones already stored keep the old one. Give an event that has to last an explicit ID. When you add a generation, put [EventTypeGenerationFor<T>] on the previous one. It takes the ID from the current generation’s own [EventType], so the two can’t drift apart the way hand-typed IDs on both can. Analyzer CHR0037 warns when the generations a migration names don’t resolve to the same event type differing only by generation. It looks at migrations, so a rename without one gets no warning from it. Year two goes further into changing events.

Projections and proxies match by name

Declarative projections map matching names by default. An event property and a read-model property map when their names match after the client’s serialization naming policy is applied and the value can be assigned to the read-model property. Where they differ, you write the mapping. An event a projection only counts, increments or adds from contributes nothing to that automatic mapping. From event to read model covers the rest of it.

The proxy generator collects the public properties declared directly on a command type, so a property inherited from a base record doesn’t become a field in the TypeScript. Field names are the C# names in camel case.

The tenant arrives by header name

In .NET, Arc’s header resolver reads the header named in Tenancy.HttpHeader, x-cratis-tenant-id by default, and a missing header gives an empty tenant:

var headerName = options.Value.Tenancy.HttpHeader;
return context.Headers.TryGetValue(headerName, out var tenantId) ? tenantId : string.Empty;

In Kotlin a missing or blank header gives no tenant (null), not an empty string.

context.header(options.headerName).toTenantIdOrNull()

Java uses the Kotlin implementation, HeaderTenantIdResolver, which gives no tenant (null) for a missing or blank header.

In TypeScript a missing header gives undefined, not an empty string.

if (source === TenantResolverType.Header) selected = request.headers.get(header) ?? undefined;

AuthProxy forwards the tenant it resolved as Tenant-ID, so Arc has to be told that name, with options.UseHeaderTenancy(...) in .NET, or the tenant never arrives. A resolver selects a tenant and doesn’t check that the user belongs to it. Tenancy and identity end to end follows the header from AuthProxy to a Chronicle namespace.

Spotting them early

What you see	The convention behind it	The fix
The form rejects input the server accepts	A condition wasn’t carried to the browser	Test both layers; keep conditional rules server-only
No client rule for a validator, and a green build	The validator’s constructor failed during extraction	Don’t call services while building rules, and check the generated file
A handwritten file is gone after a build	Full regeneration, or a second run into the same tree	One generated-only folder with one owner
A generated call hits a route the backend doesn’t map	Generator and server route settings disagree	Change `CratisProxies*` and `ArcOptions.GeneratedApis` together
A route moved after a new command	Command-name fallback in a shared namespace	Pin important routes with `[Path]`
Events land in a new stream	No property matched the event source ID convention	One unambiguous `EventSourceId` or `[Key]` property, or return an `EventSourceId`-derived identity
New events carry a different type after a class rename	Event type identity came from the type name	An explicit `[EventType]` ID on events that last
Every request gets an empty tenant	The header name isn’t the one the proxy sends	`UseHeaderTenancy` with the proxy’s header

This part was checked against Arc v22.42.0 and Chronicle v19.25.1; other parts retain the versions they were checked against. The pages linked in each section have the complete rule lists. Before you rely on the browser to reject anything, read the validation page, and Validation all the way down for what each layer behind the browser holds.

Previous: Part 14 — Year two
Next: Part 16 — Chronicle Workbench, screen by screen

From script to stage · Part 14: Year two

Wed, 30 Sep 2026 09:14:00 GMT

Cratis: from script to stage, and the long run · Part 14 of 26

When a Chronicle client appends an event in the old shape of its type, the kernel stores the new shape next to it. Append the new shape and the kernel stores the old one as well, translated back. Two services written a year apart can share an event type, each reading the generation it was built against, and nobody runs a migration script over the store.

That’s one of four kinds of change a system meets after launch. Take a made-up but ordinary year for the author feature and the book catalog beside it. The catalog team wants each book’s subtitle in a field of its own. Someone wants a new list of authors on a screen that didn’t exist at launch. Support finds one author registered with a misspelled name. And the reactor that sends welcome mail has stopped on one author and stays stopped.

Four kinds of change

A year in, four kinds of change show up that look alike: a new shape for an event, a new view over old events, a correction to something recorded, and a processor that stopped. Chronicle has a separate mechanism for each, so each is an operation you choose instead of a script you write against the store.

Four kinds of change, and which one touches the log.

A new generation changes how an event is represented and leaves the stored fact as it was. A new view only touches derived data. A correction is the one change that alters what the log shows. That can reach one event, an event source or a subject, depending on the operation. A stopped processor is about how far an observer has got in the log, and nothing stored is wrong at all. Treat the misspelled name like a new view and you end up replaying projections that were fine. Treat the stuck reactor like a correction and you touch the log to fix a mail server.

A new shape for an event

Chronicle keeps generations of an event type side by side. An event type is identified by a stable id, and a new shape is a new generation of that same id. In the .NET client, the current generation carries the id and its generation number, and the previous generation points at the current one:

using Cratis.Chronicle.Events;

// Generation 2 (current) — the subtitle has a property of its own
[EventType("book-cataloged", generation: 2)]
public record BookCataloged(BookTitle Title, BookSubtitle Subtitle);

// Generation 1 (original) — marked as a previous generation of the current record above,
// instead of carrying its own [EventType]
[EventTypeGenerationFor<BookCataloged>(1)]
public record BookCatalogedV1(BookTitle Title);

The Kotlin client repeats the explicit id on every generation.

import io.cratis.chronicle.events.EventType

// Generation 2 (current) - the subtitle has a property of its own
@EventType(id = "book-cataloged", generation = 2)
data class BookCataloged(val title: BookTitle, val subtitle: BookSubtitle)

// Generation 1 (original) - same explicit id as the current generation, only the generation differs
@EventType(id = "book-cataloged", generation = 1)
data class BookCatalogedV1(val title: BookTitle)

The Java client repeats the explicit id on every generation.

import io.cratis.chronicle.events.EventType;

// Generation 2 (current) - the subtitle has a property of its own
@EventType(id = "book-cataloged", generation = 2)
record BookCataloged(BookTitle title, BookSubtitle subtitle) {}

// Generation 1 (original) - same explicit id as the current generation, only the generation differs
@EventType(id = "book-cataloged", generation = 1)
record BookCatalogedV1(BookTitle title) {}

The TypeScript client repeats the explicit id on every generation.

import { eventType } from '@cratis/chronicle';
import { field } from '@cratis/fundamentals';

// Generation 2 (current) — the subtitle has a property of its own
@eventType('book-cataloged', 2)
class BookCataloged {
    @field(BookTitle) readonly title: BookTitle;
    @field(BookSubtitle) readonly subtitle: BookSubtitle;

    constructor(title: BookTitle, subtitle: BookSubtitle) {
        this.title = title;
        this.subtitle = subtitle;
    }
}

// Generation 1 (original) — same id, generation 1, kept only so the migration below can
// upcast from it. It is not the "current" shape of the event any more.
@eventType('book-cataloged', 1)
class BookCatalogedV1 {
    @field(BookTitle) readonly title: BookTitle;

    constructor(title: BookTitle) {
        this.title = title;
    }
}

The Elixir client repeats the explicit id on every generation.

defmodule MyApp.Events.BookCataloged do
  use Chronicle.Events.EventType, id: "book-cataloged", generation: 2

  defstruct title: %MyApp.BookTitle{}, subtitle: %MyApp.BookSubtitle{}
end

defmodule MyApp.Events.BookCatalogedV1 do
  use Chronicle.Events.EventType, id: "book-cataloged", generation: 1

  defstruct title: %MyApp.BookTitle{}
end

In the .NET client, the older record has no id of its own, and that’s deliberate. Its event type id is resolved from the current type. A previous generation that simply leaves the id out would fall back to its CLR name and quietly become a different event type, which is the trap this shape closes. The older style, with the same explicit id string on every generation and a different generation: value, still works, and it’s the style the other clients use. The naming rule behind that trap is covered in Events are facts.

You declare a migration between adjacent generations. Upcast describes how the old shape becomes the new one, and Downcast describes the way back:

public class BookCatalogedMigration : EventTypeMigration<BookCataloged, BookCatalogedV1>
{
    public override void Upcast(IEventMigrationBuilder<BookCataloged, BookCatalogedV1> builder) =>
        builder.Properties(pb => pb
            .Split(m => m.Title, e => e.Title, ": ", SplitPartIndex.First)
            .Split(m => m.Subtitle, e => e.Title, ": ", SplitPartIndex.Second));

    public override void Downcast(IEventMigrationBuilder<BookCatalogedV1, BookCataloged> builder) =>
        builder.Properties(pb => pb
            .Combine(m => m.Title, ": ", e => e.Title, e => e.Subtitle));
}

The Kotlin client takes property references and records their names as written.

class BookCatalogedMigration :
    EventTypeMigration<BookCataloged, BookCatalogedV1>(
        BookCataloged::class,
        BookCatalogedV1::class
    ) {
    override fun upcast(builder: EventTypeMigrationBuilder<BookCataloged, BookCatalogedV1>) {
        builder
            .split(BookCataloged::title, BookCatalogedV1::title, ": ", 0)
            .split(BookCataloged::subtitle, BookCatalogedV1::title, ": ", 1)
    }

    override fun downcast(builder: EventTypeMigrationBuilder<BookCatalogedV1, BookCataloged>) {
        builder.combine(
            BookCatalogedV1::title,
            ": ",
            BookCataloged::title,
            BookCataloged::subtitle
        )
    }
}

The Java client takes property names as strings and records them as written.

class BookCatalogedMigration
        extends EventTypeMigration<BookCataloged,
                                   BookCatalogedV1> {
    BookCatalogedMigration() {
        super(BookCataloged.class, BookCatalogedV1.class);
    }

    @Override
    public void upcast(EventTypeMigrationBuilder<BookCataloged,
                                                 BookCatalogedV1> builder) {
        builder
            .split("title", "title", ": ", 0)
            .split("subtitle", "title", ": ", 1);
    }

    @Override
    public void downcast(EventTypeMigrationBuilder<BookCatalogedV1,
                                                   BookCataloged> builder) {
        builder.combine("title", ": ", "title", "subtitle");
    }
}

The TypeScript client takes property names as strings, typed as keys of the event class.

@eventTypeMigration(BookCataloged, BookCatalogedV1)
class BookCatalogedMigration implements IEventTypeMigration<BookCataloged, BookCatalogedV1> {
    upcast(builder: IEventMigrationBuilder<BookCataloged, BookCatalogedV1>): void {
        builder.properties(propertyBuilder => propertyBuilder
            .split('title', 'title', ': ', 0)
            .split('subtitle', 'title', ': ', 1));
    }

    downcast(builder: IEventMigrationBuilder<BookCatalogedV1, BookCataloged>): void {
        builder.properties(propertyBuilder => propertyBuilder
            .combine('title', ': ', 'title', 'subtitle'));
    }
}

The Elixir client takes property names as atoms or strings and writes a snake_case name in camelCase. Migrations need cratis_chronicle 3.8.1 or later when the event modules compile separately; on an earlier version, require both event modules at the top of the migration.

defmodule MyApp.Migrations.BookCatalogedMigration do
  use Chronicle.Events.Migration,
    from: {MyApp.Events.BookCatalogedV1, generation: 1},
    to: {MyApp.Events.BookCataloged, generation: 2}

  alias Chronicle.Events.MigrationBuilder

  @impl true
  def upcast(builder) do
    builder
    |> MigrationBuilder.split_property(:title, :title, ": ", 0)
    |> MigrationBuilder.split_property(:title, :subtitle, ": ", 1)
  end

  @impl true
  def downcast(builder) do
    MigrationBuilder.combine_properties(builder, [:title, :subtitle], :title, ": ")
  end
end

The builder has a small vocabulary. Split and Combine handle the title, RenamedFrom covers a renamed property and DefaultValue fills a new one. MapValues translates values, applies the map forward and inverts it on the way back. Values the map doesn’t mention pass through. If two old values collapse onto one new value, the way back takes the first pair you declared, so a map like that forces you to choose what the reverse means. MapValues exists in the C# client only. Migrations run on the content after Chronicle has encrypted personal data, so a migration that splits, combines or maps a value marked [PII] works on its ciphertext (Cratis/Chronicle#4456).

In the .NET client, the property expressions are typed, and they resolve to the JSON names Chronicle stores, [JsonPropertyName] first and then the client’s naming policy. An expression that points at nothing is rejected at registration with InvalidMigrationPropertyForEventType. The other clients don’t check the names at registration. Adding or removing an optional property still needs a migration class, with no operations inside, so that the chain from generation 1 to the current one has no holes.

The base class refuses a migration whose two generations don’t share an event type ID, or that skips a generation. It’s a check in the constructor:

protected EventTypeMigration()
{
    var previousEventType = typeof(TPrevious).GetEventType();
    var upgradeEventType = typeof(TUpgrade).GetEventType();

    if (previousEventType.Id != upgradeEventType.Id)
    {
        throw new MigrationGenerationsMustShareEventTypeId(typeof(TPrevious), typeof(TUpgrade), previousEventType.Id, upgradeEventType.Id);
    }

    From = previousEventType.Generation;
    To = upgradeEventType.Generation;

    if (To.Value != From.Value + 1)
    {
        throw new InvalidMigrationGenerationGap(typeof(TPrevious), typeof(TUpgrade), From, To);
    }
}

The kernel validates the chain again, whichever client registered it. Generation 1 has to exist, generations have to be sequential, and every consecutive pair needs a migrator. A chain that breaks one of those rules fails at startup with MissingFirstGenerationForEventType, MissingMigrationForEventTypeGeneration or MissingEventTypeMigrators, and two migrators that claim the same pair throw MultipleMigratorsForSameEventTypeGeneration.

What the kernel does with it

At registration the client sends the whole event type to the kernel, every generation and every migration, with the migrations expressed as JmesPath. From then on the kernel applies them on every append. Append generation 1 and Chronicle stores generations 1 and 2. Append generation 2 and it stores generation 2 plus the downcast generation 1. Chains of three or more generations extend the same way. Chronicle produces upcast and downcast representations while keeping the originally stored generation, so old and new code can each read the shape they expect.

One stored event, readable in every generation of its type.

Events stored before the new generation existed get the same treatment later. Registering a new generation makes the kernel append an EventTypeGenerationAdded event to its system sequence. A built-in reactor observes it and starts a job that walks the default namespace’s event log for events of that type still stored in the older generation, computes every generation for each one and writes the result back into the stored event. The job covers the default namespace’s event log only. The application stays usable while the job runs, and a consumer reading the new generation sees the events migrated so far.

A migration changes representation. It can split a title that was stored as “Persuasion: A Novel” into two fields, and it has no way to know that the colon in some other title was never meant as a separator. If what the event means has changed, that’s a new event, and a migration is the wrong tool. A migration can’t fix a wrong value either. The misspelled author gets a correction, further down.

Upgrading Chronicle itself is a separate matter. A package or server upgrade doesn’t rewrite, reshape or reinterpret stored events, and event schema evolution only happens through the mechanism above. Wire compatibility is checked within a major version, across every released minor of it, and crossing a major is where a protocol change is allowed.

On the application side, nothing in the event mechanism depends on Arc, and Arc needs no change when a generation is added. A command that returns the current generation’s type just writes it. A changed C# command or read model reaches the browser only after the proxy generator has run at build time and the frontend has type-checked against the new files, which Arc: commands and queries without the plumbing follows in detail.

A new view over old events

When a projection is wrong, fix it and rebuild the read model from the retained history. Replay reads the events as they stand now, with any revisions and redaction markers that apply. The distinction between rebuilding state and delivering side effects is covered in From event to read model.

From event to read model covers how Chronicle classifies a changed definition, when it can use a partial replay, and how definitionEvolution chooses between running the work and recommending it. Reactor and webhook definition changes use their separate replay switch, covered in Reacting to facts.

A new projection, such as the list of authors on that new screen, is a different case. Registering it against a store that already holds events starts a catch-up job, and the registration call doesn’t wait for it. Registered and caught up are two different states, and the gap between them shows in Chronicle Workbench’s observer job view, which Workbench walks through. The client retries a registration with exponential backoff, so a busy kernel doesn’t fail the host. A kernel that keeps refusing still fails it once the attempts are spent, and a definition the kernel rejects fails on its own while the others still land.

When you do want a replay by hand, cratis chronicle observers replay <observer-id> starts one from the CLI. The CLI marks the command as destructive in its own effect metadata and asks for confirmation unless you pass --yes. Replays, catch-ups and event migrations run as jobs you can inspect, stop and resume, with a setting that caps how many steps run in parallel. A replay takes time in proportion to the history behind the observer, and Jobs, scale and performance covers what that means on a large store.

When a replay reaches a reactor

Before replaying the welcome mailer, apply the replay markers and delivery-identity limits from Reacting to facts; replay and recovery need different treatment.

Personal data puts one more limit on replay. A replay that covers an erased subject is refused for that subject’s partition, and a rebuild doesn’t clear ciphertext that’s already stored. Personal data in an event log explains why, and what to do before such a rebuild.

A correction to something recorded

Choose a compensation, revision, redaction or key erasure by what needs correcting and what must remain, using the boundaries in Personal data in an event log.

The misspelled author is a revision. The revised content has to use the same event type id as the original, consumers see the latest revision, and the original stays in the event’s history.

Neither revision nor redaction is free for observers. Both rewind the affected event source’s partition for every replayable observer of that event type, so the read models built from that one author are rebuilt from that author’s events. The rest of each observer stays where it was. A reactor on that event type replays that author’s events too, unless it’s marked [OnceOnly], which is the case the marker exists for.

A processor that stopped

The fourth change doesn’t touch anything stored. The welcome mailer threw on one author, and Chronicle has been holding that author’s events ever since.

The failed partition pauses without skipping the event while every other partition keeps going. Inside Chronicle covers the failure kinds, retry defaults and the quarantine that stops automatic attempts.

A timeout ends the kernel’s wait and nothing else. The subscriber keeps processing the batch it was handed while the kernel has already written it off. The events are delivered again on retry, so observers have to be idempotent.

Once the cause is fixed, someone asks for another attempt. The kernel decides whether it can start one, and it has four answers:

public async Task<PartitionRecoveryOutcome> TryStartRecoverJobForFailedPartition(Key partition)
{
    if (State.RunningState == ObserverRunningState.Quarantined)
    {
        return PartitionRecoveryOutcome.ObserverQuarantined;
    }

    if (!Failures.TryGet(partition, out var failure))
    {
        return PartitionRecoveryOutcome.PartitionNotFound;
    }

    if (failure.IsQuarantined)
    {
        return PartitionRecoveryOutcome.PartitionQuarantined;
    }

    await StartRecoverJobForFailedPartition(failure);
    return PartitionRecoveryOutcome.Started;
}

A quarantined observer has to be cleared with clear-quarantine before any of its partitions can be retried. A partition that isn’t failing has nothing to retry, and a quarantined partition refuses an ordinary retry.

The CLI passes those answers on without softening them. cratis chronicle observers retry-partition turns the response into an exit code:

if (response.Outcome == PartitionRecoveryOutcome.Started)
{
    OutputFormatter.WriteMessage(format, $"Retry started for partition '{settings.Partition}' of observer '{settings.ObserverId}'. Use 'cratis chronicle observers show {settings.ObserverId}' to check progress.");
    return ExitCodes.Success;
}

var (message, suggestion) = DescribeRefusal(response.Outcome, settings);
OutputFormatter.WriteError(format, message, suggestion, ExitCodes.ValidationErrorCode);
return ExitCodes.ValidationError;

Only Started exits successfully, and even that message says the retry started. Every refusal becomes a validation error with a suggested next step. A script that runs the retry gets a nonzero exit code when nothing happened, and a human gets told to check progress. A started retry says nothing yet about whether the partition recovered, so look at the partition again afterwards. A retry also gives no exactly-once guarantee for a reactor’s side effects, and the welcome mail may go out twice if the handler sent it before it threw.

A retry the kernel can’t start is reported as a refusal. One it starts still has to be checked.

A retry isn’t a replay. retry-partition asks for one more attempt from where the partition failed. replay-partition replays the partition from the start, for when its derived state is wrong. A typed reactor can also list its own failed partitions and retry one from application code. The troubleshooting guide walks the loop end to end, and The Cratis CLI follows it from diagnose onwards.

The four changes

Back to the made-up year. The subtitle is a second generation of BookCataloged and one migrator, and books already cataloged in the default namespace’s event log get their second generation from a background job. The new screen is a new projection that catches up from the log. The misspelled name is a revision, which rewinds that one author’s partition in the observers that care. The stuck welcome mailer is a failed partition, a fixed mail configuration and one retry, followed by a look at whether the partition is current.

Chronicle checks the chain of generations, translates on every append and classifies a changed projection before it replays anything. It also refuses a retry it can’t start, and says so.

Some decisions stay with whoever runs the system. A migration can’t tell that a field changed meaning, so that call is a modeling one. The definition-evolution setting decides whether a full replay runs straight away or waits as a recommendation. Picking between a reversal, a revision, a redaction and a key erasure is a judgment about what the mistake was. And a retry that started is only a request until someone has checked that the partition caught up.

Previous: Part 13 — Personal data in an event log
Next: Part 15 — Arc gotchas: where a convention decides for you

From script to stage · Part 13: Personal data in an event log

Wed, 30 Sep 2026 09:13:00 GMT

Cratis: from script to stage, and the long run · Part 13 of 26

Erasing a person in Chronicle is one call that deletes their key. Every event they appear in stays in the log at the same sequence number, and the values marked as personal data come back as empty strings. If something then tries to append new personal data for that person, the append fails on purpose instead of quietly starting a fresh key.

The author’s name travels further than the event: into the command’s audit trail, into read models, into other event stores and into backups.

Personal data, marked once

The author’s name is personal data. One attribute on its type makes Chronicle encrypt the value with the key of the event’s subject, and with Arc’s Chronicle integration the same attribute keeps it out of the causation record. The log remembers shows the Chronicle side in five languages.

The name’s ConceptAs<T> type is marked [PII], and every event property of that type is encrypted for the event’s subject. A person-name type marked that way:

using Cratis.Chronicle.Compliance.GDPR;
using Cratis.Concepts;

[PII]
public record PersonName(string Value) : ConceptAs<string>(Value)
{
    public static implicit operator PersonName(string value) => new(value);
}

import io.cratis.chronicle.compliance.Pii
import io.cratis.chronicle.concepts.ConceptAs

@Pii
data class PersonName(override val value: String) : ConceptAs<String>

import io.cratis.chronicle.compliance.Pii;
import io.cratis.chronicle.concepts.ConceptAs;

@Pii
record PersonName(String value) implements ConceptAs<String> {
    @Override
    public String getValue() {
        return value;
    }
}

import { pii } from '@cratis/chronicle';
import { ConceptAs } from '@cratis/fundamentals';

@pii()
class PersonName extends ConceptAs<string> {
    static readonly valueType = String;

    constructor(value: string) {
        super(value);
    }
}

defmodule MyApp.PersonName do
  use Chronicle.Concept, type: :string
  pii()
end

Projection-backed read models track the protected value’s subject through their mappings. Reducer read models need their own PII marking, because the kernel can’t infer arbitrary transformations.

Pick the attribute by what the value is. Personal data you may have to erase gets [PII]. A value that should never reach the causation record gets [NotAudited], which excludes it without encrypting it, and an operational secret you have to keep gets [Encrypted], whose separate key erasure doesn’t touch, as what a command leaves behind explains.

Erasure is one call:

await eventStore.PII.DeleteEncryptionKeyFor("person-42");

eventStore.compliance.deleteEncryptionKey("person-42")

ComplianceServiceJavaBridge.deleteEncryptionKey(eventStore.unwrap().getCompliance(), "person-42");

await eventStore.pii.deleteEncryptionKey('person-42');

Chronicle.Compliance.delete_encryption_key("person-42")

Once the key has been destroyed, Chronicle can’t decrypt anything encrypted with it. The event keeps its place in the log, so the log still shows that something happened.

Erasure stops at these points:

The key belongs to a subject within a namespace. A person who exists in two tenants needs two erasures.
Values that were never marked stay readable, and so do causation values recorded in clear before anyone marked them.
Copies outside Chronicle, including exported keys, messages sent to another system and values already shown in a browser, need separate handling.

Erasure, step by step covers the rebuild limit, and Where the keys live, and how they come back covers the restore that can undo an erasure.

Deleting a person’s key reaches the event log and managed read models, not copies.

An application that handles personal data still needs its own privacy review. Redaction and revision, which change an event instead of a key, come up again in Year two.

Where the marker lands

The [PII] marker is written into the event type’s schema as compliance metadata. Chronicle looks for it in four places, in order: on the property, on the declaring type, on the property’s own type, which is the concept case above, and on a matching constructor parameter. It lands on individual leaf values. A marked concept nested inside a value object is encrypted while its sibling stays readable, and the document keeps its shape. A marked collection is encrypted as one value, and geospatial values are never looked inside.

Some shapes are refused outright. A polymorphic base type or a dictionary carrying [PII] makes the append fail, so the value is never stored unprotected. [PII] on an EventSourceId type throws PIINotSupportedOnEventSourceId. The fix is a surrogate id that says nothing about the person, with the personal value in a marked property. The author feature already has that shape, since AuthorId identifies the author and AuthorName carries the name.

Whose key: the subject

Keys are held per subject. The subject defaults to the event source id, and it can be set on append, by an event property marked [Subject] (C# only), or from an Arc command. ShippingAddressChanged lives on the order’s stream, but the address belongs to the customer, so the customer is the subject, and every event about that customer, from any stream, shares one key.

An Arc command sets the subject by returning it next to the event:

using Cratis.Arc.Chronicle.Commands;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle;
using Cratis.Chronicle.Events;

[Command]
public record PlaceCustomerOrder(OrderId OrderId, CustomerId CustomerId, Money Total)
    : ICanProvideEventSourceId
{
    public EventSourceId GetEventSourceId() => OrderId;

    public (OrderPlaced, Subject) Handle() =>
        (new OrderPlaced(CustomerId, Total), new Subject(CustomerId.Value.ToString()));
}

[EventType]
public record OrderPlaced(CustomerId CustomerId, Money Total);

In Arc for Kotlin the command implements CommandEventSubjectProvider instead of returning the subject next to the event.

import io.cratis.arc.artifacts.Command
import io.cratis.arc.artifacts.CommandEventSubjectProvider
import io.cratis.arc.artifacts.CommandKey
import io.cratis.chronicle.events.EventType

@Command
data class PlaceCustomerOrder(
    @CommandKey val orderId: OrderId,
    val customerId: CustomerId,
    val total: Money
) : CommandEventSubjectProvider {
    override fun eventSubject(): String = customerId.value.toString()

    fun handle(): OrderPlaced = OrderPlaced(customerId, total)
}

@EventType
data class OrderPlaced(val customerId: CustomerId, val total: Money)

In Arc for Java the command implements CommandEventSubjectProvider instead of returning the subject next to the event.

import io.cratis.arc.artifacts.Command;
import io.cratis.arc.artifacts.CommandEventSubjectProvider;
import io.cratis.arc.artifacts.CommandKey;
import io.cratis.chronicle.events.EventType;

@Command
public record PlaceCustomerOrder(@CommandKey OrderId orderId, CustomerId customerId, Money total)
    implements CommandEventSubjectProvider {
    @Override
    public String eventSubject() {
        return customerId.value().toString();
    }

    public OrderPlaced handle() {
        return new OrderPlaced(customerId, total);
    }
}

@EventType
record OrderPlaced(CustomerId customerId, Money total) {}

In Arc for TypeScript the command computes the subject in getSubject() instead of returning it next to the event.

import { field, Guid } from '@cratis/fundamentals';
import { eventType } from '@cratis/chronicle/events';
import { command, key } from '@cratis/arc.core';

@command()
export class PlaceCustomerOrder {
    @field(OrderId) @key() orderId!: OrderId;
    @field(CustomerId) customerId!: CustomerId;
    @field(Money) total!: Money;

    getSubject(): string { return this.customerId.toString(); }

    handle(): OrderPlaced { return new OrderPlaced(this.customerId, this.total); }
}

@eventType()
export class OrderPlaced {
    @field(CustomerId) customerId: CustomerId;
    @field(Money) total: Money;
    constructor(customerId = new CustomerId(Guid.empty), total = new Money(0, '')) { this.customerId = customerId; this.total = total; }
}

Arc for Elixir doesn’t exist; with the Chronicle Elixir client you pass the subject as an append option.

defmodule MyApp.Events.OrderPlaced do
  use Chronicle.Events.EventType, id: "order-placed"

  defstruct customer_id: %MyApp.CustomerId{}, total: %MyApp.Money{}
end

defmodule MyApp.PlaceCustomerOrder do
  def place(%MyApp.OrderId{} = order_id, %MyApp.CustomerId{} = customer_id, total) do
    Chronicle.append(
      order_id.value,
      %MyApp.Events.OrderPlaced{customer_id: customer_id, total: total},
      subject: customer_id.value
    )
  end
end

A command can also implement ICanProvideSubject. The Subject is append metadata and never becomes the command’s response. Arc doesn’t infer the subject from the signed-in user, and an aggregate’s Apply() doesn’t forward it.

A key belongs to one event store and one namespace. The subject also travels on the event as EventContext.Subject, so an observer that forwards an event and passes context.Subject along keeps its compliance identity. An event store subscription copies the subject’s key into the target store and never across namespaces.

On the way in and on the way out

The cryptographic contract for one value fits in two methods of the kernel’s PIICompliancePropertyValueHandler:

public async Task<JsonNode> Apply(EventStoreName eventStore, EventStoreNamespaceName eventStoreNamespace, string identifier, JsonNode value)
{
    var key = await provisioner.EnsureKeyFor(eventStore, eventStoreNamespace, identifier);
    return ProtectedValueCodec.Encrypt(encryption, key, value);
}
public async Task<JsonNode> Release(EventStoreName eventStore, EventStoreNamespaceName eventStoreNamespace, string identifier, JsonNode value)
{
    if (!ProtectedValueCodec.TryDecodeCipherText(encryption, value.ToString(), out var encrypted))
    {
        return value;
    }
    var key = await encryptionKeyStore.TryGetFor(eventStore, eventStoreNamespace, identifier);
    if (key is null)
    {
        return JsonValue.Create(string.Empty);
    }
    return ProtectedValueCodec.Decrypt(encryption, key, encrypted);
}

Apply makes sure the subject has a key, minting one on first use, and replaces the value with ciphertext. Release decodes only values in the shape of ciphertext it produced. A value that was never encrypted passes through, and an encrypted value whose key is gone comes back as an empty string. Nothing throws, so a query over an erased person keeps working. The asymmetry is deliberate. If protecting a value fails on the way in, the operation fails. A value that can’t be read on the way out is blanked per property and never fails the whole read.

Reactors, webhooks, reducers and projections all receive decrypted events, from a single decryption point in the observer.

What a read model holds

Projection-backed read models get their PII lineage automatically. The kernel knows which read model properties map from PII event properties and encrypts them before the sink write, with no attribute on the read model. A reducer is opaque code, so its read model needs [PII] on its own properties.

Every managed document stores a reserved __subject. When a projection joins personal values from different subjects, only the exceptions go into __subjects, as in {"advisorName": "advisor-17"}. That one value is released and erased under advisor-17, while the rest of the document follows its own subject, employee-42. Don’t name your own properties __subject or __subjects.

Decryption happens per property. A value encrypted under the document’s subject is released, a value whose key was deleted reads as empty, and a value that was never encrypted passes through. A value encrypted under a different subject with no ownership metadata, from legacy data or data written outside the managed sinks, reads as empty, and the kernel logs an error naming the property and the subject.

Queries through IReadModels release values automatically. An instance that arrived another way, from raw storage, a cache or Watch, which streams without releasing, needs an explicit IReadModels.Release. Arc calls Release on the query paths that use its read-model interception, before the response or the WebSocket or SSE emission. Observable HTTP snapshots currently bypass that interception, so each response path that exposes a read model has to be chosen and authorized deliberately. Release isn’t authorization, and it can’t bring back an erased key.

What a command leaves behind

With Arc’s Chronicle integration in .NET and TypeScript, the causation of every event a command appends records the command’s name and its property values. Keys are camelCased, concepts render as their inner value, and nested objects become compact JSON, truncated at 1,024 characters with a marker. [PII] keeps a top-level value off that chain, whether it sits on the property, the command, the positional parameter or the concept. Arc’s own [NotAudited] does the same for secrets that aren’t personal data:

[NotAudited]
public record Password(string Value) : ConceptAs<string>(Value);

[Command]
public record ChangePassword(UserId User, Password OldPassword, Password NewPassword)
{
    public Result<PasswordChanged, ValidationResult> Handle(UserCredentials? credentials, IPasswordHasher hasher) =>
        credentials is not null && hasher.Verify(OldPassword, credentials.PasswordHash)
            ? new PasswordChanged(hasher.Hash(NewPassword))
            : ValidationResult.Error("The old password is wrong.", ["oldPassword"]);
}

Arc for Kotlin records the command’s type and key in the causation chain, not its property values, so there’s no NotAudited marker.

Arc for Java records the command’s type and key in the causation chain, not its property values, so there’s no NotAudited marker.

In Arc for TypeScript, @notAudited() marks a field, not a type.

export class Password extends ConceptAs<string> {
    static readonly valueType = String;
}

@command()
export class ChangePassword {
    @field(UserId) @key() user!: UserId;
    @field(Password) @notAudited() oldPassword!: Password;
    @field(Password) @notAudited() newPassword!: Password;

    @inject(commandReadModel(UserCredentials), PasswordHasher)
    handle(credentials: UserCredentials, hasher: PasswordHasher): Outcome<PasswordChanged> | PasswordChanged {
        if (!hasher.verify(this.oldPassword, credentials.passwordHash)) {
            return rejected(validation('The old password is wrong.', ['oldPassword']));
        }

        return new PasswordChanged(hasher.hash(this.newPassword));
    }
}

The decision fails closed, so a property whose exclusion can’t be decided is left out. Exclusion isn’t recursive, and a marked member inside a nested object still ends up in that JSON. Arc’s analyzer ARCCHR0009 warns when a command property’s name reads like a secret and carries no marker.

Causation values aren’t encrypted under the subject’s key, so deleting the key doesn’t erase them. Setting events.causationPropertyRetention to Omit stops new appends, revisions and redactions from storing causation property values, while keeping their types and times. Chains already stored stay as they are.

[PII] on an Arc command keeps a value out of causation and encrypts nothing. The event you build from the command needs its own marker, on the property or on the concept.

For an operational secret you must store, Chronicle has [Encrypted], which uses a separate key. Erasing a subject’s [PII] key leaves an [Encrypted] value readable, and Chronicle’s subject-erasure operation refuses to delete its key. [Encrypted] keys are scoped to the subject by default, or to the namespace or globally, and no operation deletes one. Combining [Encrypted] with [PII] on one property makes the schema pass throw, and analyzer CHR0053 catches the direct cases.

Four ways to change the record of an event

A request to “delete it” can mean four different operations, and each answers a different question.

A compensation is a new domain event. A cancelled registration is recorded as a cancellation, and nothing earlier changes. Redaction and revision aren’t meant for undoing a business decision.

A revision corrects content. It has to keep the same event type id, or it fails with InvalidRevisionEventType. The corrected payload is stored beside the original with the requester’s causation and identity, consumers see the latest revision from then on, and the original stays in the event’s history. Chronicle then rewinds that event source’s partition for replayable observers of the type. A revision removes nothing.

A redaction removes content. Requesting one appends a system event, EventRedactionRequested for a single event or EventsRedactedForEventSource for a whole event source, optionally limited to some event types, and both take a RedactionReason. A built-in reactor then replaces the event in place. It keeps its sequence number and becomes an EventRedacted that holds the reason, the original event type and occurred time, the correlation id and caused-by chain, and the types and times of the original causation entries without their property values. The payload, the revision history and the content hashes are gone from sequence storage. The kernel rewinds the affected partition for observers of that type, and a repeated redaction skips the rewind.

An observer hears about a redaction only if it subscribes to the original event type and also handles EventRedacted:

[EventType]
public record PersonRegistered(PersonName Name);

public class PersonRegistrations : IReactor
{
    public Task Registered(PersonRegistered @event, EventContext context) => Task.CompletedTask;

    public Task Redacted(EventRedacted @event, EventContext context)
    {
        // Called only when a PersonRegistered event is redacted.
        return Task.CompletedTask;
    }
}

That handler is where a read model gets cleaned up or a downstream system gets told. Redaction doesn’t reach database oplogs, backups, or copies already forwarded to another event store through outbox and inbox, and it doesn’t clean read models by itself.

Erasing a key is the fourth operation. Every event stays intact, and only the marked values become unreadable.

Four ways to change what an event shows, and what each one leaves.

Erasure, step by step

DeleteEncryptionKeyFor on eventStore.PII runs three phases in the kernel:

public async Task DeleteEncryptionKeyFor(EncryptionKeyIdentifier identifier)
{
    ThrowIfEncryptedValueIdentifier(identifier);
    var key = GetKey();
    List<Exception> failures = [];
    var eventStores = await EventStoresToReach(key, failures);

    await ForEach(eventStores, failures, eventStore => keyStore.RecordErasureFor(eventStore, key.Namespace, identifier));
    await ForEach(eventStores, failures, eventStore => keyStore.DeleteFor(eventStore, key.Namespace, identifier));
    await ForEach(eventStores, failures, eventStore => cacheClient.Evict(eventStore, key.Namespace, identifier));

    if (failures.Count > 0)
    {
        logger.SubjectErasureIncomplete(BindingFor(identifier), key.Namespace, failures.Count, eventStores.Count, Names(eventStores));
        throw new EncryptionKeyErasureIncomplete(identifier, failures);
    }

    logger.ErasedSubject(BindingFor(identifier), key.Namespace, eventStores.Count, Names(eventStores));
}

It refuses an identifier that belongs to an [Encrypted] value, with EncryptionKeyIsNotErasable. It lists every event store in the namespace, always including the store the caller named, even if the listing fails. It records an erasure fence in each store, and only after that destroys the key in each of them. Then it evicts the key from every silo’s cache, whether or not the earlier phases succeeded. Every phase tries every store, and if any of them failed, the call throws EncryptionKeyErasureIncomplete listing all the failures.

The order closes a window. Erasing store by store left an interval where one store still held the key and another didn’t, and an event forwarded in that interval copied the surviving key into the store that had just been cleared.

The fence is a record kept beside the keys, with three fields. ErasedThrough is the highest key revision it covers, ErasedKeyFingerprints holds SHA-256 fingerprints of the destroyed public keys, and NewKeyAllowed is false after every erasure. While a fence exists, the store refuses to provision a key for the subject, to save any revision at or below the floor, or to accept a key whose fingerprint matches a destroyed one at any revision. The fingerprint check is what stops a cross-store copy from bringing the old key back. Reads are untouched, which is why the erased values read as empty.

Appending a [PII] value for an erased subject fails with EncryptionKeyErased. It doesn’t mint a key and doesn’t blank the value.
AllowNewEncryptionKeyFor(subject) sets NewKeyAllowed in every store of the namespace and creates no key. The next protected append mints one at ErasedThrough + 1. That key decrypts nothing written before the erasure, and the destroyed material is still refused.
A forwarded event carrying [PII] for an erased subject fails to append in the target store, and that event source’s partition fails while the rest of the subscription keeps flowing.
Replaying a projection or reducer into a stored read model applies protection again, so the replay is refused for the erased subject’s partition. A rebuild doesn’t remove ciphertext already in the read model store. Before such a rebuild, authorize a new key for anyone you intend to keep protecting.

Erasure doesn’t touch the constraint index. A [Unique] constraint over a [PII] value keeps a SHA-256 hash of the plaintext, and DeleteEncryptionKeyFor removes keys and caches, not that entry. The erased author’s name therefore stays taken in that namespace, and because the hash isn’t salted, anyone who can read the index can still confirm a guessed name. The entry goes when an event marked [RemoveConstraint] with the constraint’s name is appended for the same event source, so give the author feature a removal event that carries no personal data, such as AuthorForgotten(AuthorId), and append it as part of the erasure. A constraint reindex, which runs when a constraint’s definition changes, also drops entries whose value now reads as empty. A fix is tracked in Chronicle issue #4389.

The completion is logged, as in “Erased the encryption key for the subject bound to ‘a3f1…’ in namespace ‘Default’, across all 3 event stores”. The binding is a SHA-256 hex of the identifier, a pseudonym that can be brute-forced when the space of identifiers is small. The log records that an erasure completed and where. Who asked, and on what legal basis, isn’t recorded. An incomplete run logs at error level.

Fence first, destroy second, evict always.

Erasures performed before the fence shipped aren’t fenced and can be resurrected until they’re run again. The call is idempotent, one per subject. Every silo has to run a version with the fence, and mixed versions aren’t supported while an erasure is in force. A custom IEncryptionKeyStorage without the fence fails on the first erasure. In a composed store, an unreachable member is skipped on reads, so a fence held only there is invisible while that member is down, and a key provisioning already in flight when the fence lands can still persist its key. Erase again after forwarding and appends for the subject have stopped.

Where the keys live, and how they come back

By default keys sit in the general storage backend. compliance.encryption.storage selects a dedicated store, either HashiCorp Vault (KV v2, with the token from VAULT_TOKEN) or Azure Key Vault, and both keep every key revision as its own secret. What those services do with a deleted secret follows their own retention and recovery policies.

Switching to a dedicated store on a running system with keys already stored makes those keys unreachable, and their values read as empty strings with no error. migrateFromDefaultStorage: true composes both stores, moves each key on its first read, mirrors new keys back and erases from both. A key nobody has read since the switch still lives only in the default store, so turn the flag off only after confirming that the dedicated store holds every key.

A backup has three parts: the encryption-certificate ring, the storage backend and the key store. The key store has to be restored to the same point in time as the storage. Restore it from earlier, and newer subjects’ values read as empty, indistinguishable from an erasure. The same backup, if it’s from before an erasure, brings the key back and removes the fence, so an erasure you’ve already reported as complete is silently undone, and nothing inside Chronicle can see that it happened. A lost key store can’t be rebuilt, because there’s no escrow and no recovery key.

The same markers in other clients

The C# client validates the most. The Kotlin/Java, TypeScript and Elixir clients accept the markers without the same checks. Every client takes a subject as an append option, but only C# reads it from an event’s [Subject] property. The other clients’ subject markers only pick the key a read model is released under. Elixir can’t mark a whole multi-field struct [PII], and the TypeScript decorator doesn’t read constructor parameters. [Encrypted] exists in all four. Every client can delete a subject’s key, and only .NET and TypeScript can authorize a new one afterward. Where the clients differ has the full list.

Erasing an author takes DeleteEncryptionKeyFor with the author’s subject, once in each namespace the author appears in, and because the name is [Unique], the erasure also appends a removal event so the name’s hash leaves the constraint index. The name then reads as empty in the log and in the author list, AuthorRegistered keeps its sequence number, and whatever the application already sent elsewhere is still the application’s to clean up.

Previous: Part 12 — Beyond .NET
Next: Part 14 — Year two

From script to stage · Part 12: Beyond .NET

Wed, 30 Sep 2026 09:12:00 GMT

Cratis: from script to stage, and the long run · Part 12 of 26

Chronicle has clients for .NET, Kotlin and Java, TypeScript and Elixir, and all of them append to the same kernel through the same contract. Only one of them checks concurrency on an append unless you ask it to. The .NET client reads the tail of the event source and sends the sequence number it expects, so an append that lands between that read and its write fails. The Kotlin and Java client appends with no concurrency scope, and the TypeScript and Elixir clients send no check at all.

That’s one line in a table of differences, and it matters the day a second team picks a second language. The author feature is written in C#, and nothing in its uniqueness rule needs C#. A JVM or Node team can build the same feature on Cratis, once they know what exists for their language and where it departs from the .NET path.

One contract, several ecosystems

Not every team is on .NET, and not every service in one system should have to be. Arc’s HTTP contract is shared across three server implementations, and each generates TypeScript proxies for the frontend, though each has gaps of its own.

On the JVM, Arc for Kotlin is a Spring Boot implementation for Kotlin and Java, published to Maven Central. This command and its event come from its Chronicle Spring Boot sample, trimmed and with the id and title as concepts. The C# and TypeScript tabs have the same command, the TypeScript one from Arc for TypeScript’s Chronicle guide:

The same command in C#, where TaskId, an EventSourceId<Guid>, names the event source.

using Cratis.Arc.Authorization;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle.Events;

[EventType]
public record TaskCreated(TaskTitle Title);

[Command]
[AllowAnonymous]
public record CreateTask(TaskId Id, TaskTitle Title)
{
    public TaskCreated Handle() => new(Title);
}

import io.cratis.arc.artifacts.Command
import io.cratis.arc.artifacts.CommandKey
import io.cratis.arc.authorization.AllowAnonymous
import io.cratis.chronicle.events.EventType

@EventType
data class TaskCreated(val title: TaskTitle = TaskTitle(""))

@Command
@AllowAnonymous
data class CreateTask(@CommandKey val id: TaskId, val title: TaskTitle) {
    fun handle(): TaskCreated = TaskCreated(title)
}

import io.cratis.arc.artifacts.Command;
import io.cratis.arc.artifacts.CommandKey;
import io.cratis.arc.authorization.AllowAnonymous;
import io.cratis.chronicle.events.EventType;

@EventType
public record TaskCreated(TaskTitle title) {}

@Command
@AllowAnonymous
public record CreateTask(@CommandKey TaskId id, TaskTitle title) {
    public TaskCreated handle() {
        return new TaskCreated(title);
    }
}

import { field } from '@cratis/fundamentals';
import { eventType } from '@cratis/chronicle/events';
import { allowAnonymous, command, key } from '@cratis/arc.core';

@eventType()
export class TaskCreated {
    @field(TaskTitle) title: TaskTitle;
    constructor(title: TaskTitle) { this.title = title; }
}

@command()
@allowAnonymous()
export class CreateTask {
    @field(TaskId) @key() id!: TaskId;
    @field(TaskTitle) title!: TaskTitle;

    handle(): TaskCreated {
        return new TaskCreated(this.title);
    }
}

The command returns the event, and Arc’s Chronicle integration, which the sample uses, appends it to the event source named by @CommandKey. Arc for Kotlin also has validation, authorization, tenancy, observable queries and in-process command scenarios. It isn’t at parity with .NET. Command operations and aggregates aren’t in it, and it runs only on Spring Boot.

The Node.js command is a decorated class, here from the source-only Tasks sample described in Arc for TypeScript, from source:

@command()
export class RegisterTask {
    @field(TaskId) id!: TaskId;
    @field(TaskTitle) title!: TaskTitle;

    handle(tasks: Tasks): TaskId {
        tasks.register(this.id, this.title);
        return this.id;
    }
}

Chronicle has its own set of clients: a first-class .NET SDK, and clients for TypeScript, Kotlin/Java (JVM) and Elixir, over whichever storage provider each deployment chooses. Services in one system can use different clients against the same kernel. The clients aren’t interchangeable, though. The default concurrency check, ExpectingNoMatchingEvent, decision reads and some erasure options differ, and where the clients differ lists the gaps. Event sourcing in any language explains the shared contract underneath.

The contract is shared; each implementation states its own gaps.

Two things are shared and everything else belongs to a language. The Chronicle kernel runs the observers, the constraints and the storage, and a client registers its artifacts with it over gRPC and streams events to and from it. Arc’s contract fixes the command and query envelopes, the observable transports and the validation rules. For the frontend that means very little changes. The React code from Live UIs compiles against generated proxies, and @cratis/arc and @cratis/arc.react don’t care which server the proxies came from. What changes is how the backend declares its commands and queries, and how its events reach the log.

Arc on the JVM

Arc for Kotlin is MIT-licensed and published to Maven Central as io.cratis:arc. It runs on the Spring Boot servlet stack, where auto-configuration registers the HTTP, Server-Sent Events and optional WebSocket endpoints. Java gets the same treatment as Kotlin, with plain-Java samples and Java tabs in the docs for the same features. A handler can be an ordinary function, a Kotlin suspend function or a method returning a Java CompletionStage.

A command is a @Command class with a handle() method, and a query is a companion or static method on a @ReadModel type. KSP generates the handlers at compile time, so nothing is found by reflection when the application runs. Routes come from names, and CreateTask becomes POST /api/create-task. The package segments to leave out of a route are set twice, once in the Gradle plugin as cratisArc.endpoints.segmentsToSkip and once at runtime as cratis.arc.endpoints.segments-to-skip-for-route. If the two disagree, the starter refuses to start. Arc gotchas covers names doing the mapping on .NET. On the JVM, a mismatch is caught at startup.

A query stays live by returning something that emits. In Kotlin that’s a Flow or a StateFlow. In Java it’s a JDK Flow.Publisher or Arc’s ObservableState<T>, and with the optional arc-rxjava3 artifact it can be an RxJava 3 Observable. The Kotlin and Java tabs follow the observable queries guide, the TypeScript tab follows Arc for TypeScript’s guide to observable queries, and the C# tab is the same query for .NET. Like the guides, each keeps the tasks in one value for the whole process, not one per tenant:

The same query in C#, with a BehaviorSubject as the ISubject.

[ReadModel]
[AllowAnonymous]
public record TaskView(TaskId Id, TaskTitle Title)
{
    static readonly BehaviorSubject<IEnumerable<TaskView>> Tasks = new([]);

    public static ISubject<IEnumerable<TaskView>> All() => Tasks;
}

private val _tasks = MutableStateFlow<List<TaskView>>(emptyList())

@ReadModel
@AllowAnonymous
data class TaskView(val id: TaskId, val title: TaskTitle) {
    companion object {
        @JvmStatic
        fun all(): Flow<List<TaskView>> = _tasks
    }
}

@ReadModel
@AllowAnonymous
public record TaskView(TaskId id, TaskTitle title) {
    private static final ObservableState<List<TaskView>> tasks = new ObservableState<>(List.of());

    public static Flow.Publisher<List<TaskView>> all() {
        return tasks;
    }
}

const tasks = new BehaviorSubject<TaskView[]>([]);

@readModel()
@allowAnonymous()
export class TaskView {
    @field(TaskId) id!: TaskId;
    @field(TaskTitle) title!: TaskTitle;

    @query({ observable: true })
    static all(): Observable<TaskView[]> { return tasks; }
}

MutableStateFlow does the job ISubject<T> does on .NET, and the state it holds matters. A source that only emits has nothing to answer a plain HTTP request with, so a snapshot GET against it returns 202 Not Ready unless the caller passes waitForFirstResult=true. The transports are the ones .NET uses, Server-Sent Events, WebSocket and an HTTP snapshot.

Validation is Jakarta Bean Validation, with reusable concept and model validators and shared fluent validators whose rules carry over into the generated client. The Gradle plugin, io.cratis.arc, generates strict-mode TypeScript for commands, queries, observables and models, validation metadata included, and the frontend uses it the way it would against .NET.

Events from a command

Chronicle is optional on the JVM as well. io.cratis:arc has no Chronicle dependency, and an application can sit on JPA, MongoDB or plain services. For an event-sourced application the one dependency to take is io.cratis:cratis, which pulls in Arc, its Spring wiring and the Chronicle integration.

With it, a command returns an event and Arc appends it, as CreateTask does above. @EventType on the event is required. Arc’s Chronicle integration treats only @EventType values as events. A collection or routed wrapper that contains anything else fails before anything is appended, and a single unannotated value isn’t appended at all. Arc for Kotlin’s plain example returns a TaskCreated with no annotation, which is fine there because that sample has no event log, and wrong the moment Chronicle is involved. The Chronicle sample also gives every event property a default, as TaskCreated above does with val title: TaskTitle = TaskTitle(""), and the Chronicle client’s own examples declare events the same way.

@CommandKey is required too. It names the event source, and a command without one gets back a validation result with reasonDetail: "commandKey", because Arc won’t guess which event source you meant. Events returned inside one outermost command are staged and committed with a single appendMany call, which fails closed if the event store, the namespace or the correlation doesn’t match. That makes it a commit barrier for the event log. Chronicle, JPA and MongoDB can’t join one atomic transaction, and cross-store transactions aren’t planned.

Failures come back as validation results. A broken constraint has the reason constraintViolation, and a concurrency failure has concurrencyViolation with the expected and actual sequence numbers. When a decision depends on something the command read, EventsWithConcurrencyScopes sets an exact scope per event source. A Chronicle read model can be a handler parameter with no annotation, resolved by the command key and the tenant’s store, and read-model values go through Chronicle’s release step before a query hands them out.

A reactor can pass a registered command to Arc’s real pipeline through ChronicleCommandSideEffectHandler, and gets no roles unless it declares @ExecuteCommandsAsSystem. For specs, CommandScenario finds an in-memory event log through ServiceLoader, so a command spec runs with no kernel. Testing with Arc and Chronicle follows the same idea on .NET.

The Chronicle sample is strict about tenants. Every request has to carry the x-cratis-tenant-id header, and the sample resolves the event store in exactly that namespace, with no default tenant to fall back on. Where that header should come from in a real deployment is the subject of Tenancy and identity end to end.

What the JVM doesn’t have

Arc for Kotlin runs on Spring Boot’s servlet stack only, so WebFlux and hosts outside Spring aren’t supported. Controller-based commands, static-file and SPA-fallback hosting, @FromRequest and @GenerateOneOf aren’t planned. Command operations and aggregate roots aren’t in the source, and Screenplay generation doesn’t target the JVM. Agreement with .NET is checked only in part: generated proxies against a captured .NET fixture, and HTTP behavior over nine common cases. MongoDB observables need a replica set, and Java’s delegated filters and validators need adapter beans.

Chronicle on the JVM

io.cratis:chronicle is the Kotlin and Java client, and its model is the one .NET developers know. @EventType goes on a data class or a record. A read model is a @ReadModel, and a @Reducer has one method per event. There’s no schema file and no registry to fill in. When the client connects, it finds the annotated artifacts on the classpath and registers them with the kernel in order.

In Kotlin every call to the kernel suspends. Java gets blocking bridges over the same surface and configures the client through ChronicleOptions. The Spring Boot starter, io.cratis:chronicle-spring-boot-starter, connects the client, registers the artifacts at startup, handles tenancy, identity and units of work per request, and gives you an injectable IEventStore. It targets Spring Boot 4 on the servlet stack, and its per-request features don’t apply to WebFlux.

By default the client constructs an artifact by calling a constructor with no parameters, or one where every parameter has a default. A reactor that needs a repository, or anything else from the container, needs an IArtifactActivator, and the starter supplies one.

A successful append means the fact is stored. The read model catches up asynchronously, so a read on the very next line can return null, and the client’s guide shows a bounded wait for the places that need one. Reactors take @OnceOnly and @Replay as they do on .NET. The client checks the kernel’s version when it connects and refuses a kernel it isn’t compatible with, and Arc for Kotlin’s Chronicle guide names a matching client and kernel pair. Running Chronicle in production covers the certificate-validation setup before connecting any client to a shared server.

Chronicle in TypeScript

@cratis/chronicle is on npm. Its artifacts are decorators, such as @eventType for an event and @projection or @reducer for a read model. An append goes from a ChronicleClient to an EventStore to its EventLog. The appending example, without its service wrapper and with CustomerId and Money in place of a string and a number:

@eventType()
class OrderPlaced {
    @field(CustomerId) customerId: CustomerId;
    @field(Money) total: Money;

    constructor(customerId: CustomerId, total: Money) {
        this.customerId = customerId;
        this.total = total;
    }
}

const result = await store.eventLog.append(
    orderId,
    new OrderPlaced(customerId, total)
);
if (!result.isSuccess) { /* decide whether to retry or surface a conflict */ }

eventType comes from @cratis/chronicle and field from @cratis/fundamentals. The append sends no concurrency check, so when the event depends on something you read first, give the append an explicit scope.

The client needs Node.js 22.19 or later, because it’s built on undici, and it fails to import on Node 20. Standard decorators and top-level await need TypeScript 5.2 or later and an ES module build. A read model is inferred from a @projection, a @reducer or an exported model with @fromEvent, its schema comes from the model type, and its id defaults to the class name. skipTlsValidation defaults to true, as on every client, so set it to false for any shared server.

Chronicle in Elixir

cratis_chronicle is on Hex, and it’s written for OTP. An event is a struct that uses Chronicle.Events.EventType with an id. A read model uses Chronicle.ReadModels.ReadModel with a from Event, set: [...] mapping, a model-bound projection the kernel runs. Reactors, reducers and seeders follow the same pattern, there are model-bound unique and unique-event-type constraints, and identity, correlation and causation are metadata scoped to the process. The same append:

defmodule MyApp.Events.OrderPlaced do
  use Chronicle.Events.EventType, id: "order-placed"

  defstruct customer_id: %MyApp.CustomerId{}, total: %MyApp.Money{}
end

case Chronicle.append(order_id, %MyApp.Events.OrderPlaced{
       customer_id: customer_id,
       total: total
     }) do
  :ok -> :ok
  {:error, _reason} = error -> error
end

Chronicle.append returns :ok or {:error, reason}, so there’s no sequence number to read back from a successful append. The client is a supervised child of your application, {Chronicle.Client, connection_string: ..., event_store: ..., otp_app: ...}. It connects and registers in the background with backoff, and until registration has finished, calls return {:error, :not_connected}. Lifecycle.wait_until(..., :registered) waits for it.

The client needs Elixir 1.18 or later and a kernel with contracts 19.19 or later. The Mint gRPC adapter needs enable_push: false, among other caveats. TLS has the same default as in TypeScript. Version 3.5.0 had defects, so take 3.5.1 or later.

Arc for TypeScript, from source

Arc for TypeScript is an early source preview of a TypeScript command and query server on Node.js. Its packages aren’t on npm, its version starts with 0, and its APIs can change. You run it from a clone, for example with yarn workspace @cratis/arc.core.sample.tasks start. Next to the RegisterTask command above, the Tasks sample has a live query:

@readModel()
export class TaskItem {
    @field(TaskId) id!: TaskId;
    @field(TaskTitle) title!: TaskTitle;

    @query()
    static observeAllTasks(tasks: Tasks): BehaviorSubject<TaskItem[]> { return tasks.observeAll(); }
}

An observable query returns an RxJS BehaviorSubject, an Observable or an async iterable. The older defineCommand and defineQuery functions with Zod schemas still work.

Besides Express 5, Fastify 5 and Hono 4 there’s a standalone Node host, and a Fetch API entry, @cratis/arc.core/fetch, for Next.js route handlers, Bun and Deno. Next.js App Router route handlers run on the Node runtime. Cloudflare Workers and the Next.js Edge runtime aren’t supported, and there’s no NestJS adapter. Data comes from tenant-scoped MongoDB, which observes changes through a replica set, or from Drizzle over SQLite or PostgreSQL, with no change tracking and no SQL observation. There are no automatic migrations.

The Chronicle integration, @cratis/arc.chronicle, is experimental. It appends returned events and resolves read models by key. Returned events and command operations can’t be combined, and immediate appends, aggregates and reactor command effects don’t join the single event-log batch. Wire behavior is compared with Arc on .NET in a paired suite for a bounded set of HTTP cases, which doesn’t amount to parity. A source-based arc-proxygenerator writes a bounded client that compiles against the published @cratis/arc and @cratis/arc.react.

Where the clients differ

These are the differences between the clients that change what your code has to do:

	.NET	Kotlin and Java	TypeScript	Elixir
Concurrency on append, by default	Reads the tail, sends the expected sequence number	`ConcurrencyScope.none`	No check	No check
Expect no matching event	`ExpectingNoMatchingEvent`	`withExpectsNoMatchingEvent()`	`EventSequenceNumber.beforeFirst` as the scope’s sequence number	No
What an append returns	`AppendResult`	`AppendResult`	`AppendResult`	`:ok` or an error tuple
Subject for personal data	Resolves `[Subject]`	The event source id	The event source id	The event source id
`AllowNewEncryptionKeyFor`	Yes	No	Yes	No
Reactors and replay	`[OnceOnly]`, `[Replay]`	`@OnceOnly`, `@Replay`	`@onceOnly()`, `@replay()`	Replayable, no once-only marker
Delivery identity for reactors	`ReactorDelivery.Id`	Build your own key	Build your own key	Build your own key

An append that depends on an earlier read needs an explicit scope on every client. The .NET default only catches an append that lands between its own read of the tail and its write, and the first append into an empty scope isn’t checked unless you opt in. Outside .NET, an append without a scope isn’t checked at all. The subject row matters for personal data: outside .NET, pass the subject explicitly whenever it isn’t the event source. Personal data in an event log explains what the subject decides. A reactor that needs a stable key for its side effects has one on .NET, and elsewhere you build it from the event store, the namespace, the sequence, the reactor and the position, as Reacting to facts describes. Seeding behaves differently per client as well, in what it targets and how it handles duplicates.

One kernel contract, four client defaults.

Storage is the server’s choice

Chronicle Server’s storage provider is MongoDB by default. The others are PostgreSql, MsSql, Sqlite, which is embedded and file-based, and InMemory, which is ephemeral and non-durable. The provider is a server setting, and no client, in any language, sees which one it is.

The client chooses the read-model sink, not the server’s provider. Every client registers read models against the MongoDB sink unless you set the default sink type, and the sinks don’t behave the same. On the SQL sink each read model gets a table, with a JSON column for collections, and [Index] creates no index there. Only MongoDB creates them. A live Chronicle read model in the UI is documented on MongoDB, where Arc watches it through change streams. Arc’s EF Core observation sees writes from other processes only on PostgreSQL and SQL Server, with provider setup, and not on SQLite.

On .NET, Arc’s queries can read from MongoDB, or from a relational database through EF Core. Arc’s guide to adding event sourcing follows the MongoDB branch, where a Chronicle projection fills the collection an unchanged query already reads, and doesn’t cover projecting into the EF Core branch’s tables.

Four clients, one kernel, storage chosen by the server.

Starting on the JVM

The templates create JVM applications too, with dotnet new cratis --language Kotlin or --language Java. cratis new does the same without the .NET SDK. Either way the JVM path needs JDK 17.

In a clone of the Arc for Kotlin repository, ./Samples/run.sh starts the Kotlin sample with in-memory storage and the React frontend on port 5173. --language java switches to Java, --database mongodb to MongoDB, and --chronicle starts a development kernel pinned by digest. The Chronicle sample runs backend-only. There are four samples, Kotlin and Java, each with and without Chronicle, and they’re applications you run from source.

The author feature carries over. On Spring Boot, RegisterAuthor is a @Command that returns an @EventType event, keyed by a @CommandKey, and the generated TypeScript feeds the same React form. What doesn’t carry over is the defaults. Set a concurrency scope wherever a decision depends on something you read, and pass the subject when it isn’t the event source. Every client, .NET included, skips certificate validation by default, allowing the development image’s self-signed certificate. Turn it on (skipTlsValidation=false) before connecting to anything shared, following Running Chronicle in production.

Previous: Part 11 — Testing with Arc and Chronicle
Next: Part 13 — Personal data in an event log

From script to stage · Part 11: Testing with Arc and Chronicle

Wed, 30 Sep 2026 09:11:00 GMT

Cratis: from script to stage, and the long run · Part 11 of 26

A spec for “a second author with the same name is rejected” can pass without the first author ever reaching the event log. On an Arc CommandScenario, Given seeds an in-memory read model, and nothing it seeds is appended to the log that Chronicle checks a [Unique] constraint against. The spec sits in the right folder and carries the right name, and the constraint it’s named after is never exercised.

That’s one of a handful of ways a spec in an event-sourced application can go green and prove nothing, and they all come from losing track of what a given kind of test actually runs. Cratis offers several kinds, from calling a method to running a real Chronicle in Docker, and for most rules the cheapest one is enough.

Start with the function

The decision in RegisterAuthor is a method. Call Handle(), compare the event it returns, and the rule is tested without starting a server or faking an event log. Arc’s testing guide makes that direct call the first choice for a deterministic decision:

#if DEBUG
public class when_deciding_to_register_an_author : Specification
{
    readonly AuthorName _name = "Jane Austen";
    AuthorRegistered _event = null!;

    void Because() => _event = new RegisterAuthor(AuthorId.New(), _name).Handle();

    [Fact] void should_record_the_name() => _event.Name.ShouldEqual(_name);
}
#endif

This spec uses JUnit; Cratis Specifications is a .NET library.

class RegisterAuthorTest {
    private val name = AuthorName("Jane Austen")

    @Test
    fun `records the name`() {
        val event = RegisterAuthor(AuthorId.new(), name).handle()

        assertEquals(name, event.name)
    }
}

This spec uses JUnit; Cratis Specifications is a .NET library.

class RegisterAuthorTest {
    private final AuthorName name = new AuthorName("Jane Austen");

    @Test
    void recordsTheName() {
        var event = new RegisterAuthor(AuthorId.newId(), name).handle();

        assertEquals(name, event.name());
    }
}

This spec uses Vitest.

describe('when deciding to register an author', () => {
    const name = new AuthorName('Jane Austen');
    let event: AuthorRegistered;

    beforeEach(() => {
        event = Object.assign(new RegisterAuthor(), { id: AuthorId.create(), name }).handle();
    });

    it('should record the name', () => { event.name.should.equal(name); });
});

The C# spec is written with Cratis Specifications, where Because() is the “when” and each [Fact] is a “then”. It needs no container and no fake.

An event is a record, so expecting one is an equality check on a value. The event doesn’t even repeat its own event source ID, because Chronicle keeps that in the event context, so the value Handle() returns is all there is to compare. The event-sourced commands lesson puts every branch of a decision in direct specs like this one.

Arc also splits getting data from deciding with it. Provide() fetches what a command needs, and Handle() decides with what it was given, so Handle can be a pure function of its arguments. Arc’s loan example gets a credit score in Provide() and rejects an applicant with no credit history, as in Validation all the way down. In each language below, the direct spec supplies the score to Handle() or handle() and doesn’t exercise that rejection:

[Command]
public record AssessLoan(LoanId LoanId, ApplicantId Applicant)
{
    public Result<CreditScore, ValidationResult> Provide(ICreditBureau bureau)
    {
        var score = bureau.GetScore(Applicant);
        return score is null
            ? ValidationResult.Error("No credit history", ["applicant"])
            : score;
    }

    public LoanAssessment Handle(CreditScore creditScore) => new(LoanId, creditScore);
}

#if DEBUG
public class when_assessing_a_loan : Specification
{
    readonly LoanId _loanId = LoanId.New();
    LoanAssessment _assessment = null!;

    void Because() => _assessment = new AssessLoan(_loanId, ApplicantId.New()).Handle(new CreditScore(800));

    [Fact] void should_return_the_assessment() =>
        _assessment.ShouldEqual(new LoanAssessment(_loanId, new CreditScore(800)));
}
#endif

@Command
data class AssessLoan(val loanId: LoanId, val applicant: ApplicantId) {
    suspend fun provide(bureau: CreditBureau): Any =
        bureau.score(applicant)
            ?: ValidationResult.error("No credit history", listOf("applicant"))

    fun handle(creditScore: CreditScore): LoanAssessment = LoanAssessment(loanId, creditScore)
}

class AssessLoanTest {
    @Test
    fun `handle returns the assessment`() {
        val loanId = LoanId(UUID.randomUUID())
        val command = AssessLoan(loanId, ApplicantId(UUID.randomUUID()))

        val assessment = command.handle(CreditScore(800))

        assertEquals(LoanAssessment(loanId, CreditScore(800)), assessment)
    }
}

@Command
public record AssessLoan(LoanId loanId, ApplicantId applicant) {
    public Object provide(CreditBureau bureau) {
        var score = bureau.score(applicant);
        return score == null
            ? ValidationResult.error("No credit history", List.of("applicant"))
            : score;
    }

    public LoanAssessment handle(CreditScore creditScore) {
        return new LoanAssessment(loanId, creditScore);
    }
}

class AssessLoanTest {
    @Test
    void handleReturnsTheAssessment() {
        var loanId = new LoanId(UUID.randomUUID());
        var command = new AssessLoan(loanId, new ApplicantId(UUID.randomUUID()));

        var assessment = command.handle(new CreditScore(800));

        assertEquals(new LoanAssessment(loanId, new CreditScore(800)), assessment);
    }
}

From Arc for TypeScript, an early source preview whose packages aren’t on npm yet:

@command()
export class AssessLoan {
    @field(LoanId) loanId!: LoanId;
    @field(ApplicantId) applicant!: ApplicantId;

    // provide() takes no parameters, so it resolves its services from the execution scope.
    async provide(): Promise<CreditScore | Outcome<never>> {
        const bureau = await currentServices().resolve(CreditBureau);
        const score = await bureau.findScore(this.applicant);
        return score ?? rejected(validation('No credit history', ['applicant']));
    }

    handle(creditScore: CreditScore): LoanAssessment {
        return new LoanAssessment(this.loanId, creditScore);
    }
}

describe('when assessing a loan', () => {
    it('should return the assessment', () => {
        const command = new AssessLoan();
        command.loanId = LoanId.create();
        command.applicant = ApplicantId.create();

        command.handle(new CreditScore(800)).should.deep.equal(new LoanAssessment(command.loanId, new CreditScore(800)));
    });
});

The command decisions lesson tests one command both ways, once directly and once through the pipeline. A Handle() that calls a service or reads the clock is still testable, but it isn’t a pure function just because it lives on a command.

Reducers work the same way. A reducer takes the event, the current state and the event context, and returns the next state. In .NET, the Processing sample tests its progress reducer by folding four events by hand, trimmed here to the action:

var reducer = new WorkItemProgressReducer();
_result = reducer.Opened(new WorkItemOpened("Prepare release", 10), null, ContextFor(0));
_result = reducer.Recorded(new ProgressRecorded(4), _result, ContextFor(1));
_result = reducer.Recorded(new ProgressRecorded(5), _result, ContextFor(2));
_result = reducer.Recorded(new ProgressRecorded(3), _result, ContextFor(3));
// then: _result.ShouldEqual(new WorkItemProgress(_workItemId, 10, 10, WorkPoints.NotSet, new EventSequenceNumber(3)));

The same fold against a Kotlin reducer, which takes the event, the current state and the event context.

val reducer = WorkItemProgressReducer()
result = reducer.opened(WorkItemOpened(WorkItemTitle("Prepare release"), WorkPoints(10)), null, contextFor(0))
result = reducer.recorded(ProgressRecorded(WorkPoints(4)), result, contextFor(1))
result = reducer.recorded(ProgressRecorded(WorkPoints(5)), result, contextFor(2))
result = reducer.recorded(ProgressRecorded(WorkPoints(3)), result, contextFor(3))
// then: assertEquals(WorkItemProgress(workItemId, WorkPoints(10), WorkPoints(10), WorkPoints.NOT_SET, 3), result)

The same fold against a Java reducer class.

var reducer = new WorkItemProgressReducer();
result = reducer.opened(new WorkItemOpened(new WorkItemTitle("Prepare release"), new WorkPoints(10)), null, contextFor(0));
result = reducer.recorded(new ProgressRecorded(new WorkPoints(4)), result, contextFor(1));
result = reducer.recorded(new ProgressRecorded(new WorkPoints(5)), result, contextFor(2));
result = reducer.recorded(new ProgressRecorded(new WorkPoints(3)), result, contextFor(3));
// then: assertEquals(new WorkItemProgress(workItemId, new WorkPoints(10), new WorkPoints(10), WorkPoints.NOT_SET, 3), result);

The same fold against a TypeScript reducer, whose method is named for its event class in camelCase.

const reducer = new WorkItemProgressReducer();
result = reducer.workItemOpened(new WorkItemOpened(new WorkItemTitle('Prepare release'), new WorkPoints(10)), undefined, contextFor(0));
result = reducer.progressRecorded(new ProgressRecorded(new WorkPoints(4)), result, contextFor(1));
result = reducer.progressRecorded(new ProgressRecorded(new WorkPoints(5)), result, contextFor(2));
result = reducer.progressRecorded(new ProgressRecorded(new WorkPoints(3)), result, contextFor(3));
// then: result.should.deep.equal(new WorkItemProgress(workItemId, new WorkPoints(10), new WorkPoints(10), WorkPoints.notSet, 3))

The same fold through the reduce/3 callback of an Elixir reducer.

result = WorkItemProgressReducer.reduce(%WorkItemOpened{title: "Prepare release", points: 10}, nil, context_for(0))
result = WorkItemProgressReducer.reduce(%ProgressRecorded{points: 4}, result, context_for(1))
result = WorkItemProgressReducer.reduce(%ProgressRecorded{points: 5}, result, context_for(2))
result = WorkItemProgressReducer.reduce(%ProgressRecorded{points: 3}, result, context_for(3))
# then: assert result == %WorkItemProgress{work_item_id: work_item_id, target: 10, recorded: 10, sequence_number: 3}

In .NET, the same sample calls its reactor directly. new CompletionSummaryReactor().Completed(new WorkItemCompleted(8, 8)) returns a CompletionSummarized event, with no event log and no command pipeline injected into the reactor. Chronicle’s reactor testing guide makes that split the default: the logic goes into a function that returns its side effect as a value, and the framework contract gets its own scenario. The default holds for as long as your reactors return their side effects instead of performing them.

Projections are the exception. A projection is attributes or a fluent definition, and there’s no method to call. The cheapest honest test of a projection runs the real projection engine, in memory.

One process, the real pipeline

A spec for registering an author looks like this. Here RegisterAuthor takes the author’s id and name:

#if DEBUG
public class when_registering_author : Specification
{
    readonly AuthorId _authorId = AuthorId.New();
    readonly CommandScenario<RegisterAuthor> _scenario = new();
    CommandResult _result = default!;

    async Task Because() =>
        _result = await _scenario.Execute(new RegisterAuthor(_authorId, "Jane Austen"));

    [Fact] void should_succeed() =>
        _result.ShouldBeSuccessful();

    [Fact] async Task should_have_appended_registered_event() =>
        await _scenario.ShouldHaveAppendedEvent<RegisterAuthor, AuthorRegistered>(_authorId, e => e.Name == "Jane Austen");
}
#endif

In Arc for Kotlin and Java, CommandScenario from io.cratis:arc-testing runs the real command pipeline, and the Chronicle integration gives it an in-memory event log.

class RegisterAuthorScenarioTest {
    private val authorId = AuthorId.new()

    @Test
    fun `registers the author`() = runBlocking {
        val scenario = CommandScenario(module, RegisterAuthor::class.java)

        val result = scenario.execute(RegisterAuthor(authorId, AuthorName("Jane Austen")))

        result.shouldSucceed()
        scenario.chronicle().shouldHaveAppendedEvent(authorId.value.toString(), AuthorRegistered::class.java)
    }
}

In Arc for Kotlin and Java, CommandScenario from io.cratis:arc-testing runs the real command pipeline, and the Chronicle integration gives it an in-memory event log.

class RegisterAuthorScenarioTest {
    private final AuthorId authorId = AuthorId.newId();

    @Test
    void registersTheAuthor() {
        CommandScenario<RegisterAuthor> configured = new CommandScenario<>(module, RegisterAuthor.class);
        ChronicleCommandScenario chronicle = ChronicleCommandScenarios.chronicle(configured);

        try (BlockingCommandScenario<RegisterAuthor> scenario = new BlockingCommandScenario<>(configured)) {
            scenario.execute(new RegisterAuthor(authorId, new AuthorName("Jane Austen"))).shouldSucceed();
        }

        chronicle.shouldHaveAppendedEvent(authorId.value().toString(), AuthorRegistered.class);
    }
}

In Arc for TypeScript, ChronicleCommandScenario from @cratis/arc.chronicle/testing runs the real command pipeline over an in-memory event log.

describe('when registering author', () => {
    const authorId = AuthorId.create();
    let scenario: ChronicleCommandScenario<RegisterAuthor>;
    let result: Awaited<ReturnType<typeof scenario.execute>>;

    beforeEach(async () => {
        scenario = ChronicleCommandScenario.for(RegisterAuthor, AuthorRegistered);
        result = await scenario.execute({ id: authorId, name: new AuthorName('Jane Austen') });
    });

    afterEach(async () => { await scenario.dispose(); });

    it('should succeed', () => { result.shouldBeSuccessful(); });

    it('should have appended registered event', () => {
        result.shouldHaveAppendedEvent(AuthorRegistered, authorId.toString());
    });
});

It runs Arc’s command pipeline and an in-memory Chronicle event log in one process, without a Chronicle server, and checks the decision and the recorded fact. HTTP routing, the auth middleware, a real read-model store and redelivery need a different kind of test. In .NET, Specifications supplies the given/when/then base on xUnit or NUnit. Synopsis can turn recognized specification shapes into navigable HTML documentation, though it doesn’t run them.

In .NET, CommandScenario<TCommand> runs authorization, the validators, Provide() and Handle(), and builds the command result, which is the path a request takes once routing has found the command. QueryScenario<TReadModel> does the same for a static query on a read model. With Cratis.Arc.Chronicle.Testing referenced, a command scenario gains Given, EventLog and AppendedEvents, and that’s where ShouldHaveAppendedEvent comes from. Arc for Kotlin and Java have a CommandScenario and a QueryScenario in io.cratis:arc-testing, and the source preview of Arc for TypeScript has a CommandScenario.

A direct spec and a scenario spec answer different questions about the same command. The direct one says the decision is right for the inputs you chose. The scenario says the command still reaches that decision when authorization, validation and Provide() run in front of it, and that the event it returned was appended.

Chronicle’s own scenarios

In .NET, Chronicle’s testing package, Cratis.Chronicle.Testing, runs the real projection and reducer engines, constraint evaluation and reactor dispatch over in-memory storage. Three scenarios divide the work:

Scenario	Runs	Doesn’t reach
`EventScenario`	Appends, constraints and sequencing	Network serialization, the kernel connection, storage writes
`ReadModelScenario<T>`	A projection or reducer building state from events	Sink writes, MongoDB queries, change streams
`ReactorScenario<T>`	Dispatch, dependency injection, read-model materialization, routing of side effects	Observer registration, kernel dispatch, redelivery

In .NET, the Author read model from the hub declares its projection with [FromEvent<AuthorRegistered>], and a ReadModelScenario picks up that model-bound form on its own, as it does a fluent projection or a reducer:

#if DEBUG
public class when_an_author_is_registered : Specification
{
    readonly AuthorId _authorId = AuthorId.New();
    readonly AuthorName _name = "Jane Austen";
    readonly ReadModelScenario<Author> _scenario = new();

    async Task Because() =>
        await _scenario.Given.ForEventSource(_authorId).Events(new AuthorRegistered(_name));

    [Fact] void should_have_the_name() => _scenario.Instance!.Name.ShouldEqual(_name);
}
#endif

The Kotlin client’s ReadModelScenario folds a reducer.

class AuthorReducerTest {
    private val authorId = AuthorId.new()
    private val name = AuthorName("Jane Austen")

    @Test
    fun `the author has the name`() = runBlocking {
        val scenario = ReadModelScenario<Author>(AuthorReducer())

        val author = scenario.fold(authorId.value.toString(), AuthorRegistered(name))

        assertEquals(name, author!!.name)
    }
}

The Java client calls the reducer method directly.

class AuthorReducerTest {
    private final AuthorName name = new AuthorName("Jane Austen");

    @Test
    void theAuthorHasTheName() {
        var reducer = new AuthorReducer();

        var author = reducer.registered(new AuthorRegistered(name));

        assertEquals(name, author.name());
    }
}

The TypeScript client’s ReadModelScenario evaluates a @fromEvent model-bound projection. It refuses protected fields, including fields whose concept is marked @pii(). The series’ AuthorName keeps that marking and needs a kernel-backed test. This spec uses separate, unprotected test fixtures and checks only projection behavior, not personal-data handling.

class TestAuthorName extends ConceptAs<string> {
    static readonly valueType = String;
}

@eventType()
class TestAuthorRegistered {
    @field(TestAuthorName) @unique('UniqueAuthorName') name: TestAuthorName;
    constructor(name = new TestAuthorName('')) { this.name = name; }
}

@fromEvent(TestAuthorRegistered)
class TestAuthor {
    @field(AuthorId) id!: AuthorId;
    @field(TestAuthorName) name = new TestAuthorName('');
}

describe('when an author is registered', () => {
    const authorId = AuthorId.create();
    const name = new TestAuthorName('Jane Austen');
    const scenario = new ReadModelScenario(TestAuthor);

    beforeEach(async () => {
        await scenario.given.forEventSource(authorId.toString()).events(new TestAuthorRegistered(name));
    });

    it('should have the name', async () => {
        const author = await scenario.instance;
        author!.name.should.deep.equal(name);
    });
});

This is the uniqueness rule’s natural home too. In .NET, an EventScenario appends to its in-memory event log, so a first registration seeded through its Given is in the log the constraint is checked against, and a second append with the same name is rejected there. Assert the violation by the constraint’s name with ShouldHaveConstraintViolationFor:

[EventType]
public record AuthorRegistered([property: Unique(name: "UniqueAuthorName")] AuthorName Name);

#if DEBUG
public class when_registering_a_taken_author_name : Specification
{
    readonly EventScenario _scenario = new();
    AppendResult _result = default!;

    Task Establish() =>
        _scenario.Given.ForEventSource(AuthorId.New()).Events(new AuthorRegistered("Jane Austen"));

    async Task Because() =>
        _result = await _scenario.When.ForEventSource(AuthorId.New()).Events(new AuthorRegistered("Jane Austen"));

    [Fact] void should_be_rejected() => _result.ShouldBeFailed();

    [Fact] void should_report_the_constraint() => _result.ShouldHaveConstraintViolationFor("UniqueAuthorName");

    void Destroy() => _scenario.Dispose();
}
#endif

The Kotlin client’s EventScenario doesn’t check constraints.

This spec uses Vitest and the same TestAuthorName and TestAuthorRegistered fixtures. Since @cratis/chronicle 6.31.4, EventScenario accepts string and boolean concepts, comparing their serialized scalar values. Its content still has to fit the supported flat, unprotected string/boolean schema; numeric, Guid, date and nested object fields remain unsupported. It also refuses the series’ @pii()-marked AuthorName, so testing the real AuthorRegistered still needs a kernel. This fixture tests uniqueness without personal-data handling.

class TestAuthorName extends ConceptAs<string> {
    static readonly valueType = String;
}

@eventType()
class TestAuthorRegistered {
    @field(TestAuthorName) @unique('UniqueAuthorName') name: TestAuthorName;
    constructor(name = new TestAuthorName('')) { this.name = name; }
}

describe('when registering a taken author name', () => {
    let result: AppendResult;

    beforeEach(async () => {
        const scenario = new EventScenario({ artifacts: { eventTypes: [TestAuthorRegistered] } });
        await scenario.given.forEventSource(AuthorId.create().toString()).events(new TestAuthorRegistered(new TestAuthorName('Jane Austen')));
        result = await scenario.when.forEventSource(AuthorId.create().toString()).event(new TestAuthorRegistered(new TestAuthorName('Jane Austen')));
    });

    it('should be rejected', () => { result.isSuccess.should.be.false; });

    it('should report the constraint', () => {
        result.constraintViolations.map(violation => violation.constraintId).should.contain('UniqueAuthorName');
    });
});

The same helper exists on a CommandResult and on an append result.

In .NET, ReactorScenario delivers each event once. To check that a reactor is idempotent, deliver the same event twice yourself and look at what happened the second time.

Outside .NET the scenarios are fewer. The Kotlin client has EventScenario and a ReadModelScenario for reducers. TypeScript has all three, with ReadModelScenario covering reducers and the projections it supports. Java tests appends and calls reducers directly, and Elixir has no scenarios. Beyond .NET covers the clients themselves.

Green, and proving nothing

In-process scenarios are fast, so they’re trusted, and a few mistakes make them pass without testing anything. Three are easy to make with the author feature.

The first is a discarded assertion. Chronicle’s ShouldHaveAppendedEvent and ShouldHaveTailSequenceNumber on an event sequence are genuinely asynchronous. In a void fact that doesn’t await them, a failure lands on a Task that nobody observes, and the spec passes whatever the code did. The compiler doesn’t warn about it outside an async method. Make the fact async Task and await every Should* call that returns a task. Chronicle’s analyzer, CHR0039, reports the ones you miss, for Chronicle’s and Arc’s testing packages alike.

The second is a read model nobody seeded. When a validator, Provide() or Handle() asks for a read model that doesn’t exist for the command’s key, no rule runs at all, and the command is still rejected, with a single DependencyUnavailable validation result. ShouldNotBeSuccessful() passes, and it keeps passing after the rule the spec is named after has been deleted. ShouldHaveValidationErrors() refuses a result whose only errors carry that reason. An unhappy-path spec asserts both ShouldNotBeSuccessful() and ShouldHaveValidationErrors(), and a spec about authorization asserts ShouldNotBeAuthorized().

The third is the one from the opening. Given on a CommandScenario materializes read models. A precondition the constraint has to see goes through the scenario’s EventScenario.Given, which appends it to the in-memory log before the command runs.

Two more are worth knowing. Validate(command) runs the command filters, and authorization comes before validation, so a validate-only spec on an [Authorize] command with no identity registered is denied before its rule runs. And an expected value computed in the spec with the same expression as the code under test agrees with it by construction. Write the literal.

Three green specs, and what each one never reached.

Examples in the model

A .play slice in Screenplay can carry given/when/then examples of its own, written against the model. Adapted from the Screenplay docs’ example, with for naming the event source instead of a property on the event:

specification RegisteringADraftInvoice
  given CustomerRegistered
    for "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    name = "Acme Corp"
  when RegisterInvoice
    invoiceId  = "9c858901-8a57-4791-81fe-4c455b099bc9"
    customerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  then InvoiceRegistered
    for "9c858901-8a57-4791-81fe-4c455b099bc9"
    customerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

A then can also name a read model, a query result, an error or a denial. The experimental Stage specification runner, a container job, compiles the .play files, checks each specification against the model and writes the outcome to results.json. With the default engine, nothing else starts: no Arc, no Chronicle, no database and no network. The opt-in semantic engine instead runs commands through Arc’s in-memory command pipeline, against an in-memory Chronicle event log. It shows that the example fits the model, and it says nothing about whether the C# behaves that way. Reactions aren’t executed at the model level either. Screenplay and Stage and Scene go into the model side.

A real Chronicle and a running host

Some behavior only exists with a real host. Routing, authentication middleware, real storage writes, change streams, redelivery and tenant routing from AuthProxy’s headers all sit outside one process with in-memory storage.

For .NET, Cratis.Chronicle.XUnit.Integration has two fixtures. ChronicleInProcessFixture runs the kernel inside the test process with MongoDB in a container through Testcontainers, and ChronicleOutOfProcessFixture runs the kernel in a container of its own. Both need Docker. A real kernel processes asynchronously, so IEventAppendCollection collects appends as they happen, and WaitForCount waits for the number you expect.

Arc has no packaged test host. A hosted spec is an HTTP client pointed at a running application, next to a Chronicle fixture that a project defines as an xUnit collection. The Library sample does this for the author feature. Its and_there_already_exists_one_with_same_name spec appends an existing author straight to the event log, posts a RegisterAuthor with the same name to /api/authors/register, and asserts that the command failed. It expects the application to be running on localhost:8080.

That spec covers the whole uniqueness rule end to end, and it costs Docker, a kernel shared across tests and a slower run.

The frontend

The generated proxies aren’t something to test. They’re output, and a change in the backend shows up in them on the next build. What’s worth a spec on the frontend is the code you wrote around them.

The convention Cratis recommends for application frontends mirrors the backend. Specs use Vitest, Sinon and Chai’s should, and files follow for_<Subject>/when_<context>/and_<extra>.ts. View models are plain classes you can construct without React, pure helpers get tested first, and there are no snapshots.

Test generated validation for the forms that depend on it, especially the omissions and dropped conditions in Validation all the way down. On the server side of TypeScript, Arc for TypeScript has a testing package, @cratis/arc.testing, and like the rest of Arc for TypeScript it’s a source preview.

Specs that read as sentences

Given, when and then map straight onto event sourcing. Given is the facts that already happened, or the read-model state that follows from them. When is the command, the append or the event under test. Then is the events that were appended, the command result, the read model or the side effect.

Folder names carry the same structure. A spec at for_RegisterAuthor/when_registering/and_the_name_is_taken.cs reads as a sentence about the feature, and a folder of them reads as its behavior. The word when appears only in when_ folder names, and each should_ fact finishes the sentence. One behavior goes in each spec. Logging, trivial getters and plain delegation don’t get specs of their own.

Specifications gives that shape to .NET on xUnit or NUnit, in the style of Machine.Specifications: Establish() is the given, Because() the when, the facts the then, and Destroy() cleans up. The methods are optional, can return void or Task, and run across the inheritance chain. None of it is required. Chronicle’s scenarios work with any test framework, and a plain xUnit test can call Handle() just as well.

How much of each

Cheapest first. Most specs belong on the first two steps.

Start the author suite with direct specs for each branch of the RegisterAuthor decision. One CommandScenario spec shows the command still decides that way with validation and authorization in front of it and appends what it returned. A ReadModelScenario covers the Author projection, and an EventScenario covers the [Unique] constraint with the first author actually in the log. One hosted spec sends the same name twice through a running application.

All but the last run in one process with nothing to start. The hosted spec is the only one that needs Docker, a kernel and a running application.

Previous: Part 10 — Tenancy and identity end to end
Next: Part 12 — Beyond .NET

From script to stage · Part 10: Tenancy and identity end to end

Wed, 30 Sep 2026 09:10:00 GMT

Cratis: from script to stage, and the long run · Part 10 of 26

AuthProxy forwards the tenant it resolved in a header named Tenant-ID. Arc, left on its defaults, reads the tenant from a header named x-cratis-tenant-id. Put the two together without configuring either, and Arc ignores the tenant AuthProxy resolved. A request with no x-cratis-tenant-id header gets no tenant, and Arc’s Chronicle integration sends it to Chronicle’s Default namespace. Nothing fails, and every organization ends up in one event log. A request that carries x-cratis-tenant-id gets whatever tenant the caller put there, because AuthProxy passes that header through.

The workaround is one line, options.UseHeaderTenancy("Tenant-ID"). The fix on the proxy side is tracked in the public issue Cratis/AuthProxy#157.

Keeping author names unique within an organization rests on a tenant ID that travels from the edge to the database. Take a made-up week with the mismatch in place. Contoso tries to register Jane Austen and is told the name is taken, because Acme registered her on Monday and both organizations are writing to Default. On Friday, Acme’s admin asks why their author list shows names they’ve never seen. Every step behind that week is a default, and each one is sensible on its own. Follow one tenant, acme, from sign-in to storage, and past the edge a missing tenant turns into Default at each hop, without an error.

At every hop, find out what “no tenant” turns into.

AuthProxy sits in front of the backend and the frontend. It handles OIDC and OAuth2 sign-in, plus JWT bearer authentication, resolves a tenant for each request and forwards it downstream in a header named Tenant-ID. Tenant resolution is a list of strategies under TenantResolutions, and resolving from a token claim is one entry in it:

{
  "Cratis": {
    "AuthProxy": {
      "TenantResolutions": [
        { "Strategy": "Claim", "Options": { "ClaimType": "tid" } }
      ]
    }
  }
}

AuthProxy matches the claim’s value against the source identifiers you configure for each tenant. It can also require configured claims, such as a role or a group, before it forwards a request. Let the backend accept traffic from the proxy and nothing else, because a service reachable directly believes whatever headers a caller sends it.

A user who has signed in but belongs to no tenant yet needs somewhere to go. Ante is a separate invitation and onboarding lobby for that moment, where they can join an existing tenant, create one by invitation, or self-register. It records the acceptance and publishes it for your application to act on. Membership, provisioning and email stay yours.

How the edge picks a tenant

The strategies run in order until one succeeds, so a list with Host first and Claim second tries the request host before the token. For Host, Claim and Route, a strategy finds a source identifier and looks it up in the Tenants registry, and what travels downstream is the registry key, acme, instead of the raw value of the tid claim. SubHost takes the subdomain as it is, with no lookup. For that strategy, AuthProxy’s tenant verification can ask your backend whether the tenant exists, and a tenant that exists still isn’t proof that this caller belongs to it.

Before any of that runs, AuthProxy’s tenancy middleware removes inbound identity headers and any inbound Tenant-ID. A caller can’t hand the backend a tenant of its own choosing under that name. The resolved value is then added to the proxied request.

A request can also leave the edge with no tenant at all. If strategies are configured and none resolves, a signed-in user gets a 403 page explaining that they belong to no organization, an anonymous caller gets a 401, and with a lobby configured for it the user is redirected there instead. If TenantResolutions is empty, the request goes through with no tenant and no Tenant-ID header. Sign-in, invitation, registration and paths declared anonymous go through without a tenant as well.

Who the user is

AuthProxy authenticates before a request reaches your code, and it forwards the signed-in identity downstream in the x-ms-client-principal, x-ms-client-principal-id and x-ms-client-principal-name headers, with the principal itself as base64-encoded JSON. It removes inbound copies of those headers first, so a caller can’t pass a principal of its own through the proxy.

Arc doesn’t sign anyone in. The host establishes the principal, and Arc’s authorization attributes check it on each command and query: [Authorize] for any authenticated user, [Roles] for any of the listed roles, a named policy, or [AllowAnonymous]. With no requirement declared, the built-in evaluator allows the call. A role isn’t ownership either. “Only the librarian who registered an author may rename it” is a rule the application writes, by deriving the owner from the principal and constraining the query, and Arc has no universal mapping from a claim to an owner.

For the frontend, an identity details provider composes application-specific details from the authenticated principal, and Arc serves them at /.cratis/me. The endpoint exists only when a provider is registered. The .cratis-identity cookie that carries those details to the browser is unsigned presentation data the client controls, so nothing on the backend should ever authorize on it. /.cratis/me doesn’t authorize commands or queries.

Identity and tenant arrive by the same route, as headers the proxy sets. Arc trusts both, and the difference is in what Arc does with them. The principal goes through authorization. The tenant only selects where data goes.

The header hop into Arc

Arc reads the tenant from a header too, but its default header name is x-cratis-tenant-id, so point it at the proxy’s header. The tenant resolver docs show the setting with a custom name, and in .NET the extension method lives in Cratis.Arc.Tenancy:

using Cratis.Arc;
using Cratis.Arc.Tenancy;

builder.AddCratisArc(options =>
{
    options.UseHeaderTenancy("Tenant-ID");
});

In Arc for Kotlin and Java this is a Spring property. A request without the header has no tenant (null) unless cratis.arc.tenancy.required is set, which rejects it with a 400, and the Chronicle integration uses the default event store for a null tenant.

cratis.arc.tenancy.header-name=Tenant-ID

cratis.arc.tenancy.header-name=Tenant-ID

In Arc for TypeScript this is the tenancy.httpHeader option. A request without the header has no tenantId (undefined) unless tenancy.required is set, which answers 400, and the Chronicle integration then appends in the Default namespace.

import { ArcApplication } from '@cratis/arc.core';

const builder = ArcApplication.createBuilder({
    tenancy: { httpHeader: 'Tenant-ID' }
});

In .NET, with the default resolvers, a missing header doesn’t reject the request. It selects the unset tenant and then Chronicle’s default namespace, so decide deliberately whether that’s allowed.

Nothing sets the name for you, and putting AuthProxy in front of Arc doesn’t change which header Arc reads. That’s the mismatch in Cratis/AuthProxy#157, and the one line above is the workaround.

Setting the name closes a second gap as well. AuthProxy removes the inbound headers it owns, and x-cratis-tenant-id isn’t one of them. An Arc left on its default reads a tenant from a header the proxy doesn’t remove. Configure Tenant-ID, and strip x-cratis-tenant-id at any ingress that could pass it through, the same treatment Arc recommends for the client-supplied fallback header of its subdomain resolver.

In .NET, when the header Arc reads is missing, the resolver returns an empty string and the tenant context becomes TenantId.NotSet. The tenant is resolved once per async execution flow and cached, so every service in a request sees the same value. An explicit tenant scope wins over the resolver, which matters for background work further down.

Non-ASCII tenant IDs have a seam of their own. AuthProxy sends a tenant ID that isn’t plain ASCII in RFC 8187 encoded form, and Arc’s header resolver passes the value through as it arrives. Tenant IDs that are plain lowercase labels, such as acme, never meet it, and the next hop gives a second reason to keep them that way.

The tenant becomes a namespace

A Chronicle namespace is a logical partition within one event store. Events, projections, reducers and read models are processed per namespace, and when no namespace is given, Chronicle uses Default.

Arc’s Chronicle integration is optional, and Arc runs without it. Once you add it, with WithChronicle or the all-in-one AddCratis, it registers TenantNamespaceResolver as Chronicle’s namespace resolver, and your own options callback runs afterwards, so you can replace it. The resolver is short:

public EventStoreNamespaceName Resolve()
{
    var tenantId = tenantIdAccessor.Current;
    return tenantId.IsDefault
        ? EventStoreNamespaceName.Default
        : new EventStoreNamespaceName(tenantId.Value);
}

IsDefault is true for two values, TenantId.NotSet and a tenant actually named Default. Both land in Chronicle’s Default namespace, so a tenant called “Default” and a request with no tenant read and write the same data. Any other tenant ID becomes the namespace name exactly as it is.

That cuts both ways. A wrong but accepted tenant ID sends the write to that tenant’s namespace, faithfully. Isolation follows the tenant resolver, and the mapping selects a namespace without authorizing anything. Caller-controlled headers, query strings and hosts don’t prove membership. Check membership before any tenant-scoped work, and test the no-tenant case.

On MongoDB the namespace also becomes part of a database name, so it has to be a legal one. MongoDB rejects / \ . " $ * < > : | ?, the space and the null character, and caps a database name at 63 bytes. A display-style tenant ID such as Acme Books Ltd. won’t fit. Chronicle checks the composed name and throws InvalidDatabaseName, naming the event store, the namespace and the offending character, before the driver fails somewhere later. Arc’s subdomain resolver already insists on a letter-digit-hyphen label of up to 63 characters. AuthProxy registry keys in the same shape keep all three products in agreement about what a tenant ID can look like.

This hop is where the author feature’s rule becomes per organization. A constraint is scoped to its event sequence and namespace, so with a namespace per tenant, Acme and Contoso can each register Jane Austen. In the made-up week, they were sharing one namespace.

Selecting a tenant isn’t authorizing it.

Where the read models land

Events and read models aren’t stored under the same names, and the default namespace has one asymmetry. From Chronicle’s namespace naming, for an event store named Ada on MongoDB:

Holds	Namespace `Default`	Namespace `acme`
Event store wide state	`Ada+es`	`Ada+es`
Event sequences	`Ada+es+Default`	`Ada+es+acme`
Read models	`Ada`	`Ada+acme`

Read models of the default namespace go into the bare event store name, while event sequences carry a suffix for every namespace, Default included. Query read models from outside Chronicle with a database name you composed by hand, and Ada+Default is a database nothing writes to. Reads from it come back empty instead of failing.

Read models of the default namespace use the bare store name.

Arc’s MongoDB integration uses the same shape, the configured base database for a default tenant and base+tenant for any other, and both NotSet and Default resolve to the base name. For Arc’s direct MongoDB queries to find what Chronicle materialized, the base database and Chronicle’s read-model sink have to line up, and checking that alignment is your job. With EF Core, Arc uses the connection string you configured, pooled contexts included, and appends no tenant. Separate databases, schemas or enforced filters are yours to build and test.

Work that has no request

A scheduled job, or a reactor that starts work later, has no header to read, so it names its tenant. Arc’s command pipeline shows the pattern with a cart:

public class TenantCartJob(ITenantScope tenants, ICommandPipeline pipeline)
{
    public async Task<CommandResult<CartLineId>> Add(TenantId tenant, Sku sku, Quantity quantity, CancellationToken stoppingToken)
    {
        using (tenants.Begin(tenant))
        {
            return await pipeline.Execute<CartLineId>(new AddItemToCart(sku, quantity), stoppingToken);
        }
    }
}

In Arc for Kotlin and Java the tenant travels in the CommandExecutionOptions passed to the pipeline.

class TenantCartJob(
    private val pipeline: CommandPipeline,
    private val services: ServiceResolver
) {
    suspend fun add(tenant: TenantId, sku: Sku, quantity: Quantity, principal: ArcPrincipal): CommandResult<*> =
        pipeline.execute(
            AddItemToCart(sku, quantity),
            CommandExecutionOptions(UUID.randomUUID(), principal, services, tenant.value())
        )
}

In Arc for Kotlin and Java the tenant travels in the CommandExecutionOptions passed to the pipeline.

public class TenantCartJob {
    private final BlockingCommandPipeline pipeline;
    private final ServiceResolver services;

    public TenantCartJob(BlockingCommandPipeline pipeline, ServiceResolver services) {
        this.pipeline = pipeline;
        this.services = services;
    }

    public CommandResult<?> add(TenantId tenant, Sku sku, Quantity quantity, ArcPrincipal principal) {
        return pipeline.execute(
            new AddItemToCart(sku, quantity),
            new CommandExecutionOptions(UUID.randomUUID(), principal, services, tenant.value()));
    }
}

In Arc for TypeScript the tenant is the tenantId of the execution context passed to executeCommand, and no tenant is resolved for a direct call.

export class TenantCartJob {
    constructor(private readonly app: ArcApplication) {}

    add(tenant: string, sku: Sku, quantity: Quantity, principal: Principal, signal: AbortSignal): Promise<CommandResult> {
        return this.app.server.executeCommand('AddItemToCart', { sku: sku.value, quantity: quantity.value }, {
            correlationId: randomUUID(),
            principal,
            tenantId: tenant,
            signal,
            allowedSeverity: Severity.Warning
        });
    }
}

In .NET, Begin refuses an empty tenant, and the explicit scope wins over the configured resolver, even during an HTTP request. Dependency injection is where it goes wrong. A tenant-scoped service, such as Chronicle’s event store or a DbContext, that was already resolved in an existing DI scope stays bound to that scope’s original tenant after the current tenant changes. Create the DI scope inside the tenant scope. The Execute call above takes no scope of its own and creates one for you. Arc for Kotlin and Java take the tenant in CommandExecutionOptions, and Arc for TypeScript in the execution context passed to executeCommand.

The tools you look through

Every cratis chronicle command that works on a namespace takes -n or --namespace. Leave it out, and the CLI uses the active context’s namespace, or Default when the context doesn’t set one.

So when Acme reports that a view stopped updating, cratis chronicle failed-partitions list lists the failed partitions in Default, and an empty list tells you nothing about Acme. Ask for the namespace you mean:

cratis chronicle failed-partitions list -n acme

Add --debug to any command and the CLI prints the event store and namespace it resolved, each with where the value came from: the option, the context or the built-in default. A context with a namespace saves typing, and it also means the same command answers for a different tenant depending on which context is active. State-changing commands such as observers replay and observers retry-partition take the same -n with the same fallback. They ask for confirmation first, and the target namespace is worth reading before you answer.

Workbench asks you to select the event store and a namespace you’re authorized to inspect, and to confirm both before reading anything into what it shows. Being able to open a namespace in a tool isn’t permission to change anything in it.

Why not a deployment per tenant?

The strongest case against all of this is to share nothing. Give each tenant its own deployment and its own database, and no header mismatch can mix their data. For a handful of large tenants with contractual separation, that’s a reasonable choice, and Arc supports it: UseFixedTenancy resolves every request to one tenant ID, decided once for the whole deployment.

The cost is that every tenant becomes another deployment to upgrade, migrate, back up and watch. Namespaces put many tenants on one Chronicle kernel and one event store, each with its own data. In exchange, the selection path has to be right at every hop, which is why it deserves tests.

A second objection is that the defaults should reject a missing tenant. Arc does fail early in one place. Configure the subdomain resolver without a usable base domain and the application refuses to start, because otherwise every request would take its tenant from a header any client can set. For a missing tenant, though, the resolvers select Default on purpose, so single-tenant applications work with no tenant configuration at all. Arc for .NET has no switch that rejects a request without a tenant, although Arc for Kotlin and Java (cratis.arc.tenancy.required) and Arc for TypeScript (tenancy.required) do. In .NET that check is yours, as middleware or an authorization rule, next to the membership check.

Seven tests before the second tenant signs up

Send a request with no tenant header. Decide whether default-namespace access is allowed, then assert either that the request is rejected or that it lands in Default by design.
Make sure nothing in your tenant registry can resolve to a tenant named Default, or that you’re content with it sharing data with requests that carry no tenant.
Through the proxy, as an Acme user, send Tenant-ID: contoso and x-cratis-tenant-id: contoso, and assert that the write lands in acme.
Register the same author name in acme and in contoso. Both should succeed, and if the second is rejected, your namespaces aren’t per tenant.
Run a background job under ITenantScope.Begin, with the DI scope created inside the tenant scope, and check which namespace its events land in.
Query read models directly for the default tenant and for acme, and assert that both return data. That one catches Ada+Default.
Run your usual diagnostic command with --debug, and check that the namespace it reports is the one you meant.

None of these proves that a caller belongs to a tenant. Membership is a separate rule, checked against your own data, and its spec belongs in the same suite as these seven.

Previous: Part 09 — Cratis Components, the React layer
Next: Part 11 — Testing with Arc and Chronicle

From script to stage · Part 09: Cratis Components, the React layer

Wed, 30 Sep 2026 09:09:00 GMT

Cratis: from script to stage, and the long run · Part 09 of 26

The dialog that registers a name in the cratis template has one field and no event handlers. It still keeps its button disabled while validation fails, shows a spinner while the command runs, puts a server’s rejection under the field it names and closes only when the command succeeds. Two packages share that work. Arc’s React package runs the command and holds the form state, and Cratis Components draws the dialog, the field and the buttons around it.

The cratis template, which dotnet new cratis and cratis new both scaffold (see Cratis: from script to stage, and the long run), already has the two screens the author feature needs, a list page and a register dialog, and both are built with Components 4. Live UIs covered the live query behind the list and the props of CommandDialog.

Arc underneath, Components on top

Arc’s @cratis/arc.react owns the runtime and the state. That covers the <Arc> provider with the command and query runtime, CommandForm with its field registry and validation state, the dialog host behind useDialog, and the TypeScript the proxy generator writes for each command and query. Components 4 owns the React markup, its public types, the design tokens and the stable part names that style hooks target. CommandDialog shows the split directly. Its body is Arc’s CommandForm wrapped around a Components Dialog.

Components 4 renders its own HTML. Its package manifest declares no PrimeReact, PrimeIcons or PrimeUI dependency, and a release gate checks the emitted JavaScript and declarations for Prime imports. React Aria supplies focus, keyboard, overlay and date behavior inside some components, and none of its types or class names are part of the public contract.

The package root is for setup only. Every component comes from its own subpath, such as @cratis/components/CommandDialog or @cratis/components/DataPage, and the subpaths fall into three groups. Foundation covers forms, dialogs, tables, pages, filters and notifications. Advanced React covers chat, schema and object editors, a time scrubber and a toolbar. Spatial is Canvas and PivotViewer, the only two that need the optional pixi.js peer. The groups describe dependencies, and they don’t rank stability. Next to React 19 and the Arc range that Live UIs lists, Components needs @cratis/fundamentals from 7.10.3 within 7.

An application mounts both providers and tells Arc which dialogs to use for confirmations and busy states:

import 'reflect-metadata';
import { Arc } from '@cratis/arc.react';
import { DialogComponents } from '@cratis/arc.react/dialogs';
import { CratisComponentsProvider } from '@cratis/components';
import { BusyIndicatorDialog, ConfirmationDialog } from '@cratis/components/Dialogs';
import { Authors } from './Authors/Authors';

export const App = () => (
    <Arc>
        <CratisComponentsProvider value={{ locale: 'en-US' }} toaster>
            <DialogComponents confirmation={ConfirmationDialog} busyIndicator={BusyIndicatorDialog}>
                <Authors />
            </DialogComponents>
        </CratisComponentsProvider>
    </Arc>
);

<Arc> is what the generated proxies run against, and CratisComponentsProvider doesn’t replace it. The Components provider holds the locale, the labels Components renders itself, an optional renderer and, with toaster, the region where notifications appear. DialogComponents is Arc’s, and it registers Components’ ConfirmationDialog and BusyIndicatorDialog as the renderers behind Arc’s useConfirmationDialog and useBusyIndicator, because Arc draws no dialog itself. The template splits this between .frontend/main.tsx and App.tsx, and its main.tsx puts CratisComponentsProvider outside <Arc>, which works as well, since both still wrap the whole app. That provider has no toaster, so the toasts further down never show in a template app. They go into a queue that no region displays, and nothing reports it. Adding the prop in main.tsx is the one change they need:

ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
        <CratisComponentsProvider toaster>
            <Arc>
                <App />
            </Arc>
        </CratisComponentsProvider>
    </React.StrictMode>
);

The stylesheets go in the CSS entry. The template’s starts like this:

@import "tailwindcss";
@import '@cratis/components/tokens';
@import '@cratis/components/styles';
@import '@cratis/components/theme';
@source '../';

Keeping them in CSS also keeps tsc quiet. TypeScript 6 checks side-effect imports by default, and imported from a .tsx file, those three stylesheet paths fail the build with TS2882.

The registration dialog

The template’s dialog, with the names changed for authors. In the C# template, its Register command creates the new id on the server, the shape Arc: commands and queries without the plumbing calls RegisterNewAuthor, so that’s its name here:

import { CommandDialog } from '@cratis/components/CommandDialog';
import { InputTextField } from '@cratis/components/CommandForm';
import { MdEdit } from 'react-icons/md';
import { RegisterNewAuthor } from './RegisterNewAuthor';

export const RegisterAuthorDialog = () => {
    return (
        <CommandDialog<RegisterNewAuthor>
            command={RegisterNewAuthor}
            title='Register author'
            okLabel='Register'
            cancelLabel='Cancel'>
            <InputTextField<RegisterNewAuthor>
                value={command => command.name}
                title='Name'
                icon={<MdEdit />} />
        </CommandDialog>
    );
};

RegisterNewAuthor isn’t written by hand. After each build, Arc’s proxy generator writes a class for the C# [Command] record, and the template ships the one for its Register command. Trimmed, and with the names changed, it looks like this:

export class RegisterNewAuthor extends Command<IRegisterNewAuthor, Guid> implements IRegisterNewAuthor {
    readonly route: string = '/api/authors/registration';
    readonly propertyDescriptors: PropertyDescriptor[] = [
        new PropertyDescriptor('name', String, false),
    ];

    private _name!: string;

    get name(): string {
        return this._name;
    }

    set name(value: string) {
        this._name = value;
        this.propertyChanged('name');
    }
}

CommandDialog takes that class, and Arc’s CommandForm creates an instance of it and tracks its values. The dialog walks its children. Each child that’s a command form field, such as InputTextField, gets wrapped so it binds to the command, and anything else, a heading or a layout div, renders as it is, with its own children walked the same way.

The compiler checks command => command.name against the generated class. At runtime, Arc reads the accessor a second time, as source text, and takes the first identifier after a dot as the property name. A plain property read like command => command.name is all it can infer. An accessor like command => command[key] can’t be read that way, and the field needs an explicit fieldName. In development, Arc warns in the console when a field stays unbound.

The Guid in Command<IRegisterNewAuthor, Guid> is the response type. In C#, the template’s handler creates the new id and returns it with the event, so the command responds with the new id as a Guid from @cratis/fundamentals, and onSuccess receives it. The Kotlin and Java templates take the id from the client instead, as a @CommandKey on the command, the way RegisterAuthor does. Their dialog adds initialValues={{ id: crypto.randomUUID() }}, a UUID string made in the browser, and imports the command from Api/, where the Gradle plugin writes the proxies.

The confirm button is focused when the dialog opens. With a required field the button starts disabled, so a held Enter key can’t confirm an empty form. A command with no input, such as a delete, has nothing to keep the button disabled, and the CommandDialog guide recommends initialFocus={DialogInitialFocus.Cancel} for those.

When the name is taken

A registration that reuses a taken name passes every client rule, so the rejection comes from the server, after Register is clicked. The template has no uniqueness rule. The author feature needs one, and in the template it’s a Chronicle constraint on the event, [property: Unique(message: "That name is already registered.")] on the Name of the Registered record. Rules that hold when you write explains why the check has to live at the append. A rule that spans more than one event type goes in a class that implements IConstraint, the declarative form, where the constraint takes the class name unless WithName gives it another.

With that attribute added, registering “Anselm Brackenridge” a second time through the template’s dialog goes like this in .NET:

Chronicle refuses the append. The violation carries the constraint’s name, a message, and details that name the property and the value that clashed.
The .NET client replaces the kernel’s message with the one the constraint declared. Without a declared message, the text reads like “Event ‘…’ on member ‘name’ violated a unique constraint on sequence number …”, which is written for a developer. A declared message can use {PropertyName} and {PropertyValue} placeholders.
Arc’s Chronicle integration turns each violation into a validation result. The command route answers with HTTP 400 and one result, with the message “That name is already registered.”, the member name, the reason constraintViolation and the reason detail Name, which is the constraint’s name. An unnamed [Unique] takes the property’s name. Code that needs to know which rule failed compares reasonDetail and leaves the message alone.
The command result has isSuccess and isValid both false. CommandDialog calls onFailed and onValidationFailure if you passed them, puts the result on the form and stays open.
The form matches the result’s members against each field’s property name. The member is name, the field is bound to name, and the message appears under the Name field.

The second registration of the same name, rejected by the constraint and shown under the Name field.

The field also gets aria-invalid="true" and an aria-describedby that points at the message, which ties the message to the field for assistive technology. The dialog stays open with both buttons enabled, and editing the name clears the message. The list behind it still has two rows, because nothing was appended.

The path a constraint violation takes from the kernel to the Name field, in .NET.

Step 5 works because two names match. The member comes from the event’s property, and it reaches a field only when the command has a property with the same name, as Register.Name and Registered.Name do. A validation result that matches no field has no built-in place on the form. CommandForm shows field errors and a form-level panel for exceptions, and that panel shows a safe default sentence, never the exception text. For a rule that doesn’t map to one field, handle onValidationFailure yourself, or show it as a notification.

autoServerValidate calls the /validate route; Validation all the way down explains why it can’t catch this duplicate before the user confirms.

The author list

The template’s list page, again with author names:

import { Column, DataPage, MenuItem } from '@cratis/components/DataPage';
import { MdAdd } from 'react-icons/md';
import { AllAuthors } from './AllAuthors';

export interface AuthorsPageProps {
    onRegister(): void;
}

export const AuthorsPage = ({ onRegister }: AuthorsPageProps) => {
    return (
        <DataPage
            title='Authors'
            query={AllAuthors}
            dataKey='id'
            emptyMessage='No authors registered yet.'
        >
            <DataPage.MenuItems>
                <MenuItem label='Register' icon={MdAdd} command={onRegister} />
            </DataPage.MenuItems>
            <DataPage.Columns>
                <Column field='name' header='Name' />
            </DataPage.Columns>
        </DataPage>
    );
};

DataPage checks what kind of query it got. A snapshot query gets a table that fetches when the page mounts and again when an argument or the page changes. An observable query gets a table that subscribes and updates as the server pushes results. DataPage doesn’t let you change the page size of 20 rows. The C# template’s listing is observable, so its list picks up a new name without a reload. The Kotlin and Java templates list with a plain query, All, so their list shows new names on its next fetch.

The template’s list page, a DataPage over its observable listing query. The template keeps the Id column that the author version drops.

The two icon props differ in kind. InputTextField takes an element, icon={<MdEdit />}, and MenuItem takes the component, icon={MdAdd}. MenuItem’s command is called with no arguments. The action bar is flat. A MenuItem nested in another one is ignored without an error, and so is any child of DataPage.MenuItems that isn’t a MenuItem.

The table covers the states a list goes through. The first load shows a loading row, a refetch keeps the old rows and marks the table busy, and an empty result shows emptyMessage. A failed or unauthorized query shows an alert row with failureMessage or unauthorizedMessage. The server’s exception text never reaches the page.

DataPage needs an ancestor with a definite height, and the template’s CSS gives #root a height of 100vh for it. Without one, the table grows with its rows and pushes the paginator off the page, and a page with no height above it at all falls back to a minimum of 20rem.

The page renders inside a <main> element, so a shell that already has one ends up with two. Each row is a tab stop that Enter or Space selects, and there’s no arrow-key movement between rows. The table has no accessible name until you give it one through tablePt={{ table: { 'aria-label': 'Authors' } }}. With a details panel, the divider only moves with a pointer, and the panel opens beside the table at every screen width.

The feature component puts the page and the dialog together with Arc’s useDialog:

import { useDialog } from '@cratis/arc.react/dialogs';
import { RegisterAuthorDialog } from './Registration/RegisterAuthorDialog';
import { AuthorsPage } from './Listing/AuthorsPage';

export const Authors = () => {
    const [RegistrationDialog, showRegistrationDialog] = useDialog(RegisterAuthorDialog);

    return (
        <>
            <AuthorsPage onRegister={() => { void showRegistrationDialog(); }} />
            <RegistrationDialog />
        </>
    );
};

The wrapper from Arc’s useDialog renders once, and the function next to it opens the dialog and resolves with a DialogResult and an optional response when it closes.

Dialogs and notifications

Components’ dialog guide sorts the choices by what the user does, and Live UIs covers the choice between CommandDialog and Dialog. StepperCommandDialog runs a command after several steps. A yes-or-no question goes through useConfirmationDialog and renders as ConfirmationDialog, and a blocking spinner goes through useBusyIndicator and renders as BusyIndicatorDialog. On a Dialog, placement='start' or 'end' turns it into a side panel.

Anything the user doesn’t have to answer is a toast. With toaster set on the provider, toast.success, toast.warn, toast.error and the rest can be called from components and from plain modules. Outside a dialog, toastCommandResult turns a command result into the matching toast:

const result = await command.execute();
if (toastCommandResult(result, { successTitle: 'Author registered' })) {
    close();
}

Success gives a success toast, a rejected authorization a warning, and a failed validation an error toast that lists the validation messages. Exceptions get a generic error toast, and their messages and stack traces are left for you to log. Components runs its own toast queue and region, because React Aria’s toast API isn’t stable.

Tokens, parts and layers

The three stylesheets are separate on purpose. tokens defines the semantic --cratis-* variables with light defaults. styles is the component structure, in low-priority cascade layers, with no reset and no copy of the tokens. theme is optional and adds dark mode, automatic through prefers-color-scheme or explicit with a cratis-dark or cratis-light class, as well as forced-colors support and independently themed subtrees.

A product with its own design system leaves out theme and maps its values onto the Cratis tokens:

:root {
    --cratis-primary-color: var(--product-accent);
    --cratis-surface-card: var(--product-surface);
    --cratis-text-color: var(--product-text);
    --cratis-focus-ring: var(--product-focus-ring);
}

For one component, stable parts are the hook. Documented parts carry a data-cratis-part attribute, and components that support it take a typed pt prop with ordinary HTML attributes per part, such as a className for a dialog’s root or backdrop. React Aria’s class names and the undocumented DOM around the parts aren’t styling hooks, and Components tells you not to target them.

In a Tailwind host such as the template, the layer order works against pt. styles declares its layers as cratis-theme, cratis-components and cratis-utilities, and cascade layers rank in the order they’re first declared. Tailwind declares its own layers first, so the Cratis layers land after them and a component’s own rule outranks a Tailwind utility you pass through pt. Components’ styling guide fixes the order with one statement parsed before any stylesheet:

@layer properties, theme, base, cratis-theme, cratis-components, cratis-utilities, components, utilities;

An application that uses a few surfaces can import @cratis/components/styles/base and one stylesheet per subpath, such as @cratis/components/DataPage/styles, in place of the whole styles bundle.

Swapping the primitives

By default, Components renders everything itself. Three optional packages, renderer adapters, let a set of primitives come from another library, one for MUI 9, one for PrimeReact 11 and one for PrimeReact 10 from 10.9.9. You pick one with the provider’s library prop:

import { CratisComponentsProvider } from '@cratis/components';
import { muiUiLibrary } from '@cratis/components.mui';

export const Application = () => (
    <CratisComponentsProvider value={{ locale: 'en-US' }} library={muiUiLibrary}>
        <main>Application content</main>
    </CratisComponentsProvider>
);

Each adapter covers the same nine slots: button, icon button, text input, text area, checkbox, radio, switch, progress and surface. Tooltips, dropdowns, dialogs, date pickers and the paginator stay with Components, and so do the composites. Under the MUI adapter, a DataPage is still a DataPage, and only its buttons and other primitives can come from MUI. A slot the adapter doesn’t declare falls back to the built-in one without a warning, and rendererFallback='throw' turns that into an error. Each adapter release requires exactly its own version of @cratis/components, so the two upgrade together. The PrimeReact 11 adapter needs the application’s own PrimeReactProvider with the application’s license key, and installing the adapter doesn’t move key handling into it.

When a screen needs what a vendor grid does, such as grouping, row expansion, inline editing, virtualization or sorting controlled on the server, the adapter guide points to a custom composition next to Components, and not to anything inside DataPage.

Where a view model fits

Everything above takes props, so it works the same inside a view model’s view. Arc’s MVVM package, @cratis/arc.react.mvvm, keeps screen behavior in a class that withViewModel binds to a component, and Live UIs walks through it with a Components dialog. The template doesn’t install the package. Arc’s advice is plain hooks unless a screen has substantial behavior, and a list with a register button doesn’t.

Upgrading from Components 3

Components 3 to 4 is a breaking upgrade. Root namespace imports, rendered markup, style parts and the provider changed. The migration guide comes with @cratis/components.migrator, a development CLI that rewrites imports and a few props, and @cratis/eslint-plugin-components, which stops the old imports from coming back.

Where Components stops

The contract is React in a browser. There’s no React Native, Vue, Angular or framework-neutral target.

Sorting and filtering in the tables work on the page that’s loaded, and the table doesn’t forward its state to the server for you. A filter over the whole result is a query argument that the server applies before paging.

The repository runs automated checks on its built-in renderer, including axe, form and event behavior in jsdom, and server rendering. Those checks aren’t an accessibility conformance result, and they don’t replace a review with assistive technology in your application. Some generated labels and plural text are still outside the provider’s message set, so the provider can’t translate every string a page shows.

Arc React’s published type declarations report TS2503 errors when an application type-checks libraries with skipLibCheck: false. The template sets skipLibCheck: true.

Previous: Part 08 — Live UIs
Next: Part 10 — Tenancy and identity end to end

From script to stage · Part 08: Live UIs

Wed, 30 Sep 2026 09:08:00 GMT

Cratis: from script to stage, and the long run · Part 08 of 26

In Arc, the difference between a query that loads a list once and a query that keeps pushing new results to a React screen is the return type of one C# method, as long as the data it returns comes from a source that notifies on change. Return a list and the browser gets a snapshot. Return an ISubject of that list and the generated hook subscribes, and the server pushes later results to it over Server-Sent Events or WebSocket. The C# record stays the same. The generator writes an observable query class instead of a plain one, and the component still calls .use(), whose tuple is [result, setSorting] instead of [result, perform, setSorting].

The author screen needs two things: a list of authors that shows a new one without a reload, and a form that registers one. Both sit on the TypeScript that Arc generates from the backend, and both are about the same question, which is what the browser knows and when it learns it.

A live query is a return type

A C# model-bound query is a static method on a [ReadModel] record. Returning ISubject<IEnumerable<T>>, or ISubject<T> for one item, makes it an observable query. The Ideas board in the Cratis Samples repository keeps its ideas in memory, in one store for the whole process and not one per tenant, and observes them:

[ReadModel, AllowAnonymous]
public record Idea(IdeaId Id, IdeaTitle Title, IdeaSummary Summary)
{
    public static ISubject<IEnumerable<Idea>> ObserveIdeas(IdeaStore store) => store.Observe();
}

public sealed class IdeaStore : IDisposable
{
    readonly Lock _gate = new();
    readonly BehaviorSubject<IEnumerable<Idea>> _ideas = new([]);

    public void Capture(Idea idea)
    {
        lock (_gate) { _ideas.OnNext([idea, .. _ideas.Value]); }
    }

    public ISubject<IEnumerable<Idea>> Observe() => _ideas;

    public void Dispose() => _ideas.Dispose();
}

Arc for Kotlin returns a Flow from the query, and a MutableStateFlow holds the current value for snapshot reads.

@ReadModel
@AllowAnonymous
data class Idea(val id: IdeaId, val title: IdeaTitle, val summary: IdeaSummary) {
    companion object {
        @JvmStatic
        fun observeIdeas(@FromServices store: IdeaStore): Flow<List<Idea>> = store.observe()
    }
}

@Component
class IdeaStore {
    private val ideas = MutableStateFlow<List<Idea>>(emptyList())

    fun capture(idea: Idea) {
        ideas.update { listOf(idea) + it }
    }

    fun observe(): Flow<List<Idea>> = ideas
}

Arc for Java returns a JDK Flow.Publisher from the query, and ObservableState holds the current value for snapshot reads.

@ReadModel
@AllowAnonymous
public record Idea(IdeaId id, IdeaTitle title, IdeaSummary summary) {
    public static Flow.Publisher<List<Idea>> observeIdeas(@FromServices IdeaStore store) {
        return store.observe();
    }
}

@Component
public final class IdeaStore {
    private final ObservableState<List<Idea>> ideas = new ObservableState<>(List.of());

    public synchronized void capture(Idea idea) {
        var updated = new ArrayList<Idea>();
        updated.add(idea);
        updated.addAll(ideas.get());
        ideas.set(List.copyOf(updated));
    }

    public Flow.Publisher<List<Idea>> observe() {
        return ideas;
    }
}

Arc for TypeScript returns an RxJS Observable from a @query({ observable: true }) method, and a BehaviorSubject holds the current value.

export class IdeaStore {
    readonly #ideas = new BehaviorSubject<Idea[]>([]);

    capture(idea: Idea): void {
        this.#ideas.next([idea, ...this.#ideas.value]);
    }

    observe(): Observable<Idea[]> { return this.#ideas; }
}

@readModel()
@allowAnonymous()
export class Idea {
    @field(IdeaId) id!: IdeaId;
    @field(IdeaTitle) title!: IdeaTitle;
    @field(IdeaSummary) summary!: IdeaSummary;

    @query({ observable: true }, service(IdeaStore))
    static observeIdeas(store: IdeaStore): Observable<Idea[]> { return store.observe(); }
}

In .NET, Task<ISubject<T>> is allowed as well, and an arbitrary IObservable<T> isn’t something Arc discovers as a query. You can compose with Rx operators such as Select or CombineLatest, as long as the subscription you return releases every upstream subscription when it’s disposed and passes terminal errors on. The direct transports dispose the subscription they receive.

The return type alone doesn’t open a connection. The client decides whether it wants a one-off snapshot, a direct SSE or WebSocket connection, or a subscription on a shared hub, and the default is the hub.

For ObserveIdeas, the proxy generator writes an ObservableQueryFor<Idea[]> class. A parameterless query over a list gets a use(sorting?) hook that returns the result and a function to change the sorting. It also gets useWithPaging, useSuspense, useSuspenseWithPaging, useChangeStream and a when(condition) helper. Rename a property in C#, rebuild, and the generated types and every field accessor that used the old name stop compiling until you fix them, the same way commands behave in Arc: commands and queries without the plumbing.

Arc’s real-time tutorial includes a two-tab test. Open the app in two browser tabs connected to the same backend process, add a book in one, and the other updates without a reload. That test covers the tutorial’s own path. A write from a second backend process is a separate case, and it depends on where the data lives.

The same check on the Cratis web template’s name list, with two windows side by side.

From a write to the screen

The samples show two paths, and they differ in what sits between the command and the subject the query returns.

In the .NET Ideas board there’s no event store. The command’s Handle(IdeaStore store) calls store.Capture(...), which pushes a new list into the BehaviorSubject. The query returns that same subject, so every subscriber gets the new list, the hub sends it to the browser and the hook re-renders. The command writes to a current-state store, and the query observes that same store.

With Chronicle and MongoDB, the chain is longer. In .NET, this is the author list from Cratis’s full-app walkthrough, with the name typed as AuthorName:

[ReadModel]
[FromEvent<AuthorRegistered>]
public record Author(AuthorId Id, AuthorName Name)
{
    public static ISubject<IEnumerable<Author>> AllAuthors(IMongoCollection<Author> collection) =>
        collection.Observe();
}

Arc for Kotlin and Java observe the collection with MongoObservableQuery, which resumes its MongoDB change stream after transient failures.

@ReadModel
@io.cratis.chronicle.readModels.ReadModel
@FromEvent(AuthorRegistered::class)
data class Author(
    @FromEventSourceId val id: AuthorId = AuthorId(UUID(0, 0)),
    val name: AuthorName = AuthorName("")
) {
    companion object {
        @JvmStatic
        fun allAuthors(@FromServices queries: MongoObservableQuery): Flow<List<Author>> =
            queries.observe<Author>()
    }
}

Arc for Kotlin and Java observe the collection with MongoObservableQuery, which resumes its MongoDB change stream after transient failures.

@ReadModel
@io.cratis.chronicle.readModels.ReadModel
@FromEvent(eventType = AuthorRegistered.class)
public class Author {
    @FromEventSourceId
    public AuthorId id = new AuthorId(new UUID(0, 0));

    public AuthorName name = new AuthorName("");

    public static Flow.Publisher<List<Author>> allAuthors(@FromServices MongoObservableQuery queries) {
        return queries.observePublisher(Author.class);
    }
}

In Arc for TypeScript, ChronicleReadModels watches the read model through Chronicle. mongoCollection(...).observe() is the MongoDB change-stream form.

@readModel()
@fromEvent(AuthorRegistered)
export class Author {
    @field(AuthorId) id!: AuthorId;
    @field(AuthorName) name!: AuthorName;

    @query({ observable: true }, service(ChronicleReadModels))
    static allAuthors(models: ChronicleReadModels): Observable<Author[]> {
        return models.observeAll(Author, author => author.id.toString());
    }
}

The command returns an AuthorRegistered event and Chronicle appends it. In .NET, the projection declared by [FromEvent<AuthorRegistered>] writes the Author document to MongoDB. collection.Observe() sees that document change through a MongoDB change stream, and Arc pushes the new result to every subscribed client.

The Chronicle path to the screen. The UI observes the document, not the event log.

In .NET, Observe() is database observation. It watches the MongoDB collection the projection writes to, and it isn’t a Chronicle projection or a Chronicle API. Change streams need a MongoDB replica set or a supported sharded deployment. If the MongoDB watcher fails, Arc logs the failure and completes the stream instead of raising an error, so a stream that completed doesn’t prove the data is current. Arc for Kotlin and Java observe the collection with MongoObservableQuery, which resumes its MongoDB change stream after transient failures, and Arc for TypeScript’s experimental Chronicle integration watches the read model through Chronicle.

The read model catches up after the append, asynchronously. A command that returns success has recorded the event. The projection may not have written the document yet, and the screen may not have changed yet either. There’s nothing to refresh by hand, and also nothing that promises the list has updated by the time the command’s promise resolves.

For EF Core in .NET, an observed DbSet gets in-process notifications from Arc’s SaveChanges interceptor. SQLite relies on that path only. SQL Server and PostgreSQL can pick up writes from other processes once their database notification setup is in place. If that setup fails, EF observation can fall back to in-process only. Without a notification source, an observable query can stay connected and never send fresh data.

How the result travels

Two settings on <Arc>, queryTransportMethod and queryDirectMode, choose the transport, and they’re independent of each other:

Transport	Direct mode	What happens
SSE (React default)	off	One shared EventSource at `/.cratis/queries/sse`; subscribe and unsubscribe are POSTs
WebSocket	off	One shared socket at `/.cratis/queries/ws`; subscribe and unsubscribe are socket messages
SSE or WebSocket	on	One connection per query URL, bypassing the hub

On the SSE hub, GET /.cratis/queries/sse answers with a connected message and a connection id. The client then POSTs each subscription with the connection id, a subscription id, the query name and its arguments, and results come back tagged with the subscription id. Many subscriptions share one EventSource, and the client handles reconnecting and subscribing again.

<Arc> defaults to the SSE hub with one connection slot. SSE hub connections are capped at four, so that the browser’s per-origin connection limit under HTTP/1.1 still leaves room for the control POSTs. HTTP/2 doesn’t lift Arc’s cap, and direct SSE connections are outside it. The multiplexer is module-global, shared by every <Arc> on the page, so nesting a second <Arc> doesn’t give you an isolated hub.

An observable query is also an ordinary GET. If the observable hasn’t emitted yet, the server answers 202 with isReady: false. For MongoDB’s Observe(), a snapshot without waitForFirstResult always answers 202 and can leave its watcher running, so use waitForFirstResult=true there. waitForFirstResult=true makes it wait for the first emission, 30 seconds by default, adjustable with waitForFirstResultTimeout, and a timeout is a 408. HTTP snapshots bypass read-model interception and emission guards, so masking or guarding that only happens on the streaming path doesn’t protect the snapshot endpoint.

For collection subscriptions on the hub, each item needs a stable, unique Id for Arc to send change sets in delta mode. Without one, Arc sends the whole collection every time and logs a warning once per subscription. When something looks wrong, arc.observableQueryDiagnostics.getSnapshot() and snapshots$ show the transport, the multiplexer’s state, the cache and a health summary.

One hook and its states

The board’s React component is short. Adapted from the sample, without its header and styling, it reads:

export const Board = withViewModel(BoardViewModel, ({ viewModel }) => {
    const [ideasResult] = ObserveIdeas.use();
    const [CaptureDialog, showCaptureDialog] = useDialog(CaptureIdeaDialog);
    const ideas = viewModel.filter(ideasResult.data ?? []);

    return (
        <main>
            <Button label='Capture idea' onClick={() => { void showCaptureDialog(); }} />
            <input value={viewModel.searchTerm}
                   onChange={event => viewModel.setSearchTerm(event.target.value)} />
            {ideasResult.isPerforming && !ideasResult.hasData && <p>Connecting to the live board…</p>}
            {ideas.map((idea, index) => <IdeaCard key={idea.id.toString()} idea={idea} sequence={index + 1} />)}
            <CaptureDialog />
        </main>
    );
});

ObserveIdeas.use() returns a tuple, [result, setSorting], and an observable query for a single item returns [result]. The first line destructures it and keeps the result, which is the element the component reads.

The result carries data, isSuccess, isReady, isAuthorized, isValid, hasExceptions, paging and isPerforming. Two of those are easy to confuse. isReady says a result has been produced. isPerforming says the client is fetching or subscribing right now. The initial state isn’t ready, and isReady: false after a 202 is transient and isn’t a failure. The board shows its “Connecting” line only while it’s performing and has no data yet.

ObserveSingle and ObserveById emit null when the document is gone, including when it was removed through [RemovedWith<T>], and the subscription stays open. Guard with hasData or isReady before you read a property.

Each <Arc> mount keeps a query instance cache, keyed by the query name and its arguments. Components that use the same query with the same arguments share one subscription. When the last of them unmounts, the subscription stays open for queryCacheRetentionMs, 30,000 ms by default, so going back to a screen doesn’t start from empty. It isn’t an isolation boundary between users.

useChangeStream(getKey) gives you what was added, replaced and removed since the last result. Arc computes it by comparing snapshots, on the server or in the client, so a write that happened between two emissions and was overwritten before the second one can be missing from the delta. It’s a view of the difference between results. When every operation matters, read the event log. A reconnect creates a new subscription, and it doesn’t resume from where the old one stopped.

A subscription that stays open

Authorization for an observable query runs once, when the subscription is established. The attributes from Arc: commands and queries without the plumbing are checked then, and the verdict doesn’t expire on its own when a token does or when a role is revoked. Keep-alive pings stop proxies from dropping the connection, and the client reconnects by itself, so a subscription can outlive the session that opened it.

For re-checking during a long subscription, Arc has emission guards. A class implementing IGuardObservableQueryEmission is discovered by convention, and Arc asks it about every emission on every transport, the hub, direct WebSocket and direct SSE alike. It answers Allow, Suppress for a single emission, or DenyAndTerminate. Guards cover streaming emissions only, not the HTTP snapshot. On a WebSocket the principal is the one from the handshake. A guard that throws counts as DenyAndTerminate. A filter can capture a serializable QueryContext.SubscriptionScope after the filters succeed and before the query runs, and the guard gets a fresh copy of it for each emission. An application without a guard pays nothing per emission. Controller-based queries always get a null subscription scope.

The form

After each build, Arc’s proxy generator writes a TypeScript version of the command, and Components binds a form to it. Following the Components form recipe, the form looks like this. RegisterAuthor is the generated proxy class, not something you write:

<CommandDialog<RegisterAuthor>
    command={RegisterAuthor}
    title='Add author'
    okLabel='Add'
    initialValues={{ id }}
    validateOn='change'
>
    <InputTextField<RegisterAuthor>
        value={(command) => command.name}
        title='Name'
        placeholder='Sample Author'
    />
</CommandDialog>

The field accessor is typed against the command. Rename Name in C#, rebuild, and that line stops compiling. That’s why we generate the proxy at all, so drift between frontend and backend shows up as a compile error in your own build. Add stays disabled until the validation rules the backend shared with the proxy pass, and server messages land on their fields.

The generated validator is a partial copy, with the omissions and dropped conditions covered in Validation all the way down. Keep its output in a folder of its own; Arc gotchas covers what a full regeneration deletes.

What CommandDialog does for you

A CommandDialog takes the command’s constructor. It creates the command, validates it and keeps the confirm button disabled until client validation passes. On confirm it runs the command and shows a busy state, with the buttons and fields disabled and a spinner. Server field errors land on their fields, and a success closes the dialog with DialogResult.Ok. Cancel, the close button, Escape and a click on the backdrop close it with Cancelled and fire no callback.

The Ideas board’s dialog seeds a value that no field shows, the new idea’s id.

export const CaptureIdeaDialog = () => (
    <CommandDialog<CaptureIdea>
        command={CaptureIdea}
        title="Capture an idea"
        okLabel="Add to board"
        initialValues={{ id: Guid.create(), title: '', summary: '' }}>
        <InputTextField<CaptureIdea>
            value={command => command.title}
            title="Title"
            placeholder="Make local setup self-explanatory"
        />
    </CommandDialog>
);

A generated proxy starts with every property unset, and a required Guid isn’t filled in for you. A value that no field renders, such as the new idea’s id, goes in initialValues, which counts toward validity. The sample calls Guid.create() inline, which makes a new id on every render. The CommandDialog guide recommends creating it once, for example with useState(() => Guid.create()). onBeforeExecute can transform values too, but it runs after confirm, which is too late to make an invalid command valid.

With autoServerValidate, the dialog also calls the command’s /validate route once local checks have settled, after 500 ms by default. The option has Throttle in its name and behaves as a debounce. The preflight’s limits, including the name race it can’t prevent, are in Validation all the way down.

The rule for choosing is in Components’ own guide. If confirming the dialog executes a generated command, use CommandDialog. If the dialog only gathers values and hands them back, use Dialog.

Arc also has dialogs without Components. useDialog<TResponse, TInput>(Component) returns three elements: the wrapper to render, a function that shows the dialog and the dialog’s context. Showing it resolves to a DialogResult and an optional response. DialogResult has None, Ok, Yes, No and Cancelled. useConfirmationDialog resolves to a bare DialogResult. Arc draws no dialog itself, and DialogComponents is where you supply the confirmation and busy renderers. One dialog hook stores one pending result, so don’t open the same one twice at once.

When a screen has behavior

The board wraps its component in withViewModel. Arc’s MVVM support makes the view model an @injectable() class from tsyringe, observable through MobX, and the view re-renders when a property it read changes.

In the Ideas board, the whole view model is this:

import { injectable } from 'tsyringe';
import { Idea } from './Idea';

@injectable()
export class BoardViewModel {
    searchTerm = '';

    setSearchTerm(value: string) {
        this.searchTerm = value;
    }

    filter(ideas: Idea[]): Idea[] {
        const normalizedSearch = this.searchTerm.trim().toLowerCase();
        if (!normalizedSearch) {
            return ideas;
        }

        return ideas.filter(idea =>
            idea.title.toLowerCase().includes(normalizedSearch) ||
            idea.summary.toLowerCase().includes(normalizedSearch));
    }
}

Filtering the list that’s already loaded is view behavior, so it lives in the view model, and a spec in the sample tests the filter by title and summary without rendering anything. The live data still comes from the hook in the component.

withViewModel observes only the render of the component it wraps. A child component that reads observable view-model state directly sits outside that boundary and won’t re-render when the state changes. Pass plain values down as props, or wrap the child in observer() from @cratis/arc.react.mvvm.

A view model can ask the user something through IDialogs, with show, showConfirmation and showBusyIndicator, and the view registers the dialogs it can show. The MVVM useDialog takes a request type and a component and returns two elements, the wrapper and the function that shows it, which is one fewer than the base hook. Arc’s own advice is to stay with plain hooks unless a screen has substantial behavior.

Tables and pages

For the author list, a table is often the right screen. DataTableForObservableQuery from Components subscribes when it mounts and unsubscribes when it unmounts, and rows appear, change and disappear as the server pushes results:

export function LiveAuthors() {
    return (
        <div style={{ height: '480px' }}>
            <DataTableForObservableQuery query={AllAuthors} emptyMessage='No authors yet' dataKey='id'>
                <Column field='name' header='Name' sortable />
            </DataTableForObservableQuery>
        </div>
    );
}

AllAuthors is the generated proxy for the Chronicle-backed query above. The table needs a parent with a definite height, which is why the example wraps it in a 480-pixel box. Set dataKey, or the selection is lost when an update arrives. Server paging is 20 rows per page. Sorting, column filters and the global search all work on the page that’s loaded, so filtering across the whole result belongs in query arguments, before paging.

DataPage puts a table like that into a page with an action bar and a resizable details panel. DataPage.MenuItems holds the actions, and disableOnUnselected ties an action to having a row selected. Components’ list-screen recipe wires a live table to two CommandDialog actions, and with Chronicle the new row arrives once the projection has updated the read model. Grouping, row expansion and controlled server-side sorting aren’t part of the Components tables.

Components needs React 19, and @cratis/arc and @cratis/arc.react in the range from 20.3.1 up to, but not including, 23.

The same generated query class feeds a hook, a change stream, a table and a page.

Which hop is live

For the author screen, the list and the form meet in one place. The form’s command appends AuthorRegistered, the projection writes the document, the change stream notices, and the hub pushes a new list to every tab that subscribed. The screen code is a hook call and a dialog, and on the backend it’s a return type and an Observe() call, over a projection you declared.

Each hop has its own terms. The projection writes the document after the append, asynchronously, and the change stream reports changes to that document. A snapshot GET skips read-model interception and emission guards, and for MongoDB it needs waitForFirstResult to return data. Deltas compare snapshots and can miss a write between two results. Authorization is checked at subscribe time unless a guard checks each emission. A live screen built on Arc tells the browser about new results of a query, and the event log remains the place to look when each individual change matters.

The Kotlin and TypeScript servers expose observable queries too, each with its own shape on the backend and its own differences from .NET, which Beyond .NET goes through.

Previous: Part 07 — Validation all the way down
Next: Part 09 — Cratis Components, the React layer

Cratis Blog | Blog

The assembly language of the business

A quick recap of what Screenplay is

One board, extracted out of Studio

Open a .play file, get a board

Your AI assistant gets a whiteboard

Your running application already knows its model

No need to run anything: cratis view

Why the format in the middle matters

Wrapping up

From script to stage · Part 26: Getting started with Cratis, and the tools around it

The first hour

What the template writes

cratis new: the same templates from the CLI

One feature, one folder

Samples, and what each one leaves out

Fundamentals, underneath everything

The shape every spec takes

Reading the specs back with Synopsis

Narrator and Lens: two windows onto a running system

cratis.io, and where each page comes from

Where to start

The series

From script to stage · Part 25: AI across the Cratis stack

A spec the compiler reads

Guidance in the repository

Checks that run whether the agent listened or not

Chronicle MCP: an assistant at a running store

Screenplay MCP: proposals a person applies

Cratis Studio and Cratis Direct

The docs, for an assistant that asks or reads

A person reviews, or sets who merges

Read, propose, change

Run it, read the log, start again

From script to stage · Part 24: Cratis Direct and our agentic development life cycle

The hard part moved

An agentic development life cycle

Who it’s for

What it’s for

One issue, through one journey

The signal

Screened and classified

One queue

Admitted with a ceiling

Investigation and plan

The implementation gate

The pull request, and who merges

From production back to the backlog

Content goes through it too

Where it stops

From script to stage · Part 23: Cratis Studio: one event model for the whole team

The wall ends up as a photo

Who it’s for

Why we built it

The author feature, from board to commit

On a shared board

On the canvas

A specification on the slice

AI agents on the same model

Play

Screenplay out, and back in

Code for one slice

Everyone on the same model

Where code generation stops

Assistants outside Studio

How it fits with the rest of Cratis

From script to stage · Part 22: Prologue: a first model of the system you already have

Evidence instead of memory

What the Extractor watches

What it records, and why that still matters

One capture is a command and what it caused

From captures to a first model

A language model may rename, never restructure

Running it

Two ways into a model

What the draft is for

From script to stage · Part 21: Stage and Scene: what happens after a model compiles

One input, three jobs

Rendering is planning

What the renderer admits

`cratis new`: the same templates from the CLI