API Documentation

</div>

{showCharCount && maxLength && (
                    <div className='char-count'>
                        {charCount} / {maxLength}
                    </div>
                )}

{errors.length > 0 && (
                    <ul className='error-list'>
                        {errors.map((error, idx) => (
                            <li key={idx}>{error}</li>
                        ))}
                    </ul>
                )}
            </div>
        );
    },
    {
        defaultValue: '',
        extractValue: (e: unknown) => {
            if (e && typeof e === 'object' && 'target' in e) {
                const event = e as React.ChangeEvent<HTMLTextAreaElement>;
                return event.target.value;
            }
            return String(e || '');
        },
    },
);
```

### Non-String Values (Number Example)

[Section titled “Non-String Values (Number Example)”](#non-string-values-number-example)

```tsx
import { InputNumber, InputNumberProps } from 'primereact/inputnumber';

interface PrimeNumberFieldProps extends WrappedFieldProps<number> {
    min?: InputNumberProps['min'];
    max?: InputNumberProps['max'];
    step?: InputNumberProps['step'];
    showButtons?: InputNumberProps['showButtons'];
    currency?: InputNumberProps['currency'];
    locale?: InputNumberProps['locale'];
    mode?: InputNumberProps['mode'];
    minFractionDigits?: InputNumberProps['minFractionDigits'];
    maxFractionDigits?: InputNumberProps['maxFractionDigits'];
}

export const PrimeNumberField = asCommandFormField<PrimeNumberFieldProps>(
    (props) => {
        const {
            value,
            onChange,
            invalid,
            required,
            errors,
            min,
            max,
            step,
            showButtons,
            currency,
            locale,
            mode,
            minFractionDigits,
            maxFractionDigits,
        } = props;

return (
            <div className='field'>
                <InputNumber
                    value={value}
                    onValueChange={onChange}
                    min={min}
                    max={max}
                    step={step}
                    showButtons={showButtons}
                    mode={mode}
                    currency={currency}
                    locale={locale || 'en-US'}
                    minFractionDigits={minFractionDigits}
                    maxFractionDigits={maxFractionDigits}
                    invalid={invalid}
                    className='w-full'
                />
                {errors.length > 0 && (
                    <small className='p-error'>{errors.join(', ')}</small>
                )}
            </div>
        );
    },
    {
        defaultValue: 0,
        extractValue: (e: unknown) => {
            // PrimeReact InputNumber passes an InputNumberChangeEvent
            if (e && typeof e === 'object' && 'value' in e) {
                const event = e as { value: number | null };
                return event.value ?? 0;
            }
            return Number(e) || 0;
        },
    },
);
```

### Boolean Values (Toggle/Switch)

[Section titled “Boolean Values (Toggle/Switch)”](#boolean-values-toggleswitch)

```tsx
import { InputSwitch, InputSwitchProps } from 'primereact/inputswitch';

interface PrimeSwitchFieldProps extends WrappedFieldProps<boolean> {
    trueLabel?: string;
    falseLabel?: string;
    trueValue?: InputSwitchProps['trueValue'];
    falseValue?: InputSwitchProps['falseValue'];
}

export const PrimeSwitchField = asCommandFormField<PrimeSwitchFieldProps>(
    (props) => {
        const {
            value,
            onChange,
            invalid,
            errors,
            trueLabel,
            falseLabel,
            trueValue,
            falseValue,
        } = props;

return (
            <div className='field'>
                <div className='flex align-items-center gap-2'>
                    <InputSwitch
                        checked={value}
                        onChange={onChange}
                        trueValue={trueValue}
                        falseValue={falseValue}
                        invalid={invalid}
                    />
                    <span className='ml-2'>
                        {value ? trueLabel || 'Yes' : falseLabel || 'No'}
                    </span>
                </div>
                {errors.length > 0 && (
                    <small className='p-error'>{errors.join(', ')}</small>
                )}
            </div>
        );
    },
    {
        defaultValue: false,
        extractValue: (e: unknown) => {
            // PrimeReact InputSwitch passes an InputSwitchChangeEvent
            if (e && typeof e === 'object' && 'value' in e) {
                const event = e as { value: boolean };
                return event.value;
            }
            return Boolean(e);
        },
    },
);
```

## Type Safety

[Section titled “Type Safety”](#type-safety)

CommandForm fields are fully type-safe when you provide the command type:

```tsx
interface ProductCommand {
    name: string;
    price: number;
    inStock: boolean;
}

// ✅ Type-safe: TypeScript knows c is ProductCommand
<PrimeInputTextField<ProductCommand>
    value={c => c.name}  // ✅ c.name is valid
    title="Product Name"
/>

// ✅ Type-safe: TypeScript knows c is ProductCommand
<PrimeNumberField<ProductCommand>
    value={c => c.price}  // ✅ c.price is valid
    title="Price"
    currency="USD"
/>

// ❌ Compile error: Property 'invalid' does not exist on ProductCommand
<PrimeInputTextField<ProductCommand>
    value={c => c.invalid}  // ❌ TypeScript error
    title="Invalid Field"
/>
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

### 1. Handle Null/Undefined Values

[Section titled “1. Handle Null/Undefined Values”](#1-handle-nullundefined-values)

Always provide a sensible default value and handle null/undefined in your `extractValue`:

```tsx
{
    defaultValue: '',
    extractValue: (e: unknown) => {
        if (!e) return '';
        // ... extract logic
    }
}
```

### 2. Preserve Original Events

[Section titled “2. Preserve Original Events”](#2-preserve-original-events)

Some libraries need the original event object. Pass it through when possible:

```tsx
onChange={(e) => {
    // Library might need the original event
    props.onChange(e);
}}
```

### 3. Show Validation Errors

[Section titled “3. Show Validation Errors”](#3-show-validation-errors)

Always display the `errors` array to users:

```tsx
{
    errors.length > 0 && (
        <div className='error-message'>
            {errors.map((error, idx) => (
                <small key={idx}>{error}</small>
            ))}
        </div>
    );
}
```

### 4. Apply Invalid State Styling

[Section titled “4. Apply Invalid State Styling”](#4-apply-invalid-state-styling)

Use the `invalid` prop to style fields with errors:

```tsx
className={invalid ? 'p-invalid' : ''}
```

### 5. Respect the Required Flag

[Section titled “5. Respect the Required Flag”](#5-respect-the-required-flag)

Pass the `required` prop to your underlying component:

```tsx
<input required={required} />
```

## Reusable Field Library

[Section titled “Reusable Field Library”](#reusable-field-library)

Create a library of custom fields for your organization:

src/components/fields/index.ts

```tsx
export { PrimeInputTextField } from './PrimeInputTextField';
export { PrimeNumberField } from './PrimeNumberField';
export { PrimeSwitchField } from './PrimeSwitchField';
export { PrimeDropdownField } from './PrimeDropdownField';
export { PrimeDateField } from './PrimeDateField';
export { PrimeTextAreaField } from './PrimeTextAreaField';
```

Then use them consistently across your application:

```tsx
import { CommandForm } from '@cratis/arc.react/commands';
import {
    PrimeInputTextField,
    PrimeNumberField,
    PrimeSwitchField,
    PrimeDateField,
} from '@/components/fields';

function MyForm() {
    return (
        <CommandForm command={MyCommand}>
            <PrimeInputTextField<MyCommand> value={(c) => c.name} title='Name' />
            <PrimeNumberField<MyCommand>
                value={(c) => c.age}
                title='Age'
                min={0}
                max={120}
            />
            <PrimeSwitchField<MyCommand> value={(c) => c.active} title='Active' />
            <PrimeDateField<MyCommand> value={(c) => c.birthDate} title='Birth Date' />
        </CommandForm>
    );
}
```

## See Also

[Section titled “See Also”](#see-also)

* [CommandForm Overview](/arc/frontend/react/command-form/)
* [Built-in Field Types](/arc/frontend/react/command-form/field-types/)
* [Customization](/arc/frontend/react/command-form/customization/)
* [Validation](/arc/frontend/react/command-form/validation/)

# Customization

CommandForm provides several customization options to adapt the form rendering to your specific needs while maintaining integration with the command system.

## Custom Titles

[Section titled “Custom Titles”](#custom-titles)

By default, CommandForm displays field titles above each field when they are defined. You can disable automatic title rendering and provide your own custom title rendering.

### Disabling Automatic Titles

[Section titled “Disabling Automatic Titles”](#disabling-automatic-titles)

Set the `showTitles` prop to `false`:

```tsx
<CommandForm command={MyCommand} showTitles={false}>
    <InputTextField<MyCommand> value={c => c.name} title="Full Name" />
    <InputTextField<MyCommand> value={c => c.email} type="email" title="Email Address" />
</CommandForm>
```

### Custom Title Rendering

[Section titled “Custom Title Rendering”](#custom-title-rendering)

Combine `showTitles={false}` with custom heading or label elements:

```tsx
<CommandForm command={MyCommand} showTitles={false}>
    <h3 style={{ fontSize: '1.25rem', fontWeight: 'bold', marginBottom: '0.5rem' }}>
        Full Name
    </h3>
    <InputTextField<MyCommand> value={c => c.name} title="Full Name" />

<h3 style={{ fontSize: '1.25rem', fontWeight: 'bold', marginBottom: '0.5rem', marginTop: '1rem' }}>
        Email Address
    </h3>
    <InputTextField<MyCommand> value={c => c.email} type="email" title="Email Address" />
</CommandForm>
```

### Use Case

[Section titled “Use Case”](#use-case)

Custom titles are useful when you want:

* Different visual styling than the default
* To include additional information (icons, tooltips, required indicators)
* More control over layout and spacing
* To use a custom design system

## Custom Error Rendering

[Section titled “Custom Error Rendering”](#custom-error-rendering)

CommandForm automatically displays error messages below fields when validation fails. You can take control of error rendering to match your design requirements.

### Disabling Automatic Error Messages

[Section titled “Disabling Automatic Error Messages”](#disabling-automatic-error-messages)

Set the `showErrors` prop to `false`:

```tsx
<CommandForm command={MyCommand} showErrors={false}>
    <InputTextField<MyCommand> value={c => c.email} type="email" title="Email" required />
    <InputTextField<MyCommand> value={c => c.password} type="password" title="Password" required />
</CommandForm>
```

### Custom Error Display

[Section titled “Custom Error Display”](#custom-error-display)

Use the `useCommandFormContext` hook to access validation state and render errors yourself:

```tsx
import { useCommandFormContext } from '@cratis/arc.react/commands';

function MyForm() {
    const { getFieldError } = useCommandFormContext();
    const emailError = getFieldError('email');
    const passwordError = getFieldError('password');

return (
        <CommandForm command={MyCommand} showErrors={false}>
            <InputTextField<MyCommand> value={c => c.email} type="email" title="Email" required />
            {emailError && (
                <div className="error-message" style={{
                    backgroundColor: '#fee',
                    color: '#c00',
                    padding: '0.5rem',
                    borderRadius: '0.25rem',
                    marginTop: '0.25rem',
                    fontSize: '0.875rem'
                }}>
                    ⚠️ {emailError}
                </div>
            )}

<InputTextField<MyCommand> value={c => c.password} type="password" title="Password" required />
            {passwordError && (
                <div className="error-message">
                    ⚠️ {passwordError}
                </div>
            )}
        </CommandForm>
    );
}
```

### Error Summary

[Section titled “Error Summary”](#error-summary)

Display all errors at once at the top or bottom of the form:

```tsx
function MyForm() {
    const { commandResult } = useCommandFormContext();
    const hasErrors = commandResult?.validationResults && commandResult.validationResults.length > 0;

return (
        <CommandForm command={MyCommand} showErrors={false}>
            {hasErrors && (
                <div className="error-summary" style={{
                    backgroundColor: '#fee',
                    border: '2px solid #c00',
                    padding: '1rem',
                    borderRadius: '0.5rem',
                    marginBottom: '1rem'
                }}>
                    <h4 style={{ margin: '0 0 0.5rem 0', color: '#c00' }}>
                        Please correct the following errors:
                    </h4>
                    <ul style={{ margin: 0, paddingLeft: '1.5rem' }}>
                        {Object.entries(instance.errors).map(([field, errors]) => (
                            <li key={field} style={{ color: '#c00' }}>
                                <strong>{field}:</strong> {errors.join(', ')}
                            </li>
                        ))}
                    </ul>
                </div>
            )}

<InputTextField<MyCommand> value={c => c.email} type="email" title="Email" required />
            <InputTextField<MyCommand> value={c => c.password} type="password" title="Password" required />
        </CommandForm>
    );
}
```

### Use Case

[Section titled “Use Case”](#use-case-1)

Custom error rendering is useful when you want:

* Error summaries at the form level
* Integration with a specific UI framework or design system
* Inline errors with custom icons or animations
* Accessible error messages with specific ARIA attributes

## Custom Field Container

[Section titled “Custom Field Container”](#custom-field-container)

For complete control over how each field is rendered, including its title, error message, and container, use the `fieldContainerComponent` prop.

### Using Custom Field Container

[Section titled “Using Custom Field Container”](#using-custom-field-container)

Define a custom container component that receives field metadata:

```tsx
import { FieldContainerProps } from '@cratis/arc.react/commands';

const CustomFieldContainer = ({ title, errorMessage, children }: FieldContainerProps) => (
    <div className="custom-field-container" style={{
        backgroundColor: errorMessage ? '#fff5f5' : '#f9fafb',
        border: `2px solid ${errorMessage ? '#f56565' : '#e5e7eb'}`,
        borderRadius: '0.5rem',
        padding: '1rem',
        marginBottom: '1rem'
    }}>
        {title && (
            <label style={{
                display: 'block',
                fontWeight: 600,
                fontSize: '0.875rem',
                marginBottom: '0.5rem',
                color: errorMessage ? '#c53030' : '#374151'
            }}>
                {title}
                {errorMessage && ' *'}
            </label>
        )}

{children}

{errorMessage && (
            <div style={{
                color: '#c53030',
                fontSize: '0.875rem',
                marginTop: '0.5rem',
                fontWeight: 500
            }}>
                🚫 {errorMessage}
            </div>
        )}
    </div>
);
```

Then use it with CommandForm:

```tsx
<CommandForm
    command={MyCommand}
    fieldContainerComponent={CustomFieldContainer}
>
    <InputTextField<MyCommand> value={c => c.name} title="Full Name" required />
    <InputTextField<MyCommand> value={c => c.email} type="email" title="Email Address" required />
    <TextAreaField<MyCommand> value={c => c.bio} title="Biography" rows={5} />
</CommandForm>
```

### FieldContainerProps Interface

[Section titled “FieldContainerProps Interface”](#fieldcontainerprops-interface)

The custom field container component receives these props:

| Prop           | Type                  | Description                                      |
| -------------- | --------------------- | ------------------------------------------------ |
| `title`        | `string \| undefined` | The field title (from the field’s `title` prop). |
| `errorMessage` | `string \| undefined` | The error message for the field, if any.         |
| `children`     | `React.ReactNode`     | The actual field component.                      |

### Advanced Field Container

[Section titled “Advanced Field Container”](#advanced-field-container)

Add additional features like help text, icons, or required indicators:

```tsx
interface ExtendedFieldContainerProps extends FieldContainerProps {
    helpText?: string;
    icon?: React.ReactNode;
}

const AdvancedFieldContainer = ({
    title,
    errorMessage,
    children,
    helpText,
    icon
}: ExtendedFieldContainerProps) => (
    <div className="field-wrapper" style={{
        marginBottom: '1.5rem'
    }}>
        {title && (
            <div style={{ display: 'flex', alignItems: 'center', marginBottom: '0.5rem' }}>
                {icon && <span style={{ marginRight: '0.5rem' }}>{icon}</span>}
                <label style={{ fontWeight: 600 }}>
                    {title}
                </label>
            </div>
        )}

{children}

{helpText && !errorMessage && (
            <div style={{
                fontSize: '0.875rem',
                color: '#6b7280',
                marginTop: '0.25rem'
            }}>
                ℹ️ {helpText}
            </div>
        )}

{errorMessage && (
            <div style={{
                fontSize: '0.875rem',
                color: '#dc2626',
                marginTop: '0.25rem',
                fontWeight: 500
            }}>
                ❌ {errorMessage}
            </div>
        )}
    </div>
);
```

### Use Case

[Section titled “Use Case”](#use-case-2)

Custom field containers are useful when you want:

* Consistent field styling across your application
* Integration with an existing component library
* Complex layouts with icons, help text, and labels
* Conditional styling based on validation state
* Accessibility enhancements (ARIA attributes, screen reader support)

## Custom Field Decorator

[Section titled “Custom Field Decorator”](#custom-field-decorator)

The `fieldDecoratorComponent` allows you to customize how fields with icons and descriptions are wrapped and decorated. This is particularly useful for integrating with UI frameworks like PrimeReact, Material-UI, or custom design systems.

### Using Custom Field Decorator

[Section titled “Using Custom Field Decorator”](#using-custom-field-decorator)

Define a custom decorator component:

```tsx
import { FieldDecoratorProps } from '@cratis/arc.react/commands';

const PrimeReactFieldDecorator = ({ icon, description, children }: FieldDecoratorProps) => {
    if (!icon && !description) {
        return <>{children}</>;
    }

return (
        <div className="p-inputgroup">
            {icon && (
                <span className="p-inputgroup-addon">
                    {icon}
                </span>
            )}
            <div className="p-field" data-pr-tooltip={description}>
                {children}
            </div>
        </div>
    );
};
```

Use it with CommandForm:

```tsx
<CommandForm
    command={MyCommand}
    fieldDecoratorComponent={PrimeReactFieldDecorator}
>
    <InputTextField<MyCommand>
        value={c => c.email}
        title="Email"
        icon={<i className="pi pi-envelope" />}
        description="We'll never share your email"
    />
</CommandForm>
```

### FieldDecoratorProps Interface

[Section titled “FieldDecoratorProps Interface”](#fielddecoratorprops-interface)

| Prop          | Type                              | Description                                       |
| ------------- | --------------------------------- | ------------------------------------------------- |
| `icon`        | `React.ReactElement \| undefined` | Icon element to display alongside the field.      |
| `description` | `string \| undefined`             | Description text to show as tooltip or help text. |
| `children`    | `React.ReactNode`                 | The field component to decorate.                  |

## Custom Error Display

[Section titled “Custom Error Display”](#custom-error-display-1)

The `errorDisplayComponent` allows complete control over how validation errors are rendered for each field.

### Using Custom Error Display

[Section titled “Using Custom Error Display”](#using-custom-error-display)

Define a custom error display component:

```tsx
import { ErrorDisplayProps } from '@cratis/arc.react/commands';

const CustomErrorDisplay = ({ errors, fieldName }: ErrorDisplayProps) => (
    <div className="custom-errors" role="alert" aria-live="polite">
        {errors.map((error, idx) => (
            <div key={idx} className="error-item" style={{
                display: 'flex',
                alignItems: 'center',
                gap: '0.5rem',
                padding: '0.5rem',
                backgroundColor: '#fef2f2',
                border: '1px solid #fecaca',
                borderRadius: '0.25rem',
                marginTop: '0.25rem',
                fontSize: '0.875rem',
                color: '#dc2626'
            }}>
                <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
                    <path fillRule="evenodd" d="M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zM7 5a1 1 0 1 1 2 0v4a1 1 0 1 1-2 0V5zm1 7a1 1 0 1 0 0-2 1 1 0 0 0 0 2z" />
                </svg>
                <span>{error}</span>
            </div>
        ))}
    </div>
);
```

Use it with CommandForm:

```tsx
<CommandForm
    command={MyCommand}
    errorDisplayComponent={CustomErrorDisplay}
>
    <InputTextField<MyCommand> value={c => c.email} title="Email" required />
    <InputTextField<MyCommand> value={c => c.password} title="Password" required />
</CommandForm>
```

### ErrorDisplayProps Interface

[Section titled “ErrorDisplayProps Interface”](#errordisplayprops-interface)

| Prop        | Type                  | Description                                                       |
| ----------- | --------------------- | ----------------------------------------------------------------- |
| `errors`    | `string[]`            | Array of error messages for the field.                            |
| `fieldName` | `string \| undefined` | Name of the field with errors (useful for custom error handling). |

## Custom Tooltip Component

[Section titled “Custom Tooltip Component”](#custom-tooltip-component)

The `tooltipComponent` allows you to integrate custom tooltip libraries or components for field descriptions.

### Using Custom Tooltip

[Section titled “Using Custom Tooltip”](#using-custom-tooltip)

Define a custom tooltip wrapper:

```tsx
import { TooltipWrapperProps } from '@cratis/arc.react/commands';
import { Tooltip } from 'primereact/tooltip';

const PrimeReactTooltip = ({ description, children }: TooltipWrapperProps) => {
    const tooltipId = `tooltip-${Math.random().toString(36).substr(2, 9)}`;

return (
        <>
            <div data-pr-tooltip={description} data-pr-position="top" id={tooltipId}>
                {children}
            </div>
            <Tooltip target={`#${tooltipId}`} />
        </>
    );
};
```

Use it with CommandForm:

```tsx
<CommandForm
    command={MyCommand}
    tooltipComponent={PrimeReactTooltip}
>
    <InputTextField<MyCommand>
        value={c => c.username}
        title="Username"
        description="Choose a unique username. Letters, numbers, and underscores only."
    />
</CommandForm>
```

### TooltipWrapperProps Interface

[Section titled “TooltipWrapperProps Interface”](#tooltipwrapperprops-interface)

| Prop          | Type              | Description                           |
| ------------- | ----------------- | ------------------------------------- |
| `description` | `string`          | The tooltip text to display.          |
| `children`    | `React.ReactNode` | The content to attach the tooltip to. |

## Custom CSS Classes

[Section titled “Custom CSS Classes”](#custom-css-classes)

For lightweight customization without creating custom components, use the CSS class customization options.

### Using Custom CSS Classes

[Section titled “Using Custom CSS Classes”](#using-custom-css-classes)

```tsx
<CommandForm
    command={MyCommand}
    errorClassName="my-error-message"
    iconAddonClassName="my-icon-addon"
>
    <InputTextField<MyCommand>
        value={c => c.email}
        title="Email"
        icon={<span>📧</span>}
        required
    />
</CommandForm>
```

Then define your CSS:

```css
.my-error-message {
    display: block;
    margin-top: 0.5rem;
    padding: 0.5rem;
    background-color: #fee;
    border-left: 3px solid #c00;
    color: #c00;
    font-size: 0.875rem;
    font-weight: 500;
}

.my-icon-addon {
    display: flex;
    align-items: center;
    padding: 0.75rem;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    border: none;
    border-radius: 0.5rem 0 0 0.5rem;
}
```

### CSS Class Props

[Section titled “CSS Class Props”](#css-class-props)

| Prop                 | Type     | Default                | Description                                  |
| -------------------- | -------- | ---------------------- | -------------------------------------------- |
| `errorClassName`     | `string` | `'p-error'`            | CSS class applied to error message elements. |
| `iconAddonClassName` | `string` | `'p-inputgroup-addon'` | CSS class applied to icon addon containers.  |

## Framework Integration Examples

[Section titled “Framework Integration Examples”](#framework-integration-examples)

### PrimeReact Integration

[Section titled “PrimeReact Integration”](#primereact-integration)

```tsx
import { CommandForm } from '@cratis/arc.react/commands';
import { Tooltip } from 'primereact/tooltip';
import 'primereact/resources/themes/lara-light-blue/theme.css';
import 'primereact/resources/primereact.min.css';

const PrimeFieldDecorator = ({ icon, description, children }) => (
    <div className="p-inputgroup">
        {icon && <span className="p-inputgroup-addon">{icon}</span>}
        {children}
    </div>
);

const PrimeErrorDisplay = ({ errors }) => (
    <div>
        {errors.map((error, idx) => (
            <small key={idx} className="p-error block mt-1">{error}</small>
        ))}
    </div>
);

function MyForm() {
    return (
        <CommandForm
            command={MyCommand}
            fieldDecoratorComponent={PrimeFieldDecorator}
            errorDisplayComponent={PrimeErrorDisplay}
            errorClassName="p-error"
            iconAddonClassName="p-inputgroup-addon"
        >
            {/* Your fields */}
        </CommandForm>
    );
}
```

### Tailwind CSS Integration

[Section titled “Tailwind CSS Integration”](#tailwind-css-integration)

```tsx
const TailwindFieldDecorator = ({ icon, description, children }) => (
    <div className="relative" title={description}>
        {icon && (
            <div className="absolute inset-y-0 left-0 flex items-center pl-3 pointer-events-none">
                {icon}
            </div>
        )}
        <div className={icon ? 'pl-10' : ''}>
            {children}
        </div>
    </div>
);

const TailwindErrorDisplay = ({ errors }) => (
    <div className="mt-1 space-y-1">
        {errors.map((error, idx) => (
            <p key={idx} className="text-sm text-red-600 flex items-center gap-1">
                <svg className="w-4 h-4" fill="currentColor" viewBox="0 0 20 20">
                    <path fillRule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z" clipRule="evenodd" />
                </svg>
                <span>{error}</span>
            </p>
        ))}
    </div>
);

function MyForm() {
    return (
        <CommandForm
            command={MyCommand}
            fieldDecoratorComponent={TailwindFieldDecorator}
            errorDisplayComponent={TailwindErrorDisplay}
            errorClassName="text-sm text-red-600 mt-1"
        >
            {/* Your fields */}
        </CommandForm>
    );
}
```

## Combining Customizations

[Section titled “Combining Customizations”](#combining-customizations)

You can combine multiple customization options for complete control:

```tsx
<CommandForm
    command={MyCommand}
    showTitles={false}                              // Disable auto titles
    showErrors={true}                               // Keep auto errors
    fieldContainerComponent={CustomFieldContainer}  // Custom container
    fieldDecoratorComponent={CustomFieldDecorator}  // Custom field decoration
    errorDisplayComponent={CustomErrorDisplay}      // Custom error rendering
    tooltipComponent={CustomTooltip}                // Custom tooltips
    errorClassName="my-error"                       // Custom error CSS class
    iconAddonClassName="my-icon"                    // Custom icon CSS class
>
    <h2>Account Information</h2>
    <InputTextField<MyCommand>
        value={c => c.username}
        title="Username"
        icon={<span>👤</span>}
        description="Choose a unique username"
        required
    />
    <InputTextField<MyCommand>
        value={c => c.email}
        type="email"
        title="Email"
        icon={<span>📧</span>}
        description="We'll never share your email"
        required
    />

<h2>Profile</h2>
    <TextAreaField<MyCommand> value={c => c.bio} title="Bio" />
</CommandForm>
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Consistency**: Use the same customization approach across all forms in your application
2. **Accessibility**: Ensure custom rendering maintains proper accessibility (labels, ARIA attributes)
3. **Validation**: Keep error messages visible and clear regardless of customization
4. **Performance**: Avoid creating new component instances on each render (define outside or use `useMemo`)
5. **Testing**: Test custom components with various validation states and error messages

## See Also

[Section titled “See Also”](#see-also)

* [CommandForm Overview](/arc/frontend/react/command-form/)
* [Built-in Field Types](/arc/frontend/react/command-form/field-types/)
* [Validation](/arc/frontend/react/command-form/validation/)
* [Advanced Usage](/arc/frontend/react/command-form/advanced-patterns/)

# Async Data Loading

Load data asynchronously for use in form fields.

## Loading Options for SelectField

[Section titled “Loading Options for SelectField”](#loading-options-for-selectfield)

```tsx
function OrderForm() {
    const [products, setProducts] = useState<Array<{ id: string; name: string }>>([]);
    const [loading, setLoading] = useState(true);

useEffect(() => {
        const loadProducts = async () => {
            try {
                const data = await fetch('/api/products').then((r) => r.json());
                setProducts(data);
            } finally {
                setLoading(false);
            }
        };
        loadProducts();
    }, []);

if (loading) {
        return <div>Loading...</div>;
    }

return (
        <CommandForm command={CreateOrder}>
            <SelectField<CreateOrder>
                value={(c) => c.productId}
                title='Product'
                options={products}
                optionIdField='id'
                optionLabelField='name'
                placeholder='Select a product...'
                required
            />
            <NumberField<CreateOrder>
                value={(c) => c.quantity}
                title='Quantity'
                min={1}
                required
            />
        </CommandForm>
    );
}
```

## Dependent Dropdowns

[Section titled “Dependent Dropdowns”](#dependent-dropdowns)

Load options based on another field’s value:

```tsx
function LocationForm() {
    const command = useCommandInstance(SaveLocation);
    const [cities, setCities] = useState<Array<{ id: string; name: string }>>([]);

useEffect(() => {
        if (command.country) {
            // Load cities for selected country
            const loadCities = async () => {
                const data = await fetch(`/api/cities?country=${command.country}`).then(
                    (r) => r.json(),
                );
                setCities(data);
            };
            loadCities();
        } else {
            setCities([]);
        }
    }, [command.country]);

return (
        <CommandForm command={SaveLocation}>
            <SelectField<SaveLocation>
                value={(c) => c.country}
                title='Country'
                options={countries}
                optionIdField='id'
                optionLabelField='name'
                required
            />

<SelectField<SaveLocation>
                value={(c) => c.city}
                title='City'
                options={cities}
                optionIdField='id'
                optionLabelField='name'
                placeholder={
                    command.country ? 'Select a city...' : 'Select country first'
                }
                required
            />
        </CommandForm>
    );
}
```

## Populating a Form from a Query

[Section titled “Populating a Form from a Query”](#populating-a-form-from-a-query)

The examples above load data for a *field’s options* - the form’s own values still come from `initialValues`/`currentValues`, fetched by hand. `CommandForm` can fetch its initial values itself instead, from a single-instance query:

```tsx
import { CommandForm, InputTextField } from '@cratis/arc.react/commands';
import { GetUserProfile } from './queries';
import { UpdateProfile } from './commands';

function ProfileEditor({ userId }: { userId: string }) {
    return (
        <CommandForm
            command={UpdateProfile}
            populateFromQuery={GetUserProfile}
            populateFromQueryArgs={{ userId }}
        >
            <InputTextField<UpdateProfile>
                value={(c) => c.firstName}
                title='First name'
            />
            <InputTextField<UpdateProfile> value={(c) => c.lastName} title='Last name' />
            <InputTextField<UpdateProfile> value={(c) => c.email} title='Email' />
        </CommandForm>
    );
}
```

Each field is matched onto the query’s result by property name - the command’s `firstName` is seeded from the query result’s `firstName`, and so on. `GetUserProfile` must be a **single-instance query** - a query returning multiple instances throws. For an observable query, use `populateFromObservableQuery` instead; both read their arguments from `populateFromQueryArgs`.

The resolved data becomes the form’s **baseline**, not just a one-time overlay - `command.hasChanges` reads `false` right after the query resolves, and only an edit the user actually makes flips it to `true`. Validation reruns only when the resolved data itself changes, not on every unrelated re-render - so a query that happens to return the same value twice does not re-trigger validation.

### Per-field control

[Section titled “Per-field control”](#per-field-control)

Two field props refine what a query populates:

| Prop             | Effect                                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `noInitialValue` | Skips this field entirely, even if the query result has a same-named property.                                                                                                       |
| `initialValue`   | Overrides how the field’s value is derived from the query result - either a property accessor matched by name, or an arbitrary function that composes a value from the whole result. |
| `populationKey`  | Identifies semantics captured by `initialValue`, such as a locale. Change it to recompute the field from the current query result with the latest callback.                          |

```tsx
<InputTextField<UpdateProfile>
    value={(c) => c.displayName}
    initialValue={(profile: UserProfile) => `${profile.firstName} ${profile.lastName}`}
    title='Display name'
/>
```

An inline callback may close over values that CommandForm cannot discover. Give that semantic input a `populationKey`; when the key changes, CommandForm evaluates the latest callback once against the current population source and stores the result as the new baseline:

```tsx
function DisplayNameField({ locale }: { locale: string }) {
    return (
        <InputTextField<UpdateProfile>
            value={(c) => c.displayName}
            initialValue={(profile: UserProfile) =>
                locale === 'nb'
                    ? `${profile.lastName}, ${profile.firstName}`
                    : `${profile.firstName} ${profile.lastName}`
            }
            populationKey={locale}
            title='Display name'
        />
    );
}
```

CommandForm keeps each mounted field registration stable and retains the latest **committed** accessor and `initialValue` callback. Recreating an equivalent inline function does not repopulate the field, and an interrupted concurrent render cannot publish a callback that never committed. When a callback and its population source or `populationKey` change in the same commit, CommandForm evaluates the new callback once; it never applies the previous callback for one render. The callback runs again only when the population source changes, automatic field metadata changes, or its `populationKey` changes. Use a stable semantic value such as a locale, selected mode, or revision - not a newly created object on every render.

## See Also

[Section titled “See Also”](#see-also)

* [CommandForm Overview](/arc/frontend/react/command-form/)
* [Working with Hooks](/arc/frontend/react/command-form/hooks/)
* [Field Types](/arc/frontend/react/command-form/field-types/)

# Field Types

CommandForm provides a comprehensive set of built-in field components for common form inputs. All field components automatically integrate with the command’s state management and validation system.

## Type Safety

[Section titled “Type Safety”](#type-safety)

Most field components use an explicit type parameter to ensure type-safe accessor functions:

```tsx
// ✅ Correct: Full type safety with IntelliSense
<InputTextField<UserCommand> value={c => c.name} title="Name" />

// ❌ Incorrect: Missing type parameter - 'c' will be 'unknown'
<InputTextField value={c => c.name} title="Name" />
```

The type parameter ensures the `value` accessor function parameter `c` is properly typed as your command class.

`RadioButtonField` and `RadioGroupField` also infer the selected value type from the accessor return type. When you do not provide a JSX type argument, annotate the accessor parameter inline:

```tsx
<RadioGroupField
    value={(c: UserCommand) => c.role}
    options={[
        { value: 'reader', label: 'Reader' },
        { value: 'admin', label: 'Administrator' }
    ]}
/>
```

## Common Props

[Section titled “Common Props”](#common-props)

All field components share these base props:

| Prop       | Type                              | Description                                                                                                                                                                                                                  |
| ---------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`    | `(instance: TCommand) => unknown` | **Required.** Accessor function that returns the property value from the command instance.                                                                                                                                   |
| `title`    | `string`                          | The label for the field (shown when `showTitles` is enabled).                                                                                                                                                                |
| `required` | `boolean`                         | Marks the field as required for validation. **Automatically determined** from the command property’s `PropertyDescriptor.isOptional` (required if not optional). Only specify explicitly to override the automatic behavior. |

> **Note**: Fields are automatically marked as required based on the command property’s nullability. In C#, non-nullable properties generate `PropertyDescriptor` with `isOptional: false`, making those fields required by default. You only need to specify `required` explicitly when you want to override this behavior.

## Field State

[Section titled “Field State”](#field-state)

All field components automatically handle:

* **Value Management**: Values are synchronized with the command instance
* **Validation**: Required fields and type validation are enforced
* **Error Display**: Invalid fields show error styling (red border)
* **Change Tracking**: Changes are detected and the command’s `hasChanges` property is updated

## Available Fields

[Section titled “Available Fields”](#available-fields)

* [InputTextField](/arc/frontend/react/command-form/field-types/input-text-field/) - Text, email, password, date, color, and other text-based inputs
* [NumberField](/arc/frontend/react/command-form/field-types/number-field/) - Numeric inputs with min, max, and step handling
* [TextAreaField](/arc/frontend/react/command-form/field-types/text-area-field/) - Multi-line text input
* [CheckboxField](/arc/frontend/react/command-form/field-types/checkbox-field/) - Boolean toggle input
* [RadioButtonField](/arc/frontend/react/command-form/field-types/radio-button-field/) - Single radio option that assigns a specific value
* [RadioGroupField](/arc/frontend/react/command-form/field-types/radio-group-field/) - Radio option list for one-of-many selections
* [RangeField](/arc/frontend/react/command-form/field-types/range-field/) - Slider input for numeric ranges
* [SelectField](/arc/frontend/react/command-form/field-types/select-field/) - Dropdown selection input

## Styling

[Section titled “Styling”](#styling)

Field components use a consistent styling approach:

* Full width by default (`width: 100%`)
* Standard padding (`padding: 0.75rem`)
* Rounded corners (`border-radius: 0.375rem`)
* Border color adapts to validation state (gray for valid, red for invalid)
* Responsive to theme (light/dark mode support)

## See Also

[Section titled “See Also”](#see-also)

* [CommandForm Overview](/arc/frontend/react/command-form/)
* [Validation](/arc/frontend/react/command-form/validation/)
* [Creating Custom Fields](/arc/frontend/react/command-form/custom-fields/)

# CheckboxField

A checkbox input for boolean (true/false) values.

## Props

[Section titled “Props”](#props)

| Prop       | Type                              | Default | Description                                                                             |
| ---------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `value`    | `(instance: TCommand) => unknown` |         | **Required.** Accessor function returning the property value from the command instance. |
| `title`    | `string`                          |         | The label for the field (shown when `showTitles` is enabled).                           |
| `label`    | `string`                          |         | Label text displayed next to the checkbox.                                              |
| `required` | `boolean`                         |         | Override automatic required detection.                                                  |

## Example

[Section titled “Example”](#example)

```tsx
<CheckboxField<UserCommand>
    value={c => c.agreeToTerms}
    title="Terms of Service"
    label="I agree to the terms and conditions"
/>

<CheckboxField<UserCommand>
    value={c => c.newsletter}
    title="Newsletter"
    label="Send me newsletter updates"
/>
```

## See Also

[Section titled “See Also”](#see-also)

* [Field Types Overview](/arc/frontend/react/command-form/field-types/)
* [CommandForm Overview](/arc/frontend/react/command-form/)

# InputTextField

A versatile text input field that supports multiple input types through HTML5 input elements.

## Props

[Section titled “Props”](#props)

| Prop          | Type                                                                                                               | Default  | Description                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------- |
| `value`       | `(instance: TCommand) => unknown`                                                                                  |          | **Required.** Accessor function returning the property value from the command instance. |
| `title`       | `string`                                                                                                           |          | The label for the field.                                                                |
| `type`        | `'text' \| 'email' \| 'password' \| 'color' \| 'date' \| 'datetime-local' \| 'time' \| 'url' \| 'tel' \| 'search'` | `'text'` | The HTML input type.                                                                    |
| `placeholder` | `string`                                                                                                           |          | Placeholder text shown when empty.                                                      |
| `required`    | `boolean`                                                                                                          |          | Override automatic required detection.                                                  |

## Examples

[Section titled “Examples”](#examples)

**Text Input:**

```tsx
<InputTextField<UserCommand> value={c => c.name} title="Full Name" placeholder="Enter your name" />
```

**Email Input:**

```tsx
<InputTextField<UserCommand> value={c => c.email} type="email" title="Email" placeholder="your@email.com" />
```

**Password Input:**

```tsx
<InputTextField<UserCommand> value={c => c.password} type="password" title="Password" />
```

**Date Input:**

```tsx
<InputTextField<UserCommand> value={c => c.birthDate} type="date" title="Birth Date" />
```

**Color Picker:**

```tsx
<InputTextField<UserCommand> value={c => c.favoriteColor} type="color" title="Favorite Color" />
```

**URL Input:**

```tsx
<InputTextField<UserCommand> value={c => c.website} type="url" title="Website" placeholder="https://example.com" />
```

## See Also

[Section titled “See Also”](#see-also)

* [Field Types Overview](/arc/frontend/react/command-form/field-types/)
* [CommandForm Overview](/arc/frontend/react/command-form/)

# NumberField

A specialized field for numeric input with support for min/max constraints and step increments.

## Props

[Section titled “Props”](#props)

| Prop          | Type                              | Default | Description                                                                             |
| ------------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `value`       | `(instance: TCommand) => unknown` |         | **Required.** Accessor function returning the property value from the command instance. |
| `title`       | `string`                          |         | The label for the field.                                                                |
| `placeholder` | `string`                          |         | Placeholder text shown when empty.                                                      |
| `min`         | `number`                          |         | Minimum allowed value.                                                                  |
| `max`         | `number`                          |         | Maximum allowed value.                                                                  |
| `step`        | `number`                          |         | Increment/decrement step size.                                                          |
| `required`    | `boolean`                         |         | Override automatic required detection.                                                  |

## Example

[Section titled “Example”](#example)

```tsx
<NumberField<UserCommand>
    value={c => c.age}
    title="Age"
    min={0}
    max={120}
    step={1}
/>

<NumberField<ProductCommand>
    value={c => c.price}
    title="Price"
    min={0}
    step={0.01}
    placeholder="0.00"
/>
```

## See Also

[Section titled “See Also”](#see-also)

* [Field Types Overview](/arc/frontend/react/command-form/field-types/)
* [CommandForm Overview](/arc/frontend/react/command-form/)

# RadioButtonField

A single radio input for assigning a specific value to a command property.

`RadioButtonField` infers the allowed `setValue` type from the bound accessor. That keeps each radio option aligned with the command property it updates.

## Props

[Section titled “Props”](#props)

| Prop       | Type                             | Default | Description                                                                                        |
| ---------- | -------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `value`    | `(instance: TCommand) => TValue` |         | **Required.** Accessor function returning the property value from the command instance.            |
| `setValue` | `TValue`                         |         | **Required.** Value assigned when the radio button is selected. The type is inferred from `value`. |
| `label`    | `React.ReactNode`                |         | Content displayed next to the radio button.                                                        |
| `title`    | `string`                         |         | The label for the field (shown when `showTitles` is enabled).                                      |
| `required` | `boolean`                        |         | Override automatic required detection.                                                             |
| `disabled` | `boolean`                        | `false` | Disables the radio button.                                                                         |

## Example

[Section titled “Example”](#example)

```tsx
<RadioButtonField
    value={(c: NotificationPreferences) => c.contactMethod}
    setValue="email"
    label="Email"
    title="Preferred Contact Method"
/>

<RadioButtonField
    value={(c: NotificationPreferences) => c.contactMethod}
    setValue="sms"
    label="SMS"
/>
```

## See Also

[Section titled “See Also”](#see-also)

* [RadioGroupField](/arc/frontend/react/command-form/field-types/radio-group-field/)
* [Field Types Overview](/arc/frontend/react/command-form/field-types/)
* [CommandForm Overview](/arc/frontend/react/command-form/)

# RadioGroupField

A grouped radio input for selecting one value from a predefined set of options.

`RadioGroupField` infers each option value type from the bound accessor. That keeps every option aligned with the command property it updates.

## Props

[Section titled “Props”](#props)

| Prop        | Type                              | Default      | Description                                                                                    |
| ----------- | --------------------------------- | ------------ | ---------------------------------------------------------------------------------------------- |
| `value`     | `(instance: TCommand) => TValue`  |              | **Required.** Accessor function returning the property value from the command instance.        |
| `options`   | `RadioGroupFieldOption<TValue>[]` |              | **Required.** Options rendered by the group. Each `value` must match the accessor return type. |
| `direction` | `'horizontal' \| 'vertical'`      | `'vertical'` | Layout direction for the options.                                                              |
| `title`     | `string`                          |              | The label for the field (shown when `showTitles` is enabled).                                  |
| `required`  | `boolean`                         |              | Override automatic required detection.                                                         |

## Example

[Section titled “Example”](#example)

```tsx
<RadioGroupField
    value={(c: UserSettingsCommand) => c.role}
    title="Role"
    direction="horizontal"
    options={[
        { value: 'reader', label: 'Reader' },
        { value: 'admin', label: 'Administrator' },
        { value: 'owner', label: 'Owner' }
    ]}
/>
```

## See Also

[Section titled “See Also”](#see-also)

* [RadioButtonField](/arc/frontend/react/command-form/field-types/radio-button-field/)
* [Field Types Overview](/arc/frontend/react/command-form/field-types/)
* [CommandForm Overview](/arc/frontend/react/command-form/)

# RangeField

A slider input for selecting a numeric value within a range. The current value is displayed next to the slider for immediate feedback.

## Props

[Section titled “Props”](#props)

| Prop       | Type                              | Default | Description                                                                             |
| ---------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `value`    | `(instance: TCommand) => unknown` |         | **Required.** Accessor function returning the property value from the command instance. |
| `title`    | `string`                          |         | The label for the field.                                                                |
| `min`      | `number`                          | `0`     | Minimum value of the range.                                                             |
| `max`      | `number`                          | `100`   | Maximum value of the range.                                                             |
| `step`     | `number`                          | `1`     | Increment step size.                                                                    |
| `required` | `boolean`                         |         | Override automatic required detection.                                                  |

## Example

[Section titled “Example”](#example)

```tsx
<RangeField<AudioCommand>
    value={c => c.volume}
    title="Volume"
    min={0}
    max={100}
    step={1}
/>

<RangeField<UserCommand>
    value={c => c.experience}
    title="Years of Experience"
    min={0}
    max={50}
    step={1}
/>
```

## See Also

[Section titled “See Also”](#see-also)

* [Field Types Overview](/arc/frontend/react/command-form/field-types/)
* [CommandForm Overview](/arc/frontend/react/command-form/)

# SelectField

A dropdown select field for choosing from a list of options.

## Props

[Section titled “Props”](#props)

| Prop               | Type                                | Description                                                                             |
| ------------------ | ----------------------------------- | --------------------------------------------------------------------------------------- |
| `value`            | `(instance: TCommand) => unknown`   | **Required.** Accessor function returning the property value from the command instance. |
| `title`            | `string`                            | The label for the field.                                                                |
| `options`          | `Array<{ [key: string]: unknown }>` | **Required.** Array of option objects.                                                  |
| `optionIdField`    | `string`                            | **Required.** Name of the property to use as the option value.                          |
| `optionLabelField` | `string`                            | **Required.** Name of the property to display as the option label.                      |
| `placeholder`      | `string`                            | Placeholder text shown for empty selection.                                             |
| `required`         | `boolean`                           | Override automatic required detection.                                                  |

## Example

[Section titled “Example”](#example)

```tsx
const countries = [
    { id: 'us', name: 'United States' },
    { id: 'uk', name: 'United Kingdom' },
    { id: 'ca', name: 'Canada' },
    { id: 'no', name: 'Norway' }
];

<SelectField<UserCommand>
    value={c => c.country}
    title="Country"
    options={countries}
    optionIdField="id"
    optionLabelField="name"
    placeholder="Select a country..."
/>
```

With custom data:

```tsx
const roles = [
    { value: 'admin', display: 'Administrator' },
    { value: 'user', display: 'Standard User' },
    { value: 'guest', display: 'Guest' }
];

<SelectField<UserCommand>
    value={c => c.role}
    title="User Role"
    options={roles}
    optionIdField="value"
    optionLabelField="display"
/>
```

## See Also

[Section titled “See Also”](#see-also)

* [Field Types Overview](/arc/frontend/react/command-form/field-types/)
* [CommandForm Overview](/arc/frontend/react/command-form/)

# TextAreaField

A multi-line text input field for longer content.

## Props

[Section titled “Props”](#props)

| Prop          | Type                              | Default | Description                                                                             |
| ------------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `value`       | `(instance: TCommand) => unknown` |         | **Required.** Accessor function returning the property value from the command instance. |
| `title`       | `string`                          |         | The label for the field.                                                                |
| `placeholder` | `string`                          |         | Placeholder text shown when empty.                                                      |
| `rows`        | `number`                          | `5`     | Number of visible text rows.                                                            |
| `cols`        | `number`                          |         | Number of visible text columns.                                                         |
| `required`    | `boolean`                         |         | Override automatic required detection.                                                  |

## Example

[Section titled “Example”](#example)

```tsx
<TextAreaField<UserCommand>
    value={c => c.bio}
    title="Biography"
    placeholder="Tell us about yourself..."
    rows={8}
/>

<TextAreaField<NoteCommand>
    value={c => c.notes}
    title="Additional Notes"
    rows={3}
/>
```

## See Also

[Section titled “See Also”](#see-also)

* [Field Types Overview](/arc/frontend/react/command-form/field-types/)
* [CommandForm Overview](/arc/frontend/react/command-form/)

# Form Lifecycle

Control form behavior throughout its lifecycle with hooks, state management, callbacks, and auto-save functionality.

## Command Result Callbacks

[Section titled “Command Result Callbacks”](#command-result-callbacks)

Handle command execution results with dedicated callbacks. These callbacks are invoked automatically after command execution based on the result state:

```tsx
import { CommandForm } from '@cratis/arc/commands';
import { ValidationResult } from '@cratis/arc/validation';

interface CreateUserResponse {
    userId: string;
    message: string;
}

function UserForm() {
    const handleSuccess = (response: CreateUserResponse) => {
        console.log('User created with ID:', response.userId);
        // Navigate to user profile, show success message, etc.
    };

const handleFailed = (result: CommandResult<CreateUserResponse>) => {
        console.error('Command failed:', result);
        // Handle general failure
    };

const handleException = (messages: string[], stackTrace: string) => {
        console.error('Exception occurred:', messages);
        // Log exception, show error dialog, etc.
    };

const handleUnauthorized = () => {
        console.warn('User is not authorized');
        // Redirect to login, show authorization message, etc.
    };

const handleValidationFailure = (validationResults: ValidationResult[]) => {
        console.warn('Validation failed:', validationResults);
        // Additional validation failure handling beyond automatic field errors
    };

return (
        <CommandForm<CreateUser, CreateUserResponse>
            command={CreateUser}
            onSuccess={handleSuccess}
            onFailed={handleFailed}
            onException={handleException}
            onUnauthorized={handleUnauthorized}
            onValidationFailure={handleValidationFailure}
        >
            <InputTextField<CreateUser> value={c => c.name} title="Name" required />
            <InputTextField<CreateUser> value={c => c.email} type="email" title="Email" required />
            <button type="submit">Create User</button>
        </CommandForm>
    );
}
```

### Available Callbacks

[Section titled “Available Callbacks”](#available-callbacks)

| Callback              | Parameters                                          | When Invoked                                  |
| --------------------- | --------------------------------------------------- | --------------------------------------------- |
| `onSuccess`           | `(response: TResponse) => void`                     | Command executed successfully                 |
| `onFailed`            | `(commandResult: CommandResult<TResponse>) => void` | Command execution failed (any failure type)   |
| `onException`         | `(messages: string[], stackTrace: string) => void`  | Command threw an exception                    |
| `onUnauthorized`      | `() => void`                                        | User is not authorized to execute the command |
| `onValidationFailure` | `(validationResults: ValidationResult[]) => void`   | Command failed validation                     |

### Callback Invocation Order

[Section titled “Callback Invocation Order”](#callback-invocation-order)

When a command fails, multiple callbacks may be invoked:

1. `onFailed` - Always called when `isSuccess` is `false`

2. One or more specific callbacks based on failure type:

* `onException` if `hasExceptions` is `true`
   * `onUnauthorized` if `isAuthorized` is `false`
   * `onValidationFailure` if `isValid` is `false`

### Type-Safe Response Handling

[Section titled “Type-Safe Response Handling”](#type-safe-response-handling)

CommandForm supports generic type parameters for type-safe responses:

```tsx
// Define response type
interface OrderResponse {
    orderId: string;
    orderNumber: string;
    totalAmount: number;
}

// Use generic type parameters
<CommandForm<CreateOrder, OrderResponse>
    command={CreateOrder}
    onSuccess={(response) => {
        // response is strongly typed as OrderResponse
        console.log(`Order ${response.orderNumber} created with ID ${response.orderId}`);
    }}
>
    {/* Form fields */}
</CommandForm>
```

### Integration with Navigation

[Section titled “Integration with Navigation”](#integration-with-navigation)

Common pattern for navigating after successful command execution:

```tsx
import { useNavigate } from 'react-router-dom';

function CreateProjectForm() {
    const navigate = useNavigate();

const handleSuccess = (response: ProjectResponse) => {
        // Navigate to the newly created project
        navigate(`/projects/${response.projectId}`);
    };

return (
        <CommandForm<CreateProject, ProjectResponse>
            command={CreateProject}
            onSuccess={handleSuccess}
        >
            <InputTextField<CreateProject> value={c => c.name} title="Name" required />
            <TextAreaField<CreateProject> value={c => c.description} title="Description" />
            <button type="submit">Create Project</button>
        </CommandForm>
    );
}
```

## Before Execute Hook

[Section titled “Before Execute Hook”](#before-execute-hook)

Execute code before the command is submitted:

```tsx
function OrderForm() {
    const handleBeforeExecute = async (command: CreateOrder): Promise<boolean> => {
        // Confirm before submitting
        const confirmed = window.confirm('Submit this order?');

if (!confirmed) {
            return false; // Cancel submission
        }

// Add calculated fields
        command.totalAmount = calculateTotal(command.items);
        command.submittedAt = new Date();

return true; // Proceed with submission
    };

return (
        <CommandForm
            command={CreateOrder}
            beforeExecute={handleBeforeExecute}
        >
            <InputTextField<CreateOrder> value={c => c.customerName} title="Customer" required />
            {/* More fields... */}
        </CommandForm>
    );
}
```

The `beforeExecute` callback:

* Receives the command instance
* Returns `true` to proceed, `false` to cancel
* Can modify the command before submission
* Can perform async operations

## Form State Management

[Section titled “Form State Management”](#form-state-management)

Track form state for enhanced UX:

```tsx
function SmartForm() {
    const command = useCommandInstance(UpdateProfile);
    const [isSubmitting, setIsSubmitting] = useState(false);
    const [lastSaved, setLastSaved] = useState<Date | null>(null);

return (
        <div>
            <CommandForm command={UpdateProfile}>
                <InputTextField<UpdateProfile> value={c => c.name} title="Name" />
                <InputTextField<UpdateProfile> value={c => c.email} type="email" title="Email" />
            </CommandForm>

<div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginTop: '1rem' }}>
                <button
                    onClick={handleExecute}
                    disabled={!command.hasChanges || isSubmitting}
                >
                    {isSubmitting ? 'Saving...' : 'Save'}
                </button>

{lastSaved && (
                    <span style={{ fontSize: '0.875rem', color: '#6b7280' }}>
                        Last saved: {lastSaved.toLocaleTimeString()}
                    </span>
                )}

{command.hasChanges && (
                    <span style={{ fontSize: '0.875rem', color: '#f59e0b' }}>
                        Unsaved changes
                    </span>
                )}
            </div>
        </div>
    );
}
```

## Auto-Save

[Section titled “Auto-Save”](#auto-save)

Implement auto-save functionality:

```tsx
function AutoSaveForm() {
    const command = useCommandInstance(UpdateDraft);
    const timeoutRef = useRef<NodeJS.Timeout>();

useEffect(() => {
        if (command.hasChanges) {
            // Clear previous timeout
            if (timeoutRef.current) {
                clearTimeout(timeoutRef.current);
            }

// Set new timeout to auto-save after 2 seconds
            timeoutRef.current = setTimeout(async () => {
                await command.execute();
                console.log('Auto-saved');
            }, 2000);
        }

return () => {
            if (timeoutRef.current) {
                clearTimeout(timeoutRef.current);
            }
        };
    }, [command.hasChanges]);

return (
        <CommandForm command={UpdateDraft}>
            <InputTextField<UpdateDraft> value={c => c.title} title="Title" />
            <TextAreaField<UpdateDraft> value={c => c.content} title="Content" rows={10} />
            <div style={{ fontSize: '0.875rem', color: '#6b7280', marginTop: '0.5rem' }}>
                Changes are saved automatically
            </div>
        </CommandForm>
    );
}
```

## Reaching the Form From a Parent

[Section titled “Reaching the Form From a Parent”](#reaching-the-form-from-a-parent)

Hooks such as `useIsCommandExecuting` only work *inside* the form. When the submit button lives outside it — in a dialog footer, a page toolbar, a wizard’s navigation bar — the form exposes two props for that. They are complementary, and a parent that renders a button generally wants both.

### formRef — executing the form and reading its state

[Section titled “formRef — executing the form and reading its state”](#formref--executing-the-form-and-reading-its-state)

`formRef` hands the parent a `CommandFormHandle`:

```ts
interface CommandFormState {
    isExecuting: boolean;
    isValid: boolean;
    isAuthorized: boolean;
}

interface CommandFormHandle extends CommandFormState {
    execute(): Promise<ICommandResult<unknown>>;
}
```

It is a named prop rather than a forwarded ref, because forwarding erases the generic arguments and callers write `<CommandForm<TCommand, TResponse> … />`.

```tsx
import { useRef } from 'react';
import { CommandForm, type CommandFormHandle } from '@cratis/arc.react/commands';

function ProfilePanel() {
    const formRef = useRef<CommandFormHandle>(null);

return (
        <>
            <CommandForm<UpdateProfile> command={UpdateProfile} formRef={formRef}>
                <InputTextField<UpdateProfile> value={c => c.name} title="Name" />
            </CommandForm>
            <footer>
                <button onClick={() => formRef.current?.execute()}>Save</button>
            </footer>
        </>
    );
}
```

The handle object is created once for the lifetime of the form, so it never changes identity. React still re-attaches a ref whenever the **ref itself** changes identity, though — so pass a *stable* one. An object ref from `useRef`, or a callback wrapped in `useCallback` with no dependencies, attaches once on mount and detaches once on unmount however often the parent re-renders. An inline `formRef={handle => setHandle(handle)}` is a new function on every render and therefore re-attaches on every render; it still works, but it does redundant attach/detach work, and pairing it with a state setter is a re-render loop.

Its state members are getters over live values, so a handle captured once never reports stale state.

### onStateChange — re-rendering the parent

[Section titled “onStateChange — re-rendering the parent”](#onstatechange--re-rendering-the-parent)

A ref is not reactive: reading `formRef.current.isExecuting` in an event handler is fine, but it cannot make the parent re-render, so a button cannot *disable itself* from the handle alone. `onStateChange` is the reactive half — it is called whenever execution, validity or authorization changes:

```tsx
function ProfilePanel() {
    const formRef = useRef<CommandFormHandle>(null);
    const [state, setState] = useState<CommandFormState>({
        isExecuting: false,
        isValid: false,
        isAuthorized: true
    });

return (
        <>
            <CommandForm<UpdateProfile>
                command={UpdateProfile}
                formRef={formRef}
                onStateChange={setState}>
                <InputTextField<UpdateProfile> value={c => c.name} title="Name" />
            </CommandForm>
            <footer>
                <button
                    onClick={() => formRef.current?.execute()}
                    disabled={state.isExecuting || !state.isValid || !state.isAuthorized}>
                    {state.isExecuting ? 'Saving…' : 'Save'}
                </button>
            </footer>
        </>
    );
}
```

An inline arrow function is safe here — the callback is read through a ref, so re-creating it on every render does not re-fire it. The callback is invoked on mount with the form’s initial state and then on every change, never for a parent re-render on its own.

`isExecuting` counts executions rather than flagging them, so it stays true until the last overlapping submission settles, and a rejected command gives its count back — see [Working with Hooks](/arc/frontend/react/command-form/hooks/#useiscommandexecuting).

## See Also

[Section titled “See Also”](#see-also)

* [CommandForm Overview](/arc/frontend/react/command-form/)
* [Working with Hooks](/arc/frontend/react/command-form/hooks/)
* [Validation](/arc/frontend/react/command-form/validation/)

# Working with Hooks

CommandForm provides hooks for advanced scenarios.

## useCommandFormContext

[Section titled “useCommandFormContext”](#usecommandformcontext)

Access the form context to inspect state and control behavior:

```tsx
import { useCommandFormContext } from '@cratis/arc.react/commands';
import { Command } from '@cratis/arc/commands';

function CustomSubmitButton() {
    const { commandInstance, onExecute, commandResult } = useCommandFormContext();

const handleClick = async () => {
        const command = commandInstance as unknown as Command;

if (!commandResult?.isValid && commandResult?.validationResults?.length > 0) {
            alert('Please fix validation errors');
            return;
        }

await onExecute?.();
    };

return (
        <button
            type="button"
            onClick={handleClick}
            disabled={!command.hasChanges}
        >
            {command.hasChanges ? 'Save Changes' : 'No Changes'}
        </button>
    );
}

// Use within CommandForm
<CommandForm command={UpdateProfile}>
    <InputTextField<UpdateProfile> value={c => c.name} title="Name" />
    <CustomSubmitButton />
</CommandForm>
```

## useIsCommandExecuting

[Section titled “useIsCommandExecuting”](#useiscommandexecuting)

Reports whether the surrounding form currently has an execution in flight. Use it for anything inside the form that has to reflect execution — a submit button that disables itself, a spinner — without threading state down by hand:

```tsx
import { useIsCommandExecuting } from '@cratis/arc.react/commands';

function SubmitButton() {
    const isExecuting = useIsCommandExecuting();

return (
        <button type="submit" disabled={isExecuting}>
            {isExecuting ? 'Saving…' : 'Save'}
        </button>
    );
}

// Use within CommandForm
<CommandForm command={UpdateProfile}>
    <InputTextField<UpdateProfile> value={c => c.name} title="Name" />
    <SubmitButton />
</CommandForm>
```

The same value is on the form context as `isExecuting`, so `useCommandFormContext().isExecuting` is equivalent when you need other members of the context anyway.

Executions are counted rather than flagged. A form can be submitted again while the previous submission is still running — a double click, or a submit button and a keyboard submit racing — and a flag would be cleared by whichever one finished first, re-enabling the button with a command still in flight. The count goes `0 → 1 → 2 → 1 → 0` instead, so `isExecuting` stays true until the last execution settles. A command that rejects gives its count back too, so a failed request never leaves the form stuck.

Like every CommandForm hook, this one must be called from inside a `CommandForm`; it throws otherwise. To observe execution state from *outside* the form, see [Form Lifecycle](/arc/frontend/react/command-form/form-lifecycle/).

## useCommandInstance

[Section titled “useCommandInstance”](#usecommandinstance)

Create and manage a command instance outside of CommandForm:

```tsx
import { useCommandInstance } from '@cratis/arc.react/commands';

function MyComponent() {
    const command = useCommandInstance(CreateOrder, {
        customerId: 'customer-123',
        orderDate: new Date()
    });

const handleValidate = async () => {
        const result = await command.validate();
        console.log('Valid:', result.isValid);
    };

useEffect(() => {
        // Load async data
        const loadData = async () => {
            const products = await fetchProducts();
            command.products = products;
        };
        loadData();
    }, []);

return (
        <div>
            <button onClick={handleValidate}>Check Validity</button>
            <CommandForm command={CreateOrder} initialValues={command}>
                <SelectField<CreateOrder>
                    value={c => c.productId}
                    title="Product"
                    options={command.products || []}
                    optionIdField="id"
                    optionLabelField="name"
                />
            </CommandForm>
        </div>
    );
}
```

## See Also

[Section titled “See Also”](#see-also)

* [CommandForm Overview](/arc/frontend/react/command-form/)
* [Data Loading](/arc/frontend/react/command-form/data-loading/)
* [Form Lifecycle](/arc/frontend/react/command-form/form-lifecycle/)

# Layouts

CommandForm renders children in the order they are defined. You can create custom layouts using standard HTML and CSS, or use the built-in `CommandForm.Column` component for multi-column layouts.

Fields remain bound at any descendant depth. You can place them inside fragments, intrinsic elements, grids, cards, or pass-through layout components without hoisting them to be direct children. The form preserves the layout tree while each field registers the accessor and population metadata it actually renders.

Each mounted field keeps one registration descriptor. Recreating its element or inline accessor during a layout render updates the descriptor’s callback references only after that render commits; it does not register or populate the field again, and an interrupted concurrent render cannot leak its callbacks into the mounted form. CommandForm automatically reacts when a layout changes the resolved property, `currentValue`, or `noInitialValue`. When an `initialValue` callback captures other semantics, pass that value through `populationKey` so a change recomputes the transformed value with the latest committed callback. A changed population source also uses the latest committed callback, including when both change in the same commit. This keeps layout and context renders stable without hiding intentional population changes.

## Multi-Column Layout with CommandForm.Column

[Section titled “Multi-Column Layout with CommandForm.Column”](#multi-column-layout-with-commandformcolumn)

CommandForm provides a built-in `CommandForm.Column` component for creating responsive multi-column layouts:

```tsx
<CommandForm command={UpdateProfile}>
    <h3>Personal Information</h3>

<CommandForm.Column>
        <InputTextField<UpdateProfile> value={(c) => c.firstName} title='First Name' />
        <InputTextField<UpdateProfile> value={(c) => c.lastName} title='Last Name' />
        <InputTextField<UpdateProfile> value={(c) => c.phone} title='Phone' />
    </CommandForm.Column>

<CommandForm.Column>
        <InputTextField<UpdateProfile>
            value={(c) => c.email}
            type='email'
            title='Email'
        />
        <InputTextField<UpdateProfile> value={(c) => c.city} title='City' />
        <InputTextField<UpdateProfile> value={(c) => c.country} title='Country' />
    </CommandForm.Column>

<h3>Additional Details</h3>
    <TextAreaField<UpdateProfile> value={(c) => c.bio} title='Biography' rows={5} />
</CommandForm>
```

The `CommandForm.Column` component:

* Automatically arranges columns in a responsive layout
* Displays side-by-side on wider screens
* Stacks vertically on mobile devices
* Maintains consistent spacing between fields
* Works seamlessly with other CommandForm features (validation, errors, etc.)

**Benefits**:

* Cleaner syntax than manual CSS Grid/Flexbox
* Responsive by default
* Consistent styling with the rest of CommandForm
* Fields within columns behave identically to regular fields

## Multi-Column Layout with CSS Grid (Alternative)

[Section titled “Multi-Column Layout with CSS Grid (Alternative)”](#multi-column-layout-with-css-grid-alternative)

For more control over layout, you can use CSS Grid directly:

```tsx
<CommandForm command={UpdateProfile}>
    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem' }}>
        <InputTextField<UpdateProfile> value={(c) => c.firstName} title='First Name' />
        <InputTextField<UpdateProfile> value={(c) => c.lastName} title='Last Name' />
    </div>

<InputTextField<UpdateProfile> value={(c) => c.email} type='email' title='Email' />
    <TextAreaField<UpdateProfile> value={(c) => c.bio} title='Biography' rows={5} />
</CommandForm>
```

**When to use CSS Grid**:

* You need precise control over column widths
* You have complex, asymmetric layouts
* You want to span fields across multiple columns

**When to use CommandForm.Column**:

* Standard multi-column layouts
* You want responsive behavior out of the box
* You prefer cleaner, more semantic code

## Grouped Fields

[Section titled “Grouped Fields”](#grouped-fields)

```tsx
<CommandForm command={RegisterUser}>
    <fieldset
        style={{
            border: '1px solid #e5e7eb',
            borderRadius: '0.5rem',
            padding: '1rem',
            marginBottom: '1rem',
        }}
    >
        <legend style={{ fontWeight: 'bold', padding: '0 0.5rem' }}>
            Account Information
        </legend>
        <InputTextField<RegisterUser> value={(c) => c.username} title='Username' />
        <InputTextField<RegisterUser> value={(c) => c.email} type='email' title='Email' />
        <InputTextField<RegisterUser>
            value={(c) => c.password}
            type='password'
            title='Password'
        />
    </fieldset>

<fieldset
        style={{ border: '1px solid #e5e7eb', borderRadius: '0.5rem', padding: '1rem' }}
    >
        <legend style={{ fontWeight: 'bold', padding: '0 0.5rem' }}>
            Personal Information
        </legend>
        <InputTextField<RegisterUser> value={(c) => c.firstName} title='First Name' />
        <InputTextField<RegisterUser> value={(c) => c.lastName} title='Last Name' />
        <TextAreaField<RegisterUser> value={(c) => c.bio} title='Bio' rows={4} />
    </fieldset>
</CommandForm>
```

## Conditional Fields

[Section titled “Conditional Fields”](#conditional-fields)

Show fields based on other field values:

```tsx
function RegistrationForm() {
    const command = useCommandInstance(RegisterUser);

return (
        <CommandForm command={RegisterUser}>
            <InputTextField<RegisterUser>
                value={(c) => c.email}
                type='email'
                title='Email'
            />

<SelectField<RegisterUser>
                value={(c) => c.accountType}
                title='Account Type'
                options={[
                    { id: 'personal', name: 'Personal' },
                    { id: 'business', name: 'Business' },
                ]}
                optionIdField='id'
                optionLabelField='name'
            />

{command.accountType === 'business' && (
                <>
                    <InputTextField<RegisterUser>
                        value={(c) => c.companyName}
                        title='Company Name'
                    />
                    <InputTextField<RegisterUser> value={(c) => c.taxId} title='Tax ID' />
                </>
            )}
        </CommandForm>
    );
}
```

## See Also

[Section titled “See Also”](#see-also)

* [CommandForm Overview](/arc/frontend/react/command-form/)
* [Validation](/arc/frontend/react/command-form/validation/)
* [Customization](/arc/frontend/react/command-form/customization/)

# Validation

CommandForm integrates seamlessly with the Arc command validation system to provide automatic validation feedback and error handling.

## Overview

[Section titled “Overview”](#overview)

CommandForm automatically validates field inputs and displays errors based on:

* **Required Fields**: Fields marked with `required` prop
* **Type Validation**: Built-in HTML5 validation (email, URL, number ranges, etc.)
* **Command Validation Rules**: Backend validation rules defined on your command
* **Custom Validation**: Custom validators you define

## Validation Timing

[Section titled “Validation Timing”](#validation-timing)

CommandForm provides flexible control over when validation occurs through the `validateOn` prop:

### Validate on Blur (Default)

[Section titled “Validate on Blur (Default)”](#validate-on-blur-default)

By default, validation occurs when a field loses focus (blur event). This provides a balance between immediate feedback and not interrupting the user while typing:

```tsx
<CommandForm command={RegisterUser} validateOn="blur">
    <InputTextField<RegisterUser> value={c => c.email} type="email" title="Email" required />
    <InputTextField<RegisterUser> value={c => c.password} type="password" title="Password" required />
</CommandForm>
```

**When to use**: Most forms - provides feedback after the user completes a field without being intrusive.

### Validate on Change

[Section titled “Validate on Change”](#validate-on-change)

Validation runs immediately as the user types. This provides the fastest feedback but can be distracting:

```tsx
<CommandForm command={RegisterUser} validateOn="change">
    <InputTextField<RegisterUser> value={c => c.email} type="email" title="Email" required />
    <InputTextField<RegisterUser> value={c => c.password} type="password" title="Password" required />
</CommandForm>
```

**When to use**: Forms where immediate validation is critical, like password strength meters or username availability checks.

### Validate on Both

[Section titled “Validate on Both”](#validate-on-both)

Validation runs on both change and blur events:

```tsx
<CommandForm command={RegisterUser} validateOn="both">
    <InputTextField<RegisterUser> value={c => c.email} type="email" title="Email" required />
    <InputTextField<RegisterUser> value={c => c.password} type="password" title="Password" required />
</CommandForm>
```

**When to use**: Forms where continuous validation is important for complex rules.

## Validation Scope

[Section titled “Validation Scope”](#validation-scope)

Control whether validation validates just the changed field or all fields:

### Per-Field Validation (Default)

[Section titled “Per-Field Validation (Default)”](#per-field-validation-default)

By default, only the field that changed is validated. This is more efficient and provides focused feedback:

```tsx
<CommandForm
    command={CreateUser}
    validateOn="blur"
>
    <InputTextField<CreateUser> value={c => c.username} title="Username" required />
    <InputTextField<CreateUser> value={c => c.email} type="email" title="Email" required />
</CommandForm>
```

In this example, when the username field loses focus, only username validation runs.

### Full Form Validation

[Section titled “Full Form Validation”](#full-form-validation)

Set `validateAllFieldsOnChange` to `true` to validate the entire form when any field changes:

```tsx
<CommandForm
    command={CreateUser}
    validateOn="blur"
    validateAllFieldsOnChange={true}
>
    <InputTextField<CreateUser> value={c => c.username} title="Username" required />
    <InputTextField<CreateUser> value={c => c.email} type="email" title="Email" required />
    <InputTextField<CreateUser> value={c => c.confirmEmail} type="email" title="Confirm Email" required />
</CommandForm>
```

**When to use**: Forms with interdependent fields where one field’s validity depends on another (e.g., password confirmation, start/end dates).

## Silent Validation on Load

[Section titled “Silent Validation on Load”](#silent-validation-on-load)

CommandForm **always** runs client validation silently on load, regardless of any other settings. This means `isValid` in the form context correctly reflects the real validity state from the very first render — before the user has interacted with any field.

This is useful for scenarios such as:

* Disabling a submit button until the form is valid
* Conditionally rendering actions based on form state
* Knowing whether previously loaded data is valid before the user touches anything

```tsx
function EditUserForm({ user }: { user: User }) {
    return (
        <CommandForm command={UpdateUser} currentValues={user}>
            <InputTextField<UpdateUser> value={c => c.username} title="Username" required />
            <InputTextField<UpdateUser> value={c => c.email} type="email" title="Email" required />
            <SubmitButton /> {/* can use isValid from useCommandFormContext */}
        </CommandForm>
    );
}
```

The silent validation **does not display any error messages**. Errors are only rendered after the user has interacted with a field (governed by `validateOn`) or when `validateOnInit` is set to `true`.

## Showing Errors on Load (`validateOnInit`)

[Section titled “Showing Errors on Load (validateOnInit)”](#showing-errors-on-load-validateoninit)

Set `validateOnInit` to `true` to show validation error messages immediately when the form renders:

```tsx
<CommandForm
    command={CreateUser}
    validateOnInit={true}
    initialValues={{ username: '', email: '' }}
>
    <InputTextField<CreateUser> value={c => c.username} title="Username" required />
    <InputTextField<CreateUser> value={c => c.email} type="email" title="Email" required />
</CommandForm>
```

**When to use**:

* Edit forms where existing data might have validation issues
* Forms where you want to show all errors upfront
* Step-by-step wizards showing validation state of upcoming steps

For automatic server-side validation as users type, see [Auto Server Validation](/arc/frontend/react/command-form/auto-server-validation/).

## Validation Options Summary

[Section titled “Validation Options Summary”](#validation-options-summary)

| Prop                        | Type                           | Default  | Description                                                                                            |
| --------------------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `validateOn`                | `'blur' \| 'change' \| 'both'` | `'blur'` | When to trigger validation                                                                             |
| `validateAllFieldsOnChange` | `boolean`                      | `false`  | Validate all fields or just the changed field                                                          |
| `validateOnInit`            | `boolean`                      | `false`  | Show validation error messages on form initialization (validation itself always runs silently on load) |

### Examples

[Section titled “Examples”](#examples)

**Gentle validation (recommended for most forms)**:

```tsx
<CommandForm command={T} validateOn="blur" />
```

> Note: `isValid` in context is already accurate on first render due to silent validation on load, even though no errors are displayed yet.

**Aggressive validation (real-time feedback)**:

```tsx
<CommandForm command={T} validateOn="change" validateAllFieldsOnChange={true} />
```

**Show all errors immediately**:

```tsx
<CommandForm command={T} validateOn="blur" validateOnInit={true} />
```

## Required Fields

[Section titled “Required Fields”](#required-fields)

Mark fields as required using the `required` prop:

```tsx
<CommandForm command={RegisterUser}>
    <InputTextField<RegisterUser> value={c => c.email} type="email" title="Email" required />
    <InputTextField<RegisterUser> value={c => c.password} type="password" title="Password" required />
    <CheckboxField<RegisterUser> value={c => c.agreeToTerms} title="Terms" label="I agree" required />
</CommandForm>
```

Required fields:

* Show visual indicator when invalid
* Mark field controls as required
* Display error messages when validation rules fail
* Should be paired with explicit command validation rules when empty strings must be invalid

Non-nullable command properties are treated as required for command payload presence, but empty strings are valid string values unless a validation rule rejects them. Use `[Required]`, FluentValidation `NotEmpty()`, or generated client validators when empty or whitespace-only strings should fail before submit.

## Automatic Error Display

[Section titled “Automatic Error Display”](#automatic-error-display)

By default, CommandForm displays error messages below each invalid field:

```tsx
// Errors shown automatically for invalid/required fields
<CommandForm command={CreateAccount}>
    <InputTextField<CreateAccount> value={c => c.username} title="Username" required />
    {/* Error appears here if username is empty or invalid */}

<InputTextField<CreateAccount> value={c => c.email} type="email" title="Email" required />
    {/* Error appears here if email is invalid format */}
</CommandForm>
```

### Disabling Error Display

[Section titled “Disabling Error Display”](#disabling-error-display)

Disable automatic errors to implement custom error rendering:

```tsx
<CommandForm command={CreateAccount} showErrors={false}>
    <InputTextField<CreateAccount> value={c => c.username} title="Username" required />
    {/* No automatic error rendering */}
</CommandForm>
```

See [Customization](/arc/frontend/react/command-form/customization/) for custom error rendering patterns.

## HTML5 Validation

[Section titled “HTML5 Validation”](#html5-validation)

Field components leverage HTML5 validation attributes:

```tsx
<CommandForm command={UpdateProfile}>
    {/* Email format validation */}
    <InputTextField<UpdateProfile>
        value={c => c.email}
        type="email"
        title="Email"
        required
    />

{/* URL format validation */}
    <InputTextField<UpdateProfile>
        value={c => c.website}
        type="url"
        title="Website"
        placeholder="https://example.com"
    />

{/* Number range validation */}
    <NumberField<UpdateProfile>
        value={c => c.age}
        title="Age"
        min={18}
        max={120}
        required
    />

{/* Pattern matching */}
    <InputTextField<UpdateProfile>
        value={c => c.phone}
        type="tel"
        title="Phone Number"
    />
</CommandForm>
```

## Backend Validation

[Section titled “Backend Validation”](#backend-validation)

CommandForm automatically propagates validation results from backend command handlers:

### Command Definition (C#)

[Section titled “Command Definition (C#)”](#command-definition-c)

```csharp
[Command]
public record CreateUser(string Email, string Username)
{
    public Result<UserRegistered, ValidationResult> Handle()
    {
        // Backend validation
        if (Username.Length < 3)
        {
            return ValidationResult.Error("Username must be at least 3 characters");
        }

if (!Email.Contains('@'))
        {
            return ValidationResult.Error("Email must be a valid address");
        }

return new UserRegistered(Email, Username);
    }
}
```

### Form Usage

[Section titled “Form Usage”](#form-usage)

```tsx
<CommandForm command={CreateUser}>
    <InputTextField<CreateUser> value={c => c.email} type="email" title="Email" required />
    <InputTextField<CreateUser> value={c => c.username} title="Username" required />
</CommandForm>
```

When the form is submitted:

1. Generated frontend validation rules run first
2. Command is sent to backend if frontend validation passes
3. Backend validation rules execute
4. Validation errors are returned and displayed in the form
5. The form remains interactive for corrections

## Accessing Validation State

[Section titled “Accessing Validation State”](#accessing-validation-state)

Use the `useCommandFormContext` hook to access validation state programmatically:

```tsx
import { useCommandFormContext } from '@cratis/arc.react/commands';

function MyForm() {
    const { getFieldError, commandResult } = useCommandFormContext();
    const emailError = getFieldError('email');
    const hasAnyErrors = commandResult?.validationResults && commandResult.validationResults.length > 0;

return (
        <CommandForm command={CreateAccount} showErrors={false}>
            <InputTextField<CreateAccount> value={c => c.email} type="email" title="Email" required />

{/* Check for specific field errors */}
            {emailError && (
                <div className="error">
                    {emailError}
                </div>
            )}

<InputTextField<CreateAccount> value={c => c.username} title="Username" required />

{/* Check for any errors */}
            {hasAnyErrors && (
                <div className="error-summary">
                    Please fix the errors above before submitting.
                </div>
            )}
        </CommandForm>
    );
}
```

## Progressive Validation

[Section titled “Progressive Validation”](#progressive-validation)

Validate as users interact with the form using the `useCommandInstance` hook:

```tsx
import { useCommandInstance } from '@cratis/arc.react/commands';
import { useEffect } from 'react';

function MyForm() {
    const command = useCommandInstance(CreateAccount);
    const [canSubmit, setCanSubmit] = useState(false);

useEffect(() => {
        // Validate whenever command changes
        const validate = async () => {
            const result = await command.validate();
            setCanSubmit(result.isValid);
        };

if (command.hasChanges) {
            validate();
        }
    }, [command.hasChanges]);

return (
        <CommandForm command={CreateAccount}>
            <InputTextField<CreateAccount> value={c => c.email} type="email" title="Email" required />
            <InputTextField<CreateAccount> value={c => c.username} title="Username" required />

<button type="submit" disabled={!canSubmit}>
                Create Account
            </button>
        </CommandForm>
    );
}
```

## Field-Level Validation

[Section titled “Field-Level Validation”](#field-level-validation)

Validate individual fields on blur for immediate feedback:

```tsx
function RegistrationForm() {
    const command = useCommandInstance(RegisterUser);
    const [emailError, setEmailError] = useState<string>();

const handleEmailBlur = async () => {
        // Validate just the email field
        const result = await command.validate();

if (result.hasErrors('email')) {
            setEmailError(result.getErrorsFor('email')[0]);
        } else {
            setEmailError(undefined);
        }
    };

return (
        <CommandForm command={RegisterUser} showErrors={false}>
            <InputTextField<RegisterUser>
                value={c => c.email}
                type="email"
                title="Email"
                required
                onBlur={handleEmailBlur}
            />
            {emailError && <div className="error">{emailError}</div>}
        </CommandForm>
    );
}
```

## Validation Results

[Section titled “Validation Results”](#validation-results)

The command `validate()` method returns a `CommandResult` with:

```typescript
interface CommandResult {
    isSuccess: boolean;
    isValid: boolean;
    isAuthorized: boolean;
    validationResults: ValidationResult[];
    errors: Record<string, string[]>;

hasErrors(property?: string): boolean;
    getErrorsFor(property: string): string[];
}
```

### Example

[Section titled “Example”](#example)

```tsx
const result = await command.validate();

if (!result.isValid) {
    console.log('Validation failed');
    console.log('All errors:', result.errors);
    console.log('Email errors:', result.getErrorsFor('email'));
}

if (!result.isAuthorized) {
    console.log('User not authorized to execute this command');
}
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Use Required Fields**: Mark essential fields with `required` for client-side validation
2. **Type-Specific Fields**: Use appropriate input types (email, url, number) for built-in validation
3. **Backend Validation**: Always validate on the server for security and data integrity
4. **Progressive Feedback**: Consider validating on field blur for better UX
5. **Clear Messages**: Provide clear, actionable error messages
6. **Accessible Errors**: Ensure error messages are associated with their fields for screen readers
7. **Visual Feedback**: Use consistent visual styling for invalid fields

## Command Validation System

[Section titled “Command Validation System”](#command-validation-system)

For comprehensive details on the command validation system:

* **TypeScript/React**: See [Core Validation](/arc/frontend/core/commands/validation/)
* **Backend**: See [Backend Command Validation](/arc/backend/commands/command-validation/)
* **Command Usage**: See [Commands Overview](/arc/frontend/react/)

## See Also

[Section titled “See Also”](#see-also)

* [CommandForm Overview](/arc/frontend/react/command-form/)
* [Built-in Field Types](/arc/frontend/react/command-form/field-types/)
* [Customization](/arc/frontend/react/command-form/customization/)
* [Advanced Usage](/arc/frontend/react/command-form/advanced-patterns/)

# Commands

Commands represent actions you want to perform against the system. They are encapsulated as objects that serve as the payload for HTTP Post controller actions in the backend. Commands can have validation and business rules associated with them, and controllers can have authorization policies that apply to commands.

## Overview

[Section titled “Overview”](#overview)

Commands provide a structured way to:

* Encapsulate business operations and state changes
* Validate input before execution
* Track changes from original values
* Integrate with React’s rendering pipeline
* Handle authorization and error scenarios

## Quick Start

[Section titled “Quick Start”](#quick-start)

**Backend Command (C#):**

```csharp
public record OpenDebitAccount(AccountId AccountId, AccountName Name, CustomerId Owner);
```

**Generated TypeScript:**

```typescript
import { OpenDebitAccount } from './generated/commands';

const [command] = OpenDebitAccount.use({
    accountId: 'a23edccc-6cb5-44fd-a7a7-7563716fb080',
    name: 'My Account',
    owner: '84cda809-9201-4d8c-8589-0be37c6e3f18'
});

await command.execute();
```

## HTTP Headers

[Section titled “HTTP Headers”](#http-headers)

Commands automatically include HTTP headers provided by the `httpHeadersCallback` configured in [Arc](/arc/frontend/react/arc/). This allows you to include authentication cookies, authorization tokens, or other custom headers with every command request.

## Proxy Generation

[Section titled “Proxy Generation”](#proxy-generation)

Commands are automatically generated from your backend using the [proxy generator](/arc/backend/proxy-generation/). The generator scans HTTP Post actions during compile time and creates TypeScript classes that:

* Match your backend command structure
* Provide type-safe properties
* Include validation support
* Offer a `.use()` method for React integration
* Track changes automatically

See [Proxy Generation](/arc/backend/proxy-generation/) for setup details.

## Command Result

[Section titled “Command Result”](#command-result)

When executed, commands return a `CommandResult` with detailed information about the outcome:

```typescript
const result = await command.execute();

if (result.isSuccess) {
    console.log('Success!', result.response);
} else {
    if (!result.isAuthorized) {
        // Handle authorization failure
    }
    if (!result.isValid) {
        // Handle validation errors
    }
}
```

For comprehensive details, see [Command Result documentation](/arc/frontend/core/commands/command-result/).

## Topics

[Section titled “Topics”](#topics)

| Topic                                                              | Description                                                                    |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [React Usage](/arc/frontend/react/commands/react-usage/)           | Using the `.use()` hook in React components (recommended).                     |
| [Data Binding](/arc/frontend/react/commands/data-binding/)         | Binding to command properties and managing initial values for change tracking. |
| [Validation](/arc/frontend/react/commands/validation/)             | Pre-flight validation, progressive validation, and error handling.             |
| [Command Scope](/arc/frontend/react/commands/scope/)               | Tracking changes across multiple commands in composite UIs.                    |
| [Imperative Usage](/arc/frontend/react/commands/imperative-usage/) | Advanced direct instantiation for non-React scenarios.                         |

## Related Documentation

[Section titled “Related Documentation”](#related-documentation)

* [CommandForm](/arc/frontend/react/command-form/) - Declarative form component for commands
* [Queries](/arc/frontend/react/queries/) - Data retrieval operations
* [Core Commands](/arc/frontend/core/commands/) - Lower-level command concepts- [Proxy Generation](/arc/backend/proxy-generation/) - Setting up command generation

# Data Binding and Initial Values

Commands act as the data model for your forms and UI components. Understanding how to bind to command properties and manage initial values is essential for building responsive, change-tracked forms.

## Overview

[Section titled “Overview”](#overview)

The command holds properties that represent the payload of what you want to have happen. These properties are:

* Subject to validation rules
* Subject to business rules
* Often sourced from read models coming from [queries](/arc/frontend/react/queries/)
* Used for operations that are typically updates to existing data

## Binding to Command Properties

[Section titled “Binding to Command Properties”](#binding-to-command-properties)

Instead of binding your frontend components to read models from queries, you can bind directly to command properties. This provides several benefits:

### Benefits

[Section titled “Benefits”](#benefits)

1. **Automatic Validation**: Validation rules running on the frontend execute automatically as values change
2. **Change Tracking**: The command tracks whether properties have changed from their original values
3. **Consistent State**: Single source of truth for form data
4. **Type Safety**: TypeScript types generated from backend command definitions

### Example

[Section titled “Example”](#example)

```typescript
import { UpdateProfile } from './generated/commands';

export const ProfileEditor = () => {
    const [command] = UpdateProfile.use({
        userId: currentUser.id,
        firstName: currentUser.firstName,
        lastName: currentUser.lastName,
        email: currentUser.email
    });

return (
        <form>
            <input
                type="text"
                value={command.firstName}
                onChange={(e) => command.firstName = e.target.value}
            />
            <input
                type="text"
                value={command.lastName}
                onChange={(e) => command.lastName = e.target.value}
            />
            <input
                type="email"
                value={command.email}
                onChange={(e) => command.email = e.target.value}
            />
        </form>
    );
};
```

## Initial Values

[Section titled “Initial Values”](#initial-values)

Commands need initial values to enable change tracking. The `hasChanges` property compares current values against these initial values.

### Setting Initial Values

[Section titled “Setting Initial Values”](#setting-initial-values)

There are two recommended ways to set initial values:

**1. Via React Hook (Recommended):**

```typescript
const [command] = UpdateProfile.use({
    userId: 'user-123',
    firstName: 'John',
    lastName: 'Doe',
    email: 'john@example.com'
});
```

**2. Via setCommandValues Function:**

```typescript
const [command, setCommandValues] = UpdateProfile.use();

useEffect(() => {
    // Load data from API or query
    fetchUserProfile(userId).then(profile => {
        setCommandValues(profile);
    });
}, [userId]);
```

**3. Via setInitialValues (Advanced):**

```typescript
const [command] = UpdateProfile.use();

useEffect(() => {
    fetchUserProfile(userId).then(profile => {
        command.setInitialValues(profile);
    });
}, [userId]);
```

### When to Use Each Approach

[Section titled “When to Use Each Approach”](#when-to-use-each-approach)

* **React Hook Parameter**: When you have initial data available at component mount
* **setCommandValues**: When loading data asynchronously or from queries
* **setInitialValues**: Advanced scenarios requiring direct control (rare)

## Change Tracking

[Section titled “Change Tracking”](#change-tracking)

The `hasChanges` property automatically tracks whether any command property differs from its initial value.

### Basic Change Tracking

[Section titled “Basic Change Tracking”](#basic-change-tracking)

```typescript
const [command] = UpdateProfile.use({
    firstName: 'John',
    lastName: 'Doe'
});

console.log(command.hasChanges); // false

command.firstName = 'Jane';
console.log(command.hasChanges); // true

command.firstName = 'John'; // Reverted to original
console.log(command.hasChanges); // false
```

### Using hasChanges in UI

[Section titled “Using hasChanges in UI”](#using-haschanges-in-ui)

```typescript
export const ProfileEditor = () => {
    const [command] = UpdateProfile.use(currentProfile);

const handleSave = async () => {
        if (command.hasChanges) {
            await command.execute();
        }
    };

return (
        <form>
            {/* Form fields */}

<button
                onClick={handleSave}
                disabled={!command.hasChanges}
            >
                Save Changes
            </button>

{command.hasChanges && (
                <div className="warning">
                    You have unsaved changes
                </div>
            )}
        </form>
    );
};
```

## Loading Data from Queries

[Section titled “Loading Data from Queries”](#loading-data-from-queries)

A common pattern is loading data from a query and using it to initialize a command. If you are building the form with [CommandForm](/arc/frontend/react/command-form/), it can do this fetch-and-seed itself - see [Populating a Form from a Query](/arc/frontend/react/command-form/data-loading/#populating-a-form-from-a-query). The manual pattern below is what to reach for outside `CommandForm`, or when you need full control over the fetch:

```typescript
import { GetUserProfile } from './generated/queries';
import { UpdateProfile } from './generated/commands';

export const ProfileEditor = ({ userId }: { userId: string }) => {
    const profile = GetUserProfile.use({ userId });
    const [command, setCommandValues] = UpdateProfile.use();

useEffect(() => {
        if (profile) {
            setCommandValues({
                userId: profile.userId,
                firstName: profile.firstName,
                lastName: profile.lastName,
                email: profile.email
            });
        }
    }, [profile]);

if (!profile) {
        return <div>Loading...</div>;
    }

return (
        <form>
            <input
                value={command.firstName}
                onChange={(e) => command.firstName = e.target.value}
            />
            {/* More fields... */}

<button disabled={!command.hasChanges}>
                Save
            </button>
        </form>
    );
};
```

## Tracking Changes Across Multiple Commands

[Section titled “Tracking Changes Across Multiple Commands”](#tracking-changes-across-multiple-commands)

When you have a component with sub-components that each work with different commands, you can track the aggregate `hasChanges` state using [Command Scope](/arc/frontend/react/commands/scope/).

### Example Without Scope

[Section titled “Example Without Scope”](#example-without-scope)

```typescript
// Each command tracks its own changes
const [profileCommand] = UpdateProfile.use(profile);
const [settingsCommand] = UpdateSettings.use(settings);

// Need to manually check both
const hasAnyChanges = profileCommand.hasChanges || settingsCommand.hasChanges;
```

### Example With Scope

[Section titled “Example With Scope”](#example-with-scope)

```typescript
import { CommandScope } from '@cratis/arc.react/commands';

export const UserEditor = () => {
    return (
        <CommandScope>
            {(scope) => (
                <>
                    <ProfileForm />
                    <SettingsForm />

<button disabled={!scope.hasChanges}>
                        Save All Changes
                    </button>
                </>
            )}
        </CommandScope>
    );
};
```

See [Command Scope](/arc/frontend/react/commands/scope/) for complete documentation.

## Resetting to Initial Values

[Section titled “Resetting to Initial Values”](#resetting-to-initial-values)

To reset a command to its initial state:

```typescript
const [command, setCommandValues] = UpdateProfile.use(initialProfile);

const handleReset = () => {
    setCommandValues(initialProfile);
};

// Or get fresh data
const handleRefresh = async () => {
    const freshProfile = await fetchUserProfile(userId);
    setCommandValues(freshProfile);
};
```

## Partial Updates

[Section titled “Partial Updates”](#partial-updates)

You can update only specific properties while keeping others unchanged:

```typescript
const [command, setCommandValues] = UpdateProfile.use({
    userId: 'user-123',
    firstName: 'John',
    lastName: 'Doe',
    email: 'john@example.com'
});

// Update only email
setCommandValues({
    ...command,
    email: 'newemail@example.com'
});
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Always Provide Initial Values**: Set initial values to enable proper change tracking
2. **Use Queries as Source**: Load data from queries to initialize commands
3. **Check hasChanges**: Prevent unnecessary API calls by checking if data actually changed
4. **Use CommandScope**: For forms with multiple commands, use CommandScope to track aggregate state
5. **Reset After Save**: Consider resetting initial values after successful save to clear `hasChanges`
6. **Type Safety**: Leverage TypeScript to ensure initial values match command structure

## Example: Complete Edit Form

[Section titled “Example: Complete Edit Form”](#example-complete-edit-form)

```typescript
import { GetUserProfile } from './generated/queries';
import { UpdateProfile } from './generated/commands';
import { useEffect, useState } from 'react';

export const UserProfileEditor = ({ userId }: { userId: string }) => {
    const profile = GetUserProfile.use({ userId });
    const [command, setCommandValues] = UpdateProfile.use();
    const [saved, setSaved] = useState(false);

// Initialize command when profile loads
    useEffect(() => {
        if (profile) {
            setCommandValues(profile);
        }
    }, [profile]);

const handleSave = async () => {
        if (!command.hasChanges) return;

const result = await command.execute();
        if (result.isSuccess) {
            // Reset initial values to current values
            setCommandValues(command);
            setSaved(true);
            setTimeout(() => setSaved(false), 3000);
        }
    };

const handleReset = () => {
        if (profile) {
            setCommandValues(profile);
        }
    };

if (!profile) {
        return <div>Loading...</div>;
    }

return (
        <div>
            <form>
                <div>
                    <label>First Name:</label>
                    <input
                        value={command.firstName}
                        onChange={(e) => command.firstName = e.target.value}
                    />
                </div>
                <div>
                    <label>Last Name:</label>
                    <input
                        value={command.lastName}
                        onChange={(e) => command.lastName = e.target.value}
                    />
                </div>
                <div>
                    <label>Email:</label>
                    <input
                        type="email"
                        value={command.email}
                        onChange={(e) => command.email = e.target.value}
                    />
                </div>
            </form>

<div>
                <button
                    onClick={handleSave}
                    disabled={!command.hasChanges}
                >
                    Save
                </button>
                <button
                    onClick={handleReset}
                    disabled={!command.hasChanges}
                >
                    Reset
                </button>
            </div>

{saved && <div className="success">Profile saved successfully!</div>}
            {command.hasChanges && <div className="info">You have unsaved changes</div>}
        </div>
    );
};
```

## See Also

[Section titled “See Also”](#see-also)

* [Commands Overview](/arc/frontend/react/commands/)
* [React Hook Usage](/arc/frontend/react/commands/react-usage/)
* [Command Scope](/arc/frontend/react/commands/scope/)
* [Validation](/arc/frontend/react/commands/validation/)
* [Queries](/arc/frontend/react/queries/)

# Imperative Usage

While the [React Hook Usage](/arc/frontend/react/commands/react-usage/) is the recommended approach for React components, there are scenarios where you need more direct control or are working outside of React’s component lifecycle. This guide covers imperative command usage.

## Overview

[Section titled “Overview”](#overview)

Imperative usage involves directly instantiating and manipulating command objects without React hooks. This is useful for:

* **Non-React Code**: Service layers, utility functions, or vanilla JavaScript
* **Event Handlers**: Complex operations in event handlers
* **Testing**: Unit tests and integration tests
* **Advanced Scenarios**: Custom command orchestration or batching

## Basic Imperative Usage

[Section titled “Basic Imperative Usage”](#basic-imperative-usage)

Directly instantiate and execute a command:

```typescript
import { OpenDebitAccount } from './generated/commands';

const command = new OpenDebitAccount();
command.accountId = 'a23edccc-6cb5-44fd-a7a7-7563716fb080';
command.name = 'My Account';
command.owner = '84cda809-9201-4d8c-8589-0be37c6e3f18';

const result = await command.execute();

if (result.isSuccess) {
    console.log('Account opened successfully');
}
```

## Setting Initial Values

[Section titled “Setting Initial Values”](#setting-initial-values)

For change tracking to work, set initial values using `setInitialValues()`:

```typescript
const command = new OpenDebitAccount();

command.setInitialValues({
    accountId: 'a23edccc-6cb5-44fd-a7a7-7563716fb080',
    name: 'My Account',
    owner: '84cda809-9201-4d8c-8589-0be37c6e3f18'
});

// At this point hasChanges is false
console.log(command.hasChanges); // false

command.name = 'My other account';
// Now hasChanges is true
console.log(command.hasChanges); // true
```

## Use Cases

[Section titled “Use Cases”](#use-cases)

### Service Layer Functions

[Section titled “Service Layer Functions”](#service-layer-functions)

```typescript
export class AccountService {
    async openAccount(accountData: { accountId: string; name: string; owner: string }) {
        const command = new OpenDebitAccount();
        command.accountId = accountData.accountId;
        command.name = accountData.name;
        command.owner = accountData.owner;

const result = await command.execute();

if (!result.isSuccess) {
            throw new Error('Failed to open account: ' + result.exceptionMessages.join(', '));
        }

return result.response;
    }
}
```

### Batch Operations

[Section titled “Batch Operations”](#batch-operations)

```typescript
async function batchOpenAccounts(accounts: Array<{ accountId: string; name: string; owner: string }>) {
    const results = await Promise.all(
        accounts.map(async (data) => {
            const command = new OpenDebitAccount();
            command.accountId = data.accountId;
            command.name = data.name;
            command.owner = data.owner;
            return command.execute();
        })
    );

const successful = results.filter(r => r.isSuccess);
    const failed = results.filter(r => !r.isSuccess);

return {
        successful: successful.length,
        failed: failed.length,
        failedReasons: failed.map(r => r.exceptionMessages)
    };
}
```

### Event Handler

[Section titled “Event Handler”](#event-handler)

```typescript
async function handleAccountCreation(event: CustomEvent) {
    const { accountId, name, owner } = event.detail;

const command = new OpenDebitAccount();
    command.accountId = accountId;
    command.name = name;
    command.owner = owner;

const result = await command.execute();

if (result.isSuccess) {
        // Trigger success event
        window.dispatchEvent(new CustomEvent('account-opened', {
            detail: result.response
        }));
    } else {
        // Trigger error event
        window.dispatchEvent(new CustomEvent('account-error', {
            detail: result.exceptionMessages
        }));
    }
}
```

### Testing

[Section titled “Testing”](#testing)

```typescript
import { describe, it, expect } from 'vitest';
import { OpenDebitAccount } from './generated/commands';

describe('OpenDebitAccount', () => {
    it('should successfully open an account with valid data', async () => {
        const command = new OpenDebitAccount();
        command.accountId = 'test-account-id';
        command.name = 'Test Account';
        command.owner = 'test-owner-id';

const result = await command.execute();

expect(result.isSuccess).toBe(true);
        expect(result.isValid).toBe(true);
        expect(result.isAuthorized).toBe(true);
    });

it('should track changes correctly', () => {
        const command = new OpenDebitAccount();
        command.setInitialValues({
            accountId: 'test-id',
            name: 'Original Name',
            owner: 'owner-id'
        });

expect(command.hasChanges).toBe(false);

command.name = 'Modified Name';
        expect(command.hasChanges).toBe(true);

command.name = 'Original Name';
        expect(command.hasChanges).toBe(false);
    });

it('should validate without executing', async () => {
        const command = new OpenDebitAccount();
        command.accountId = '';
        command.name = '';
        command.owner = '';

const result = await command.validate();

expect(result.isValid).toBe(false);
        expect(result.validationResults.length).toBeGreaterThan(0);
    });
});
```

## Validation

[Section titled “Validation”](#validation)

Commands can be validated imperatively without execution:

```typescript
const command = new OpenDebitAccount();
command.accountId = 'test-id';
command.name = ''; // Invalid - empty name
command.owner = 'owner-id';

const validationResult = await command.validate();

if (!validationResult.isValid) {
    console.error('Validation failed:');
    validationResult.validationResults.forEach(error => {
        console.error(`- ${error.members.join(', ')}: ${error.message}`);
    });
}
```

See [Validation](/arc/frontend/react/commands/validation/) for more details.

## Using with Factories

[Section titled “Using with Factories”](#using-with-factories)

Create factory functions for common command patterns:

```typescript
function createAccountCommand(data: {
    accountId: string;
    name: string;
    owner: string;
    initialBalance?: number;
}): OpenDebitAccount {
    const command = new OpenDebitAccount();
    command.accountId = data.accountId;
    command.name = data.name;
    command.owner = data.owner;

// Set initial values for change tracking
    command.setInitialValues(data);

return command;
}

// Usage
const command = createAccountCommand({
    accountId: crypto.randomUUID(),
    name: 'Savings Account',
    owner: 'user-123'
});

await command.execute();
```

## Error Handling

[Section titled “Error Handling”](#error-handling)

Always handle errors properly with imperative usage:

```typescript
async function executeCommand(command: OpenDebitAccount) {
    try {
        const result = await command.execute();

if (!result.isSuccess) {
            if (!result.isAuthorized) {
                throw new Error('Unauthorized');
            }
            if (!result.isValid) {
                const errors = result.validationResults.map(v => v.message).join(', ');
                throw new Error(`Validation failed: ${errors}`);
            }
            if (result.hasExceptions) {
                throw new Error(result.exceptionMessages.join(', '));
            }
        }

return result.response;
    } catch (error) {
        console.error('Command execution failed:', error);
        throw error;
    }
}
```

## Integration with React (Advanced)

[Section titled “Integration with React (Advanced)”](#integration-with-react-advanced)

While React hooks are preferred, you can use imperative commands within React components for specific scenarios:

```typescript
import { useState } from 'react';
import { OpenDebitAccount } from './generated/commands';

export const AccountCreator = () => {
    const [processing, setProcessing] = useState(false);

const handleQuickCreate = async () => {
        setProcessing(true);

// Create and execute command imperatively
        const command = new OpenDebitAccount();
        command.accountId = crypto.randomUUID();
        command.name = 'Quick Account';
        command.owner = 'default-owner';

try {
            const result = await command.execute();
            if (result.isSuccess) {
                alert('Account created!');
            }
        } finally {
            setProcessing(false);
        }
    };

return (
        <button onClick={handleQuickCreate} disabled={processing}>
            Quick Create Account
        </button>
    );
};
```

**Note:** For React components, prefer using the [React Hook Usage](/arc/frontend/react/commands/react-usage/) approach, as it provides automatic re-rendering and better integration with React’s lifecycle.

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Use React Hooks in Components**: Only use imperative approach when necessary
2. **Handle All Result States**: Check `isSuccess`, `isValid`, `isAuthorized`
3. **Set Initial Values**: Call `setInitialValues()` when you need change tracking
4. **Error Handling**: Always handle errors appropriately
5. **Type Safety**: Leverage TypeScript for type checking
6. **Testing**: Imperative usage is excellent for unit testing
7. **Documentation**: Document why imperative usage was chosen over hooks

## When NOT to Use Imperative Usage

[Section titled “When NOT to Use Imperative Usage”](#when-not-to-use-imperative-usage)

Avoid imperative usage when:

* You’re in a React component (use hooks instead)
* You need automatic re-rendering
* You want React lifecycle integration
* Building forms (use [CommandForm](/arc/frontend/react/command-form/))

## See Also

[Section titled “See Also”](#see-also)

* [Commands Overview](/arc/frontend/react/commands/)
* [React Hook Usage](/arc/frontend/react/commands/react-usage/) - Recommended approach for React
* [Data Binding](/arc/frontend/react/commands/data-binding/)
* [Validation](/arc/frontend/react/commands/validation/)
* [CommandForm](/arc/frontend/react/command-form/)
* [Core Commands](/arc/frontend/core/commands/) - Lower-level command concepts

# React Hook Usage

Working with commands in React requires integration with React’s component lifecycle and rendering pipeline. The proxy-generated command classes provide a static `.use()` method that makes commands work seamlessly with React.

## Overview

[Section titled “Overview”](#overview)

The `.use()` method integrates commands with React’s rendering pipeline and provides automatic re-rendering for state changes such as `hasChanges`. It internally calls the `useCommand()` hook and returns a tuple containing:

1. **Command instance** - The actual command object with all properties and methods
2. **SetCommandValues function** - A function to update multiple command properties at once

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

```typescript
import { OpenDebitAccount } from './generated/commands';

export const MyComponent = () => {
    const [openDebitAccount, setCommandValues] = OpenDebitAccount.use();

return (
        <></>
    );
};
```

## With Initial Values

[Section titled “With Initial Values”](#with-initial-values)

The `.use()` method accepts an optional `initialValues` parameter to set the command’s initial state:

```typescript
export const MyComponent = () => {
    const [openDebitAccount, setCommandValues] = OpenDebitAccount.use({
        accountId: 'a23edccc-6cb5-44fd-a7a7-7563716fb080',
        name: 'My Account',
        owner: '84cda809-9201-4d8c-8589-0be37c6e3f18'
    });

return (
        <></>
    );
};
```

## Working with the Command Instance

[Section titled “Working with the Command Instance”](#working-with-the-command-instance)

The first element of the tuple gives you access to the command’s properties, methods, and state:

```typescript
export const MyComponent = () => {
    const [command] = OpenDebitAccount.use();

const handleSubmit = async () => {
        if (command.hasChanges) {
            const result = await command.execute();
            // Handle result - see CommandResult documentation
        }
    };

return (
        <input
            value={command.name}
            onChange={(e) => command.name = e.target.value}
        />
    );
};
```

### Available Properties and Methods

[Section titled “Available Properties and Methods”](#available-properties-and-methods)

**Properties:**

* `hasChanges` - Boolean indicating if any property has changed from initial values
* Command-specific properties (generated from your backend command)

**Methods:**

* `execute()` - Executes the command and returns a `CommandResult`
* `validate()` - Validates the command without executing it (see [Validation](/arc/frontend/react/commands/validation/))
* `setInitialValues(values)` - Sets the initial values for change tracking

## Updating Multiple Properties

[Section titled “Updating Multiple Properties”](#updating-multiple-properties)

The second element of the tuple allows you to update multiple properties at once, which is useful when loading data from a query or API:

```typescript
export const MyComponent = () => {
    const [command, setCommandValues] = OpenDebitAccount.use();

useEffect(() => {
        // Load data from an API or query
        fetchAccountData().then(data => {
            setCommandValues(data);
        });
    }, []);

return (
        <></>
    );
};
```

This approach:

* Updates all specified properties in one operation
* Triggers a single re-render
* Maintains change tracking correctly

## Complete Example

[Section titled “Complete Example”](#complete-example)

Here’s a complete example showing form handling with a command:

```typescript
import { OpenDebitAccount } from './generated/commands';
import { useState } from 'react';

export const OpenAccountForm = () => {
    const [command, setCommandValues] = OpenDebitAccount.use({
        accountId: crypto.randomUUID(),
        name: '',
        owner: ''
    });
    const [submitting, setSubmitting] = useState(false);
    const [error, setError] = useState<string | null>(null);

const handleSubmit = async (e: React.FormEvent) => {
        e.preventDefault();

if (!command.hasChanges) {
            return; // No changes to save
        }

setSubmitting(true);
        setError(null);

try {
            const result = await command.execute();

if (result.isSuccess) {
                // Handle success - maybe navigate away or show success message
                console.log('Account opened successfully');
            } else {
                // Handle validation or authorization errors
                if (!result.isValid) {
                    setError('Validation failed: ' + result.validationResults.map(v => v.message).join(', '));
                } else if (!result.isAuthorized) {
                    setError('You are not authorized to perform this action');
                } else {
                    setError('An error occurred');
                }
            }
        } catch (err) {
            setError('Network error: ' + err.message);
        } finally {
            setSubmitting(false);
        }
    };

return (
        <form onSubmit={handleSubmit}>
            <div>
                <label>
                    Account Name:
                    <input
                        type="text"
                        value={command.name}
                        onChange={(e) => command.name = e.target.value}
                        required
                    />
                </label>
            </div>

<div>
                <label>
                    Owner ID:
                    <input
                        type="text"
                        value={command.owner}
                        onChange={(e) => command.owner = e.target.value}
                        required
                    />
                </label>
            </div>

{error && <div className="error">{error}</div>}

<button
                type="submit"
                disabled={!command.hasChanges || submitting}
            >
                {submitting ? 'Opening Account...' : 'Open Account'}
            </button>
        </form>
    );
};
```

## React Re-rendering

[Section titled “React Re-rendering”](#react-re-rendering)

The `.use()` hook ensures your component re-renders when:

* Command properties change
* `hasChanges` state changes
* Command execution completes

This provides a seamless integration between the command pattern and React’s declarative UI model.

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Use Destructuring**: Destructure only what you need from the tuple

```typescript
   const [command] = OpenDebitAccount.use(); // If you don't need setCommandValues
   ```

2. **Initialize with Data**: Pass initial values when you have them

```typescript
   const [command] = OpenDebitAccount.use(existingData);
   ```

3. **Check hasChanges**: Prevent unnecessary submissions

```typescript
   if (!command.hasChanges) return;
   ```

4. **Handle All Result States**: Always check `isSuccess`, `isValid`, and `isAuthorized`

5. **Use CommandForm**: For complex forms, consider using [CommandForm](/arc/frontend/react/command-form/) which handles much of this automatically

## See Also

[Section titled “See Also”](#see-also)

* [Commands Overview](/arc/frontend/react/commands/)
* [Data Binding](/arc/frontend/react/commands/data-binding/)
* [Validation](/arc/frontend/react/commands/validation/)
* [Command Scope](/arc/frontend/react/commands/scope/)
* [CommandForm](/arc/frontend/react/command-form/) - Declarative form component for commands
* [Imperative Usage](/arc/frontend/react/commands/imperative-usage/) - Advanced non-React usage

# Command Scope

If you want to track commands and create an aggregation of their status at a compositional level, the command scope provides a React context for this. This is typically useful when having something like a top level toolbar with a **Save** button that you want to enable or disable depending on whether or not there are changes within any components used within it, or a loading indicator when commands or queries are being performed.

Using the toolbar scenario as an example; at the top level we can wrap everything in the `<CommandScope>` component. This will establish a React context for this part of the hierarchy and track any commands and queries used within any descendants.

```typescript
import { CommandScope } from '@cratis/arc.react/commands';

export const MyComposition = () => {
    const [hasChanges, setHasChanges] = useState(false);
    const [isPerforming, setIsPerforming] = useState(false);

return (
        <CommandScope
            setHasChanges={setHasChanges}
            setIsPerforming={setIsPerforming}>
            <Toolbar hasChanges={hasChanges} isPerforming={isPerforming}/>
            <FirstComponent/>
            <SecondComponent/>
        </CommandScope>
    );
};
```

## Hierarchical Scopes

[Section titled “Hierarchical Scopes”](#hierarchical-scopes)

Command scopes can be nested to create a hierarchy. When you add a `<CommandScope>` inside another one, the inner scope automatically registers itself with the nearest outer scope. Commands always bind to the **nearest** enclosing scope, so each part of the component tree only tracks the commands directly beneath it. The outer scope aggregates state across all inner scopes, giving you both local and global views of changes, performing state, validation failures, and exceptions.

```typescript
export const MyPage = () => {
    const [hasChanges, setHasChanges] = useState(false);
    const [hasValidationFailures, setHasValidationFailures] = useState(false);

return (
        <CommandScope setHasChanges={setHasChanges}>
            {/* PageToolbar sees aggregate state for the whole page */}
            <PageToolbar hasChanges={hasChanges} hasValidationFailures={hasValidationFailures}/>
            <Section1>
                <CommandScope>
                    {/* SectionToolbar only sees state for Section1's commands */}
                    <SectionToolbar/>
                    <SectionContent/>
                </CommandScope>
            </Section1>
        </CommandScope>
    );
};
```

In this example:

* Commands inside `<Section1>` bind to the inner `<CommandScope>`.
* The outer `<CommandScope>` sees their state through the nested scope link.
* `pageScope.hasValidationFailures` is `true` whenever any inner scope has failures.

## Validation Failures and Exceptions

[Section titled “Validation Failures and Exceptions”](#validation-failures-and-exceptions)

The `CommandScope` tracks which commands produced validation failures or exceptions after execution. These are cleared automatically when a command executes again — you never need to reset them manually.

### Checking aggregate state

[Section titled “Checking aggregate state”](#checking-aggregate-state)

```typescript
import { useCommandScope } from '@cratis/arc.react/commands';

export const Toolbar = () => {
    const scope = useCommandScope();

return (
        <div>
            {scope.hasValidationFailures && (
                <span className="error">Some inputs have validation errors.</span>
            )}
            {scope.hasExceptions && (
                <span className="error">An unexpected error occurred.</span>
            )}
        </div>
    );
};
```

### Inspecting per-command detail

[Section titled “Inspecting per-command detail”](#inspecting-per-command-detail)

When you need to know exactly which command had a problem and what the errors were, use the `validationFailures` and `exceptions` maps. Both are `ReadonlyMap<ICommand, ...>`.

If you only need a flattened aggregate view (across the current scope and all nested child scopes), use `aggregatedValidationFailures` and `aggregatedExceptions`.

```typescript
const scope = useCommandScope();

// Validation failures — map of command → ValidationResult[]
for (const [command, failures] of scope.validationFailures) {
    failures.forEach(f => console.log(f.message, f.members));
}

// Exceptions — map of command → string[]
for (const [command, messages] of scope.exceptions) {
    messages.forEach(m => console.log(m));
}

// Flattened aggregates across this scope and child scopes
scope.aggregatedValidationFailures.forEach(f => console.log(f.message));
scope.aggregatedExceptions.forEach(m => console.log(m));
```

Only the **own commands** of a scope appear in its `validationFailures` and `exceptions` maps. Commands from nested child scopes appear in those child scopes’ maps, but bubble up to the parent via `hasValidationFailures` and `hasExceptions`.

### Automatic clearing on re-execution

[Section titled “Automatic clearing on re-execution”](#automatic-clearing-on-re-execution)

When a command executes again, its previous failures and exceptions are cleared **before** the new execution begins. This means a scope’s `hasValidationFailures` and `hasExceptions` always reflect the result of the most recent execution, not a stale prior result.

```typescript
// First execute — validation fails
await scope.execute();
console.log(scope.hasValidationFailures); // true

// User fixes the input; execute again — succeeds
await scope.execute();
console.log(scope.hasValidationFailures); // false — automatically cleared
```

You can provide callbacks to the `<CommandScope>` component to react to command execution results. These callbacks are invoked for any command tracked within the scope, and each receives the specific command that was executed together with its result.

### Before Execution

[Section titled “Before Execution”](#before-execution)

The `onBeforeExecute` callback is called just before each command is executed:

```typescript
<CommandScope onBeforeExecute={(command) => console.log('About to execute', command)}>
    {/* ... */}
</CommandScope>
```

### Result Callbacks

[Section titled “Result Callbacks”](#result-callbacks)

The result callbacks mirror the callbacks available on `CommandResult` but also include the command instance so you can identify which command produced the result:

```typescript
<CommandScope
    onSuccess={(command, result) => {
        console.log('Command succeeded:', command, result);
    }}
    onFailed={(command, result) => {
        console.log('Command failed:', command, result);
    }}
    onException={(command, result) => {
        console.log('Command threw an exception:', command, result.exceptionMessages);
    }}
    onUnauthorized={(command, result) => {
        console.log('Command was unauthorized:', command);
    }}
    onValidationFailure={(command, result) => {
        console.log('Command had validation errors:', command, result.validationResults);
    }}>
    {/* ... */}
</CommandScope>
```

| Callback                               | When called                                          |
| -------------------------------------- | ---------------------------------------------------- |
| `onBeforeExecute(command)`             | Before each command is executed                      |
| `onSuccess(command, result)`           | When a command executes successfully                 |
| `onFailed(command, result)`            | When a command fails for any reason                  |
| `onException(command, result)`         | When a command fails due to an exception             |
| `onUnauthorized(command, result)`      | When a command fails due to an authorization failure |
| `onValidationFailure(command, result)` | When a command fails due to validation errors        |

Note that `onFailed` is always called alongside the more specific callbacks (`onException`, `onUnauthorized`, `onValidationFailure`) when the command fails.

## Command Scope API

[Section titled “Command Scope API”](#command-scope-api)

The command scope provides the following properties and methods:

| Name                         | Type                                        | Description                                                                                         |
| ---------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| hasChanges                   | Boolean                                     | Whether or not there are changes in any commands within the scope                                   |
| isPerforming                 | Boolean                                     | Whether or not any commands or queries are currently being performed                                |
| hasValidationFailures        | Boolean                                     | Whether any commands in this scope or child scopes have validation failures from the last execution |
| hasExceptions                | Boolean                                     | Whether any commands in this scope or child scopes produced exceptions in the last execution        |
| validationFailures           | ReadonlyMap\<ICommand, ValidationResult\[]> | Validation failures per command for this scope’s own commands                                       |
| exceptions                   | ReadonlyMap\<ICommand, string\[]>           | Exception messages per command for this scope’s own commands                                        |
| aggregatedValidationFailures | ReadonlyArray\<ValidationResult>            | Flattened validation failures across this scope and all child scopes                                |
| aggregatedExceptions         | ReadonlyArray\<string>                      | Flattened exception messages across this scope and all child scopes                                 |
| parent                       | ICommandScope \| undefined                  | The parent scope, if this scope is nested                                                           |
| execute()                    | Promise\<CommandResults>                    | Execute all commands with changes within the scope                                                  |
| revertChanges()              | void                                        | Revert any changes to commands within the scope                                                     |
| addCommand(command)          | void                                        | Manually add a command for tracking (usually done automatically)                                    |
| addQuery(query)              | void                                        | Manually add a query for tracking (usually done automatically)                                      |
| addChildScope(scope)         | void                                        | Register a child scope for aggregate state propagation (done automatically)                         |

## Using Command Scope in React

[Section titled “Using Command Scope in React”](#using-command-scope-in-react)

To consume the command scope context you can use the hook that is provided.

```typescript
import { useCommandScope } from '@cratis/arc.react/commands';

export const Toolbar = ({ hasChanges, isPerforming }) => {
    const commandScope = useCommandScope();

return (
        <div>
            <button
                disabled={!hasChanges || isPerforming}
                onClick={() => commandScope.execute()}>
                Save
            </button>
            <button
                disabled={!hasChanges || isPerforming}
                onClick={() => commandScope.revertChanges()}>
                Cancel
            </button>
            {isPerforming && <Spinner />}
        </div>
    );
};
```

The hook is a convenience hook that makes it easier to get the context. You can also consume the context directly by using its consumer:

```typescript
import { CommandScopeContext } from '@cratis/arc.react/commands';

export const Toolbar = () => {
    return (
        <div>
            <CommandScopeContext.Consumer>
                {value => {
                    return (
                        <button disabled={!value.hasChanges}>Save</button>
                    )
                }}
            </CommandScopeContext.Consumer>
        </div>
    );
};
```

## Using Command Scope in ViewModels

[Section titled “Using Command Scope in ViewModels”](#using-command-scope-in-viewmodels)

The command scope can also be injected into ViewModels through dependency injection. The ViewModel will automatically receive the closest command scope in the component hierarchy.

```typescript
import { ICommandScope } from '@cratis/arc.react/commands';
import { injectable } from 'tsyringe';

@injectable()
export class MyViewModel {
    constructor(private readonly _commandScope: ICommandScope) {
    }

get hasChanges(): boolean {
        return this._commandScope.hasChanges;
    }

get isPerforming(): boolean {
        return this._commandScope.isPerforming;
    }

async save() {
        if (!this.hasChanges || this.isPerforming) {
            return;
        }

await this._commandScope.execute();
    }

cancel() {
        this._commandScope.revertChanges();
    }
}
```

## Automatic Command and Query Tracking

[Section titled “Automatic Command and Query Tracking”](#automatic-command-and-query-tracking)

For the `<FirstComponent>` we could then have something like below:

```typescript
export const FirstComponent = () => {
    const myCommand = MyCommand.use();

return (
        <div>
            <input type="text" value={command.someValue} onChange={(e,v) => myCommand.someValue = v; }/>
        </div>
    )
}
```

Commands created with the `use()` hook are automatically added to the nearest command scope.

Queries are also automatically tracked:

```typescript
export const SecondComponent = () => {
    const [result] = useQuery(MyQuery, { id: '123' });

return (
        <div>
            {result.data && <DisplayData data={result.data} />}
        </div>
    )
}
```

Any changes to properties within commands will bubble up to the context and affect the state flags (`hasChanges`, `isPerforming`).

# Command Validation

Command validation enables pre-flight validation of commands without executing them. This provides early feedback to users in React applications before performing potentially expensive or state-changing operations.

## Purpose

[Section titled “Purpose”](#purpose)

The validation mechanism allows you to check authorization and validation rules without executing the command handler. This is essential for:

* **Early User Feedback**: Show validation errors before the user submits a form
* **UX Improvements**: Enable/disable submit buttons based on validation state
* **Authorization Checks**: Verify user permissions without side effects
* **Progressive Validation**: Validate fields as users interact with forms

## How It Works

[Section titled “How It Works”](#how-it-works)

When you validate a command, the request is sent to the backend validation endpoint where:

1. All command filters run (authorization, validation)
2. The command handler is **not** executed
3. A `CommandResult` is returned with validation and authorization status
4. No side effects occur on the system

For details on:

* The TypeScript command validation API, see [Core Validation](/arc/frontend/core/commands/validation/)
* The backend validation pipeline, see [Backend Command Validation](/arc/backend/commands/command-validation/)

## React Hook Usage

[Section titled “React Hook Usage”](#react-hook-usage)

React commands created with `.use()` include the `validate()` method:

```typescript
import { CreateOrder } from './generated/commands';

function OrderForm() {
    const [command, setValues] = CreateOrder.use();
    const [validationErrors, setValidationErrors] = useState<string[]>([]);

const handleFieldBlur = async () => {
        // Validate on field blur for early feedback
        const result = await command.validate();

if (!result.isValid) {
            setValidationErrors(result.validationResults.map(v => v.message));
        } else {
            setValidationErrors([]);
        }
    };

const handleSubmit = async () => {
        // Execute the command
        const result = await command.execute();

if (result.isSuccess) {
            // Handle success
        }
    };

return (
        <form onSubmit={handleSubmit}>
            <input
                value={command.orderNumber}
                onChange={e => command.orderNumber = e.target.value}
                onBlur={handleFieldBlur}
            />
            {validationErrors.map(error => (
                <div key={error} className="error">{error}</div>
            ))}
            <button type="submit">Create Order</button>
        </form>
    );
}
```

## Progressive Validation

[Section titled “Progressive Validation”](#progressive-validation)

You can validate commands reactively as properties change:

```typescript
function ProductOrderForm() {
    const [command, setValues] = CreateOrder.use();
    const [canSubmit, setCanSubmit] = useState(false);

useEffect(() => {
        // Validate whenever command properties change
        const validateCommand = async () => {
            const result = await command.validate();
            setCanSubmit(result.isSuccess);
        };

validateCommand();
    }, [command.hasChanges]);

return (
        <form>
            <input
                value={command.productId}
                onChange={e => command.productId = e.target.value}
            />
            <input
                value={command.quantity}
                onChange={e => command.quantity = parseInt(e.target.value)}
            />
            <button
                type="submit"
                disabled={!canSubmit}
                onClick={() => command.execute()}
            >
                Create Order
            </button>
        </form>
    );
}
```

## Debounced Validation

[Section titled “Debounced Validation”](#debounced-validation)

To avoid excessive server calls during typing, debounce your validation:

```typescript
import { useMemo, useEffect } from 'react';
import { debounce } from 'lodash';

function OrderForm() {
    const [command] = CreateOrder.use();
    const [errors, setErrors] = useState<string[]>([]);

const debouncedValidate = useMemo(
        () => debounce(async () => {
            const result = await command.validate();

if (!result.isSuccess) {
                setErrors(result.validationResults.map(v => v.message));
            } else {
                setErrors([]);
            }
        }, 500),
        [command]
    );

useEffect(() => {
        if (command.hasChanges) {
            debouncedValidate();
        }
    }, [command.orderNumber, command.quantity, debouncedValidate]);

return (
        <form>
            <input
                value={command.orderNumber}
                onChange={e => command.orderNumber = e.target.value}
            />
            {errors.map(error => (
                <div key={error} className="error">{error}</div>
            ))}
            <button onClick={() => command.execute()}>
                Create Order
            </button>
        </form>
    );
}
```

## Validation on Blur

[Section titled “Validation on Blur”](#validation-on-blur)

A common pattern is to validate when a field loses focus:

```typescript
function CustomerForm() {
    const [command] = CreateCustomer.use();
    const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({});

const validateField = async (fieldName: string) => {
        const result = await command.validate();

if (!result.isValid) {
            const fieldError = result.validationResults.find(
                v => v.members.includes(fieldName)
            );

if (fieldError) {
                setFieldErrors(prev => ({
                    ...prev,
                    [fieldName]: fieldError.message
                }));
            }
        } else {
            setFieldErrors(prev => {
                const { [fieldName]: _, ...rest } = prev;
                return rest;
            });
        }
    };

return (
        <form>
            <div>
                <input
                    value={command.email}
                    onChange={e => command.email = e.target.value}
                    onBlur={() => validateField('email')}
                />
                {fieldErrors.email && (
                    <span className="error">{fieldErrors.email}</span>
                )}
            </div>
            <div>
                <input
                    value={command.phone}
                    onChange={e => command.phone = e.target.value}
                    onBlur={() => validateField('phone')}
                />
                {fieldErrors.phone && (
                    <span className="error">{fieldErrors.phone}</span>
                )}
            </div>
            <button onClick={() => command.execute()}>
                Create Customer
            </button>
        </form>
    );
}
```

## CommandResult Structure

[Section titled “CommandResult Structure”](#commandresult-structure)

Both `execute()` and `validate()` return the same `CommandResult` structure:

```typescript
interface CommandResult<TResponse> {
    correlationId: string;
    isSuccess: boolean;        // Overall success (authorized + valid + no exceptions)
    isAuthorized: boolean;     // Authorization status
    isValid: boolean;          // Validation status
    hasExceptions: boolean;    // Whether exceptions occurred
    validationResults: ValidationResult[];
    exceptionMessages: string[];
    exceptionStackTrace: string;
    response?: TResponse;      // Only populated on execute()
}
```

**Note**: The `response` property will be `null` or `undefined` when using `validate()` since the handler is not executed.

## Best Practices

[Section titled “Best Practices”](#best-practices)

### When to Use Validate

[Section titled “When to Use Validate”](#when-to-use-validate)

✅ **Good Use Cases:**

* Form validation as users type or blur fields
* Enabling/disabling submit buttons based on validation state
* Showing validation messages before submission
* Checking authorization before showing UI elements

❌ **Avoid:**

* Calling validate() immediately before execute() (execute already validates)
* Over-validating (don’t validate on every keystroke without debouncing)
* Using validate() as a substitute for client-side validation

### Performance Considerations

[Section titled “Performance Considerations”](#performance-considerations)

* Validation makes a server round-trip, so use judiciously
* Always debounce validation calls for real-time feedback
* Client-side validation is still important for immediate feedback
* Server validation ensures security and data integrity

## Security Considerations

[Section titled “Security Considerations”](#security-considerations)

* Validation endpoints run the same authorization filters as execute endpoints
* Unauthorized users receive 401/403 responses from validation endpoints
* Validation does not expose sensitive data since handlers aren’t executed
* Validation results may reveal authorization policies (by design)

## Troubleshooting

[Section titled “Troubleshooting”](#troubleshooting)

### Validation is slow

[Section titled “Validation is slow”](#validation-is-slow)

**Cause**: Complex validation logic or database queries in validators.

**Solution**:

* Debounce validation calls
* Optimize validator implementations on the backend
* Consider client-side validation for immediate feedback

### Validation passes but execute fails

[Section titled “Validation passes but execute fails”](#validation-passes-but-execute-fails)

**Cause**: State may have changed between validate and execute calls, or the handler encountered an error.

**Solution**: This is expected behavior. Always check the result of `execute()` for the authoritative status.

# Dialogs

Cratis Arc provides a consistent way of working with dialogs independent of component libraries. The purpose is to promote a way of working with dialogs as separate components and not something you do inline within another component.

## Confirmation Dialogs

[Section titled “Confirmation Dialogs”](#confirmation-dialogs)

A common use of modal dialogs are the standard confirmation dialogs. These are dialogs where you ask the user to confirm a specific action. The Arc supports these out of the box and you have options for what type of confirmation you’re looking for in the form of passing it which buttons to show.

There is an enum called `DialogButtons` that has the following options:

| Value       | Description                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------- |
| Ok          | Only show a single Ok button, typically used to inform the user and the user to acknowledge |
| OkCancel    | Show both an Ok and a Cancel button                                                         |
| YesNo       | Show a Yes and No button                                                                    |
| YesNoCancel | Show Yes, No and a Cancel button                                                            |

For standard confirmation dialogs, there is a specific expected result called `DialogResult` that the dialog needs to communicate back. The values are:

* Yes
* No
* Ok
* Cancel

There is a custom React hook for leveraging this type of dialog.

```tsx
import { Button } from 'primereact/button';
import { DialogButtons, useConfirmationDialog } from '@cratis/arc.react/dialogs';

export const Feature = () => {
    const [showConfirmationDialog] = useConfirmationDialog('The title', 'The message', DialogButtons.YesNo);

return (
        <div>
            <Button onClick={() => showConfirmationDialog() }/>
        </div>
    )
}
```

The code uses the `useConfirmationDialog` hook that returns a function for showing the dialog. It passes the definition of the dialog as parameters to the hook, setting the title, the message and what buttons to show.

Alternatively to defining the dialog on the hook level, you can also pass it along on the `showConfirmationDialog` function returned.

```tsx
import { Button } from 'primereact/button';
import { DialogButtons, useConfirmationDialog } from '@cratis/arc.react/dialogs';

export const Feature = () => {
    const [showConfirmationDialog] = useConfirmationDialog();

return (
        <div>
            <Button onClick={() => showConfirmationDialog('The title', 'The message', DialogButtons.YesNo) }/>
        </div>
    )
}
```

The code uses the `showConfirmationDialog` function to pass the definition of the dialog, rather than using the hook.

In order for there to be a confirmation dialog at all, you need to define how it looks like and also configure it for your app.

### Defining the Confirmation Dialog

[Section titled “Defining the Confirmation Dialog”](#defining-the-confirmation-dialog)

You define a confirmation dialog on the application level. It is then the dialog that will be used across your entire application.

The anatomy of any dialog is that it uses the `useDialogContext()` in the dialog itself to get what context it is in. With the context you get access to the actual request payload and the method to call when the dialog should close; `closeDialog`.

Below is an example using [Prime React](http://primereact.org) to create a confirmation dialog supporting the different button types.

```tsx
import { Dialog } from 'primereact/dialog';
import { DialogButtons, DialogResult, ConfirmationDialogRequest, useDialogContext } from '@cratis/arc.react/dialogs';
import { Button } from 'primereact/button';

export const ConfirmationDialog = () => {
    const { request, closeDialog } = useDialogContext<ConfirmationDialogRequest>();

const headerElement = (
        <div className="inline-flex align-items-center justify-content-center gap-2">
            <span className="font-bold white-space-nowrap">{request.title}</span>
        </div>
    );

const okFooter = (
        <>
            {/* Hook up buttons with function to close the dialog with expected DialogResult */}
            <Button label="Ok" icon="pi pi-check" onClick={() => closeDialog(DialogResult.Ok)} autoFocus />
        </>
    );

const okCancelFooter = (
        <>
            {/* Hook up buttons with function to close the dialog with expected DialogResult */}
            <Button label="Ok" icon="pi pi-check" onClick={() => closeDialog(DialogResult.Ok)} autoFocus />
            <Button label="Cancel" icon="pi pi-times" severity='secondary' onClick={() => closeDialog(DialogResult.Cancelled)} />
        </>
    );

const yesNoFooter = (
        <>
            {/* Hook up buttons with function to close the dialog with expected DialogResult */}
            <Button label="Yes" icon="pi pi-check" onClick={() => closeDialog(DialogResult.Yes)} autoFocus />
            <Button label="No" icon="pi pi-times" severity='secondary' onClick={() => closeDialog(DialogResult.No)} />
        </>
    );

const yesNoCancelFooter = (
        <>
            {/* Hook up buttons with function to close the dialog with expected DialogResult */}
            <Button label="Yes" icon="pi pi-check" onClick={() => closeDialog(DialogResult.Yes)} autoFocus />
            <Button label="No" icon="pi pi-times" severity='secondary' onClick={() => closeDialog(DialogResult.No)} />
        </>
    );

const getFooterInterior = () => {
        switch (request.buttons) {
            case DialogButtons.Ok:
                return okFooter;
            case DialogButtons.OkCancel:
                return okCancelFooter;
            case DialogButtons.YesNo:
                return yesNoFooter;
            case DialogButtons.YesNoCancel:
                return yesNoCancelFooter;
        }

return (<></>)
    }

const footer = (
        <div className="card flex flex-wrap justify-content-center gap-3">
            {getFooterInterior()}
        </div>
    );

return (
        <>
            {/* On hide we call the closeDialog with cancelled */}
            <Dialog header={headerElement} modal footer={footer} onHide={() => closeDialog(DialogResult.Cancelled)} visible={true}>
                <p className="m-0">
                    {request.message}
                </p>
            </Dialog>
        </>
    );
};
```

The code above uses the `useDialogContext()` with the `ConfirmationDialogRequest` and `DialogResult` as the types expected from the request and response type. Within the rendering of the component you’ll notice that buttons are hooked up to close the dialog with the expected `DialogResult`. Once a button is called, it closes the dialog with a response that will be passed onto the `Promise` created within the `IDialogs` service.

> Note: It is possible to take the **request** as props instead of using it from the dialog context `export const ConfirmationDialog = (props: ConfirmationDialogRequest) ....`

To enable the new `ConfirmationDialog` all you need to do is hook it up in your application like below.

```tsx
export const App = () => {
    return (
        <DialogComponents confirmation={ConfirmationDialog}>
            {/* Your application */}
        </DialogComponents>
    );
};
```

## Busy indicator dialogs

[Section titled “Busy indicator dialogs”](#busy-indicator-dialogs)

Another common type of modal dialog is the indeterminate busy indicator dialog. You typically use these dialogs for giving a visual clue to the user that the system is working. These type of dialogs are not meant to be something the user can close, but rather something the system closes when it is ready with the work the system is doing.

There is a custom React hook for showing a busy indicator.

```tsx
import { Button } from 'primereact/button';
import {useBusyIndicator } from '@cratis/arc.react/dialogs';

export const Feature = () => {
    const [showBusyIndicator, closeBusyIndicator] = useBusyIndicator('The title', 'The message');

return (
        <div>
            <Button onClick={() => {
                showBusyIndicator();

setTimeout(() => {
                    closeBusyIndicator();
                }, 1000);
            }} />
        </div>
    )
}
```

The code uses the `useBusyIndicator` hook that returns a function for showing the dialog. It passes the definition of the dialog as parameters to the hook, setting the title and the message to show.

Alternatively to defining the dialog on the hook level, you can also pass it along on the `useBusyIndicator` function returned.

```tsx
import { Button } from 'primereact/button';
import {useBusyIndicator } from '@cratis/arc.react/dialogs';

export const Feature = () => {
    const [showBusyIndicator, closeBusyIndicator] = useBusyIndicator();

return (
        <div>
            <Button onClick={() => {
                showBusyIndicator('The title', 'The message');

setTimeout(() => {
                    closeBusyIndicator();
                }, 1000);
            }} />
        </div>
    )
}
```

The code uses the `showBusyIndicator` function to pass the definition of the dialog, rather than using the hook.

In order for there to be a busy indicator dialog at all, you need to define how it looks like and also configure it for your app.

### Defining the Busy Indicator Dialog

[Section titled “Defining the Busy Indicator Dialog”](#defining-the-busy-indicator-dialog)

As with the confirmation dialog, you define a busy indicator dialog on the application level. It is then the dialog that will be used across your entire application.

Below is an example using [Prime React](http://primereact.org) to create a confirmation dialog supporting the different button types.

```tsx
import { Dialog } from 'primereact/dialog';
import { BusyIndicatorDialogRequest, useDialogContext } from '@cratis/arc.react/dialogs';
import { ProgressSpinner } from 'primereact/progressspinner';

export const BusyIndicatorDialog = () => {
    const { request } = useDialogContext<BusyIndicatorDialogRequest, DialogResult>();

return (
        <>
            <Dialog header={headerElement} modal visible={true} onHide={() => { }}>
                <ProgressSpinner />
                <p className="m-0">
                    {request.message}
                </p>
            </Dialog>
        </>
    );
};
```

The code above uses the `useDialogContext()` with the `BusyIndicatorDialogRequest` and `DialogResult` as the types expected from the request and response type. For this implementation, it shows a spinner.

> Note: It is possible to take the **request** as props instead of using it from the dialog context. `export const BusyIndicatorDialog = (props: BusyIndicatorDialogRequest) ....`

To enable the new `BusyIndicatorDialog` all you need to do is hook it up in your application like below.

```tsx
export const App = () => {
    return (
        <DialogComponents busyIndicator={BusyIndicatorDialog}>
            {/* Your application */}
        </DialogComponents>
    );
};
```

## Custom dialogs

[Section titled “Custom dialogs”](#custom-dialogs)

Creating a custom dialog is basically just creating a component that represents the dialog and then use the `useDialog()` hook in the component you want to use the component.

For **closing** the dialog you do however need access to a function that will close it and pass any result back to the consumer. This can either be done through a **props** definition for the dialog component that holds the function or you can get to it by getting the **dialog context**.

The following code creates a custom dialog component using [Prime React](http://primereact.org).

```tsx
import { Button } from 'primereact/button';
import { Dialog } from 'primereact/dialog';
import { useDialogContext, DialogResult } from '@cratis/arc.react/dialogs';

export const CustomDialog = () => {
    const { request, closeDialog } = useDialogContext();

return (
        <Dialog header="My custom dialog" visible={true} onHide={() => closeDialog(DialogResult.Cancelled, 'Did not do it..')}>
            <h2>Dialog</h2>
            {request.content}
            <br />
            <Button onClick={() => closeDialog(DialogResult.Ok, 'Done done done...')}>We're done</Button>
        </Dialog>
    );
};
```

The dialog component is a standard component with the exception of the use of the `useDialogContext()` hook. This hook gives you the current details about the dialog and a function delegate for closing the dialog.

With the `closeDialog` delegate you get to signal what the result of the dialog was and if there is an expected response, you can also communicate this back to the consumer.

> Note: The `visible` property is always true. This is by design as the logic for showing it or not is handled by the `useDialog` hook itself.

For consuming the dialog, we use the `useDialog()` hook. The following code shows an example of this.

```tsx
import { CustomDialog } from './CustomDialog';
import { Button } from 'primereact/button';

export const Feature = () => {
    const [CustomDialogWrapper, showCustomDialog] = useDialog<string>(CustomDialog);

return (
        <>
            <Button onClick={async () => {
                const [result, response] = await showCustomDialog();
                if( result == DialogResult.Ok ) {
                    console.log('It was ok');
                }
                console.log(response);
            }}>Show dialog</Button>
            <CustomDialogWrapper />
        </>
    )
};
```

The `useDialog()` hook returns a tuple with the wrapper of the dialog and a function for showing the dialog. Within the component you see that the `showCustomDialog` function is an async function that will return the `DialogResult` and any response from the dialog.

# Identity

The React implementation of identity is built on top of what you find the [core](/arc/frontend/core/identity/). It provides an encapsulation that feels more natural to a React application.

## HTTP Headers

[Section titled “HTTP Headers”](#http-headers)

Identity requests automatically include any HTTP headers provided by the `httpHeadersCallback` configured in the [Arc](/arc/frontend/react/arc/). This is particularly useful for including authentication cookies or other headers needed for identity verification and retrieval.

## Identity provider context

[Section titled “Identity provider context”](#identity-provider-context)

To use the identity system you need to provide the identity context for your application.

At the top level of your application, typically in your `App.tsx` file you would add the provider by doing the following:

```typescript
import { IdentityProvider } from '@cratis/arc.react/identity';

export const App = () => {
    return (
        <IdentityProvider>
            {/* ... your app content ... */}
        </IdentityProvider>
    );
};
```

This context can then be used anywhere by consuming the React context directly:

```typescript
import { IdentityProviderContext } from '@cratis/arc.react/identity';

export const SomeComponent = () => {
    return (
        <IdentityProviderContext.Consumer>
            {({ details }) => {
                const actualDetails = details as Identity;
                return (
                    <h1>{actualDetails.firstName} {actualDetails.firstName}</h1>
                );
            }}
        </IdentityProviderContext.Consumer>
    );
};
```

> Note: As you can see, the `details` type will be of type `any` in the context. This means that if your type is a specific type, you’ll need to cast it to that type before using it.

### Refreshing

[Section titled “Refreshing”](#refreshing)

Sometimes you need to refresh the identity due to backend changes. On the `IIdentityContext` that represents the context you find a method called `refresh()`. Calling this will invalidate the cookie and also just call the backend to get the current identity details.

```typescript
import { IdentityProviderContext } from '@cratis/arc.react/identity';

export const SomeComponent = () => {
    return (
        <IdentityProviderContext.Consumer>
            {(identity) => {
                const actualDetails = identity.details as Identity;
                return (
                    <h1>{actualDetails.firstName} {actualDetails.firstName}</h1>

{/* Refresh button */}
                    <button onClick={() => identity.refresh()}>Refresh identity</button>
                );
            }}
        </IdentityProviderContext.Consumer>
    );
};
```

## useIdentity() hook

[Section titled “useIdentity() hook”](#useidentity-hook)

Anywhere within your application you can then access the identity by adding using the `useIdentity()` hook:

```typescript
import { useIdentity } from '@cratis/arc.react/identity';

export const Home = () => {
    const identity = useIdentity();

return (
        <h3>User: {identity.details.firstName} {identity.details.lastName}</h3>
    );
};
```

The `useIdentity()` hook returns the context which holds a property called `details`. This details property is what the backend returned to the ingress middleware.

By default, if not specified, the type of the details is `any`. You can change this by passing it a generic argument with the exact shape of what’s expected:

```typescript
import { useIdentity } from '@cratis/arc.react/identity';

type Identity = {
    firstName: string;
    lastName: string;
};

export const Home = () => {
    const identity = useIdentity<Identity>();

return (
        <h3>User: {identity.details.firstName} {identity.details.lastName}</h3>
    );
};
```

## Has the identity arrived yet?

[Section titled “Has the identity arrived yet?”](#has-the-identity-arrived-yet)

The identity is fetched from the backend, which means there is a moment - short, but real - where your application is rendering and nobody knows who the user is yet. `isSet` cannot tell you about that moment: it reads `false` both *before* the first request has answered and *after* it answered that nobody is signed in.

That is what `isLoading` is for. It is on the object `useIdentity()` returns and it separates the two:

```typescript
import { useIdentity } from '@cratis/arc.react/identity';

export const Greeting = () => {
    const identity = useIdentity();

if (identity.isLoading) return <Spinner />;
    if (!identity.isSet) return <SignInPrompt />;

return <h3>Welcome back, {identity.name}</h3>;
};
```

`isLoading` covers every resolution, not only the first one. Calling `refresh()` - which is what you do after a sign-in or after the backend grants a role - puts it back up until the round-trip answers, so anything that gates on who the user is keeps waiting instead of briefly deciding on the old identity.

Note that `isLoading` lives on `IIdentityContext`, not on the framework-agnostic `IIdentity` in the core package. It is a React lifecycle concern and it stays on the React side.

## Role checking

[Section titled “Role checking”](#role-checking)

The identity context includes information about the roles assigned to the user. You can check if a user is in a specific role using the `isInRole()` method, or read the roles array directly:

```typescript
import { useIdentity } from '@cratis/arc.react/identity';

export const UserProfile = () => {
    const identity = useIdentity();

return (
        <div>
            <h3>User: {identity.name}</h3>
            <p>Roles: {identity.roles.join(', ')}</p>
            {identity.isInRole('Admin') && <AdminBadge />}
        </div>
    );
};
```

That is the right shape for decorating a screen. It is the wrong shape for guarding one:

```typescript
// Don't do this - it decides on an identity that may not have arrived.
if (!identity.isInRole('Admin')) {
    return <div>Access denied. Admin role required.</div>;
}
```

Before the identity request answers, an administrator holds no roles yet - so this renders “Access denied”, then swaps to the panel a moment later. Every signed-in user sees the rejection flash by on every load. There are three outcomes here, not two, and a guard has to say something about all of them.

## Guarding a screen with RequireRole

[Section titled “Guarding a screen with RequireRole”](#guarding-a-screen-with-requirerole)

`RequireRole` is that guard. It renders one of three slots, and which one is never in doubt:

```typescript
import { RequireRole } from '@cratis/arc.react/identity';

export const Admin = () => (
    <RequireRole
        roles={['Administrator', 'Auditor']}
        whileLoading={<Spinner />}
        forbidden={<AccessDenied />}>
        <AdminPanel />
    </RequireRole>
);
```

| Prop           | Type                             | What it does                                                                                       |
| -------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
| `roles`        | `string[]`                       | Roles that grant access - the identity needs any one of them                                       |
| `allow`        | `(details, identity) => boolean` | Predicate deciding access from the identity’s details                                              |
| `children`     | `ReactNode`                      | Rendered when the caller is authenticated and allowed                                              |
| `whileLoading` | `ReactNode`                      | Rendered while the identity is still being resolved. Defaults to nothing                           |
| `forbidden`    | `ReactNode`                      | Rendered for an anonymous caller, or an authenticated one that is not allowed. Defaults to nothing |

At least one of `roles` and `allow` has to be there; the type system says so, and the component denies at runtime if `undefined` gets past it anyway. Supply both and both must pass.

`forbidden` is a slot rather than a `redirectTo` on purpose. Arc.React does not depend on a router, so instead of picking one for you it lets you hand it whatever your application already uses:

```typescript
<RequireRole roles={['Administrator']} forbidden={<Navigate to="/" replace />}>
    <AdminPanel />
</RequireRole>
```

### Deciding on details

[Section titled “Deciding on details”](#deciding-on-details)

Roles are what the backend put in the token. When access depends on something your own domain knows, pass a predicate over the identity’s details:

```typescript
import { RequireRole } from '@cratis/arc.react/identity';

type OrganizationDetails = {
    department: string;
};

export const Ledger = () => (
    <RequireRole<OrganizationDetails>
        allow={details => details?.department === 'Finance'}
        forbidden={<AccessDenied />}>
        <LedgerContent />
    </RequireRole>
);
```

The details come first because that is what an application’s own access rules are written against; the whole identity arrives as a second argument when a rule also needs `isInRole`.

The details are typed as possibly absent, and the `?.` above is not decoration. An identity is set as soon as the backend answers, whether or not the application registered anything to fill details in - so a predicate written as though they are always there throws on exactly the deployments that have none.

### Everything that is not a yes is a no

[Section titled “Everything that is not a yes is a no”](#everything-that-is-not-a-yes-is-a-no)

A gate that cannot reach a decision does not open. `RequireRole` renders `forbidden` for all of these, and warns on the console for the ones that are configuration mistakes:

* The caller is anonymous.
* No role matched, or the predicate answered `false`.
* `roles` is an empty array. That is not “no rule” - it is a rule no caller can satisfy.
* `roles` is not an array at all (a `null` out of JSON configuration, say).
* Neither `roles` nor `allow` was supplied. A key renamed in a feature-flag object arrives as `undefined`, compiles, lints, and would otherwise open the panel to everyone signed in. If authentication alone really is the rule, say so: `allow={() => true}`.
* The predicate threw.
* The identity carries no details but an `allow` predicate was supplied. There is nothing to decide on, and the two natural ways to phrase a predicate disagree about absence - one throws, the other reads it as innocence and admits - so the gate answers instead of letting the phrasing decide.

### RequireRole hides UI, it does not protect data

[Section titled “RequireRole hides UI, it does not protect data”](#requirerole-hides-ui-it-does-not-protect-data)

Danger

`RequireRole` is a usability feature, not a security boundary. The identity it reads comes from a cookie that is deliberately not `HttpOnly` - the frontend has to be able to read it - which means the browser, and anyone driving it, can edit that cookie and render these children at will.

Use the gate to keep people out of screens that would only frustrate them. Never use it as the thing that keeps them out of the data. Every query and command behind the gate has to carry its own `[Authorize]` / `[Roles]` on the server, where the decision is made from the real credential and cannot be edited.

## Type-safe identity with complex types

[Section titled “Type-safe identity with complex types”](#type-safe-identity-with-complex-types)

If your identity details contain complex types like `Guid` from `@cratis/fundamentals`, you can enable type-safe deserialization by providing a constructor. This ensures that complex types are properly instantiated with their methods and behavior, not just plain JSON objects.

First, define your identity details class:

```typescript
import { Guid } from '@cratis/fundamentals';

class UserIdentityDetails {
    userId: Guid = Guid.empty;
    firstName: string = '';
    lastName: string = '';
}
```

Then, configure the `IdentityProvider` with the details type:

```typescript
import { IdentityProvider } from '@cratis/arc.react/identity';

export const App = () => {
    return (
        <IdentityProvider detailsType={UserIdentityDetails}>
            {/* ... your app content ... */}
        </IdentityProvider>
    );
};
```

Finally, use the `useIdentity()` hook with the constructor:

```typescript
import { useIdentity } from '@cratis/arc.react/identity';
import { Guid } from '@cratis/fundamentals';

class UserIdentityDetails {
    userId: Guid = Guid.empty;
    firstName: string = '';
    lastName: string = '';
}

export const Home = () => {
    const identity = useIdentity(UserIdentityDetails);

// Now identity.details.userId is a proper Guid instance with all its methods
    return (
        <h3>User ID: {identity.details.userId.toString()}</h3>
        <h3>User: {identity.details.firstName} {identity.details.lastName}</h3>
    );
};
```

This approach uses `JsonSerializer.deserializeFromInstance()` under the hood to recursively deserialize complex types, ensuring that types like `Guid`, `DateTime`, and other custom types are properly instantiated rather than being plain JSON objects.

## Refreshing with hook

[Section titled “Refreshing with hook”](#refreshing-with-hook)

Since the `useIdentity()` returns an instance of the `IIdentityContext`. So for refreshing with a hook, its easily accessible:

```typescript
import { useIdentity } from '@cratis/arc.react/identity';

type Identity = {
    firstName: string;
    lastName: string;
};

export const Home = () => {
    const identity = useIdentity<Identity>();

return (
        <h3>User: {identity.details.firstName} {identity.details.lastName}</h3>

{/* Refresh button */}
        <button onClick={() => identity.refresh()}>Refresh identity</button>
    );
};
```

## Default value

[Section titled “Default value”](#default-value)

You can also provide a default value for the `details` property in the identity context.

### Clearing identity

[Section titled “Clearing identity”](#clearing-identity)

When a user logs out, you can clear the client-side identity state and remove the identity cookie using `clearIdentity()`. This is available on the object returned by `useIdentity()`:

```typescript
import { useIdentity } from '@cratis/arc.react/identity';

export const LogoutButton = () => {
    const identity = useIdentity();

const handleLogout = () => {
        identity.clearIdentity();
    };

return <button onClick={handleLogout}>Log out</button>;
};
```

Calling `clearIdentity()` does two things:

1. Removes the `.cratis-identity` cookie.
2. Resets the identity context to its initial unset state (`isSet` becomes `false`, `details` is reset).

> Note: If your application uses observable queries that require authentication, you should also call `reconnectQueries()` from the [Arc context](/arc/frontend/react/arc/#reconnecting-queries) after clearing identity so that transport connections are re-established without the old credentials.

## Default details value

[Section titled “Default details value”](#default-details-value)

If you don’t provide one, it will default to an empty object, `{}`. This is especially useful when working in local development and the cookie has not been provided

The default value can be provided as an argument to the `useIdentity()` hook:

```typescript
import { useIdentity } from '@cratis/arc.react/identity';

type Identity = {
    firstName: string;
    lastName: string;
};

export const Home = () => {
    const identity = useIdentity<Identity>({
        firstName: '[N/A]',
        lastName: '[N/A]'
    });

return (
        <h3>User: {identity.details.firstName} {identity.details.lastName}</h3>
    );
};
```

When using the type-safe overload with a constructor, the default value is provided as the second parameter:

```typescript
import { useIdentity } from '@cratis/arc.react/identity';
import { Guid } from '@cratis/fundamentals';

class UserIdentityDetails {
    userId: Guid = Guid.empty;
    firstName: string = '';
    lastName: string = '';
}

export const Home = () => {
    const defaultDetails: UserIdentityDetails = {
        userId: Guid.empty,
        firstName: '[N/A]',
        lastName: '[N/A]'
    };

const identity = useIdentity(UserIdentityDetails, defaultDetails);

return (
        <h3>User: {identity.details.firstName} {identity.details.lastName}</h3>
    );
};
```

# Messaging

`<Arc />` sets up a root messenger that is available through React context.

Use `useMessenger()` to get the nearest messenger:

```tsx
import { useMessenger } from '@cratis/arc.react/messaging';

export const Details = () => {
    const messenger = useMessenger();
    // use messenger.subscribe(...) or messenger.publish(...)
    return null;
};
```

## Subscribing — `useOnMessage`

[Section titled “Subscribing — useOnMessage”](#subscribing--useonmessage)

`useOnMessage` subscribes to messages of a given type from the nearest messenger for the lifetime of the component. The subscription is cleaned up automatically on unmount, and the callback does not need to be wrapped in `useCallback` — the latest reference is always invoked.

```tsx
import { useOnMessage } from '@cratis/arc.react/messaging';

class UserSelected {
    constructor(readonly userId: string) {
    }
}

export const UserDetails = () => {
    useOnMessage(UserSelected, message => {
        console.log('Selected user:', message.userId);
    });
    return null;
};
```

### Filtering

[Section titled “Filtering”](#filtering)

An optional filter narrows on message content without re-subscribing. The filter receives the actual typed message and tells the hook whether the consumer is interested:

```tsx
useOnMessage(
    UserSelected,
    message => console.log('Selected admin:', message.userId),
    message => message.role === 'admin'
);
```

## Publishing — `useSendMessage`

[Section titled “Publishing — useSendMessage”](#publishing--usesendmessage)

`useSendMessage` returns a stable function that publishes to the nearest messenger. Use it when a component needs to send messages without holding a reference to the messenger itself:

```tsx
import { useSendMessage } from '@cratis/arc.react/messaging';

class UserSelected {
    constructor(readonly userId: string) {
    }
}

export const UserList = () => {
    const send = useSendMessage();
    return (
        <button onClick={() => send(new UserSelected('42'))}>
            Select user
        </button>
    );
};
```

## Scoped messenger hierarchy

[Section titled “Scoped messenger hierarchy”](#scoped-messenger-hierarchy)

Use `<MessengerScope>` to create a nested messenger:

```tsx
import { MessengerScope } from '@cratis/arc.react/messaging';

export const Page = () => (
    <MessengerScope>
        <FeatureA />
        <FeatureB />
    </MessengerScope>
);
```

`useMessenger()`, `useOnMessage`, and `useSendMessage` all resolve the nearest scope first, then fall back to the Arc root messenger.

By default:

* Child publishes do **not** bubble to parent.
* Parent publishes trickle down to children recursively.

You can override this on a scope with:

* `bubbleToParent`
* `trickleDownToChildren`

# Proxy Generation

Cratis Arc automatically generates TypeScript proxies for your backend commands and queries, providing seamless integration between your React frontend and backend APIs.

> **Setup and Configuration**: For detailed information about setting up proxy generation, configuration options, and build integration, see the [Backend Proxy Generation](/arc/backend/proxy-generation/) documentation.

## Type Safety and IntelliSense

[Section titled “Type Safety and IntelliSense”](#type-safety-and-intellisense)

One of the key benefits of the generated proxies is compile-time type safety. Your IDE will provide:

* **IntelliSense**: Auto-completion for all available commands and queries
* **Type Checking**: Compile-time verification of parameter types and return values
* **Refactoring Support**: Automatic updates when backend APIs change
* **Navigation**: Go-to-definition support for exploring generated types

This eliminates the need to reference Swagger documentation or manually write API integration code, as everything is generated and type-safe directly in your TypeScript codebase.

## Frontend Usage

[Section titled “Frontend Usage”](#frontend-usage)

Once proxy generation is configured in your backend projects, you’ll get automatically generated TypeScript proxies that provide compile-time type safety and intellisense support for all your commands and queries.

### Prerequisites

[Section titled “Prerequisites”](#prerequisites)

Install the base [`@cratis/arc`](https://www.npmjs.com/package/@cratis/arc) NPM package in your React project, as the generated proxies inherit from and leverage types found in this package:

```bash
npm install @cratis/arc
```

## Commands

[Section titled “Commands”](#commands)

Commands represent actions you want to perform and correspond to **HttpPost** operations on your backend controllers. The generated proxies inherit from the `Command` type found in `@cratis/arc/commands` and provide type-safe access to all command parameters.

Arc supports both backend command styles and generates equivalent TypeScript proxies for each:

* [Controller-based commands](/arc/backend/commands/controller-based/)
* [Model-bound commands](/arc/backend/commands/model-bound/)

### Example Generated Command

[Section titled “Example Generated Command”](#example-generated-command)

For a backend controller action like this:

```csharp
[Route("/api/accounts/debit")]
public class DebitAccounts : Controller
{
    [HttpPost]
    public Task OpenDebitAccount([FromBody] OpenDebitAccount create)
    {
        // Implementation...
    }
}
```

You’ll get a generated TypeScript command that flattens all parameters (from route, query string, and body) into properties:

```typescript
import { OpenDebitAccount } from './generated/commands';

const command = new OpenDebitAccount();
// Set properties and execute
```

For a model-bound command like this:

```csharp
[Command]
public record OpenDebitAccount(string Name, decimal InitialBalance)
{
    public Task Handle(IEventLog eventLog)
    {
        // Implementation...
        return Task.CompletedTask;
    }
}
```

You’ll get a generated TypeScript command with the same command name and strongly typed properties:

```typescript
import { OpenDebitAccount } from './generated/commands';

const command = new OpenDebitAccount();
command.name = 'Primary account';
command.initialBalance = 500;
```

The generated command automatically handles route parameters, query string arguments, and request body serialization.

For detailed information on using commands in React, see the [Commands documentation](/arc/frontend/react/commands/).

## Queries

[Section titled “Queries”](#queries)

Queries represent data retrieval operations that correspond to **HttpGet** operations on your backend controllers. They can return either single items or collections and support parameters from routes or query strings.

Arc supports both backend query styles and generates equivalent TypeScript query proxies for each:

* [Controller-based queries](/arc/backend/queries/controller-based/)
* [Model-bound queries](/arc/backend/queries/model-bound/)

### Example Generated Query

[Section titled “Example Generated Query”](#example-generated-query)

For a backend controller action like this:

```csharp
[HttpGet]
public IEnumerable<DebitAccount> AllAccounts()
{
    // Get data and return
}
```

You’ll get a generated TypeScript query that provides a React hook via the `.use()` method:

```typescript
import { AllAccounts } from './generated/queries';

const MyComponent = () => {
    const [result, perform] = AllAccounts.use();

// result is of type `QueryResultWithState<DebitAccount[]>`
    // Contains: data, isPerforming, error, etc.

return (
        <div>
            {result.isPerforming && <span>Loading...</span>}
            {result.data?.map(account => <div key={account.id}>{account.name}</div>)}
        </div>
    );
};
```

For a model-bound query like this:

```csharp
[ReadModel]
public record DebitAccount(AccountId Id, AccountName Name, CustomerId Owner, decimal Balance)
{
    public static IEnumerable<DebitAccount> GetAllAccounts(IMongoCollection<DebitAccount> collection)
        => collection.Find(_ => true).ToList();
}
```

You’ll get a generated TypeScript query proxy with the same ergonomic hook pattern:

```typescript
import { GetAllAccounts } from './generated/queries';

const MyComponent = () => {
    const [result, perform] = GetAllAccounts.use();

return (
        <div>
            {result.isPerforming && <span>Loading...</span>}
            {result.data?.map(account => <div key={account.id}>{account.name}</div>)}
        </div>
    );
};
```

The return type `QueryResultWithState<>` provides additional metadata about the query state, including whether the query is currently executing (`isPerforming`), making it easy to implement loading indicators and error handling.

### Suspense Hooks on Proxies

[Section titled “Suspense Hooks on Proxies”](#suspense-hooks-on-proxies)

Every generated query proxy also exposes `useSuspense()` and `useSuspenseWithPaging()` static methods. These forward to `useSuspenseQuery` / `useSuspenseObservableQuery` and are designed for use inside `QueryBoundary` (or a `<Suspense>` + `QueryErrorBoundary` pair), where the component suspends while data loads and any server-side errors are propagated to the boundary.

```typescript
import { AllAccounts } from './generated/queries';

function AccountList() {
    // Component suspends until the query resolves
    const [result, perform] = AllAccounts.useSuspense();

return (
        <ul>
            {result.data.map(account => <li key={account.id}>{account.name}</li>)}
        </ul>
    );
}
```

See [Suspense Queries](/arc/frontend/react/queries/suspense-queries/) for full documentation and error handling patterns.

### Observable Queries

[Section titled “Observable Queries”](#observable-queries)

Observable queries provide real-time updates to your React components, typically using WebSockets for live data synchronization.

> **Backend Setup**: To learn how to implement observable queries on the backend, see [Controller-based Observable Queries](/arc/backend/queries/controller-based/observable-queries/) and [Model-bound Observable Queries](/arc/backend/queries/model-bound/observable-queries/).

Observable queries are generated the same way as regular queries, but they don’t provide a manual `perform` method in the returned tuple. Instead, they automatically subscribe to updates and re-render your React components when the underlying data changes, providing a transparent and seamless real-time experience.

## Generated File Structure

[Section titled “Generated File Structure”](#generated-file-structure)

The proxy generator maintains your backend folder structure while generating TypeScript files based on the namespaces of your source files. Each namespace segment typically becomes a subfolder in the generated output.

For detailed information about configuring the output structure, including how to skip namespace segments and customize the generated folder hierarchy, see the [Backend Proxy Generation Configuration](/arc/backend/proxy-generation/configuration/) section.

# Queries

React queries in Arc provide strongly typed data-access patterns for request/response reads, paged views, and live observable streams.

This page is an overview of capabilities. Detailed behavior is documented on the dedicated pages below.

## Capabilities

[Section titled “Capabilities”](#capabilities)

| Capability              | What It Covers                                                                 | Learn More                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Arc-level configuration | Query-related `<Arc />` props for transport, headers, and stream transfer mode | [Configuration](/arc/frontend/react/queries/configuration/)                                 |
| Core query usage        | `use()` patterns, arguments, and `QueryResultWithState`                        | [Core Query Usage](/arc/frontend/react/queries/usage/)                                      |
| Paging and sorting      | `useWithPaging`, page/sort callbacks, and paging metadata                      | [Paging](/arc/frontend/react/queries/paging/)                                               |
| Observable streams      | Real-time subscriptions, transport selection, and direct mode                  | [Observable Queries](/arc/frontend/react/queries/observable-queries/)                       |
| Diagnostics             | Live snapshots for cache, transport, and ownership state                       | [Observable Query Diagnostics](/arc/frontend/react/queries/observable-query-diagnostics/)   |
| Suspense integration    | `useSuspense()` with query boundaries and error boundaries                     | [Suspense Queries](/arc/frontend/react/queries/suspense-queries/)                           |
| Conditional execution   | `when(condition)` patterns for safe query activation                           | [Conditional Queries](/arc/frontend/react/queries/conditional-queries/)                     |
| Change deltas           | `useChangeStream()` and transfer-mode behavior                                 | [Change Stream](/arc/frontend/react/queries/change-stream/)                                 |
| Connection behavior     | Multiplexing, connection count, and hub routing                                | [Observable Query Multiplexing](/arc/frontend/react/queries/observable-query-multiplexing/) |
| Instance lifecycle      | Shared query instances and cache behavior                                      | [Query Instance Caching](/arc/frontend/react/queries/query-instance-caching/)               |
| Performing state        | Track in-flight queries across components and ViewModels                       | [Query Scope](/arc/frontend/react/queries/scope/)                                           |

## Frontend Layering

[Section titled “Frontend Layering”](#frontend-layering)

For low-level query contracts and non-React runtime behavior, see [Frontend Core Queries](/arc/frontend/core/queries/).

## Backend References

[Section titled “Backend References”](#backend-references)

* [Backend Queries Overview](/arc/backend/queries/)
* [Controller-based Queries](/arc/backend/queries/controller-based/)
* [Model-bound Queries](/arc/backend/queries/model-bound/)
* [Query Pipeline](/arc/backend/queries/query-pipeline/)
* [Backend Proxy Generation](/arc/backend/proxy-generation/)

# Change Stream

Observable queries deliver full collection snapshots by default. **Change stream** is a thin layer on top that exposes per-update deltas — which items were added, replaced, or removed — as React state instead of requiring consumers to diff the full array themselves.

## Quick Start

[Section titled “Quick Start”](#quick-start)

```tsx
// All.useChangeStream() is auto-generated for any enumerable observable query.
const changes = All.useChangeStream(
    undefined,           // optional query arguments
    item => item.id      // optional key accessor — enables "replaced" detection
);

useEffect(() => {
    changes.added.forEach(item => console.log('added', item));
    changes.replaced.forEach(item => console.log('replaced', item));
    changes.removed.forEach(item => console.log('removed', item));
}, [changes]);
```

## `useChangeStream()` Hook

[Section titled “useChangeStream() Hook”](#usechangestream-hook)

```typescript
function useChangeStream<TDataType, TQuery, TArguments>(
    query:     Constructor<TQuery>,
    args?:     TArguments,
    getKey?:   (item: TDataType) => unknown,
    sorting?:  Sorting,
    isEnabled: boolean = true
): ChangeSet<TDataType>
```

The hook uses the same subscription and caching infrastructure as `useObservableQuery` — no extra server connections are opened.

### Parameters

[Section titled “Parameters”](#parameters)

| Parameter   | Type                           | Description                                                                                                                                                               |
| ----------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`     | `Constructor<TQuery>`          | The observable query constructor (must be enumerable).                                                                                                                    |
| `args`      | `TArguments`                   | Optional query arguments passed through to the underlying query.                                                                                                          |
| `getKey`    | `(item: TDataType) => unknown` | Optional identity accessor. When provided, items with the same key but different content are reported as `replaced`. Without it, only `added` and `removed` are detected. |
| `sorting`   | `Sorting`                      | Optional sorting configuration.                                                                                                                                           |
| `isEnabled` | `boolean`                      | When `false`, the hook is a no-op. Defaults to `true`.                                                                                                                    |

### Return Value

[Section titled “Return Value”](#return-value)

A `ChangeSet<TDataType>` object that is stable between updates when nothing changes:

```typescript
interface ChangeSet<T> {
    readonly added:    T[];   // items that appeared since the last update
    readonly replaced: T[];   // items that have the same key but different content
    readonly removed:  T[];   // items that were present before but are not now
}
```

## Generated Proxy Method

[Section titled “Generated Proxy Method”](#generated-proxy-method)

The proxy generator emits a `static useChangeStream()` method on every enumerable observable query class automatically. No manual wiring is needed:

```typescript
// Generated proxy — call site
import { All } from './Proxy';

const changes = All.useChangeStream(undefined, item => item.id);
```

## Transfer Modes

[Section titled “Transfer Modes”](#transfer-modes)

Two transfer modes control how the client processes incoming updates.

### Delta mode (default)

[Section titled “Delta mode (default)”](#delta-mode-default)

When the server attaches a `ChangeSet` to the `QueryResult`, the hook uses it directly. This is the most accurate mode because the server tracks individual MongoDB operations (insert, update, delete) rather than diffing snapshots.

When no server `ChangeSet` is available, the hook falls back to client-side snapshot comparison:

* **With `getKey`**: added, replaced, and removed are all detected.
* **Without `getKey`**: only added and removed are detected (identity unknown).

### Full mode

[Section titled “Full mode”](#full-mode)

Set `observableQueryTransferMode` to `ObservableQueryTransferMode.Full` on the `<Arc>` component to treat every incoming snapshot as if all its items were just added. This is useful for debugging or for consumers that need a fresh batch on every tick regardless of what actually changed.

```tsx
import { Arc } from '@cratis/arc.react';
import { ObservableQueryTransferMode } from '@cratis/arc';

export const App = () => (
    <Arc
        microservice="my-app"
        observableQueryTransferMode={ObservableQueryTransferMode.Full}
    >
        <MyRoutes />
    </Arc>
);
```

| Value                               | Description                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------- |
| `ObservableQueryTransferMode.Delta` | Default. Uses server-provided `ChangeSet` or falls back to client-side snapshot comparison. |
| `ObservableQueryTransferMode.Full`  | Treats every snapshot as a fresh batch of additions.                                        |

## `IChangeStreamFor<T>`

[Section titled “IChangeStreamFor\<T>”](#ichangestreamfort)

All generated enumerable observable query classes automatically implement `IChangeStreamFor<TItem>` (which extends `IObservableQueryFor<TItem[]>`). You can use this interface in generic components:

```typescript
import { IChangeStreamFor } from '@cratis/arc/queries';

function MyComponent<T, TQuery extends IChangeStreamFor<T>>({
    query
}: { query: Constructor<TQuery> }) {
    const changes = useChangeStream<T, TQuery>(query);
    // ...
}
```

## See Also

[Section titled “See Also”](#see-also)

* [Change Stream — Backend](/arc/backend/queries/change-stream/) — `ChangeSetComputor`, identity property discovery, and wire format.
* [Observable Query Multiplexing](/arc/frontend/react/queries/observable-query-multiplexing/) — Transport configuration (WebSocket vs SSE, connection count, direct mode).
* [Queries](/arc/frontend/react/queries/) — General query hooks and usage patterns.

# Conditional Queries

Sometimes a component receives a query argument through a prop or local state that may not be available yet — for example, an entity ID that starts as `undefined` until the user makes a selection. Issuing the query before the value is available leads to an invalid request. At the same time, React’s rules of hooks prohibit calling hooks inside `if` statements, so you cannot simply wrap `use()` in a conditional.

The `when()` pattern solves this. Every generated query class exposes a static `when(condition)` method that returns a `QueryWhen` (or `ObservableQueryWhen`) wrapper. The wrapper exposes the same `use`, `useWithPaging`, `useSuspense`, and `useSuspenseWithPaging` methods as the query class, but the underlying hook is a no-op when `condition` is `false`. When `condition` is `true`, behaviour is identical to calling the hook directly.

## Generated API

[Section titled “Generated API”](#generated-api)

The proxy generator emits a `when()` static method on every query and observable query class:

```ts
// Generated for a regular query
static when(condition: boolean): QueryWhen<AllAccounts, Account[], AllAccountsParameters>

// Generated for an observable query
static when(condition: boolean): ObservableQueryWhen<LiveFeed, Message[], LiveFeedParameters>
```

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

```tsx
import { AllAccounts } from './Proxies';

export const AccountDetail = ({ accountId }: { accountId: string | undefined }) => {
    // Hook always runs — no conditional hook violation.
    // When accountId is undefined the query is disabled.
    const [accounts] = AllAccounts.when(!!accountId).use({ id: accountId ?? '' });

if (!accounts.hasData) return <p>Select an account.</p>;

return <div>{accounts.data.map(a => <p key={a.id}>{a.name}</p>)}</div>;
};
```

When `condition` is `false`:

* No HTTP request or WebSocket/SSE subscription is created.
* The hook returns `QueryResultWithState.empty()` — `hasData` is `false`, `isPerforming` is `false`, `data` is `[]` / `undefined` depending on the query shape.

When `condition` becomes `true` on a subsequent render, the hook connects to the server and the component re-renders with real data.

## With Paging

[Section titled “With Paging”](#with-paging)

```tsx
const [accounts] = AllAccounts.when(isReady).useWithPaging(20, args);
```

## With Suspense

[Section titled “With Suspense”](#with-suspense)

```tsx
// Inside a <Suspense> boundary
const [feed] = LiveFeed.when(!!topicId).useSuspense({ topic: topicId ?? '' });
```

## Observable Queries

[Section titled “Observable Queries”](#observable-queries)

The pattern works identically for observable queries via `ObservableQueryWhen`:

```tsx
import { LiveFeed } from './Proxies';

export const FilteredFeed = ({ author }: { author: string }) => {
    // Subscription only starts once author is non-empty
    const [feed] = LiveFeed.when(author.length > 0).use({ author });

return <ul>{feed.data.map(m => <li key={m.id}>{m.text}</li>)}</ul>;
};
```

## How It Interacts with `QueryInstanceCache`

[Section titled “How It Interacts with QueryInstanceCache”](#how-it-interacts-with-queryinstancecache)

When `condition` is `false` no cache entry is created or referenced. The moment `condition` turns `true` the hook resolves or creates a cache entry for the type + arguments combination. If another component has already populated that cache entry, the new subscriber receives the last known result immediately — no server round-trip needed. See [Query Instance Caching](/arc/frontend/react/queries/query-instance-caching/) for details.

## Memoization

[Section titled “Memoization”](#memoization)

`when()` creates a lightweight wrapper object on every render. For components where the condition expression is complex or the render is performance-sensitive, you can memoize the result:

```ts
const query = useMemo(() => AllAccounts.when(!!accountId), [accountId]);
const [accounts] = query.use({ id: accountId ?? '' });
```

In practice the object is small enough that memoization is rarely needed.

## `isEnabled` on Raw Hooks

[Section titled “isEnabled on Raw Hooks”](#isenabled-on-raw-hooks)

Behind the scenes `QueryWhen` and `ObservableQueryWhen` delegate to the raw `useQuery` / `useObservableQuery` (and their `*WithPaging` and `useSuspense*` variants) by passing `isEnabled` as the last argument. The raw hooks also accept this parameter directly if you need low-level control:

```ts
import { useObservableQuery } from '@cratis/arc.react/queries';

const [result] = useObservableQuery(MyQuery, args, sorting, isEnabled);
```

The generated `when()` API is preferred for application code because it keeps intent explicit and co-located with the query class.

# Configuration

Configure query behavior centrally through the `<Arc />` component instead of per query instance.

## Query-Related Arc Props

[Section titled “Query-Related Arc Props”](#query-related-arc-props)

| Prop                          | Type                           | Default            | Purpose                                                                                                                                                            |
| ----------------------------- | ------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `microservice`                | `string`                       | `undefined`        | Routes query requests to a named microservice in shared-ingress environments.                                                                                      |
| `apiBasePath`                 | `string`                       | `''`               | Prepends a base API path to query requests.                                                                                                                        |
| `httpHeadersCallback`         | `() => HeadersInit`            | `undefined`        | Adds dynamic headers (auth, cookies, custom headers) to query requests.                                                                                            |
| `queryTransportMethod`        | `QueryTransportMethod`         | `ServerSentEvents` | Selects SSE or WebSocket transport for observable query connections.                                                                                               |
| `queryDirectMode`             | `boolean`                      | `false`            | Bypasses centralized hubs and connects observable queries directly per query URL.                                                                                  |
| `queryConnectionCount`        | `number`                       | `1`                | Number of observable query hub connection slots.                                                                                                                   |
| `observableQueryTransferMode` | `ObservableQueryTransferMode`  | `Delta`            | Controls how `useChangeStream()` processes incoming snapshots and deltas.                                                                                          |
| `queryCacheRetentionMs`       | `number`                       | `30000`            | How long to keep cached query data alive after the last subscriber unmounts.                                                                                       |
| `eventSourceFactory`          | `(url: string) => EventSource` | `undefined`        | Custom factory for creating the `EventSource` instances used by SSE observable query connections. Falls back to the global `EventSource` constructor when not set. |

## Example

[Section titled “Example”](#example)

```tsx
import { Arc } from '@cratis/arc.react';
import { ObservableQueryTransferMode } from '@cratis/arc';
import { QueryTransportMethod } from '@cratis/arc/queries';

export const App = () => (
    <Arc
        microservice="my-app"
        apiBasePath="/api"
        queryTransportMethod={QueryTransportMethod.ServerSentEvents}
        queryDirectMode={false}
        queryConnectionCount={1}
        observableQueryTransferMode={ObservableQueryTransferMode.Delta}
        httpHeadersCallback={() => ({ Authorization: `Bearer ${getToken()}` })}
    >
        <MyRoutes />
    </Arc>
);
```

## Query Cache Retention

[Section titled “Query Cache Retention”](#query-cache-retention)

When a component that uses `useObservableQuery` unmounts — for example, when the user navigates to a different page — Arc holds the cached query data and the active server subscription alive for `queryCacheRetentionMs` milliseconds (default: 30 seconds) before evicting them.

This has two practical effects:

* **Instant navigation**: If the user returns to the same page within the retention window, cached data renders immediately instead of showing a loading state while the subscription re-establishes.
* **Bounded memory**: After the window expires, the cache entry and the underlying connection are released automatically, so long-lived single-page applications do not accumulate stale subscriptions.

```tsx
<Arc queryCacheRetentionMs={60_000}>
    {/* data survives for 60 s after the last subscriber unmounts */}
</Arc>
```

Set the value to `0` to restore the previous behavior of evicting the subscription as soon as the last subscriber unmounts:

```tsx
<Arc queryCacheRetentionMs={0}>
    {/* immediate eviction — original behavior */}
</Arc>
```

The default can also be adjusted globally without the React component:

```typescript
import { Globals } from '@cratis/arc';

Globals.queryCacheRetentionMs = 60_000;
```

> **Note:** The retention window applies per cache entry, not globally. Each query type and argument combination has its own independent timer.

## Observable Query Transport

[Section titled “Observable Query Transport”](#observable-query-transport)

Use `queryTransportMethod`, `queryDirectMode`, and `queryConnectionCount` to control observable query connection behavior.

For transport semantics, hub behavior, SSE limits, and pooling details, see [Observable Query Multiplexing](/arc/frontend/react/queries/observable-query-multiplexing/).

## Custom EventSource Factory

[Section titled “Custom EventSource Factory”](#custom-eventsource-factory)

By default, SSE observable query connections create their transport with the global `EventSource` constructor. Some environments either lack a native `EventSource` — React Native does not ship one — or ship one with unreliable streaming behavior. JS-based polyfills built on `XMLHttpRequest` are known to deliver messages in bulk instead of streaming them, silently drop connections when the app is backgrounded, and provide no reliable way to detect a dead connection on Android.

Set `eventSourceFactory` to substitute your own SSE client without changing anything else about how observable queries work:

```tsx
import { Arc } from '@cratis/arc.react';
import RNEventSource from 'react-native-nitro-sse';

export const App = () => (
    <Arc eventSourceFactory={(url) => new RNEventSource(url)}>
        <MyRoutes />
    </Arc>
);
```

The factory receives the fully-qualified connection URL and must return an object implementing the standard `EventSource` interface (`onmessage`, `onerror`, `close()`, `readyState`). This applies to both direct-mode and hub-mode SSE connections.

The default can also be set globally without the React component:

```typescript
import { Globals } from '@cratis/arc';

Globals.eventSourceFactory = (url) => new RNEventSource(url);
```

## Change Stream Transfer Mode

[Section titled “Change Stream Transfer Mode”](#change-stream-transfer-mode)

`observableQueryTransferMode` sets the global default for `useChangeStream()` processing.

| Value                               | Behavior                                                                               |
| ----------------------------------- | -------------------------------------------------------------------------------------- |
| `ObservableQueryTransferMode.Delta` | Uses server-provided `ChangeSet` when available and falls back to client-side diffing. |
| `ObservableQueryTransferMode.Full`  | Treats every snapshot as a full batch of additions.                                    |

For hook-level behavior, see [Change Stream](/arc/frontend/react/queries/change-stream/).

## Related

[Section titled “Related”](#related)

* [Arc Component](/arc/frontend/react/arc/)
* [Core Query Configuration](/arc/frontend/core/queries/configuration/)
* [Observable Queries](/arc/frontend/react/queries/observable-queries/)

# Observable Queries

Observable queries provide real-time updates in React through `useObservableQuery()` and generated proxy helpers. Arc supports both centralized hub routing and direct per-query connections.

For backend implementation patterns, see [Controller-based Observable Queries](/arc/backend/queries/controller-based/observable-queries/), [Model-bound Observable Queries](/arc/backend/queries/model-bound/observable-queries/), and [Observable Query Hub](/arc/backend/queries/observable-query-demultiplexer/).

## Observable Query Transport

[Section titled “Observable Query Transport”](#observable-query-transport)

By default, observable queries connect through centralized hub endpoints. Two props on the `<Arc>` component control this behavior.

### `queryTransportMethod`

[Section titled “queryTransportMethod”](#querytransportmethod)

Selects the transport protocol used for the hub connection.

| Value                                   | Description                                                                             |
| --------------------------------------- | --------------------------------------------------------------------------------------- |
| `QueryTransportMethod.ServerSentEvents` | SSE hub — one `EventSource` per query, routed through `/.cratis/queries/sse` (default). |
| `QueryTransportMethod.WebSocket`        | WebSocket hub transport.                                                                |

```tsx
import { Arc } from '@cratis/arc.react';
import { QueryTransportMethod } from '@cratis/arc/queries';

export const App = () => (
    <Arc
        microservice="my-app"
        queryTransportMethod={QueryTransportMethod.ServerSentEvents}
    >
        <MyRoutes />
    </Arc>
);
```

### `queryDirectMode`

[Section titled “queryDirectMode”](#querydirectmode)

Controls whether observable queries connect directly to each query’s own URL or route through the centralized hub.

* When `false` (default): queries are routed through the centralized hub endpoint (`/.cratis/queries/sse` or `/.cratis/queries/ws` depending on `queryTransportMethod`).
* When `true`: each observable query opens its own connection directly to the per-query URL, bypassing the hub entirely. This is useful during local development or when connecting to services that do not expose the centralized hub.

```tsx
import { Arc } from '@cratis/arc.react';

export const App = () => (
    <Arc
        microservice="my-app"
        queryDirectMode={true}
    >
        <MyRoutes />
    </Arc>
);
```

| Prop                   | Type                   | Default            | Description                                                    |
| ---------------------- | ---------------------- | ------------------ | -------------------------------------------------------------- |
| `queryTransportMethod` | `QueryTransportMethod` | `ServerSentEvents` | Transport used for observable query connections.               |
| `queryDirectMode`      | `boolean`              | `false`            | When `true`, bypasses the hub and connects directly per query. |

## Related Pages

[Section titled “Related Pages”](#related-pages)

* [Observable Query Multiplexing](/arc/frontend/react/queries/observable-query-multiplexing/) for connection pooling, SSE limits, and protocol behavior.
* [Change Stream](/arc/frontend/react/queries/change-stream/) for item-level delta tracking on observable collections.
* [Use Observable Queries with cURL](/arc/backend/queries/using-observable-queries-with-curl/) for backend endpoint debugging workflows.

# Observable Query Diagnostics

Observable query diagnostics give you a live view into the query subsystem from React. They are useful when you need to build developer tools, inspect cache behavior, or show the current transport state in an internal dashboard.

The diagnostics service is exposed through `ArcContext` as `observableQueryDiagnostics`. It provides two ways to read the current state:

* `getSnapshot()` for a point-in-time read.
* `snapshots$` for a live stream of updates.

Diagnostics snapshots are only exposed through this API surface. Arc does not emit browser `window` events for diagnostics updates.

## What the snapshot contains

[Section titled “What the snapshot contains”](#what-the-snapshot-contains)

Each snapshot includes:

* transport configuration
* multiplexer connection state
* cache state and cache size
* ownership information for hooks that opted into tracking
* a health summary

This is intentionally diagnostic data, not application state. Use it for tooling, not for rendering core business screens.

## Watching snapshots from React

[Section titled “Watching snapshots from React”](#watching-snapshots-from-react)

Subscribe to `snapshots$` when you want live updates.

```tsx
import { useContext, useEffect, useState } from 'react';
import { ArcContext } from '@cratis/arc.react';
import { ObservableQueryDiagnosticsSnapshot } from '@cratis/arc/queries';

export const QueryDiagnosticsPanel = () => {
    const arc = useContext(ArcContext);
    const [snapshot, setSnapshot] = useState<ObservableQueryDiagnosticsSnapshot | undefined>();

useEffect(() => {
        const diagnostics = arc.observableQueryDiagnostics;
        if (!diagnostics) {
            return;
        }

setSnapshot(diagnostics.getSnapshot());

const subscription = diagnostics.snapshots$.subscribe(setSnapshot);
        return () => subscription.unsubscribe();
    }, [arc.observableQueryDiagnostics]);

if (!snapshot) {
        return <p>No diagnostics available.</p>;
    }

return (
        <dl>
            <dt>Connected</dt>
            <dd>{snapshot.health.allQueriesConnected ? 'Yes' : 'No'}</dd>
            <dt>Tracked queries</dt>
            <dd>{snapshot.cache.entryCount}</dd>
            <dt>Owners</dt>
            <dd>{Object.keys(snapshot.ownership.ownersByQueryKey).length}</dd>
        </dl>
    );
};
```

## Tracking ownership

[Section titled “Tracking ownership”](#tracking-ownership)

The query hooks can optionally tag a cache entry with a human-readable owner label. This lets diagnostics show which component is responsible for each tracked query instance.

Use the optional `owner` argument on `useQuery()` or `useObservableQuery()` when you want that metadata to appear in the snapshot.

```tsx
const [result] = useObservableQuery(MyObservableQuery, args, sorting, true, 'OrdersPage');
```

If you omit the owner, the diagnostics stream still works. You just get the connection and cache information without ownership labels.

## Correlating with the backend health endpoint

[Section titled “Correlating with the backend health endpoint”](#correlating-with-the-backend-health-endpoint)

The frontend diagnostics show one side of the picture — what the browser cache and transport layer know. When you need to verify that the server is actually pushing data to the right subscribers, Arc provides a matching backend endpoint at `/.cratis/queries/health`.

The two surfaces use the same query identifier format. Each entry in `snapshot.cache.entries` has a `queryName` field in the form `{TypeFullName}.{MethodName}`. The backend health endpoint exposes a `querySubscriptions` array where each entry’s `queryName` field uses the exact same string. You can match them by name.

A typical investigation flow:

1. Pull `snapshot.cache.entries` from the frontend diagnostics.
2. Find the entry whose `queryName` matches the query you are investigating.
3. Check whether `subscribed` is `true` (the frontend has established a server subscription) and whether `hasResult` is `true` (at least one data frame has arrived).
4. Open `/.cratis/queries/health` or subscribe to it in a dev tool component, then look for the matching `queryName` in `querySubscriptions`.
5. Inspect `lastDataServedAt` and `lastPongReceivedAt` to confirm the backend is actively serving data.

If the frontend reports `subscribed: true` but `hasResult: false`, and the backend shows a matching subscriber with a stale `lastDataServedAt`, the problem is a data source that has not emitted since the subscription opened.

If the frontend reports `subscribed: false`, the subscription request never reached the backend — look for a connection problem in the multiplexer or SSE transport.

See [Query Health Endpoint](/arc/backend/queries/query-health/) for the full backend API and response shape.

## Related pages

[Section titled “Related pages”](#related-pages)

* [Observable Queries](/arc/frontend/react/queries/observable-queries/)
* [Observable Query Multiplexing](/arc/frontend/react/queries/observable-query-multiplexing/)
* [Query Instance Caching](/arc/frontend/react/queries/query-instance-caching/)
* [Backend: Query Health Endpoint](/arc/backend/queries/query-health/)

# Observable Query Multiplexing

Observable queries in Arc connect through a centralized hub rather than opening one WebSocket per query. This page explains how the multiplexing works from the frontend perspective and how to configure it.

For the server-side protocol reference — endpoints, message types, keep-alive configuration — see [Observable Query Hub](/arc/backend/queries/observable-query-demultiplexer/).

## How It Works

[Section titled “How It Works”](#how-it-works)

When `queryDirectMode` is `false` (the default), every observable query subscription is routed through one of two fixed hub endpoints instead of connecting to a per-query URL:

| Transport          | Hub Endpoint           | Notes                                                                   |
| ------------------ | ---------------------- | ----------------------------------------------------------------------- |
| Server-Sent Events | `/.cratis/queries/sse` | One `EventSource` per query, multiplexed by query name via query-string |
| WebSocket          | `/.cratis/queries/ws`  | Single connection carrying N subscriptions via a typed protocol         |

The frontend `ObservableQueryFor.subscribe()` constructs the correct URL from the query’s fully qualified name and its arguments, then establishes a connection to the hub. The server resolves the query by name, runs it through the query pipeline (including authorization), and streams results back.

### SSE hub connection

[Section titled “SSE hub connection”](#sse-hub-connection)

When transport is SSE, `subscribe()` calls the hub as:

```http
GET /.cratis/queries/sse?query=<fullyQualifiedQueryName>&<queryArgs>
```

The `EventSource` re-establishes the connection automatically if the server becomes temporarily unavailable.

### WebSocket hub connection

[Section titled “WebSocket hub connection”](#websocket-hub-connection)

When transport is WebSocket, `subscribe()` sends a typed `subscribe` message over a shared WebSocket connection. Refer to the [protocol reference](/arc/backend/queries/observable-query-demultiplexer/#protocol) for the full message format.

## Configuring Transport and Mode

[Section titled “Configuring Transport and Mode”](#configuring-transport-and-mode)

All multiplexing configuration flows through the `<Arc>` component.

### Selecting the transport method

[Section titled “Selecting the transport method”](#selecting-the-transport-method)

```tsx
import { Arc } from '@cratis/arc.react';
import { QueryTransportMethod } from '@cratis/arc/queries';

export const App = () => (
    <Arc
        microservice="my-app"
        queryTransportMethod={QueryTransportMethod.ServerSentEvents}
    >
        <MyRoutes />
    </Arc>
);
```

| Value                                   | Description                                               |
| --------------------------------------- | --------------------------------------------------------- |
| `QueryTransportMethod.ServerSentEvents` | SSE hub — one `EventSource` per query (default).          |
| `QueryTransportMethod.WebSocket`        | WebSocket hub — single shared connection per application. |

### Bypassing the hub (direct mode)

[Section titled “Bypassing the hub (direct mode)”](#bypassing-the-hub-direct-mode)

Set `queryDirectMode={true}` to connect each observable query directly to its own per-query WebSocket URL, bypassing the hub entirely.

```tsx
export const App = () => (
    <Arc
        microservice="my-app"
        queryDirectMode={true}
    >
        <MyRoutes />
    </Arc>
);
```

Use direct mode when:

* Connecting to backend services that do not expose the centralized hub endpoints.
* Debugging individual query connections in isolation.

| Prop              | Type      | Default | Description                                                                  |
| ----------------- | --------- | ------- | ---------------------------------------------------------------------------- |
| `queryDirectMode` | `boolean` | `false` | When `true`, bypasses the hub and connects directly to each query’s own URL. |

### Configuring the number of hub connections

[Section titled “Configuring the number of hub connections”](#configuring-the-number-of-hub-connections)

By default a single centralized hub connection handles all subscriptions. Use `queryConnectionCount` to distribute subscriptions across multiple connections:

```tsx
<Arc
    microservice="my-app"
    queryConnectionCount={2}
/>
```

The `ObservableQueryConnectionPool` picks the least-loaded slot round-robin when a new subscription is created. Increasing the connection count can improve throughput for applications with many concurrent observable queries.

| Prop                   | Type     | Default | Description                                                       |
| ---------------------- | -------- | ------- | ----------------------------------------------------------------- |
| `queryConnectionCount` | `number` | `1`     | Number of hub connection slots maintained for observable queries. |

#### SSE connection limit (HTTP/1.1)

[Section titled “SSE connection limit (HTTP/1.1)”](#sse-connection-limit-http11)

HTTP/1.1 browsers enforce a hard limit of **six simultaneous connections per origin**. Each SSE `EventSource` occupies one of those slots for as long as the page is open because the connection is kept alive indefinitely to receive server pushes. If all six slots are taken by `EventSource` connections, subscribe and unsubscribe POST requests cannot get a connection and queue indefinitely — queries appear to hang and produce no data.

Arc automatically caps the number of SSE hub connections at **4** regardless of what `queryConnectionCount` is set to. This leaves two slots free for the subscribe/unsubscribe POST calls and for ordinary `fetch` requests. A `console.warn` is emitted at startup when the configured count exceeds this limit.

```tsx
// This is capped at 4 automatically when using SSE — a warning is logged.
<Arc
    microservice="my-app"
    queryTransportMethod={QueryTransportMethod.ServerSentEvents}
    queryConnectionCount={10}
/>
```

The cap only applies to SSE. WebSocket connections do not consume HTTP/1.1 connection slots after the initial upgrade handshake, so `queryConnectionCount` is respected in full when using WebSocket transport.

> **Enable HTTP/2 to remove the limit.** HTTP/2 multiplexes all requests over a single TCP connection, making the per-origin slot limit irrelevant. When your server supports HTTP/2, `queryConnectionCount` may be set to any value without risk of connection starvation.
>
> References:
>
> * [HTTP/1.x connection management — MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Connection_management_in_HTTP_1.x)
> * [Server-Sent Events — HTML Living Standard](https://html.spec.whatwg.org/multipage/server-sent-events.html)

### Controlling change-stream transfer mode

[Section titled “Controlling change-stream transfer mode”](#controlling-change-stream-transfer-mode)

The `observableQueryTransferMode` prop sets the global default for how the `useChangeStream` hook processes incoming updates.

```tsx
import { Arc } from '@cratis/arc.react';
import { ObservableQueryTransferMode } from '@cratis/arc';

export const App = () => (
    <Arc
        microservice="my-app"
        observableQueryTransferMode={ObservableQueryTransferMode.Delta}
    >
        <MyRoutes />
    </Arc>
);
```

See [Change Stream](/arc/frontend/react/queries/change-stream/) for a full explanation of the two modes.

## Props Reference

[Section titled “Props Reference”](#props-reference)

| Prop                          | Type                          | Default            | Description                                                |
| ----------------------------- | ----------------------------- | ------------------ | ---------------------------------------------------------- |
| `queryTransportMethod`        | `QueryTransportMethod`        | `ServerSentEvents` | Transport used for hub connections.                        |
| `queryDirectMode`             | `boolean`                     | `false`            | When `true`, bypasses the hub entirely.                    |
| `queryConnectionCount`        | `number`                      | `1`                | Number of concurrent hub connections to maintain.          |
| `observableQueryTransferMode` | `ObservableQueryTransferMode` | `Delta`            | Controls how `useChangeStream` processes incoming updates. |

## See also

[Section titled “See also”](#see-also)

* [Observable Query Hub](/arc/backend/queries/observable-query-demultiplexer/) — Protocol reference, authorization semantics, and keep-alive configuration on the backend.
* [Query Instance Caching](/arc/frontend/react/queries/query-instance-caching/) — How query instances are deduplicated and last-known results cached across components.
* [Queries](/arc/frontend/react/queries/) — General query hooks and usage patterns.
* [Vite Configuration](/arc/frontend/react/vite-configuration/) — Required Vite proxy settings for WebSocket transport in development.

# Paging

Arc supports server-side paging for query proxies when the backend query returns `IQueryable<T>`.

## How Paging Works

[Section titled “How Paging Works”](#how-paging-works)

When the backend returns `IQueryable<T>`, the query pipeline applies `.Skip()` and `.Take()` on the server so only the requested page is fetched. Generated proxies expose `useWithPaging` and `useSuspenseWithPaging` for this flow.

For backend implementation details, see [Controller-based Paging](/arc/backend/queries/controller-based/paging/) and [Model-bound Paging](/arc/backend/queries/model-bound/paging/).

## Enabling Paging

[Section titled “Enabling Paging”](#enabling-paging)

Use `useWithPaging` instead of `use`, passing a page size:

```tsx
export const AccountList = () => {
    const [result, perform, setSorting, setPage, setPageSize] = AllAccounts.useWithPaging(25);

return (
        <>
            <DataTable value={result.data}>
                <Column field="name" header="Name" />
                <Column field="balance" header="Balance" />
            </DataTable>
            <p>
                Page {result.paging.page + 1} of {result.paging.totalPages}
                ({result.paging.totalItems} total items)
            </p>
            <button
                disabled={result.paging.page === 0}
                onClick={() => setPage(result.paging.page - 1)}>
                Previous
            </button>
            <button
                disabled={result.paging.page >= result.paging.totalPages - 1}
                onClick={() => setPage(result.paging.page + 1)}>
                Next
            </button>
        </>
    );
};
```

## Return Tuple for Paged Queries

[Section titled “Return Tuple for Paged Queries”](#return-tuple-for-paged-queries)

`useWithPaging` returns an extended tuple:

| Index | Name          | Type                                  | Description                              |
| ----- | ------------- | ------------------------------------- | ---------------------------------------- |
| 0     | `result`      | `QueryResultWithState<T>`             | Query result including paging metadata   |
| 1     | `perform`     | `() => Promise<void>`                 | Re-execute the query                     |
| 2     | `setSorting`  | `(sorting: Sorting) => Promise<void>` | Change sort field and direction          |
| 3     | `setPage`     | `(page: number) => Promise<void>`     | Navigate to a specific page (zero-based) |
| 4     | `setPageSize` | `(pageSize: number) => Promise<void>` | Change number of items per page          |

## Paging Metadata

[Section titled “Paging Metadata”](#paging-metadata)

Paging information is available on `result.paging`:

| Property     | Type     | Description                    |
| ------------ | -------- | ------------------------------ |
| `page`       | `number` | Current zero-based page number |
| `size`       | `number` | Items per page                 |
| `totalItems` | `number` | Total items across all pages   |
| `totalPages` | `number` | Total number of pages          |

## Hook Variants with Paging

[Section titled “Hook Variants with Paging”](#hook-variants-with-paging)

| Hook                                        | Description                           |
| ------------------------------------------- | ------------------------------------- |
| `MyQuery.useWithPaging(pageSize)`           | Standard query with paging            |
| `MyQuery.useSuspenseWithPaging(pageSize)`   | Suspense-compatible query with paging |
| `MyObservableQuery.useWithPaging(pageSize)` | Observable query with paging          |

Each variant accepts optional `args` and optional `sorting`.

## Sorting with Paging

[Section titled “Sorting with Paging”](#sorting-with-paging)

Sorting is independent of paging and works with all query hooks.

```tsx
import { Sorting, SortDirection } from '@cratis/arc/queries';

// Initial sorting
const [result] = AllAccounts.use(undefined, new Sorting('name', SortDirection.ascending));

// Change sorting dynamically
const [paged, perform, setSorting] = AllAccounts.useWithPaging(25);
await setSorting(new Sorting('balance', SortDirection.descending));
```

## Important Requirement

[Section titled “Important Requirement”](#important-requirement)

Automatic paging requires the backend to return `IQueryable<T>`. If the backend returns `IEnumerable<T>` or `List<T>`, paging parameters are sent but ignored, and all rows are returned in one response.

## See Also

[Section titled “See Also”](#see-also)

* [Core Query Usage](/arc/frontend/react/queries/usage/)
* [Suspense Queries](/arc/frontend/react/queries/suspense-queries/)
* [Backend Query Pipeline](/arc/backend/queries/query-pipeline/)

# Query Instance Caching

Arc maintains an application-scoped cache of query instances. When two components subscribe to the same query with the same arguments, they share a single underlying query object rather than creating two independent instances — reducing server round-trips and keeping all consumers in sync automatically.

## How It Works

[Section titled “How It Works”](#how-it-works)

The cache is keyed by **query type name** and **serialized arguments**. The following rules apply:

| Scenario                              | Result                                                   |
| ------------------------------------- | -------------------------------------------------------- |
| Same type + same arguments            | Same shared instance                                     |
| Same type + different arguments       | Different instances                                      |
| Two components, same type + same args | One shared instance; both receive updates simultaneously |

When a new subscriber mounts, it receives the **last known result** immediately from the cache rather than waiting for the next server push. This means components that unmount and remount (or re-render into a new subtree) present stale-but-fast data first, then update as fresh data arrives.

When the last subscriber unmounts, the cache entry is released. The next time any component subscribes to the same query, a fresh connection is established.

## Lifecycle

[Section titled “Lifecycle”](#lifecycle)

```text
Component A mounts
  → Cache miss → create new query instance → subscribe to server → receive first result
  → Cache stores the result

Component B mounts (same query, same args)
  → Cache hit → reuse existing instance
  → Immediately seeded with the last known result from the cache
  → No new server connection

Component A unmounts
  → Release reference (ref-count decrements)
  → Instance stays alive because Component B still holds a reference

Component B unmounts
  → Release reference → ref-count reaches 0 → cache entry evicted
  → Query instance unsubscribed from server
```

## Transparent Integration

[Section titled “Transparent Integration”](#transparent-integration)

The cache is used automatically by `useObservableQuery` and `useQuery`. No changes are needed in component code — the public hook signatures are unchanged.

```tsx
// These two components share one query instance and one server connection.
export const BalanceSummary = () => {
    const [result] = AllAccounts.use();
    return <span>Total: {result.data?.length ?? 0} accounts</span>;
};

export const AccountList = () => {
    const [result] = AllAccounts.use();
    return <DataTable value={result.data} />;
};
```

Both `BalanceSummary` and `AccountList` consume the same `AllAccounts` instance. When `AllAccounts` pushes an update, both components re-render simultaneously.

## Cache Context

[Section titled “Cache Context”](#cache-context)

The cache is provided via `QueryInstanceCacheContext`, initialized once per `<Arc>` mount. This means the cache scope matches the application boundary — all components under `<Arc>` share the same cache, and there is no need to configure anything explicitly.

```tsx
// The cache is initialized here, once per app.
<Arc microservice="my-app">
    <MyApp />
</Arc>
```

## Parameterized Queries

[Section titled “Parameterized Queries”](#parameterized-queries)

The cache key includes serialized arguments, so queries with different arguments are stored as separate instances.

```tsx
// These are TWO separate cache entries — different arguments.
const [accountsForAlice] = AccountsByOwner.use({ owner: 'alice' });
const [accountsForBob]   = AccountsByOwner.use({ owner: 'bob' });

// This is the SAME cache entry as accountsForAlice above.
const [aliceAgain] = AccountsByOwner.use({ owner: 'alice' });
```

Arguments are serialized by sorting the object keys alphabetically and stringifying, so `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same cache key.

## React StrictMode Compatibility

[Section titled “React StrictMode Compatibility”](#react-strictmode-compatibility)

React 18 and later run effects twice in development — and, crucially, the same synthetic unmount/remount cycle can occur in production when React reconciles across Suspense boundaries or concurrent renders. This means a component’s `useEffect` cleanup may fire even when the component immediately re-mounts.

Arc handles this automatically using **deferred teardown**. When the last subscriber releases a cache entry, the teardown (server unsubscribe) is not called immediately. Instead, it is scheduled with `setTimeout(0)`. If the same query re-subscribes before the timer fires — which is exactly what React’s remount cycle does — the pending teardown is cancelled and the existing connection is reused transparently.

```text
Component mounts            → acquire entry (refCount = 1)
Component unmounts          → release entry (refCount = 0) → schedule deferred teardown
  [setTimeout fires]
    ← Component remounts    → acquire entry cancels teardown before timer fires
                            → connection survives; last result still available
```

This behavior is unconditional — it applies in all environments, not just when React DevTools’ “Strict Mode” is active. The `development` prop on `<Arc>` does not change teardown timing and is retained only for API compatibility.

## Relationship with the Conditional `when()` Hook

[Section titled “Relationship with the Conditional when() Hook”](#relationship-with-the-conditional-when-hook)

The `when(condition)` pattern interacts with the cache correctly: when `isEnabled` is `false`, no cache lookup or creation occurs, and no server connection is established. The hook returns `QueryResultWithState.empty()` without touching the cache.

```tsx
// No cache entry is created until `selectedId` is truthy.
const [result] = AllProjects.when(!!selectedId).use({ id: selectedId });
```

Once the condition becomes `true`, the cache is looked up or populated on the next render.

## See also

[Section titled “See also”](#see-also)

* [Observable Query Multiplexing](/arc/frontend/react/queries/observable-query-multiplexing/) — How hub connections are managed and configured.
* [Queries](/arc/frontend/react/queries/) — General query hooks and the `when()` conditional pattern.
* [Observable Query Hub](/arc/backend/queries/observable-query-demultiplexer/) — Server-side protocol and authorization.

# Query Scope

If you want to know whether any queries or observable queries are currently in-flight — typically to show a loading indicator or disable parts of the UI — the query scope provides a React context for this.

Using a toolbar as an example: at the top level you can wrap everything in the `<QueryScope>` component. This establishes a React context for that part of the hierarchy and tracks the performing state of any queries or observable queries used by any descendant component.

```typescript
import { QueryScope } from '@cratis/arc.react/queries';

export const MyComposition = () => {
    const [isPerforming, setIsPerforming] = useState(false);

return (
        <QueryScope setIsPerforming={setIsPerforming}>
            <Toolbar isLoading={isPerforming} />
            <DataPanel />
            <SidePanel />
        </QueryScope>
    );
};
```

## How Performing State Is Tracked

[Section titled “How Performing State Is Tracked”](#how-performing-state-is-tracked)

* **Regular queries** — `isPerforming` is `true` while the HTTP request is in-flight and becomes `false` when the response is received.
* **Observable queries** — `isPerforming` is `true` from the moment a subscription is opened until the first result is pushed from the server.

## Hierarchical Scopes

[Section titled “Hierarchical Scopes”](#hierarchical-scopes)

Query scopes can be nested to create a hierarchy. When you add a `<QueryScope>` inside another one, the inner scope automatically registers itself with the nearest outer scope. Outer scopes aggregate state across all inner scopes, giving you both local and global views of the performing state.

```typescript
export const MyPage = () => {
    const [isPerforming, setIsPerforming] = useState(false);

return (
        <QueryScope setIsPerforming={setIsPerforming}>
            {/* PageToolbar sees aggregate state for the whole page */}
            <PageToolbar isLoading={isPerforming} />
            <Section1>
                <QueryScope>
                    {/* SectionLoader only sees state for queries in Section1 */}
                    <SectionLoader />
                    <SectionContent />
                </QueryScope>
            </Section1>
        </QueryScope>
    );
};
```

In this example:

* Queries inside `<Section1>` bind to the inner `<QueryScope>`.
* The outer `<QueryScope>` reports `isPerforming` as `true` whenever any inner scope has an in-flight query.

## Query Scope API

[Section titled “Query Scope API”](#query-scope-api)

| Name                          | Type                       | Description                                                                        |
| ----------------------------- | -------------------------- | ---------------------------------------------------------------------------------- |
| `isPerforming`                | `boolean`                  | Whether any queries in this scope or child scopes are currently in-flight.         |
| `parent`                      | `IQueryScope \| undefined` | The parent scope, if this scope is nested.                                         |
| `addChildScope(scope)`        | `void`                     | Register a child scope for aggregate state propagation (done automatically).       |
| `notifyPerformingStarted()`   | `void`                     | Signal that a query has started performing (called automatically by query hooks).  |
| `notifyPerformingCompleted()` | `void`                     | Signal that a query has finished performing (called automatically by query hooks). |

## Using Query Scope in React

[Section titled “Using Query Scope in React”](#using-query-scope-in-react)

To read the performing state imperatively from inside the scope, use the `useQueryScope` hook:

```typescript
import { useQueryScope } from '@cratis/arc.react/queries';

export const Toolbar = () => {
    const queryScope = useQueryScope();

return (
        <div>
            {queryScope.isPerforming && <Spinner />}
        </div>
    );
};
```

You can also consume the context directly:

```typescript
import { QueryScopeContext } from '@cratis/arc.react/queries';

export const Toolbar = () => {
    return (
        <QueryScopeContext.Consumer>
            {scope => (
                <div>
                    {scope.isPerforming && <Spinner />}
                </div>
            )}
        </QueryScopeContext.Consumer>
    );
};
```

## Using Query Scope in ViewModels

[Section titled “Using Query Scope in ViewModels”](#using-query-scope-in-viewmodels)

The query scope can be injected into ViewModels through dependency injection. The ViewModel automatically receives the closest query scope in the component hierarchy.

```typescript
import { IQueryScope } from '@cratis/arc.react/queries';
import { injectable } from 'tsyringe';

@injectable()
export class MyViewModel {
    constructor(private readonly _queryScope: IQueryScope) {
    }

get isLoading(): boolean {
        return this._queryScope.isPerforming;
    }
}
```

The ViewModel then exposes `isLoading` as an observable property (MobX makes this automatic via `withViewModel`), which your component can bind to:

```typescript
export const MyPage = withViewModel(MyViewModel, ({ viewModel }) => {
    return (
        <div>
            {viewModel.isLoading && <Spinner />}
            <DataTable />
        </div>
    );
});
```

## Automatic Query Tracking

[Section titled “Automatic Query Tracking”](#automatic-query-tracking)

Any query hook used inside a `<QueryScope>` is automatically tracked — there is nothing extra to wire up:

```typescript
export const DataPanel = () => {
    const [result] = AllAccounts.use();

return (
        <DataTable value={result.data} />
    );
};
```

When `AllAccounts.use()` fires an HTTP request, `isPerforming` on the nearest enclosing `<QueryScope>` becomes `true`. It returns to `false` once the response arrives.

Observable queries work the same way:

```typescript
export const LiveFeed = () => {
    const [feed] = FeedItems.use();

return (
        <ul>
            {feed.data.map(item => <li key={item.id}>{item.message}</li>)}
        </ul>
    );
};
```

`isPerforming` is `true` from the moment the subscription is opened until the first result is received.

## See Also

[Section titled “See Also”](#see-also)

* [Queries Overview](/arc/frontend/react/queries/)
* [React Usage](/arc/frontend/react/commands/react-usage/)
* [Command Scope](/arc/frontend/react/commands/scope/) — Equivalent feature for tracking command execution state.

# Suspense Queries

React 18 introduced first-class support for [Suspense](https://react.dev/reference/react/Suspense) and [ErrorBoundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) patterns. Arc provides Suspense-compatible variants of every query hook so components can declaratively express their loading and error states without managing `isPerforming` or `hasExceptions` flags manually.

## How It Works

[Section titled “How It Works”](#how-it-works)

Suspense-compatible hooks use React’s throw-a-Promise protocol:

1. The hook is called inside a component tree wrapped in `<Suspense>` and a `QueryErrorBoundary`.
2. While the query is in-flight the hook **throws a Promise**. React catches it, shows the `<Suspense>` `fallback`, and re-renders the component when the Promise resolves.
3. On success the component renders normally, with the result already available.
4. On failure the hook **throws an error** (`QueryFailed` or `QueryUnauthorized`). The nearest `QueryErrorBoundary` catches it and shows its fallback.

This means the component body contains only the **happy-path** rendering logic — loading and error handling are entirely declarative through the surrounding boundaries.

```tsx
<QueryErrorBoundary onError={({ isQueryUnauthorized, reset }) =>
    isQueryUnauthorized
        ? <p>Not authorized. <button onClick={reset}>Retry</button></p>
        : <p>Something went wrong. <button onClick={reset}>Retry</button></p>
}>
    <Suspense fallback={<Spinner />}>
        <ItemList />  {/* suspends until data arrives */}
    </Suspense>
</QueryErrorBoundary>
```

> **Note**: Because these hooks suspend during loading, they **must** be rendered inside a `<Suspense>` boundary; otherwise React will throw an unhandled Promise to the root.

## Boundary Components

[Section titled “Boundary Components”](#boundary-components)

Arc ships two ready-to-use boundary components so you don’t need to write your own class-based `ErrorBoundary`.

### QueryErrorBoundary

[Section titled “QueryErrorBoundary”](#queryerrorboundary)

A class-based error boundary that catches `QueryFailed` and `QueryUnauthorized` thrown by the Suspense query hooks. Use it when you want to control the `<Suspense>` and `QueryErrorBoundary` separately.

```tsx
import { QueryErrorBoundary } from '@cratis/arc.react/queries';

<QueryErrorBoundary
    onError={({ error, isQueryFailed, isQueryUnauthorized, reset }) => (
        <div>
            <p>{isQueryUnauthorized ? 'Not authorized' : 'Server error'}</p>
            {isQueryFailed && <p>{error.exceptionMessages.join(', ')}</p>}
            <button onClick={reset}>Retry</button>
        </div>
    )}
>
    <Suspense fallback={<Spinner />}>
        <ItemList />
    </Suspense>
</QueryErrorBoundary>
```

**Props:**

| Prop       | Type                                  | Description                                                                                         |
| ---------- | ------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `onError`  | `(info: QueryErrorInfo) => ReactNode` | Called when an error is caught. Return the fallback UI.                                             |
| `fallback` | `ReactNode`                           | Static fallback to render when an error is caught. `onError` takes precedence if both are provided. |
| `children` | `ReactNode`                           | The subtree to protect.                                                                             |

**`QueryErrorInfo`:**

| Property              | Type         | Description                                             |
| --------------------- | ------------ | ------------------------------------------------------- |
| `error`               | `Error`      | The raw error that was caught.                          |
| `isQueryFailed`       | `boolean`    | `true` when the error is a `QueryFailed`.               |
| `isQueryUnauthorized` | `boolean`    | `true` when the error is a `QueryUnauthorized`.         |
| `reset()`             | `() => void` | Resets the boundary so the child subtree is re-mounted. |

### QueryBoundary

[Section titled “QueryBoundary”](#queryboundary)

A convenience wrapper that combines `<Suspense>` and `QueryErrorBoundary` in a single component. Use this for the common case where you want to handle both loading and error states together.

```tsx
import { QueryBoundary } from '@cratis/arc.react/queries';

<QueryBoundary
    loadingFallback={<Spinner />}
    onError={({ isQueryUnauthorized, reset }) =>
        isQueryUnauthorized
            ? <p>Not authorized. <button onClick={reset}>Retry</button></p>
            : <p>Something went wrong. <button onClick={reset}>Retry</button></p>
    }
>
    <ItemList />
</QueryBoundary>
```

**Props:**

| Prop              | Type                                  | Description                                                                        |
| ----------------- | ------------------------------------- | ---------------------------------------------------------------------------------- |
| `loadingFallback` | `ReactNode`                           | Rendered by the inner `<Suspense>` while the query is loading. Defaults to `null`. |
| `onError`         | `(info: QueryErrorInfo) => ReactNode` | Called when an error is caught. Return the fallback UI.                            |
| `fallback`        | `ReactNode`                           | Static error fallback. `onError` takes precedence if both are provided.            |
| `children`        | `ReactNode`                           | The subtree to protect.                                                            |

## Hooks

[Section titled “Hooks”](#hooks)

### useSuspenseQuery

[Section titled “useSuspenseQuery”](#usesuspensequery)

Use `useSuspenseQuery` for standard request/response HTTP queries.

```typescript
import { useSuspenseQuery } from '@cratis/arc.react/queries';

function ItemList() {
    const [result, perform] = useSuspenseQuery(AllItems);

return (
        <ul>
            {result.data.map(item => <li key={item.id}>{item.name}</li>)}
        </ul>
    );
}
```

**Signature:**

```typescript
useSuspenseQuery<TDataType, TQuery, TArguments>(
    query: Constructor<TQuery>,
    args?: TArguments,
    sorting?: Sorting
): [QueryResultWithState<TDataType>, PerformQuery<TArguments>, SetSorting]
```

| Return value | Type                                  | Description                                                              |
| ------------ | ------------------------------------- | ------------------------------------------------------------------------ |
| `result`     | `QueryResultWithState<TDataType>`     | The resolved query result. Never `undefined` when the component renders. |
| `perform`    | `() => Promise<void>`                 | Re-runs the query. Clears the cache and triggers a new Suspense cycle.   |
| `setSorting` | `(sorting: Sorting) => Promise<void>` | Changes the sort order and triggers a new Suspense cycle.                |

#### With Paging

[Section titled “With Paging”](#with-paging)

```typescript
import { useSuspenseQueryWithPaging } from '@cratis/arc.react/queries';
import { Paging } from '@cratis/arc/queries';

function PagedList() {
    const [result, perform, setSorting, setPage, setPageSize] =
        useSuspenseQueryWithPaging(AllItems, new Paging(0, 20));

return (
        <>
            <ul>
                {result.data.map(item => <li key={item.id}>{item.name}</li>)}
            </ul>
            <button onClick={() => setPage(result.paging.page + 1)}>Next page</button>
        </>
    );
}
```

### useSuspenseObservableQuery

[Section titled “useSuspenseObservableQuery”](#usesuspenseobservablequery)

Use `useSuspenseObservableQuery` for WebSocket-based observable queries. The component suspends until the **first message** is received over the WebSocket, then re-renders reactively on every subsequent update without suspending again.

```typescript
import { useSuspenseObservableQuery } from '@cratis/arc.react/queries';

function LiveFeed() {
    const [result] = useSuspenseObservableQuery(LiveItems);

return (
        <ul>
            {result.data.map(item => <li key={item.id}>{item.name}</li>)}
        </ul>
    );
}
```

**Signature:**

```typescript
useSuspenseObservableQuery<TDataType, TQuery, TArguments>(
    query: Constructor<TQuery>,
    args?: TArguments,
    sorting?: Sorting
): [QueryResultWithState<TDataType>, SetSorting]
```

| Return value | Type                                  | Description                                                                          |
| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------ |
| `result`     | `QueryResultWithState<TDataType>`     | The latest result from the observable. Never `undefined` when the component renders. |
| `setSorting` | `(sorting: Sorting) => Promise<void>` | Changes the sort order, unsubscribes the old stream, and subscribes a new one.       |

#### With Paging

[Section titled “With Paging”](#with-paging-1)

```typescript
import { useSuspenseObservableQueryWithPaging } from '@cratis/arc.react/queries';
import { Paging } from '@cratis/arc/queries';

function PagedFeed() {
    const [result, setSorting, setPage, setPageSize] =
        useSuspenseObservableQueryWithPaging(LiveItems, new Paging(0, 20));
    // ...
}
```

## Error Types

[Section titled “Error Types”](#error-types)

When a query fails the hook throws one of two typed errors, both of which extend `Error`.

### QueryFailed

[Section titled “QueryFailed”](#queryfailed)

Thrown when the server returns `hasExceptions: true`. Carries the server-side exception details.

| Property              | Type       | Description                                     |
| --------------------- | ---------- | ----------------------------------------------- |
| `exceptionMessages`   | `string[]` | One or more exception messages from the server. |
| `exceptionStackTrace` | `string`   | The full server-side stack trace.               |

### QueryUnauthorized

[Section titled “QueryUnauthorized”](#queryunauthorized)

Thrown when the server returns `isAuthorized: false`.

## Using the Proxy Static Methods

[Section titled “Using the Proxy Static Methods”](#using-the-proxy-static-methods)

Generated query proxies expose `useSuspense()` and `useSuspenseWithPaging()` static methods that forward directly to the hooks above, giving the same ergonomics as the existing `use()` method.

```typescript
// Regular query via proxy
function ItemList() {
    const [result, perform] = AllItems.useSuspense();
    return <ul>{result.data.map(i => <li key={i.id}>{i.name}</li>)}</ul>;
}

// With arguments
function FilteredList() {
    const [result] = AllItems.useSuspense({ filter: 'active' });
    return <ul>{result.data.map(i => <li key={i.id}>{i.name}</li>)}</ul>;
}

// Observable query via proxy
function LiveFeed() {
    const [result] = LiveItems.useSuspense();
    return <ul>{result.data.map(i => <li key={i.id}>{i.name}</li>)}</ul>;
}
```

## Complete Example

[Section titled “Complete Example”](#complete-example)

The following example uses `QueryBoundary` — the simplest way to wrap a Suspense component in Arc.

```tsx
import { QueryBoundary, QueryFailed } from '@cratis/arc.react/queries';
import { AllItems } from './generated/queries';

function ItemList() {
    const [result, perform] = AllItems.useSuspense();

return (
        <>
            <ul>
                {result.data.map(item => <li key={item.id}>{item.name}</li>)}
            </ul>
            <button onClick={perform}>Refresh</button>
        </>
    );
}

export function App() {
    return (
        <QueryBoundary
            loadingFallback={<p>Loading…</p>}
            onError={({ error, isQueryFailed, isQueryUnauthorized, reset }) => (
                <div>
                    {isQueryUnauthorized && <p>You are not authorized to view this data.</p>}
                    {isQueryFailed && (
                        <>
                            <p>Failed to load data:</p>
                            <ul>
                                {(error as QueryFailed).exceptionMessages.map((m, i) => (
                                    <li key={i}>{m}</li>
                                ))}
                            </ul>
                        </>
                    )}
                    <button onClick={reset}>Retry</button>
                </div>
            )}
        >
            <ItemList />
        </QueryBoundary>
    );
}
```

## Comparison with Standard Hooks

[Section titled “Comparison with Standard Hooks”](#comparison-with-standard-hooks)

| Feature                        | `useQuery` / `useObservableQuery` | `useSuspenseQuery` / `useSuspenseObservableQuery`                  |
| ------------------------------ | --------------------------------- | ------------------------------------------------------------------ |
| Loading state                  | `result.isPerforming === true`    | Component suspends; `<Suspense fallback>` renders                  |
| Error state                    | `result.hasExceptions === true`   | Hook throws; `QueryErrorBoundary` catches                          |
| Authorization failure          | `result.isAuthorized === false`   | Hook throws `QueryUnauthorized`; `QueryErrorBoundary` catches      |
| Requires `<Suspense>` boundary | No                                | **Yes** (or use `QueryBoundary`)                                   |
| Requires error boundary        | No (optional)                     | **Strongly recommended** (`QueryErrorBoundary` or `QueryBoundary`) |
| Re-run trigger                 | `perform()` callback              | `perform()` callback — clears cache, re-suspends                   |
| Proxy static method            | `.use()`                          | `.useSuspense()`                                                   |

## Cache and Re-Fetching

[Section titled “Cache and Re-Fetching”](#cache-and-re-fetching)

Suspense hooks maintain a module-level cache so the in-flight Promise and its resolved result survive React’s Suspense retry cycle on uncommitted components. When you call `perform()` (or `setSorting()` / `setPage()`) the cache entry is cleared and the component enters a new Suspense cycle.

> **Testing**: Call `clearSuspenseQueryCache()` or `clearSuspenseObservableQueryCache()` in your test teardown to prevent state leaking between tests.

```typescript
import { clearSuspenseQueryCache, clearSuspenseObservableQueryCache } from '@cratis/arc.react/queries';

afterEach(() => {
    clearSuspenseQueryCache();
    clearSuspenseObservableQueryCache();
});
```

# Core Query Usage

Use generated query proxies to retrieve data in React with strong typing and predictable state.

## Proxy Generation

[Section titled “Proxy Generation”](#proxy-generation)

Arc generates query proxies from backend queries (controller-based and model-bound). These proxies expose static React helpers such as `.use()` and `.useWithPaging()`.

See [Backend Proxy Generation](/arc/backend/proxy-generation/) for setup details.

## Basic Query Hook

[Section titled “Basic Query Hook”](#basic-query-hook)

From a React component, call the generated static `use()` method:

```typescript
export const MyComponent = () => {
    const [accounts, queryAccounts] = AllAccounts.use();

return (
        <>
        </>
    );
};
```

All results are strongly typed from backend metadata.

## Return Tuple

[Section titled “Return Tuple”](#return-tuple)

For standard request/response queries, the tuple contains two elements:

* Query result
* Delegate for issuing the query again

Observable queries differ and are covered in [Observable Queries](/arc/frontend/react/queries/observable-queries/).

## QueryResultWithState

[Section titled “QueryResultWithState”](#queryresultwithstate)

The query result type in React is `QueryResultWithState`. It implements the same `IQueryResult` contract as `QueryResult` and adds React-focused execution state.

Properties from the shared `IQueryResult` contract:

| Property              | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| `data`                | The actual data returned in the expected type.                                |
| `isSuccess`           | Whether the query completed successfully.                                     |
| `isReady`             | Whether the query has produced a result. `false` is transient, not a failure. |
| `isAuthorized`        | Whether the query was authorized.                                             |
| `isValid`             | Whether the query input was valid.                                            |
| `validationResults`   | Validation errors returned by the backend.                                    |
| `hasExceptions`       | Whether exceptions were returned.                                             |
| `exceptionMessages`   | Exception messages from the backend.                                          |
| `exceptionStackTrace` | Exception stack trace when available.                                         |
| `paging`              | Paging metadata (page, size, totals) when paging is enabled.                  |

React execution state:

| Property       | Description                                   |
| -------------- | --------------------------------------------- |
| `isPerforming` | Whether the query is currently fetching data. |

### Readiness and performing state

[Section titled “Readiness and performing state”](#readiness-and-performing-state)

An observable query HTTP request can return `202 Accepted` with `isReady: false` before the observable has produced its first result. This is a transient server state: `isSuccess` is false, but `hasExceptions` remains false. Inspect `isReady` before treating an unsuccessful result as a failure.

`isReady` and `isPerforming` describe different things. Readiness says whether a result has been produced; performing says whether the client is currently fetching or subscribing. Initial React query state is not ready, while disabled or synthetic failure states are ready because no server result remains pending.

`IQueryResult.isReady` is optional for source compatibility: older Arc servers and third-party structural query-result objects may omit it. Arc normalizes query results received through its HTTP, WebSocket, and Server-Sent Events transports to `isReady: true` when the member is absent, while preserving an explicit `false`. SDK-produced `QueryResult` and `QueryResultWithState` instances always expose a concrete boolean.

## Query Parameters

[Section titled “Query Parameters”](#query-parameters)

Queries can expose parameters through backend attributes (for example `[FromQuery]` and route parameters). These become typed arguments on generated proxies.

```csharp
[HttpGet("starting-with")]
public IEnumerable<DebitAccount> StartingWith([FromQuery] string? filter)
{
    var filterDocument = Builders<DebitAccount>
        .Filter
        .Regex("name", $"^{filter ?? string.Empty}.*");

return _collection.Find(filterDocument).ToList();
}
```

Use the parameterized proxy from React:

```typescript
export const MyComponent = () => {
    const [accounts, queryAccounts] = StartingWith.use({ filter: '' });

return (
        <>
        </>
    );
};
```

## HTTP Headers

[Section titled “HTTP Headers”](#http-headers)

Queries automatically include HTTP headers from the `httpHeadersCallback` configured in [Arc](/arc/frontend/react/arc/). This lets you attach auth tokens, cookies, or custom headers for every query call without per-query setup.

## See Also

[Section titled “See Also”](#see-also)

* [Paging](/arc/frontend/react/queries/paging/)
* [Suspense Queries](/arc/frontend/react/queries/suspense-queries/)
* [Conditional Queries](/arc/frontend/react/queries/conditional-queries/)
* [Observable Queries](/arc/frontend/react/queries/observable-queries/)

# Story Components

## Overview

[Section titled “Overview”](#overview)

The Arc.React Story Components library provides a comprehensive set of reusable components and utilities designed specifically for creating beautiful, consistent Storybook stories. These components ensure that all your stories have a uniform look and feel while automatically adapting to both dark and light themes.

## Motivation

[Section titled “Motivation”](#motivation)

When building component libraries, documentation through Storybook is essential. However, creating stories that look professional and consistent across different themes can be time-consuming and repetitive. Common challenges include:

* **Inconsistent Spacing**: Different stories use different padding and margins, making the documentation feel disjointed
* **Theme Support**: Manual theme handling requires duplicate code and careful maintenance
* **Layout Patterns**: Repeating the same container, grid, and section patterns across multiple stories
* **Visual Hierarchy**: Ensuring consistent typography, colors, and visual structure
* **Developer Experience**: Spending more time on story presentation than on showcasing the actual components

## Solution

[Section titled “Solution”](#solution)

The Story Components library solves these problems by providing:

### Consistency

[Section titled “Consistency”](#consistency)

Pre-built components with standardized spacing, sizing, and layout patterns ensure every story looks cohesive. Developers can focus on showcasing their components rather than styling containers.

### Automatic Theme Adaptation

[Section titled “Automatic Theme Adaptation”](#automatic-theme-adaptation)

All components use CSS variables that automatically update based on the current Storybook theme. Switch between dark and light modes seamlessly without any additional code.

### Reusable Patterns

[Section titled “Reusable Patterns”](#reusable-patterns)

Common UI patterns like containers, grids, sections, badges, and dividers are available as ready-to-use components, reducing boilerplate and improving maintainability.

### Beautiful by Default

[Section titled “Beautiful by Default”](#beautiful-by-default)

Thoughtfully designed defaults for colors, shadows, borders, and spacing mean your stories look professional out of the box.

The stylesheet behind those defaults ships inside the package. Add one import to your Storybook preview and every component below is styled - see [Styling](/arc/frontend/react/stories/styling/).

## Getting Started

[Section titled “Getting Started”](#getting-started)

Load the stylesheet once, in your Storybook preview:

.storybook/preview\.ts

```ts
import '@cratis/arc.react/stories/styles.css';
```

Then import the components you need in your story files:

```tsx
import { StoryContainer, StorySection, StoryGrid, StoryBadge, StoryDivider } from '@cratis/arc.react/stories';

export const MyStory: Story = {
  render: () => (
    <StoryContainer size="md" asCard>
      <h1>My Component</h1>
      <MyComponent />
    </StoryContainer>
  ),
};
```

## What’s Included

[Section titled “What’s Included”](#whats-included)

* **[Components](/arc/frontend/react/stories/components/)**: Pre-built React components for common story layouts
* **[Styling](/arc/frontend/react/stories/styling/)**: CSS variables and utility classes for consistent theming
* **[Theme Support](/arc/frontend/react/stories/theme-support/)**: Automatic dark/light mode adaptation

## Examples

[Section titled “Examples”](#examples)

For comprehensive examples of all components and patterns, see the `StoryContainer.stories.tsx` file in the source code.

# Story Components Reference

This page documents all available components for building Storybook stories.

## StoryContainer

[Section titled “StoryContainer”](#storycontainer)

A container component for wrapping stories with consistent spacing and styling.

### Props

[Section titled “Props”](#props)

* `children`: React.ReactNode - The content to render

* `size`: ‘sm’ | ‘md’ | ‘lg’ | ‘full’ - Container size (default: ‘md’)

* `sm`: 600px max width
  * `md`: 1200px max width
  * `lg`: 1400px max width
  * `full`: no max width

* `asCard`: boolean - Render as a card with background and border (default: false)

* `className`: string - Additional CSS classes

### Example

[Section titled “Example”](#example)

```tsx
import { StoryContainer } from '@cratis/arc.react/stories';

export const MyStory: Story = {
  render: () => (
    <StoryContainer size="sm" asCard>
      <h1>My Component</h1>
      <MyComponent />
    </StoryContainer>
  ),
};
```

### Usage Guidelines

[Section titled “Usage Guidelines”](#usage-guidelines)

* Use `size="sm"` for focused examples with narrow content
* Use `size="md"` (default) for most standard stories
* Use `size="lg"` for complex layouts or multiple columns
* Use `size="full"` for full-width demonstrations
* Add `asCard` when you want visual separation from the background

## StorySection

[Section titled “StorySection”](#storysection)

A section component for grouping related content with consistent vertical spacing.

### Props

[Section titled “Props”](#props-1)

* `children`: React.ReactNode - The content to render

### Example

[Section titled “Example”](#example-1)

```tsx
<StoryContainer>
  <StorySection>
    <h2>First Section</h2>
    <p>Content here</p>
  </StorySection>

<StorySection>
    <h2>Second Section</h2>
    <p>More content</p>
  </StorySection>
</StoryContainer>
```

### Usage Guidelines

[Section titled “Usage Guidelines”](#usage-guidelines-1)

* Use sections to separate distinct topics or examples within a story
* Sections provide consistent vertical spacing between content blocks
* Ideal for multi-part demonstrations

## StoryGrid

[Section titled “StoryGrid”](#storygrid)

A responsive grid container for displaying multiple items.

### Props

[Section titled “Props”](#props-2)

* `children`: React.ReactNode - Grid items to render

### Example

[Section titled “Example”](#example-2)

```tsx
<StoryGrid>
  <div className="story-card">Card 1</div>
  <div className="story-card">Card 2</div>
  <div className="story-card">Card 3</div>
</StoryGrid>
```

### Usage Guidelines

[Section titled “Usage Guidelines”](#usage-guidelines-2)

* Use grids to showcase variations or multiple states of a component
* Grid automatically adjusts columns based on screen size
* Combine with `.story-card` class for card-style grid items

## StoryDivider

[Section titled “StoryDivider”](#storydivider)

A visual divider between sections.

### Props

[Section titled “Props”](#props-3)

No props - it’s a simple visual element.

### Example

[Section titled “Example”](#example-3)

```tsx
<StoryContainer>
  <p>First section</p>
  <StoryDivider />
  <p>Second section</p>
</StoryContainer>
```

### Usage Guidelines

[Section titled “Usage Guidelines”](#usage-guidelines-3)

* Use dividers to create clear visual separation
* Automatically adapts color to current theme
* Lighter alternative to separate sections

## StoryBadge

[Section titled “StoryBadge”](#storybadge)

A status badge component for displaying colored labels.

### Props

[Section titled “Props”](#props-4)

* `children`: React.ReactNode - Badge content
* `variant`: ‘success’ | ‘warning’ | ‘error’ | ‘info’ - Badge color variant
* `className`: string - Additional CSS classes

### Example

[Section titled “Example”](#example-4)

```tsx
<p>
  Build Status: <StoryBadge variant="success">Passing</StoryBadge>
</p>
```

### Variants

[Section titled “Variants”](#variants)

* `success`: Green badge for positive states
* `warning`: Yellow/orange badge for cautionary states
* `error`: Red badge for error states
* `info`: Blue badge for informational states

### Usage Guidelines

[Section titled “Usage Guidelines”](#usage-guidelines-4)

* Use badges to highlight status, state, or metadata
* Keep badge content concise (1-2 words)
* Choose variants that match semantic meaning

# Styling Reference

The story components use a comprehensive set of CSS variables and utility classes for consistent theming.

## Where the styling comes from

[Section titled “Where the styling comes from”](#where-the-styling-comes-from)

Everything on this page is defined in a single stylesheet that ships inside `@cratis/arc.react`. Import it once, in your Storybook preview:

.storybook/preview\.ts

```ts
import '@cratis/arc.react/stories/styles.css';
```

That is the whole setup. Import it before your own theme so your rules win, and every variable and class below becomes yours to override from ordinary CSS.

The components do not import the stylesheet themselves, and that is deliberate. Doing so would put the stylesheet’s path into the package’s compiled JavaScript, which only resolves when the package is built by the bundler that copies the file alongside it - and not when a TypeScript project reference builds it, where no such copy happens. One import you can see beats an import that works in some builds and not others.

## CSS Variables

[Section titled “CSS Variables”](#css-variables)

All variables automatically update based on the current Storybook theme (dark/light mode).

### Colors

[Section titled “Colors”](#colors)

#### Text Colors

[Section titled “Text Colors”](#text-colors)

* `--color-text`: Primary text color
* `--color-text-secondary`: Secondary text color for less important content
* `--color-text-muted`: Muted text color for hints and labels

#### Background Colors

[Section titled “Background Colors”](#background-colors)

* `--color-background`: Main background color
* `--color-background-secondary`: Secondary background (cards, inputs)
* `--color-background-tertiary`: Tertiary background (hover states)

#### Border Colors

[Section titled “Border Colors”](#border-colors)

* `--color-border`: Standard border color
* `--color-border-light`: Lighter border color for subtle divisions

#### Brand Colors

[Section titled “Brand Colors”](#brand-colors)

* `--color-primary`: Primary brand color
* `--color-primary-hover`: Primary color hover state

#### Semantic Colors

[Section titled “Semantic Colors”](#semantic-colors)

* `--color-success`: Success state color (typically green)
* `--color-warning`: Warning state color (typically yellow/orange)
* `--color-error`: Error state color (typically red)
* `--color-info`: Info state color (typically blue)

### Spacing

[Section titled “Spacing”](#spacing)

Consistent spacing values for padding and margins:

* `--space-xs`: 0.25rem (4px)
* `--space-sm`: 0.5rem (8px)
* `--space-md`: 1rem (16px)
* `--space-lg`: 1.5rem (24px)
* `--space-xl`: 2rem (32px)
* `--space-2xl`: 3rem (48px)

### Visual Effects

[Section titled “Visual Effects”](#visual-effects)

#### Border Radius

[Section titled “Border Radius”](#border-radius)

* `--radius-sm`: Small border radius
* `--radius-md`: Medium border radius
* `--radius-lg`: Large border radius

#### Box Shadows

[Section titled “Box Shadows”](#box-shadows)

* `--shadow-sm`: Subtle shadow for slight elevation
* `--shadow-md`: Medium shadow for cards and modals
* `--shadow-lg`: Large shadow for prominent elements

### Typography

[Section titled “Typography”](#typography)

* `--font-sans`: Sans-serif font family for UI text
* `--font-mono`: Monospace font family for code

## Utility Classes

[Section titled “Utility Classes”](#utility-classes)

Pre-built CSS classes you can use directly in your stories.

### Container Classes

[Section titled “Container Classes”](#container-classes)

* `.story-container`: Standard container with medium width
* `.story-container-sm`: Small container (600px max width)
* `.story-container-lg`: Large container (1400px max width)

### Layout Classes

[Section titled “Layout Classes”](#layout-classes)

* `.story-section`: Section wrapper with consistent vertical spacing
* `.story-grid`: Responsive grid layout
* `.story-card`: Card styling with background, border, and shadow

### Visual Elements

[Section titled “Visual Elements”](#visual-elements)

* `.story-divider`: Horizontal divider line

### Badge Classes

[Section titled “Badge Classes”](#badge-classes)

* `.story-badge`: Base badge style
* `.story-badge-success`: Green success badge
* `.story-badge-warning`: Yellow/orange warning badge
* `.story-badge-error`: Red error badge
* `.story-badge-info`: Blue info badge

## Usage Examples

[Section titled “Usage Examples”](#usage-examples)

### Using CSS Variables

[Section titled “Using CSS Variables”](#using-css-variables)

```tsx
<div style={{
  padding: 'var(--space-lg)',
  backgroundColor: 'var(--color-background-secondary)',
  borderRadius: 'var(--radius-md)',
  boxShadow: 'var(--shadow-sm)'
}}>
  Custom styled content
</div>
```

### Using Utility Classes

[Section titled “Using Utility Classes”](#using-utility-classes)

```tsx
<div className="story-container">
  <div className="story-card">
    <h2>Card Title</h2>
    <p>Card content</p>
  </div>
</div>
```

### Combining Variables and Classes

[Section titled “Combining Variables and Classes”](#combining-variables-and-classes)

```tsx
<div className="story-grid">
  <div
    className="story-card"
    style={{ borderColor: 'var(--color-primary)' }}
  >
    Custom card with primary border
  </div>
</div>
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Prefer CSS Variables**: Use variables instead of hard-coded colors for theme compatibility
2. **Use Utility Classes**: Leverage utility classes for common patterns to ensure consistency
3. **Semantic Colors**: Use semantic color variables (`--color-success`, etc.) for meaningful states
4. **Consistent Spacing**: Stick to the spacing scale (`--space-*`) for consistent rhythm
5. **Theme Testing**: Always test your stories in both dark and light modes

# Automatic Theme Support

All story components and CSS variables adapt to the theme in effect, providing seamless dark and light mode support.

## How It Works

[Section titled “How It Works”](#how-it-works)

Every color in the story components is read from a CSS custom property rather than written into a rule. The stylesheet that ships with the package declares those properties twice - once for dark, once for light - so changing the theme changes one attribute and every component follows.

### Default Theme

[Section titled “Default Theme”](#default-theme)

The default theme is **dark mode**. This ensures a consistent baseline experience when viewing stories.

### Switching Themes

[Section titled “Switching Themes”](#switching-themes)

Set `data-theme` on `<html>` or `<body>`. `data-theme="light"` selects the light palette, `data-theme="dark"` selects the dark one, and no attribute at all leaves you with dark. Because the properties are inherited, the attribute can also sit on a container to theme one part of a page:

```html
<script>
  document.documentElement.setAttribute('data-theme', 'light');
</script>
```

The package deliberately does **not** read the operating system color scheme on its own. The palette has to agree with whatever paints the canvas behind it - the Storybook background, your own preview decorator - and only your Storybook configuration knows what that is. Deciding for you would produce dark text on a dark canvas for anyone whose machine disagreed with their toolbar.

The Arc repository’s own Storybook wires the two together: a snippet in its `.storybook/preview-head.html` watches the canvas background, measures its luminance, and sets `data-theme` to match - so the backgrounds toolbar drives the theme. Copy that approach if you want the same behavior in yours.

## Theme-Aware Design

[Section titled “Theme-Aware Design”](#theme-aware-design)

### Color Adaptation

[Section titled “Color Adaptation”](#color-adaptation)

Colors are the primary difference between themes:

* **Dark Mode**: Uses lighter text on darker backgrounds
* **Light Mode**: Uses darker text on lighter backgrounds

All semantic colors (success, warning, error, info) have theme-appropriate variants to ensure proper contrast and readability.

### Automatic Adjustments

[Section titled “Automatic Adjustments”](#automatic-adjustments)

When switching themes, the following automatically update:

* **Text Colors**: Primary, secondary, and muted text colors adjust for readability
* **Background Colors**: Container, card, and input backgrounds adapt
* **Border Colors**: Borders become lighter or darker based on the theme
* **Shadows**: Box shadows are optimized for each theme
* **Status Colors**: Success, warning, error, and info colors maintain proper contrast

## Developer Experience

[Section titled “Developer Experience”](#developer-experience)

### No Additional Code Required

[Section titled “No Additional Code Required”](#no-additional-code-required)

Beyond importing the stylesheet once and deciding when `data-theme` flips, you don’t write any theme-switching logic. Simply use the provided components and CSS variables:

```tsx
// This automatically works in both themes
<StoryContainer asCard>
  <h1>My Component</h1>
  <MyComponent />
</StoryContainer>
```

### Theme-Safe Custom Styles

[Section titled “Theme-Safe Custom Styles”](#theme-safe-custom-styles)

When adding custom styles, use CSS variables to ensure theme compatibility:

```tsx
// ✅ Good - Uses CSS variables
<div style={{
  color: 'var(--color-text)',
  backgroundColor: 'var(--color-background-secondary)'
}}>
  Theme-safe content
</div>

// ❌ Avoid - Hard-coded colors
<div style={{
  color: '#ffffff',
  backgroundColor: '#1a1a1a'
}}>
  Only works in dark mode
</div>
```

## Testing Your Stories

[Section titled “Testing Your Stories”](#testing-your-stories)

### Always Test Both Themes

[Section titled “Always Test Both Themes”](#always-test-both-themes)

To ensure your stories look great in all contexts:

1. **Start in Dark Mode**: Verify your story looks correct in the default theme
2. **Switch to Light Mode**: Set `data-theme="light"` and check that all elements remain readable and visually appealing
3. **Check Color Contrast**: Ensure text is legible against backgrounds in both themes
4. **Verify Interactive States**: Hover, focus, and active states should work in both themes

### Common Issues and Solutions

[Section titled “Common Issues and Solutions”](#common-issues-and-solutions)

#### Issue: Poor Contrast in One Theme

[Section titled “Issue: Poor Contrast in One Theme”](#issue-poor-contrast-in-one-theme)

**Problem**: Text is hard to read in light mode but fine in dark mode.

**Solution**: Use semantic text color variables instead of hard-coded values:

```tsx
// Instead of:
<p style={{ color: '#888' }}>Text</p>

// Use:
<p style={{ color: 'var(--color-text-secondary)' }}>Text</p>
```

#### Issue: Borders Not Visible

[Section titled “Issue: Borders Not Visible”](#issue-borders-not-visible)

**Problem**: Borders disappear or become too prominent when switching themes.

**Solution**: Use border color variables:

```tsx
// Instead of:
<div style={{ border: '1px solid #333' }}>Content</div>

// Use:
<div style={{ border: '1px solid var(--color-border)' }}>Content</div>
```

#### Issue: Custom Colors Don’t Adapt

[Section titled “Issue: Custom Colors Don’t Adapt”](#issue-custom-colors-dont-adapt)

**Problem**: Brand or custom colors don’t change with the theme.

**Solution**: Define theme-specific versions of your custom colors or use the primary color variable:

```tsx
// For brand colors that should adapt:
<button style={{
  backgroundColor: 'var(--color-primary)',
  color: 'var(--color-background)' // Inverts with theme
}}>
  Button
</button>
```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Always Use Variables**: Prefer CSS variables over hard-coded color values
2. **Test Both Themes**: Verify your stories in dark and light modes before committing
3. **Semantic Colors**: Use semantic variables (`--color-text`, `--color-background`) instead of specific shades
4. **Document Theme Considerations**: If a component has theme-specific behavior, document it
5. **Consistent Patterns**: Follow the patterns established by existing story components

## Implementation Details

[Section titled “Implementation Details”](#implementation-details)

The theme system is implemented using:

* A stylesheet published inside `@cratis/arc.react`, reached through the `@cratis/arc.react/stories/styles.css` export and imported once from your Storybook preview
* CSS custom properties declared on `:root` for the dark palette and on `[data-theme='light']` for the light one, which is why the attribute can sit on any ancestor and why your own CSS can override any of them
* Nothing else - no runtime, no theme provider, no build step

Developers using the story components don’t need to understand these implementation details—the system works transparently.

# Storybook

> Browse Arc's React building blocks — CommandForm fields, query and observable-query helpers, and the story components — live in an interactive Storybook.

[Cratis Arc React Storybook](/storybook-arc/index.html?docsSiteTheme=dark)

# Vite Configuration

When you use Vite’s built-in dev server to proxy API requests to a backend running on a different port, WebSocket connections require explicit opt-in.

## WebSocket proxy for the observable query hub

[Section titled “WebSocket proxy for the observable query hub”](#websocket-proxy-for-the-observable-query-hub)

Vite’s proxy is built on [http-proxy](https://github.com/http-party/node-http-proxy). By default it only proxies regular HTTP requests. To also forward the WebSocket upgrade handshake that the [observable query hub](/arc/frontend/react/queries/observable-query-multiplexing/) requires, you must set `ws: true` on every proxy rule whose target serves WebSocket connections.

The hub endpoint is `/.cratis/queries/ws`. Without `ws: true` on the `/.cratis` proxy rule, the browser issues a WebSocket upgrade to the Vite dev server, but Vite returns a plain HTTP response and the connection fails. Observable queries silently receive no data and repeatedly attempt to reconnect.

### Correct configuration

[Section titled “Correct configuration”](#correct-configuration)

vite.config.ts

```ts
export default defineConfig({
    server: {
        proxy: {
            '/.cratis': {
                target: 'http://localhost:5001',
                ws: true,                          // required for WebSocket upgrade
            },
        },
    },
});
```

Compare with a common incorrect configuration that handles only HTTP:

```ts
// ❌ Missing ws: true — WebSocket connections fail silently
'/.cratis': {
    target: 'http://localhost:5001',
},
```

### Why it is easy to miss

[Section titled “Why it is easy to miss”](#why-it-is-easy-to-miss)

Most proxy rules are added to forward `fetch` and `XHR` traffic. Those work without `ws: true` because they are ordinary HTTP requests. Observable queries are the only part of Arc that upgrade to a WebSocket, so the missing flag goes unnoticed until you observe that live data is never delivered to the frontend.

Vite docs: [Server options — proxy](https://vite.dev/config/server-options.html#server-proxy).

### Checking a full proxy block

[Section titled “Checking a full proxy block”](#checking-a-full-proxy-block)

A typical Vite setup that exposes both the REST API and the observable query hub looks like this:

```ts
server: {
    proxy: {
        '/api': {
            target: 'http://localhost:5001',
            ws: true,        // required if any /api route also uses WebSocket
        },
        '/.cratis': {
            target: 'http://localhost:5001',
            ws: true,        // required for /.cratis/queries/ws
        },
    },
},
```

Neither rule needs `changeOrigin: true` when the backend is on the same machine.

# MVVM with React

For most screens, the [React hooks](/arc/frontend/react/) keep state in the component and that’s exactly right. But as a screen’s logic grows — orchestrating several commands, deriving display state, reacting to navigation — that logic starts to crowd the markup. The **Model-View-ViewModel** approach moves it into a dedicated view model class: the component renders, the view model decides. The result is logic you can test and reuse independently of the JSX.

Reach for MVVM when a screen has substantial behavior; stay with plain hooks when it doesn’t.

| Topic                                                           | What it covers                                              |
| --------------------------------------------------------------- | ----------------------------------------------------------- |
| [Using a view model](/arc/frontend/reactmvvm/using-view-model/) | Bind a component to a view model and drive it from there.   |
| [MVVM context](/arc/frontend/reactmvvm/mvvm-context/)           | How the MVVM context is established and resolved.           |
| [TSyringe](/arc/frontend/reactmvvm/tsyringe/)                   | Dependency injection for view models with TSyringe.         |
| [Browser](/arc/frontend/reactmvvm/browser/)                     | Working with browser APIs and navigation from a view model. |
| [Dialogs](/arc/frontend/reactmvvm/dialogs/)                     | Driving dialogs from a view model.                          |
| [Identity](/arc/frontend/reactmvvm/identity/)                   | Accessing identity and user context in MVVM.                |
| [Messaging](/arc/frontend/reactmvvm/messaging/)                 | Messaging and communication patterns in MVVM.               |

New to the frontend? Start with the [React hooks](/arc/frontend/react/) first — MVVM is the next step up, not the starting point.

# Browser

When working with view models in the MVVM pattern, you typically want to avoid direct dependencies on browser globals like `window`, `document`, or `localStorage`. This makes your code more testable and maintainable. Cratis Arc provides abstracted interfaces for common browser functionality that can be injected into your view models.

## Available Interfaces

[Section titled “Available Interfaces”](#available-interfaces)

### INavigation

[Section titled “INavigation”](#inavigation)

The `INavigation` interface provides a way to observe URL changes in your application without directly accessing the browser’s navigation APIs.

```typescript
export type UrlChangedCallback = (url: string, previousUrl: string) => void;

export abstract class INavigation {
    abstract onUrlChanged(callback: UrlChangedCallback): void;
}
```

#### Usage in a View Model

[Section titled “Usage in a View Model”](#usage-in-a-view-model)

```typescript
import { injectable, inject } from 'tsyringe';
import { INavigation } from '@cratis/arc.react.mvvm/browser';

@injectable()
export class MyViewModel {
    constructor(@inject(INavigation) private readonly _navigation: INavigation) {
        this._navigation.onUrlChanged((url, previousUrl) => {
            console.log(`Navigated from ${previousUrl} to ${url}`);
            // Handle navigation change
        });
    }
}
```

The `Navigation` implementation uses a `MutationObserver` to detect URL changes in the DOM, making it compatible with client-side routing libraries like React Router.

### ILocalStorage

[Section titled “ILocalStorage”](#ilocalstorage)

The `ILocalStorage` interface provides access to browser local storage following the standard `Storage` interface:

```typescript
export abstract class ILocalStorage implements Storage {
    abstract length: number;
    abstract clear(): void;
    abstract getItem(key: string): string | null;
    abstract key(index: number): string | null;
    abstract removeItem(key: string): void;
    abstract setItem(key: string, value: string): void;
}
```

#### Usage in a View Model

[Section titled “Usage in a View Model”](#usage-in-a-view-model-1)

```typescript
import { injectable, inject } from 'tsyringe';
import { ILocalStorage } from '@cratis/arc.react.mvvm/browser';

@injectable()
export class PreferencesViewModel {
    constructor(@inject(ILocalStorage) private readonly _localStorage: ILocalStorage) {
    }

savePreference(key: string, value: string): void {
        this._localStorage.setItem(key, value);
    }

loadPreference(key: string): string | null {
        return this._localStorage.getItem(key);
    }

clearAllPreferences(): void {
        this._localStorage.clear();
    }
}
```

## Dependency Injection Setup

[Section titled “Dependency Injection Setup”](#dependency-injection-setup)

These browser interfaces are automatically registered when you initialize the MVVM bindings. The registration happens in the `Bindings.initialize()` method:

* `INavigation` is registered as a singleton with the `Navigation` implementation
* `ILocalStorage` is registered as an instance pointing to the browser’s native `localStorage`

You don’t need to manually register these - they’re available as soon as you set up your MVVM context.

## Benefits

[Section titled “Benefits”](#benefits)

Using these abstracted interfaces provides several advantages:

1. **Testability**: You can easily mock these interfaces in your unit tests
2. **Decoupling**: Your view models don’t directly depend on browser globals
3. **Consistency**: All browser interactions go through well-defined interfaces
4. **Type Safety**: Full TypeScript support with proper typing

## Example: Complete View Model

[Section titled “Example: Complete View Model”](#example-complete-view-model)

Here’s a complete example showing both interfaces in use:

```typescript
import { injectable, inject } from 'tsyringe';
import { INavigation, ILocalStorage } from '@cratis/arc.react.mvvm/browser';
import { makeObservable, observable } from 'mobx';

@injectable()
export class NavigationHistoryViewModel {
    @observable currentUrl: string = '';
    @observable visitedUrls: string[] = [];

constructor(
        @inject(INavigation) private readonly _navigation: INavigation,
        @inject(ILocalStorage) private readonly _localStorage: ILocalStorage
    ) {
        makeObservable(this);

// Load previously visited URLs from storage
        const stored = this._localStorage.getItem('visitedUrls');
        if (stored) {
            this.visitedUrls = JSON.parse(stored);
        }

// Track URL changes
        this._navigation.onUrlChanged((url, previousUrl) => {
            this.currentUrl = url;
            this.visitedUrls.push(url);
            this._localStorage.setItem('visitedUrls', JSON.stringify(this.visitedUrls));
        });
    }

clearHistory(): void {
        this.visitedUrls = [];
        this._localStorage.removeItem('visitedUrls');
    }
}
```

# Dialogs

Working with dialogs is different when decoupling your code as you do with the MVVM paradigm. Even though the view models are not responsible for rendering and should be blissfully unaware of how things gets rendered, you do need at times to interact with the user.

Cratis Arc supports an approach to working with dialogs and still maintain the clear separation of concerns. It promotes the idea of letting the view and React as a rendering library do just that and then bridges everything through a service called `IDialogs` and the use of specific hooks to glue it together, making it feel natural for you as a React developer whilst having a clear separation and making your view model logic clear and concise.

The beauty of this is that you can quite easily also write automated unit tests that test for the scenarios, involving dialogs.

## Confirmation Dialogs

[Section titled “Confirmation Dialogs”](#confirmation-dialogs)

There is an enum called `DialogButtons` that has the following options:

For standard confirmation dialogs, there is a specific expected result called `DialogResult` that the dialog needs to communicate back. The values are:

* Yes
* No
* Ok
* Cancel

To use a confirmation dialog from a ViewModel, you need to take a dependency to the `IDialogs`, assuming you have hooked up [TSyringe and bindings](/arc/frontend/reactmvvm/tsyringe/). Then in a method, you can call the `showConfirmation()` on the `IDialogs` to show the confirmation.

Below is a full sample of how this works.

```ts
import { injectable } from 'tsyringe';
import { DialogResult } from '@cratis/arc.react/dialogs';
import { DialogButtons } from '@cratis/arc.react/dialogs';
import { IDialogs } from '@cratis/arc.react.mvvm/dialogs';

@injectable()
export class YourViewModel {
    constructor(
        private readonly _dialogs: IDialogs) {
    }

// Method called from typically your view
    async deleteTheThing() {
        const result = await this._dialogs.showConfirmation('Delete?', 'Are you sure you want to delete?', DialogButtons.YesNo);
        if( result == DialogResult.Yes ) {
            // Do something - typically call your server
        }
    }
}
```

In order for the dialogs to show, you need to configure the component that represent it. You can read more about [configuring dialogs](/arc/frontend/react/dialogs/).

## Busy indicator dialogs

[Section titled “Busy indicator dialogs”](#busy-indicator-dialogs)

To use a busy indicator dialog from a ViewModel, you need to take a dependency to the `IDialogs`, assuming you have hooked up [TSyringe and bindings](/arc/frontend/reactmvvm/tsyringe/). Then in a method, you can call the `showBusyIndicator()` on the `IDialogs` to show the confirmation.

Below is a full sample of how this works.

@injectable()
export class YourViewModel {
    constructor(
        private readonly _dialogs: IDialogs) {
    }

// Method called from typically your view
    async performLongRunningOperation() {
        const busyIndicator = this._dialogs.showBusyIndicator('Performing something that will take a while', 'Please wait');
        setTimeout(() => {
            busyIndicator.close();
        }, 1000);
    }
}
```

The `showBusyIndicator()` returns an object that has a method called `close()`. This method is then something you use to close the dialog.

In order for the dialogs to show, you need to configure the component that represent it. You can read more about that [configuring dialogs](/arc/frontend/react/dialogs/)

## Custom dialogs

[Section titled “Custom dialogs”](#custom-dialogs)

The anatomy of dialogs in general is based on a **request** and **response** pattern. You request a dialog through the `IDialogs` service by giving it an instance of a type of a message that the view knows how to resolve into a dialog. This mechanism is in use on the confirmation dialogs and is the same for a custom dialog.

For the dialog to know the context in which it is rendering, there is a hook called `useDialogContext()`. In the view where the dialog is used, you define the context implicitly by using the `useDialog()`. This establishes the **subscriber** that responds to a request from your view model of showing a dialog.

Subscriptions are based on type and it must be a well known type at runtime, so typically in TypeScript you’d define the request as a class as `interface` and `type` is optimized away by the TypeScript transpiler and are not present at runtime.

The following code creates a custom dialog component.

```tsx
import { Button } from 'primereact/button';
import { Dialog } from 'primereact/dialog';
import { useDialogContext } from '@cratis/arc.react/dialogs';

export class CustomDialogRequest {
    constructor(readonly content: string) {
    }
}

export const CustomDialog = () => {
    const { request, closeDialog } = useDialogContext<CustomDialogRequest, string>();

Notice that the code creates a `CustomDialogRequest` class, it is defined as an immutable class with a constructor that holds the properties as `readonly`. The purpose of the the request object is to provide information that can be passed along from a view model to the dialog. This could for instance be data is needed to be displayed in the dialog or similar. You don’t need to have any properties on it, the type as a class is however required.

Within the dialog component, you use the `useDialogContext()` and pass it the request type and the expected response type. The hook returns an object called `IDialogContext`, this holds the request and a delegate type that can be called to close the dialog. Both properties are type-safe based on the generic parameters passed to the hook.

With the custom dialog defined, we can start using it.

Below is an example of a view that leverages the dialog and has a view model behind that actually shows it.

```tsx
import { withViewModel } from '@cratis/arc.react.mvvm';
import { FeatureViewModel } from './FeatureViewModel';
import { useDialog } from '@cratis/arc.react.mvvm/dialogs';
import { CustomDialog, CustomDialogRequest } from './CustomDialog';

export const Feature = withViewModel<FeatureViewModel>(FeatureViewModel, ({ viewModel }) => {

// Use the dialog request to get a wrapper for rendering our dialog
    const [CustomDialogWrapper] = useDialog<CustomDialogRequest, string>(CustomDialogRequest, CustomDialog);

return (
        <div>
            {/* Use the dialog wrapper here. It will automatically include the actual dialog and show your dialog.
            If using a component that represents the dialog and it has a property for visibility, just set it to true.
             */}
            <CustomDialogWrapper/>
        </div>
    );
});
```

The code leverages the `useDialog()` with the generic parameters corresponding to the request and response types, as you saw when defining the `CustomDialog` component. It returns a **tuple** that holds a wrapper as a React functional component, then the context which holds the request when a request is made and a function to close the dialog. This allows for inlining dialogs or passing the information on to things that need it. For this scenario, we don’t need them and therefore only capture the wrapper.

> Note: See the sample later on how to create dialogs with a view model for an example of context and `closeDialog` use.

With the wrapper, the code wraps the actual `CustomDialog` component as part of the rendering of the component. This ensures that it will only be displayed when it is supposed to.

The last piece of the puzzle is now to use it from the view model. Following is a sample that shows the usage.

```ts
import { injectable } from 'tsyringe';
import { DialogButtons } from '@cratis/arc.react/dialogs';
import { IDialogs } from '@cratis/arc.react.mvvm/dialogs';
import { CustomDialogRequest } from './CustomDialogRequest;

@injectable()
export class FeatureViewModel {
    constructor(
        private readonly _dialogs: IDialogs) {
    }

async doThings() {
        // Show the custom dialog
        const result = await this._dialogs.show<CustomDialogRequest, string>(new CustomDialogRequest('This is the content to show'));
        if( result == 'Done done done...') {
            // Do something
        }
    }
}
```

The view model takes a dependency to `IDialogs` which is resolved by the IoC, assuming you have hooked up [TSyringe and bindings](/arc/frontend/reactmvvm/tsyringe/).

In the `doThings()` method we show the dialog by calling `.show()` on the `IDialogs` service, giving it an instance of the `CustomDialogRequest`. With the generic arguments; `CustomDialogRequest` and `string` we are sure to get type-safety for the response. If you don’t provide any of the generic arguments, the return type will become `unknown`.

The `.show()` method is an async, `Promise` based method that will return when the dialog is resolved. The return from the `.show()` method will then be the response type, in this case; **a string**.

### Dialog with a view model

[Section titled “Dialog with a view model”](#dialog-with-a-view-model)

You might want to use a view model for the dialog itself. That is fully possible and recommended for scenarios where there will be logic and / or you want to be able to test the dialog logic code.

Your dialog view would then look like below:

```tsx
import { Button } from 'primereact/button';
import { Dialog } from 'primereact/dialog';
import { useDialogContext, CloseDialog } from '@cratis/arc.react/dialogs';
import { withViewModel } from '@cratis/arc.react.mvvm';
import { CustomDialogViewModel } from './CustomDialogViewModel';

export class CustomDialogRequest {
    constructor(readonly content: string) {
    }
}

// Use the withViewModel() to pull in and specify props
export const CustomDialog = withViewModel<CustomDialogViewModel>({ viewModel }) => {
    return (
        <Dialog header="My custom dialog" visible={true} onHide={() => viewModel.cancel() }>
            <h2>Dialog</h2>
            {request.content}
            <br />
            <Button onClick={() => viewModel.done() }>We're done</Button>
        </Dialog>
    );
};
```

The above code is not different for the component except that it uses the `withViewModel()` which points it to the view model type.

Your view model can then be something like the following:

```ts
import { inject, injectable } from 'tsyringe';
import { DialogContextContent, DialogResult } from '@cratis/arc.react/dialogs';

@injectable()
export class CustomDialogViewModel {

constructor(private readonly _dialogContext: DialogContextContent) {
    }

name: string = '';

done() {
        this._dialogContext.closeDialog(DialogResult.Ok, 'Done done done...');
    }

cancel() {
        this._dialogContext.closeDialog(DialogResult.Cancelled, 'Did not do it..');
    }
}
```

The **view model** now takes the `DialogContextContent` as a dependency. This will be the correct context for the current dialog and contains the `closeDialog` function that can be called for closing the dialog in addition to the request instance.

Using the dialog is exactly the same as before.

# Identity

The MVVM implementation of identity is built on top of what you find the [core](/arc/frontend/core/identity/). To access identity in an MVVM solution with a view model, the `IdentityProvider` is hooked up to the [container](/arc/frontend/reactmvvm/tsyringe/) through its interface `IIdentityProvider`.

> Note: This depends on the [MVVM Context](/arc/frontend/reactmvvm/mvvm-context/) being used.

```typescript
import { injectable } from 'tsyringe';
import { IIdentityProvider } from '@cratis/arc/identity';

type IdentityDetails = {
    department: string,
    age: number
};

@injectable()
export class MyViewModel {
    constructor(private readonly _identityProvider: IIdentityProvider) {
    }

async sayHello() {
        const identity = await this._identityProvider.getCurrent<IdentityDetails>();
        console.log(`Hello '${identity.name}' from ´${identity.details.department}`);
    }
}
```

The code takes a dependency to the abstract class called `IIdentityProvider` representing the interface for the identity provider. With this the code simply calls the `getCurrent()` method to get the identity.

# Messaging

At times you want to allow multiple features on a page to know about changes that happens in one component. A common scenario is a list + detail scenario where you typically have a list and when you click an item you get the details of it somewhere else on the page.

With React you would typically create a context and wrap the components needing the same information in a React context. The problem with this is that you are having to create these different contexts, which creates a set of boiler plate code that has little value and you need to put it into the correct place in the rendering hierarchy. This creates a logical coupling in your application and is error prone when changing structure.

With the MVVM model this doesn’t really work either, as the contexts aren’t available to the view model. Instead, we can leverage a publish/subscribe mechanism where components through their view model can publish messages that can be subscribed to by other parts of your system that lives on the page.

This creates for a more decoupled approach and making your code and structure easier to change.

## IMessenger

[Section titled “IMessenger”](#imessenger)

In Cratis Arc the system that deals with this is called `IMessenger`. It has a method called `publish()` for publishing messages, and one for subscribing called `subscribe()`. Both of these methods work on types and require a runtime type like a `class` to be the message type. The implementation is provided by Arc core (`@cratis/arc/messaging`) and wired into MVVM bindings.

Below is an example of the view models for two components, one listing items and the other holding details.

The first thing we want is a message saying user is selected (assuming a type of `User`):

```ts
export class UserSelected {
    constructor(readonly user: User) {
    }
}
```

Then for the list component we would typically have something like the following:

```ts
import { IMessenger } from '@cratis/arc.react.mvvm/messaging';

@injectable()
export class UsersListViewModel {

// Take the IMessenger as a dependency
    constructor(private readonly _messenger: IMessenger) {
    }

selectUser(user: User) {
        // Publish the message saying the user was selected
        this._messenger.publish(new UserSelected(user));
    }
}
```

Whenever a selection is done, the view would call the `selectUser()` method, which would then publish the message.

For the details component, the view model would then need to subscribe to this:

```ts
import { IMessenger } from '@cratis/arc.react.mvvm/messaging';

@injectable()
export class UserDetailsViewModel {

// Take the IMessenger as a dependency
    constructor(messenger: IMessenger) {
        messenger.subscribe(UserSelected, (user) => this.user = user)
    }

// State that would be used in the view
    user?: User;
}
```

With this, the details view model will subscribe to the `UserSelected` message and set the state of the view model accordingly.

## Scoped messaging

[Section titled “Scoped messaging”](#scoped-messaging)

When using Arc React, the root `<Arc />` provides a root messenger. You can add nested scopes with `MessengerScope` from `@cratis/arc.react/messaging`. View models resolved with `withViewModel()` receive the nearest scoped messenger automatically, and fall back to the root messenger.

By default:

* Messages do not bubble to parent scopes.
* Messages from parent scopes trickle down to child scopes recursively.

Override behavior through:

* `bubbleToParent`
* `trickleDownToChildren`

# MVVM Context

The MVVM solution in Cratis Arc is based on top of [mobx](https://mobx.js.org). In addition to being based on top of it, everything internal is expecting a certain behavior that needs to be configured for mobx for everything to work.

This is were the `MVVM` context comes into play. The Arc exposes a component that configures mobx and also ensures the necessary bindings for [tsyringe](/arc/frontend/reactmvvm/tsyringe/) are configured.

All you need to do is include it in your application setup:

```tsx
import { MVVM } from '@cratis/arc.react.mvvm';

export const App = () => {
    return (
        <MVVM>
            {/* Your application */}
        </MVVM>
    );
};
```

# Tsyringe

Cratis Arc relies on [Microsoft Tsyringe](https://github.com/microsoft/tsyringe) a lightweight IoC container for TypeScript.

In order to use Tsyringe, your application needs to produce type metadata that it can use to resolve dependencies. Tsyringe leverages decorators to bee able to do this, you will have to include this in your TypeScript configuration. In your `tsconfig.json` make sure to enable the following compiler options:

```json
{
    "compilerOptions": {
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true,
    }
}
```

In addition to this, Tsyringe needs the `Reflect` metadata API to be available at runtime. Cratis Arc ships a lightweight polyfill for this (provided by `@cratis/fundamentals`) and loads it automatically when you import `@cratis/arc`, so there is nothing extra to install or set up.

```tsx
import { App } from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
        <App />
    </React.StrictMode>
);
```

This enables the necessary reflection metadata for Tsyringe to work properly.

## Vite

[Section titled “Vite”](#vite)

If you’re using Vite you will find that things are not working as expected. This is because Vite during development with the dev server will not provide the necessary metadata. Cratis Arc offers a vite plugin for emitting the necessary metadata.

Add a dev package reference to `@cratis/arc.vite`. Then in your `vite.config` you can add it to plugins:

```js
import { defineConfig } from 'vite';
import { EmitMetadataPlugin } from '@cratis/arc.vite';

export default defineConfig({
    plugins: [
        EmitMetadataPlugin() as any
    ]
});
```

## Bindings

[Section titled “Bindings”](#bindings)

In the Rect MVVM package you’ll find services that will help you as a developer work with MVVM, these are typically services you would take a dependency to in your view models. Within the package sits a type called `Bindings`, you can call this to get everything initialized:

> Note: If you’re using the [MVVM context](/arc/frontend/reactmvvm/mvvm-context/) all bindings are automatically configured for the MVVM scenario and you are good to go and you can skip this step.

```ts
import { Bindings } from '@cratis/arc.react.mvvm';

Bindings.initialize();
```

# Using a View Model

Every React functional component can have a view model. This is accomplished using the `withViewModel()` method.

```tsx
import { withViewModel } from '@cratis/arc.react.mvvm';

export const Counter = withViewModel(CounterViewModel, ({viewModel}) => {
    return (
        <>
            Counter is : {viewModel.counter}
            <button onClick={() => viewModel.increaseCounter()}>Increase counter</button>
        </>
    )
});
```

The component uses the `withViewModel` and passes the type `CounterViewModel` to be created for the view. As arguments you can then have the `viewModel`, this instance survives re-renders and can be stateful.

```ts
export class CounterViewModel {
    counter: number;

increaseCounter() {
        this.counter++;
    }
}
```

The `viewModel` is automatically observable, which means that all properties on it will notify the view if there are any changes to them. This means that the `increaseCounter()` method can just go ahead and increase the counter and the view will automatically re-render.

## Observer boundaries

[Section titled “Observer boundaries”](#observer-boundaries)

`withViewModel()` observes the render of the component it wraps — and only that render. The view model is built on [mobx](https://mobx.js.org) (see [MVVM context](/arc/frontend/reactmvvm/mvvm-context/)), so MobX tracks which observable view model properties a render reads and re-renders that component when they change.

This has an important consequence: a **child** component that reads observable view model state *directly* sits outside the parent’s observer boundary. MobX never tracks that read, so the child does not re-render when the state changes — even though the value on screen is stale.

```tsx
import { withViewModel } from '@cratis/arc.react.mvvm';

// The child reads `viewModel.counter` directly — but it has no observer boundary of its own,
// so it will NOT re-render when the counter changes.
const CounterValue = ({ viewModel }: { viewModel: CounterViewModel }) => (
    <span>Counter is : {viewModel.counter}</span>
);

export const Counter = withViewModel(CounterViewModel, ({ viewModel }) => {
    return (
        <>
            <CounterValue viewModel={viewModel} />
            <button onClick={() => viewModel.increaseCounter()}>Increase counter</button>
        </>
    );
});
```

### Prefer passing plain props down

[Section titled “Prefer passing plain props down”](#prefer-passing-plain-props-down)

The cleanest fix is to keep observable reads inside the wrapped component and pass plain values down to presentational children. The parent is already observed, so reading `viewModel.counter` there is tracked, and the child re-renders because its `value` prop changed like any other React prop:

```tsx
import { withViewModel } from '@cratis/arc.react.mvvm';

// Presentational child — receives a plain value, knows nothing about the view model.
const CounterValue = ({ value }: { value: number }) => (
    <span>Counter is : {value}</span>
);

export const Counter = withViewModel(CounterViewModel, ({ viewModel }) => {
    return (
        <>
            <CounterValue value={viewModel.counter} />
            <button onClick={() => viewModel.increaseCounter()}>Increase counter</button>
        </>
    );
});
```

This keeps reactivity entirely within the wrapped component and leaves children as simple, predictable functions of their props.

### Wrap a leaf that must read view model state directly

[Section titled “Wrap a leaf that must read view model state directly”](#wrap-a-leaf-that-must-read-view-model-state-directly)

When a child genuinely needs to read observable view model state directly — for example a list that filters a large collection the view model owns — give just that leaf its own observer boundary with `observer()`. Import it from `@cratis/arc.react.mvvm`:

```tsx
import { observer, withViewModel } from '@cratis/arc.react.mvvm';

// The leaf reads observable state directly and is wrapped in `observer()`, so it has its
// own boundary and re-renders when `filteredPartners` changes.
const PartnerResults = observer(({ viewModel }: { viewModel: PartnerSearchViewModel }) => (
    <ul>
        {viewModel.filteredPartners.map(partner => <li key={partner.id}>{partner.name}</li>)}
    </ul>
));

export const PartnerSearch = withViewModel(PartnerSearchViewModel, ({ viewModel }) => {
    return (
        <>
            <input
                value={viewModel.partnerSearch}
                onChange={event => viewModel.setPartnerSearch(event.target.value)} />
            <PartnerResults viewModel={viewModel} />
        </>
    );
});
```

> Note: Always import `observer` from `@cratis/arc.react.mvvm`, never directly from `mobx-react` or `mobx-react-lite`. Going through Cratis Arc keeps the MobX binding an internal detail that can evolve without breaking your code, and the [Cratis Arc ESLint plugin](https://github.com/Cratis/Arc/blob/main/Source/JavaScript/Arc.ESLint/README.md) flags direct imports for you.

Reach for `observer()` only on the specific leaf that reads observable state directly. Do not blanket-wrap every component — that adds render-tracking overhead everywhere and obscures which components actually depend on view model state. Prefer the plain-props pattern above, and drop down to a leaf `observer()` only when a child must read view model observables itself.

## Props

[Section titled “Props”](#props)

Components can have props associated with them. The `withViewModel` supports specifying props type and ability to take the props in as a parameter on the render function:

```tsx
import { withViewModel } from '@cratis/arc.react.mvvm';

export interface CounterProps {
    initialValue: number;
}

export const Counter = withViewModel<CounterViewModel, CounterProps>(CounterViewModel, ({viewModel, props}) => {
    return (
        <>
            Counter is : {viewModel.counter}
            <button onClick={() => viewModel.increaseCounter()}>Increase counter</button>
        </>
    )
});
```

The `withViewModel` has 2 generic arguments that can be passed:

* ViewModel type
* Props type

When you don’t have a props type, you don’t need to specify the `ViewModel` type arguments, as TypeScript will automatically infer its type from the first argument that specifies the type to use.

> Note: The reason we provide the type of view model to use as a parameter to the `withViewModel` and not just rely on the `ViewModel` type argument, is that we need a proper token / type to be used to be able to create an instance of it. Generic information is only available at compile-time in TypeScript and when transpiled to JavaScript this information is gone.

### Injecting Props as dependency

[Section titled “Injecting Props as dependency”](#injecting-props-as-dependency)

If you’re component only gets loaded once and the props typically don’t change without the component being unloaded and then loaded again, you can simply inject it as part of the constructor.

#### Using `@props` decorator (recommended)

[Section titled “Using @props decorator (recommended)”](#using-props-decorator-recommended)

The `@props` decorator wraps tsyringe’s `@inject` and also captures the parameter type:

```ts
import { props } from '@cratis/arc.react.mvvm';
import { injectable } from 'tsyringe';

@injectable()
export class MyViewModel {
    constructor(@props componentProps: Props) {
    }
}
```

#### Using `@inject` manually

[Section titled “Using @inject manually”](#using-inject-manually)

You can also use tsyringe’s `@inject` directly with `WellKnownBindings.props`:

```ts
import { WellKnownBindings } from '@cratis/arc.react.mvvm';
import { inject, injectable } from 'tsyringe';

@injectable()
export class MyViewModel {
    constructor(@inject(WellKnownBindings.props) props: Props) {
    }
}
```

### Handling Props

[Section titled “Handling Props”](#handling-props)

For the scenario were the props are changing by a consumer of your component, you need to implement the `IHandleProps<>`. It is a generic interface, but the generic argument is optional and is defaulted to `object` if not specified.

```ts
import { IHandleProps } from '@cratis/arc.react.mvvm';

export class MyViewModel implements IHandleProps<Props>  {
    handleProps(props: Props): void {
        // Do things based on props
    }
}
```

> Note: The `handleProps` method will be called both on initial load and for any subsequent changes.

## Params

[Section titled “Params”](#params)

Params defined as part of routes using `react-router` can easily be accessed by a view model in a couple of ways.

### Injecting Params as dependency

[Section titled “Injecting Params as dependency”](#injecting-params-as-dependency)

If you’re component only gets loaded once and the parameters can’t change without the component being unloaded and then loaded again, you can simply inject it as part of the constructor.

#### Using `@params` decorator (recommended)

[Section titled “Using @params decorator (recommended)”](#using-params-decorator-recommended)

The `@params` decorator wraps tsyringe’s `@inject` and also captures the parameter type. When a typed class is provided, `withViewModel` will use `JsonSerializer` to deserialize the string-based URL parameters into the correct types. Properties on the params class must be annotated with `@field` from `@cratis/fundamentals` so the serializer knows how to convert each value — for example a `number` property will be converted from the URL string `"42"` to the integer `42`. Without `@field`, the property values remain as strings:

```ts
import { field } from '@cratis/fundamentals';
import { params } from '@cratis/arc.react.mvvm';
import { injectable } from 'tsyringe';

class RouteParams {
    @field id!: string;
    @field count!: number;
}

@injectable()
export class MyViewModel {
    constructor(@params routeParams: RouteParams) {
        // routeParams.count is a proper number, not the URL string "42"
    }
}
```

#### Using `@inject` manually

[Section titled “Using @inject manually”](#using-inject-manually-1)

You can also use tsyringe’s `@inject` directly with `WellKnownBindings.params`. In this case the parameters are injected as raw strings as they appear in the URL:

```ts
import { WellKnownBindings } from '@cratis/arc.react.mvvm';
import { inject, injectable } from 'tsyringe';

@injectable()
export class MyViewModel {
    constructor(@inject(WellKnownBindings.params) params: Params) {
    }
}
```

The downside of this approach is that if a param changes and the component is not unloaded, you won’t get the change.

### Handling Params

[Section titled “Handling Params”](#handling-params)

For the scenario were the params are changing while the component is not unloaded, implementing the `IHandleParams<>` interface is a better option. It is a generic interface, but the generic argument is optional and is defaulted to `object` if not specified.

```ts
import { IHandleParams } from '@cratis/arc.react.mvvm';

export class MyViewModel implements IHandleParams<Params>  {
    handleParams(params: Params): void {
        // Do things based on params
    }
}
```

> Note: The `handleParams` method will be called both on initial load and for any subsequent changes.

## QueryParams

[Section titled “QueryParams”](#queryparams)

QueryParams defined as part of routes using `react-router` can easily be accessed by a view model in a couple of ways.

### Injecting Query Params as dependency

[Section titled “Injecting Query Params as dependency”](#injecting-query-params-as-dependency)

If you’re component only gets loaded once and the query parameters can’t change without the component being unloaded and then loaded again, you can simply inject it as part of the constructor.

#### Using `@queryParams` decorator (recommended)

[Section titled “Using @queryParams decorator (recommended)”](#using-queryparams-decorator-recommended)

The `@queryParams` decorator wraps tsyringe’s `@inject` and also captures the parameter type. When a typed class is provided, `withViewModel` will use `JsonSerializer` to deserialize the string-based URL query parameters into the correct types. Properties on the query params class must be annotated with `@field` from `@cratis/fundamentals` so the serializer knows how to convert each value — for example a `number` property will be converted from the URL string `"1"` to the integer `1`. Without `@field`, the property values remain as strings:

```ts
import { field } from '@cratis/fundamentals';
import { queryParams } from '@cratis/arc.react.mvvm';
import { injectable } from 'tsyringe';

class SearchParams {
    @field filter!: string;
    @field page!: number;
}

@injectable()
export class MyViewModel {
    constructor(@queryParams searchParams: SearchParams) {
        // searchParams.page is a proper number, not the URL string "1"
    }
}
```

#### Using `@inject` manually

[Section titled “Using @inject manually”](#using-inject-manually-2)

You can also use tsyringe’s `@inject` directly with `WellKnownBindings.queryParams`. In this case the parameters are injected as raw strings as they appear in the URL:

```ts
import { WellKnownBindings } from '@cratis/arc.react.mvvm';
import { inject, injectable } from 'tsyringe';

@injectable()
export class MyViewModel {
    constructor(@inject(WellKnownBindings.queryParams) queryParams: Params) {
    }
}
```

The downside of this approach is that if a query param changes and the component is not unloaded, you won’t get the change.

### Handling Query Params

[Section titled “Handling Query Params”](#handling-query-params)

For the scenario were the query params are changing while the component is not unloaded, implementing the `IHandleParams<>` interface is a better option. It is a generic interface, but the generic argument is optional and is defaulted to `object` if not specified.

```ts
import { IHandleQueryParams } from '@cratis/arc.react.mvvm';

export class MyViewModel implements IHandleQueryParams<Params>  {
    handleQueryParams(queryParams: QueryParams): void {
        // Do things based on query params
    }
}
```

> Note: The `handleQueryParams` method will be called both on initial load and for any subsequent changes.

## View Model lifecycle

[Section titled “View Model lifecycle”](#view-model-lifecycle)

### Detaches

[Section titled “Detaches”](#detaches)

You can get notified when a view model is detached from its view, typically as a consequence of the view being removed from the DOM. This is achieved by implementing the `IViewModelDetached` interface on your view model:

```ts
import { IViewModelDetached } from '@cratis/arc.react.mvvm';

export class MyViewModel implements IViewModelDetached {
    detached() {
        // Clean up...
    }
}
```

# General

| Topic                                                      | Description                                                                                                     |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [Generating Principal](/arc/general/generating-principal/) | How to work with principals in your local development environment for testing authentication and authorization. |

# Generating Microsoft Identity Principal for Local Development

When working with [Microsoft Identity Platform integration](/arc/backend/asp-net-core/microsoft-identity/) in your application, you’ll often need to test different user identities and claims during local development. Since local development environments typically don’t have Microsoft Azure’s identity provider configured, you need to simulate the Microsoft Client Principal tokens that would normally be provided by Azure services like Container Apps or Web Apps.

The [Microsoft Identity backend integration](/arc/backend/asp-net-core/microsoft-identity/) relies on specific HTTP headers that are automatically set by Azure services in production, but need to be manually configured during local development:

| Header                     | Description                                                                                                                                                                                                                                         |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| x-ms-client-principal      | The Microsoft Client Principal token holding all user details, base64 encoded according to [Microsoft Client Principal Data definition](https://learn.microsoft.com/en-us/azure/static-web-apps/user-information?tabs=csharp#client-principal-data) |
| x-ms-client-principal-id   | The unique identifier from the Microsoft identity provider (Azure AD/Entra ID) for the user                                                                                                                                                         |
| x-ms-client-principal-name | The display name of the user, typically resolved from claims within the Microsoft identity token                                                                                                                                                    |

Once these Microsoft Identity headers are properly set and the `x-ms-client-principal` token is in the expected format, the [Microsoft Identity authentication handler](/arc/backend/asp-net-core/microsoft-identity/) will process them and pass the identity information to your **identity details provider**.

The expected format needs to be according to the [Microsoft Client Principal Data definition](https://learn.microsoft.com/en-us/azure/static-web-apps/user-information?tabs=csharp#client-principal-data). To simulate Microsoft Identity users during local development, generate the correct token values and use a browser extension to set the HTTP request headers.

Here’s an example of a Microsoft Client Principal token structure for an Azure AD user:

```json
{
  "identityProvider": "aad",
  "userId": "e7f664ca-4ecc-45be-84cf-74b6240d049a",
  "userDetails": "jane.doe@contoso.com",
  "userRoles": ["anonymous", "authenticated"],
  "claims": [{
    "typ": "preferred_username",
    "val": "jane.doe@contoso.com"
  }, {
    "typ": "name",
    "val": "Jane Doe"
  }, {
    "typ": "given_name",
    "val": "Jane"
  }, {
    "typ": "family_name",
    "val": "Doe"
  }, {
    "typ": "oid",
    "val": "e7f664ca-4ecc-45be-84cf-74b6240d049a"
  }]
}
```

Basically what you then need to do is generate a Microsoft Client Principal token that matches the structure above and `Base64` encode it. If you’re using VSCode, you could use an [extension](https://marketplace.visualstudio.com/items?itemName=adamhartford.vscode-base64) for doing the base64 encoding. As an alternative, you could also use an online [base64 encoder](https://www.base64encode.org).

For the above Microsoft Identity structure that would become:

```text
ewogICJpZGVudGl0eVByb3ZpZGVyIjogImFhZCIsCiAgInVzZXJJZCI6ICJlN2Y2NjRjYS00ZWNjLTQ1YmUtODRjZi03NGI2MjQwZDA0OWEiLAogICJ1c2VyRGV0YWlscyI6ICJqYW5lLmRvZUBjb250b3NvLmNvbSIsCiAgInVzZXJSb2xlcyI6IFsiYW5vbnltb3VzIiwgImF1dGhlbnRpY2F0ZWQiXSwKICAiY2xhaW1zIjogW3sKICAgICJ0eXAiOiAicHJlZmVycmVkX3VzZXJuYW1lIiwKICAgICJ2YWwiOiAiamFuZS5kb2VAY29udG9zby5jb20iCiAgfSwgewogICAgInR5cCI6ICJuYW1lIiwKICAgICJ2YWwiOiAiSmFuZSBEb2UiCiAgfSwgewogICAgInR5cCI6ICJnaXZlbl9uYW1lIiwKICAgICJ2YWwiOiAiSmFuZSIKICB9LCB7CiAgICAidHlwIjogImZhbWlseV9uYW1lIiwKICAgICJ2YWwiOiAiRG9lIgogIH0sIHsKICAgICJ0eXAiOiAib2lkIiwKICAgICJ2YWwiOiAiZTdmNjY0Y2EtNGVjYy00NWJlLTg0Y2YtNzRiNjI0MGQwNDlhIgogIH1dCn0K
```

From the terminal on a Unix based operating system you could also generate a base64 encoded Microsoft Client Principal:

```shell
echo "{\"identityProvider\":\"aad\",\"userId\":\"e7f664ca-4ecc-45be-84cf-74b6240d049a\",\"userDetails\":\"jane.doe@contoso.com\"}" | base64
```

Which would generate:

```text
eyJpZGVudGl0eVByb3ZpZGVyIjoiYWFkIiwidXNlcklkIjoiZTdmNjY0Y2EtNGVjYy00NWJlLTg0Y2YtNzRiNjI0MGQwNDlhIiwidXNlckRldGFpbHMiOiJqYW5lLmRvZUBjb250b3NvLmNvbSJ9Cg==
```

## ModHeader for Microsoft Identity Testing

[Section titled “ModHeader for Microsoft Identity Testing”](#modheader-for-microsoft-identity-testing)

Once you have the Microsoft Client Principal token as **base64**, you can inject it as headers for testing your [Microsoft Identity integration](/arc/backend/asp-net-core/microsoft-identity/) locally.

In your browser you can use an extension such as [ModHeader](https://modheader.com). It allows you to setup headers that simulate the Azure-provided Microsoft Identity headers for local development. Use this to add the expected Microsoft Identity headers:

* The `x-ms-client-principal-id` should be the Azure AD object identifier (oid) or user ID from your identity provider
* The `x-ms-client-principal-name` should be the user’s display name or email address from Azure AD
* The `x-ms-client-principal` should contain your base64-encoded Microsoft Client Principal token

> Important: For the `x-ms-client-principal` you want to paste the **base64** generated value. Ensure the base64 string is properly formatted and valid.

![ModHeader configuration for Microsoft Identity](/_astro/configure-mod-header.gqMtjH-v_1WS9Wy.webp)

> Pro-tip: With ModHeader you can create profiles. This is super useful if you want to be testing with different Microsoft Identity users and easily switch between them during development.

## Integration with Microsoft Identity Backend

[Section titled “Integration with Microsoft Identity Backend”](#integration-with-microsoft-identity-backend)

Once you have these headers configured, your application’s [Microsoft Identity authentication handler](/arc/backend/asp-net-core/microsoft-identity/) will automatically process the Microsoft Client Principal token and populate the ASP.NET Core authentication context. This allows you to:

* Test authorization policies that depend on Azure AD claims
* Verify that your [identity details provider](/arc/backend/identity/) receives the correct user information
* Ensure your application behaves correctly with different Microsoft Identity user scenarios

The Microsoft Identity integration seamlessly handles the token validation and claim extraction, making your local development experience consistent with how the application behaves when deployed to Azure services.

# Generating a Screenplay

> How Arc reads the source of your application and writes the event model it already describes — what a .play file is, what it buys you, and exactly what it does and does not say.

An [event model](/event-modeling/) is the picture of your system: which commands change state, which events they produce, which read models those events build, and which reactors turn one thing into another. Teams draw it on a whiteboard at the start, and then the code moves on without it. Six months later the picture is fiction and nobody trusts it enough to open.

**Screenplay** is a small language for writing that picture down as text — a `.play` file — so it can live in the repository next to the code it describes. Arc can *generate* one from your application’s source. The model stops being something you maintain by hand and becomes something you regenerate, the same way the [TypeScript proxies](/arc/understanding-the-proxy-boundary/) are regenerated rather than hand-written.

## Generated from source, not from a running system

[Section titled “Generated from source, not from a running system”](#generated-from-source-not-from-a-running-system)

The generator reads a Roslyn compilation of your C# — the same thing the compiler sees. It never starts your application, connects to Chronicle, or looks at a deployed instance.

That choice is what makes the output useful:

* **It works from a checkout.** No database, no configuration, no environment. Clone and generate.
* **It is diffable in a pull request.** A commit that adds a command shows up as a few lines added to the `.play`. Reviewers see the model change next to the code change, and “did this alter the event model?” becomes a question the diff answers.
* **It is reproducible.** The same source always produces byte-identical output. Everything is ordered explicitly rather than by whatever order symbols happened to arrive in, so regenerating in CI and failing on a diff is a viable check.

A runtime-derived model would answer a different question — what one deployed instance looks like right now — and would vary with configuration and environment. There is one model, and its source of truth is your source code.

```
Roslyn compilation

anything it cannot express

C# source — commands, events,

read models, reactors

analysis

application model

.play document

diagnostics
```

## Running it

[Section titled “Running it”](#running-it)

The generator is used through the Cratis CLI, which ships separately from Arc:

```shell
cratis screenplay generate ./MyApp/MyApp.csproj --file MyApp.play
```

Point it at a project or a solution. A solution is one application rather than several, so its projects are read together into a single document — see [an application written as several projects](#an-application-written-as-several-projects). Anything the generator could not express is reported on the way out, and a run that reports an error exits non-zero — so a document nothing trustworthy went into never quietly looks fine. What the CLI has to do before it hands the source over is covered in [what the generator expects of its host](#what-the-generator-expects-of-its-host).

Because output is reproducible, a CI step can regenerate and fail when the committed `.play` no longer matches the source.

## Nothing is dropped silently

[Section titled “Nothing is dropped silently”](#nothing-is-dropped-silently)

The gap between “what C# can say” and “what Screenplay can say” is real, and the worst thing a generator can do is paper over it. Every construct that cannot be expressed is reported as a located diagnostic — a stable code, a message you can act on, and where it came from — rather than quietly disappearing.

```text
Warning SP0019: The query 'Raw' returns 'IActionResult', which says how the result is
transported rather than what it is, so the query was left out (Library.Messaging.Feed)
```

Diagnostics come in three severities. **Information** means something is worth knowing but the document is complete. **Warning** means something was left out. **Error** means the document should not be trusted at all — either because the generator produced something the language rejects, or because nothing at all was recovered from source the compiler accepted.

## What the generator expects of its host

[Section titled “What the generator expects of its host”](#what-the-generator-expects-of-its-host)

The compatibility generator accepts either a Roslyn `Compilation` or a Generation `DotNetProjectCompilation`. It never opens a project file or loads a workspace, which is what lets it be driven from a CLI, from a specification, or from an editor. `DotNetProjectCompilation` adds the host-owned project role, authored syntax trees, and stable source-path context needed by neutral source adapters; the established compilation-only overloads remain available and produce the same `.play` bytes. The other side of that bargain is that **assembling the compilation the way a real build would is the caller’s job** — the generator reads what it is handed and cannot tell a missing type from a type that was never written.

The part hosts get wrong is source generators. `MSBuildWorkspace.GetCompilationAsync()` does not run them, and neither does any loading mode that stops at the compile items the project file lists. An Arc application leans on generation heavily — `[LoggerMessage]` partial classes, strongly-typed resource designer classes, the proxy and metrics generators — so a compilation loaded that way is missing every type those emit, and every reference to one becomes an unresolved-symbol error. This is the common case rather than an edge case.

A host should run the project’s generators before handing the compilation over:

```csharp
var driver = CSharpGeneratorDriver.Create(
    generators: project.AnalyzerReferences
        .SelectMany(reference => reference.GetGenerators(LanguageNames.CSharp))
        .Select(GeneratorExtensions.AsSourceGenerator),
    parseOptions: (CSharpParseOptions)project.ParseOptions!);

driver.RunGeneratorsAndUpdateCompilation(compilation, out var generated, out _);
```

Then generate from `generated` rather than from `compilation`.

### What happens when it does not

[Section titled “What happens when it does not”](#what-happens-when-it-does-not)

Nothing is hidden, and nothing correct is thrown away. A compilation carrying errors is still analyzed, and `SP0024` says what happened — how many errors there were, the first of them, and how many artifacts came through anyway:

```text
Warning SP0024: The source did not compile - 607 error(s), the first being 'The name
'AccountsMessages' does not exist in the current context'. 341 artifact(s) were recovered
anyway, 341 of them from a declaration no error sits inside, so the document describes those
exactly as the source states them - a missing type named like 'SomethingMessages' or a
designer class usually means the compilation was handed over without the compile items a
build generates (Accounts)
```

Its **severity is decided rather than fixed**, because “the source did not compile” covers two outcomes that could not be further apart:

* **Warning** when at least one artifact was recovered from a declaration no compilation error sits inside. Those artifacts are described exactly as their source states them whatever failed elsewhere, so the run is successful and the document is worth keeping. A compilation missing its generated symbols lands here — the errors sit in code that declares no artifact, and the model is unaffected.
* **Error** when none were, either because nothing was recovered at all or because every declaration something came out of is one the compiler could not make sense of. There is then no part of the document a reader could trust, and a host following the contract exits non-zero.

A count is used rather than a proportion deliberately: any threshold would make the same recovery pass for a large application and fail for a small one, and zero is the only number that means recovery was *prevented* rather than merely dented.

Either way the document is written out, so what was recovered can be read.

### An application written as several projects

[Section titled “An application written as several projects”](#an-application-written-as-several-projects)

Nothing says an application is one project. A layered one puts its contracts in a project of their own; a host sitting beside the bounded contexts it serves is two projects at least — and no single one of them describes the application. Pointed at any one, the generator would describe half of it and refer to events it never introduced.

So `Generate` takes a list of compilations as well as a single one, and a host generating from a solution hands over one per project:

```csharp
var result = generator.Generate([contracts, application, host], options);
```

A host that also runs neutral adapters should retain the project metadata instead of reducing each project to its compilation:

```csharp
IReadOnlyList<DotNetProjectCompilation> projects = LoadProjects();
var result = generator.Generate(projects, options);
```

This project-aware compatibility overload intentionally delegates to the same established generator. The source context is carried for the neutral adapter path, not used to reinterpret legacy placement.

What comes back is one document rather than one per project, because the boundaries between projects are a build concern rather than something the model has:

* A namespace two projects declare into is **one slice**, whichever project each artifact sits in.
* A concept is **declared once**, however many projects refer to it.
* An event a sibling project declares is one the application **has**, so it is declared like anything else — not imported the way an event from a referenced package outside the application is.

Paths stay readable because they are written relative to the directory all the projects sit under rather than to each project’s own root, so every path opens with the project it belongs to — `Library/Shipping/Dispatching/Dispatching.cs` beside `Library.Contracts/Ordering/Placing/Placing.cs`. Projects checked out in unrelated places share no such directory; each one’s paths then fall back to its own root, and `SP0038` says so, because two files can then come out as the same path.

The order the projects arrive in never reaches the document. Nothing decides what order a host enumerates a solution in, so they are sorted by assembly name before anything is read and the same projects always print the same bytes. Where that order has to decide something it says so: two projects declaring the same artifact name into one slice keep the first and report `SP0037`.

## The generator checks its own output

[Section titled “The generator checks its own output”](#the-generator-checks-its-own-output)

Every diagnostic above names something about *your application* — a construct the language cannot hold, source that did not compile, projects that share no directory. There is one that names a defect in the generator instead.

After the document is written, the generator hands it straight back to the Screenplay compiler. If the compiler rejects it, `SP0034` is reported as an error — because a `.play` that does not compile is output nobody can use, and there is no way of writing an application that avoids it. This is not a mode you turn on: it runs on every generation, since the only way a rejected document is ever found is by reading each one back.

```text
Error SP0034: The generated document did not compile - 1 error(s), the first being
'Invalid description 'description RequestDescription' - expected 'description "<text>"''
on line 6. That is the generator being wrong rather than anything the source declared,
and the document is returned as it stands so the line can be read (Library)
```

The document is still written out, so you can open it at the reported line and see what happened. If you hit this, it is a bug worth [reporting](https://github.com/Cratis/Arc/issues) — include the line, and the C# declaration it came from.

Source that did not compile (`SP0024`) suppresses `SP0034` **when it is reported as an error** — a model recovered from symbols the compiler never accepted describes an application that does not exist, so a poor document made from it is a consequence of the broken build rather than a second, separate defect. Fix the build and generate again.

As a warning it suppresses nothing. That severity says the model stands, and a document built from a model that stands is exactly what the check exists for — suppressing it there would hand back a `.play` the language rejects with nothing wrong reported.

## A value is only ever what the source states

[Section titled “A value is only ever what the source states”](#a-value-is-only-ever-what-the-source-states)

Wherever the document states a value — the mapping a command’s `produces` writes into an event, the values a scenario is issued with, the message a validation rule fails with — it states what the source states and nothing beyond it. Two sources survive: a constant the compiler already holds, and a path into the command’s own input. Anything arrived at while the request runs is left out and reported, because a guessed value is worse than an absent one.

Messages are where that bites. An application speaking more than one language declares each message once in a resource and names it from the validator, and the property it names resolves its text against the caller’s culture — so there is no text for the compiler to hold, and no single text the document could honestly state.

The key is there to be read even though the text is not, and it is the better of the two to take: text would settle the document on one language the application itself never settled on. So the key is what is written, unresolved:

```text
command RequestBook
  title String
  validate
    title not empty message $strings.RequestMessages.TitleRequired
```

A key is qualified by the class declaring it, because a key is unique to its own resource and to nothing wider. Two areas of one application both requiring an organization number is ordinary rather than a mistake, and bare, those two would be one key that can carry only one text.

A message genuinely put together in code — `string.Format`, an interpolation — still has no text to write down, and is reported as `SP0016` rather than guessed at. So is a key the language has no way of writing: a reference is a path of bare words, and a resource key is under no such constraint.

## The scenarios a slice is specified by

[Section titled “The scenarios a slice is specified by”](#the-scenarios-a-slice-is-specified-by)

A `.play` says what a slice does. The Chronicle integration specs in the folder beneath it already say the same thing by example — what had happened, the command that was issued, what followed — which is exactly the shape of a Screenplay `specification`. So they are read too, and the document carries the examples proving the model rather than only the model:

```text
slice StateChange Registration

command RegisterAuthor
    name String
    produces AuthorRegistered
      name = name

event AuthorRegistered
    name String

specification WhenRegisteringAndTheNameIsTaken
    given AuthorRegistered
      name = "Jane Austen"
    given readmodel Author
      id = "author"
      name = "Jane Austen"
    when RegisterAuthor
      name = "Jane Austen"
    then error "unique-author-name"
```

* **`given`** is what the specification started from — the events it seeded, and the read model it pinned.
* **`when`** is the command it executed.
* **`then`** is each event it asserted was appended, and **`then error`** a rejection it asserted.

Both shapes Arc documents are read: the in-process one driving the pipeline through a scenario (`Scenario.Given…`, `Scenario.Execute`) and the one driving a running host (`EventLog.Append`, `Client.ExecuteCommand`). Which calls are which is decided by the type each one sits on, so neither testing package has to be referenced for either to be read.

A rejection the source asserts without naming a reason is written as bare `then error`. The source gives no code or presentation message, and inventing either would put meaning in the document the application never states.

Expect the document to grow. On a real application this roughly doubled it, at about seven lines per scenario.

### A scenario is read whole or not at all

[Section titled “A scenario is read whole or not at all”](#a-scenario-is-read-whole-or-not-at-all)

A mapping stands on its own, so one that cannot be read can be left out while the rest of its block still says something true. A scenario cannot: an example missing the state it started from, the command it issued, or the outcome it expected is not that example — it is a different one nobody wrote. So a step that cannot be read takes the whole scenario with it, and `SP0039` names the scenario and what made it unreadable.

Conditional steps are the common case. Anything written under an `if`, a `switch`, a loop, a ternary or a lambda happened in some runs of the specification and not in others, and the source text does not say which — so a step recovered as unconditional would state a world nobody specified. That is the one failure mode a reader has no way of catching, which is why it is reported rather than guessed at.

A step need not construct what it states where it is written. A specification routinely holds the event or the command in a member and names that member in the step — `Scenario.Given.ForEventSource(id).ReadModel(TargetUser)`, `Scenario.Execute(_command)` — because the same value is asserted on later, or because it is built where the values it needs already are. Such a member is followed **one hop**, to the single place it was put together, and the step reads exactly as the inline form does. A `= null!` or `= default` declaration is not one of those places: it exists to satisfy the compiler and states no value.

One hop, and only from one place. A member given a value twice, or given it under a condition, held different values in different runs and the source does not say which one the step saw — so it stays unread and the scenario is left out with `SP0039`, the same as any other conditional step. Following a chain would mean reasoning about what a value was at the moment the step ran, which is a different discipline from reading what was written.

Values are the exception for the compatibility document generator, because a value stands on its own the way a mapping does. They follow [the discipline every other value follows](#a-value-is-only-ever-what-the-source-states): the identity two steps agree on is routinely a fresh identifier held in a field rather than something written down, and such a value is reported on its own while the rest of the legacy scenario stands.

### Neutral specification facts are stricter

[Section titled “Neutral specification facts are stricter”](#neutral-specification-facts-are-stricter)

`ArcSpecificationFactAdapter` is the independently consumable source-evidence surface. It contributes Generation scenario, ordered-step, and typed-value facts only when every explicitly authored step and value is exact. One computed or unreadable required value, conditional/repeated step, unretained read-model assertion, or event predicate value blocks the whole neutral scenario with `ARCSP0001`; it never contributes a smaller example than the source wrote.

The adapter retains scenario-, step-, value-, and rejection-level source ranges separately from the existing Arc model. This does not change legacy model equality or the current `.play` generator’s compatibility output. It creates one fixed `DotNetSourceStructures` snapshot and asks `DotNetSourcePlacementDerivation` to place all exact targets together. Application and specification projects therefore use the application target’s source placement, read-model and query targets retain `StateView` placement, and folder/namespace disagreement or invalid source policy produces a typed `DOTNETSP####` diagnostic instead of a guessed placement. Generation attaches a scenario only through that exact target placement and lowers it only after complete atomic admission.

This distinction is deliberate: the compatibility generator keeps existing consumers stable, while the neutral adapter provides the fail-closed evidence required for render→recover semantic fidelity.

## Screens

[Section titled “Screens”](#screens)

A [vertical slice](/arc/vertical-slices/) puts the React component that realizes a slice’s screen in the same folder as its C#. Roslyn syntax trees carry real file paths, so the generator knows where each slice’s source lives and declares a `screen` for every `.tsx` component sitting next to it, named after the file:

```text
slice StateView Listing
  query AllAuthors => Author[]
  query AuthorById(id : String) => Author

screen AuthorList
    file Authors/Listing/AuthorList.tsx
    data Author[] via query AllAuthors
    data Author via query AuthorById by id
```

Two things about a screen are recovered, and both come from something that can be checked.

**The `file` reference** says which file realizes the screen. It is what a reader opens, and no directive replaces it, so it stays on the screen even when directives sit beside it.

**The `data` directives** say which of the slice’s queries the screen reads through. Arc generates a TypeScript proxy per query and a component imports that proxy by name, so the component’s `import` statements name candidates — and a candidate is kept only when it matches a query the slice really declares. Nothing about the binding comes from the component beyond that name: the read model, whether there is one or many of it, and the parameter it is keyed by all come from the C# query. An import naming anything else — a package, a command, a sibling component, a type-only import — leaves nothing behind.

Everything else in the declarative form — `title`, `section`, `table` and `summary` with their columns and fields, `action`, `navigate to`, `layout` — is **never inferred**. That is structure expressed in JSX and component properties, and a guessed column is worse than an absent one: it puts a confident falsehood into a document whose entire value is that it describes the real application. Every screen reports `SP0028` to say so. Write those directives by hand if you want them, and expect a regeneration to leave them out.

Two more rules keep the result honest:

* **Components only, no descending.** A file carrying a second extension — `AddAuthor.stories.tsx`, `AddAuthor.spec.tsx` — is a companion of a component, not a screen. A folder *inside* a slice folder is a slice of its own under the same convention, so its files belong to it.
* **Anything uncertain is reported.** The relationship between a file and a slice comes entirely from where the file sits, so `SP0025` is reported whenever sitting there says less than usual: a slice whose source is spread over several folders, one folder holding the source of several slices, or two files claiming a single screen name.

## What is not expressed

[Section titled “What is not expressed”](#what-is-not-expressed)

A `.play` is a description of an application, not a second copy of it. **It does not round-trip back to code**, and reading one will not tell you everything the code does. The losses run in both directions.

### Screenplay constructs the generator cannot infer

[Section titled “Screenplay constructs the generator cannot infer”](#screenplay-constructs-the-generator-cannot-infer)

These are part of the language, but nothing in C# says them, so a generated document never contains them. Add them by hand if you want them, and expect a regeneration to leave them out:

| Construct                                                                                                      | Why it cannot be inferred                                                                                                                               |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `capture`                                                                                                      | Describes ingesting an external system. Nothing in an Arc application declares one.                                                                     |
| `persona`                                                                                                      | Who uses the system is a product decision, not a code artifact.                                                                                         |
| `seed`                                                                                                         | Sample data is a modeling concern, not something the source states.                                                                                     |
| The declarative body of a `screen` — `title`, `section`, `table`, `summary`, `action`, `navigate to`, `layout` | What a screen *shows and does* is JSX. Its `file` reference and its `data` bindings are generated; the rest would be a guess — see [Screens](#screens). |
| `@sensitive`                                                                                                   | `@pii` is the one of the two concept attributes with a counterpart — `[PII]`. Nothing in Arc or Chronicle says `@sensitive`.                            |

### Detail Screenplay cannot represent

[Section titled “Detail Screenplay cannot represent”](#detail-screenplay-cannot-represent)

These exist in your application and do not reach the document, because the language has no counterpart. Each is reported as a diagnostic when encountered, so the document tells you it is silent about them.

| In Arc or Chronicle                                                                                   | Why it is not in the document                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Event generations, `[Tombstone]`, `[CompensationFor]`                                                 | Screenplay describes the current shape of an event. It has no notion of versioning, of a deletion marker, or of one event compensating another. `SP0014`.                                                                                                                                                                                                                                                                                           |
| Reducer folds (`IReducerFor<T>`)                                                                      | The fold is code. The read model and the events it observes are recovered; the logic that combines them is not. `SP0020`.                                                                                                                                                                                                                                                                                                                           |
| Aggregate roots no command reaches                                                                    | The events an aggregate root applies are stated through the command that hands its work to it. One that nothing calls has nothing to state them through — a document has no construct for a class that decides on its own. `SP0018`.                                                                                                                                                                                                                |
| A behavior deciding on the state an aggregate root holds                                              | A `produces when` condition compares the input of the command, which is all a document knows at the moment the command is issued. A behavior refusing to act on what it has already seen is a real decision with nowhere to go, so the event is stated unconditionally and `SP0027` reports the decision. A behavior deciding on one of its own *parameters* is recovered, because the call site says which command input that parameter was given. |
| Inline `policy` code and requirements built in code                                                   | `RequireAssertion(…)` and a policy registered from an `AuthorizationPolicy` built elsewhere are code. `RequireAuthenticatedUser`, `RequireRole`, and `RequireClaim` given the values it accepts are recovered; the rest is reported as `SP0026` — including a `RequireClaim` naming only a claim type, which a policy condition has no way to state.                                                                                                |
| The event source id from a `(TKey, TEvent)` handler                                                   | The event is recovered; the identifier saying *which* event source it goes to has no counterpart. `SP0013`.                                                                                                                                                                                                                                                                                                                                         |
| Emptying a scope with `[ClearWith]`; removing a child with `[RemovedWith]` on the property holding it | Nothing in the model a projection is built from carries a scope being emptied again, so `[ClearWith]` has nowhere to go (`SP0015`). A removal does have somewhere — but it is read from the type of the child, alongside the events filling that child in, so the same removal written beside the collection is reported as `SP0007` instead.                                                                                                       |
| Read model tags                                                                                       | A read model has no declaration of its own — it appears as the type a query returns — so there is nowhere to hang a tag. Tags on *events* are recovered and written out. `SP0042`.                                                                                                                                                                                                                                                                  |
| Query paging and sorting, custom routes                                                               | These say how a model is served rather than what it is. The parameters the host fills in are left out, and a route template — `[Path]`, `[Route]`, or a template on an HTTP verb — has no counterpart. `SP0041`.                                                                                                                                                                                                                                    |

If a generated `.play` is missing something you expected, the diagnostics are the first place to look — the omission is almost always reported.

## When this is the wrong fit

[Section titled “When this is the wrong fit”](#when-this-is-the-wrong-fit)

If you maintain a `.play` by hand as the *design* your code is written against — modeling first, then implementing — generation is the wrong direction and will overwrite your intent. Generation suits the opposite flow: code exists, and you want the model it already describes, kept honest automatically.

## Related

[Section titled “Related”](#related)

* [Vertical slices](/arc/vertical-slices/) — the folder shape the generator recovers slices from. A slice per namespace produces a far better document than artifacts sitting in the root namespace.
* [Understanding the proxy boundary](/arc/understanding-the-proxy-boundary/) — the other thing Arc generates from the same source of truth.

# Scenarios

> Short, task-oriented recipes for the things you'll actually do with Arc — each assumes you know the basics and gets straight to the goal.

These are recipes: “I need to do X — how?” Each one is short and assumes you’ve built a slice or two (the [tutorial](/arc/tutorial/) is the long way round). For the *why* and the full set of options, follow the links into the reference.

| Recipe                                                                           | When you reach for it                                                                      |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [Validate a command](/arc/scenarios/validate-a-command/)                         | Reject malformed or duplicate input before it writes state                                 |
| [Return a result or an error](/arc/scenarios/return-a-result-or-error/)          | A command needs to hand back more than “it worked” — a value, or a typed failure           |
| [Provide data to a command handler](/arc/scenarios/provide-data-to-a-command/)   | A decision needs data you must fetch — keep the fetch out of `Handle` so it stays testable |
| [Use current state in a command](/arc/scenarios/use-current-state-in-a-command/) | A decision depends on projected state — inject the read model instead of querying for it   |
| [Query data across slices](/arc/scenarios/query-related-data/)                   | A screen needs data that spans more than one feature                                       |
| [Execute a command from React](/arc/scenarios/run-a-command-from-react/)         | Wire a form or button to a command through the generated proxy                             |
| [Test a command](/arc/scenarios/test-a-command/)                                 | Prove a slice works through the real pipeline — no HTTP, no database                       |
| [Authorize a command or query](/arc/backend/authorizing-commands-and-queries/)   | Restrict who may run a command or read a query                                             |

Event-sourced Arc slices have their own Chronicle-specific recipes, starting with [React to an event](/arc/backend/chronicle/react-to-an-event/) and [Add event sourcing to an Arc slice](/arc/backend/chronicle/add-event-sourcing/).

Missing a recipe you expected? The [Backend](/arc/backend/) and [Frontend](/arc/frontend/) guides cover the long tail, and [Troubleshooting](/arc/troubleshooting/) catches the common snags.

# Provide data to a command handler

> Fetch the data a command's decision needs in a Provide method so Handle stays a pure, easily tested function of its arguments.

**Goal:** your command’s `Handle()` needs data it doesn’t carry — usually data from another service, such as a credit bureau, pricing service, inventory lookup, risk model, or tenant configuration — and you don’t want that IO tangled into the decision logic, where it’s hard to test.

## Lift the IO out of `Handle`

[Section titled “Lift the IO out of Handle”](#lift-the-io-out-of-handle)

Add a `Provide()` method next to `Handle()` on the command. `Provide` fetches or computes the data the decision needs, and its return value is passed into `Handle()` as an argument. `Handle` is left as a pure function of its arguments — given its inputs it returns events or results, with no IO to set up.

`Provide` runs before `Handle`, after validation and authorization pass. Its parameters are resolved from dependency injection just like `Handle`’s, and `this` is the command, so it can read the command’s own data.

```csharp
[Command]
public record ApproveLoan(LoanId LoanId, ApplicantId Applicant)
{
    public CreditScore Provide(ICreditBureau bureau) => bureau.GetScore(Applicant);

public LoanApproved Handle(CreditScore creditScore) => new(LoanId, creditScore);
}
```

## Why this matters: testability

[Section titled “Why this matters: testability”](#why-this-matters-testability)

Because the IO lives in `Provide`, testing the decision needs no mocking — construct the command and call `Handle` directly with the values it would have received:

```csharp
[Fact] void should_produce_the_event() =>
    new ApproveLoan(LoanId.New(), ApplicantId.New())
        .Handle(new CreditScore(800))
        .ShouldBeOfExactType<LoanApproved>();
```

`Provide` has a single job — acquire data — so it is easy to test in isolation too, with a stubbed `ICreditBureau`.

## Return more than one value

[Section titled “Return more than one value”](#return-more-than-one-value)

Return a tuple to feed several `Handle` parameters; each value is matched to a parameter by type:

```csharp
public (CreditScore, RiskBand) Provide(ICreditBureau bureau, IRiskModel risk) =>
    (bureau.GetScore(Applicant), risk.Band(Applicant));

public LoanApproved Handle(CreditScore score, RiskBand band) => new(LoanId, score, band);
```

`Provide` may be synchronous or `async` (`Task<T>` / `ValueTask<T>`).

## Use cancellation when the work can stop

[Section titled “Use cancellation when the work can stop”](#use-cancellation-when-the-work-can-stop)

`Provide` and `Handle` can both take a `CancellationToken`. Arc supplies the current command execution token. For HTTP command endpoints, that is the request-aborted token. For direct `ICommandPipeline` execution, pass the token to the pipeline call.

```csharp
[Command]
public record ApproveLoan(LoanId LoanId, ApplicantId Applicant)
{
    public Task<CreditScore> Provide(ICreditBureau bureau, CancellationToken cancellationToken) =>
        bureau.GetScore(Applicant, cancellationToken);

public Task<LoanApproved> Handle(CreditScore creditScore, CancellationToken cancellationToken) =>
        Task.FromResult(new LoanApproved(LoanId, creditScore));
}
```

Use the token for IO or long-running work. You do not register `CancellationToken` in the service container; Arc treats it as part of the command execution context.

## Short-circuit before `Handle` runs

[Section titled “Short-circuit before Handle runs”](#short-circuit-before-handle-runs)

`Provide` can stop the command before `Handle` is ever called:

| Return / do                                     | Result                                      |
| ----------------------------------------------- | ------------------------------------------- |
| `ValidationResult.Error("…")`                   | command fails validation (HTTP 400)         |
| an `AuthorizationResult` that is not authorized | command is unauthorized (HTTP 403)          |
| throw                                           | command fails with the exception (HTTP 500) |
| a value                                         | flows into `Handle` as an argument          |

Use `Result<,>` to reject or proceed when the data acquisition itself determines whether the command can continue — return the error to stop, or the value to continue:

```csharp
public Result<CreditScore, ValidationResult> Provide(ICreditBureau bureau)
{
    var score = bureau.GetScore(Applicant);
    return score is null
        ? ValidationResult.Error("No credit history", [nameof(Applicant)])
        : score;
}
```

A `Provide` value that no `Handle` parameter consumes is almost always a mistake, so the analyzer flags it (ARC0005).

For ordinary command validation, including read-model existence checks, prefer a `CommandValidator<>`. Use `Provide()` when `Handle()` needs acquired data as an input to the decision.

## Projected state is already available

[Section titled “Projected state is already available”](#projected-state-is-already-available)

One thing `Provide` doesn’t need to fetch: the read model for the command’s own key. Arc resolves that for you, so a `Provide` method can take it as a parameter alongside the services it uses — handy when the projected state is what determines *what* to fetch:

```csharp
public Task<ShippingQuote> Provide(OrderReadModel? order, IShippingRates rates) =>
    order is null
        ? Task.FromResult(ShippingQuote.None)
        : rates.Quote(order.Destination, order.TotalWeight);
```

See [Use current state in a command](/arc/scenarios/use-current-state-in-a-command/) for how that resolution works and what a nullable parameter means.

## Cross-cutting values

[Section titled “Cross-cutting values”](#cross-cutting-values)

`Provide` is per-command. For a value that many handlers need — the current tenant’s settings, say — register it as a scoped service and take it as a `Handle` parameter. Arc resolves any `Handle` or `Provide` parameter it can’t otherwise supply from the container.

## When not to use it

[Section titled “When not to use it”](#when-not-to-use-it)

If `Handle` already has everything it needs from the command and its injected services, you don’t need `Provide`. Reach for it specifically when a decision depends on data you must fetch — most often external or application-service data — where moving the fetch out buys you the testability.

## See also

[Section titled “See also”](#see-also)

* [Return a result or an error](/arc/scenarios/return-a-result-or-error/) — the shapes `Handle()` itself can return.
* [Test a command](/arc/scenarios/test-a-command/) — testing a slice through the real pipeline.
* [Validate a command](/arc/scenarios/validate-a-command/) — where `ValidationResult.Error` comes from.
* [Use current state in a command](/arc/scenarios/use-current-state-in-a-command/) — the read model Arc resolves for you, in all three positions.

# Query data across slices

> Serve a screen that needs data spanning more than one feature — by filtering live queries around a relationship.

**Goal:** a screen needs data that doesn’t live in a single slice — authors *with* their books, an order *with* its line items, anything where one thing owns a list of another.

## Keep the relationship explicit

[Section titled “Keep the relationship explicit”](#keep-the-relationship-explicit)

In a database-backed Arc slice, model the relationship the same way you would in the domain: the child carries the parent’s id, and the query filters by it. Arc’s part is making that query a typed, live endpoint and generating the React proxy that calls it.

## Do it

[Section titled “Do it”](#do-it)

**For an owns-a-list relationship, keep the child keyed to its parent.** A book belongs to an author, so the `Book` read model carries `AuthorId`:

```csharp
[ReadModel]
public record Book(BookId Id, AuthorId AuthorId, BookTitle Title)
{
    public static ISubject<IEnumerable<Book>> BooksForAuthor(AuthorId authorId, IMongoCollection<Book> books) =>
        books.Observe(book => book.AuthorId == authorId);
}
```

No attribute marks the identity — by convention the `Id` property is the read model’s identity. Arc sorts the query method’s parameters by type: `authorId` is data, so it becomes a query parameter; `IMongoCollection<Book>` is a service, so it’s injected. The generated proxy takes the data parameter:

```tsx
const [books] = BooksForAuthor.use(authorId);
```

Because the query returns `Observe(...)`, it stays live. Add a book for that author and the row updates without polling.

For a list-with-details screen, let the author list call `AllAuthors.use()` and each row call `BooksForAuthor.use(author.id)`. That keeps each slice small: the author slice owns authors, the book slice owns books, and the screen composes their generated proxies.

## See also

[Section titled “See also”](#see-also)

* [Queries](/arc/backend/queries/) — observable and non-observable query methods, parameters, and filtering.
* [Relate your slices](/arc/tutorial/books-and-relationships/) — this relationship built step by step.
* [Execute a command from React](/arc/scenarios/run-a-command-from-react/) — consuming the query proxy.

# Return a result or an error

> Choose what a command's Handle() hands back — one event, several, a value for the caller, or a typed failure — and read it on the client.

**Goal:** your command needs to return more than a single event — maybe a generated id the caller needs, maybe a typed failure, maybe several events at once.

## `Handle()` returns what happened

[Section titled “Handle() returns what happened”](#handle-returns-what-happened)

A command’s `Handle()` method returns the event(s) it produced, and Arc appends them. The *shape* you return is how you express intent — Arc understands several, so pick the one that fits rather than bending your logic to a single form.

## Do it

[Section titled “Do it”](#do-it)

Return the shape that matches the outcome:

| You want to…                                         | Return                                           |
| ---------------------------------------------------- | ------------------------------------------------ |
| record one event (source from the command’s `[Key]`) | the event: `AuthorRegistered Handle()`           |
| record one event against an explicit source          | a tuple: `(AuthorId, AuthorRegistered) Handle()` |
| also hand the caller a value                         | a tuple of `(result, event)`                     |
| reject with a typed failure *or* succeed             | `Result<AuthorRegistered, ValidationResult>`     |
| record several events                                | return them together as an `IEnumerable<…>`      |
| record nothing                                       | `void`                                           |

The `Result<,>` form is how a handler rejects based on state it had to consult — return `ValidationResult.Error("…")` to fail, or the event to proceed:

```csharp
public Result<AuthorRegistered, ValidationResult> Handle(RegisteredAuthorName? existing) =>
    existing is not null && existing.Name != AuthorName.NotSet
        ? ValidationResult.Error("An author with that name is already registered.")
        : new AuthorRegistered(Name);
```

## Reading it on the client

[Section titled “Reading it on the client”](#reading-it-on-the-client)

Whatever the handler returns, the generated proxy gives the caller a `CommandResult`. Check `isSuccess`, read any returned value off the result, and inspect validation errors when it failed — the same object carries all three.

## See also

[Section titled “See also”](#see-also)

* [Commands](/arc/backend/commands/) — the full command model and handler signatures.
* [Command Result](/arc/frontend/core/commands/command-result/) — reading the result on the frontend.
* [Validate a command](/arc/scenarios/validate-a-command/) — where `ValidationResult.Error` comes from.

# Execute a command from React

> Wire a React form or button to a command through the generated proxy — with CommandDialog handling instantiation, validation, and the buttons.

**Goal:** a user clicks a button or fills a form, and a command runs — with validation feedback, a disabled-while-running button, and no hand-written API client.

## Call the proxy, don’t write a client

[Section titled “Call the proxy, don’t write a client”](#call-the-proxy-dont-write-a-client)

When the backend builds, Arc generates a typed proxy for every command. You don’t write a `fetch`, redeclare the command’s shape, or wire validation — the proxy already knows the types, and `CommandDialog` drives the whole interaction.

## Do it

[Section titled “Do it”](#do-it)

1. **Use `CommandDialog` for a form.** Pass the command constructor; the dialog instantiates it, renders the confirm/cancel buttons, and disables confirm while it executes. Use command form fields for the inputs:

AddAuthor.tsx

```tsx
   import { CommandDialog } from '@cratis/components/CommandDialog';
   import { InputTextField } from '@cratis/components/CommandForm';
   import { RegisterAuthor } from './Authors/RegisterAuthor';   // generated proxy

export const AddAuthor = () => (
       <CommandDialog<RegisterAuthor> command={RegisterAuthor} title="Add author" okLabel="Add">
           <InputTextField<RegisterAuthor> value={i => i.name} title="Name" />
       </CommandDialog>
   );
   ```

The field accessor `i => i.name` is a property on the generated type — rename it in C#, rebuild, and the frontend stops compiling until you fix it.

2. **Inject context the form needs to be valid via `initialValues`.** A parent id the user shouldn’t type goes here — not in `onBeforeExecute`, which fires too late to affect validity:

```tsx
   <CommandDialog<AddBook> command={AddBook} initialValues={{ authorId, bookId: Guid.create() }}>
       <InputTextField<AddBook> value={i => i.title} title="Title" />
   </CommandDialog>
   ```

3. **Validation surfaces itself.** Rules you wrote on the command (and its value types) run client-side and on the server, and `CommandDialog` renders the messages against the fields. You write none of that wiring.

For executing a command without a dialog (a plain button, custom flow), the proxy exposes an execute call that returns a `CommandResult` — check `isSuccess` and read any returned value off it.

## See also

[Section titled “See also”](#see-also)

* [Dialogs](/components/) — `CommandDialog`, `Dialog`, and the form-field components.
* [Command Result](/arc/frontend/core/commands/command-result/) — handling the result in code.
* [Validate a command](/arc/scenarios/validate-a-command/) — the rules that surface in the form.

# Test a command

> Prove a slice works through the real Arc pipeline — validation, authorization, and the handler — with no HTTP server and no database.

**Goal:** verify a command does the right thing — succeeds when it should, rejects bad input, refuses an unauthorized caller — without standing up a web server or a database.

## The real pipeline, in-process

[Section titled “The real pipeline, in-process”](#the-real-pipeline-in-process)

`CommandScenario<TCommand>` drives a command through the **same** pipeline production uses: validation filters, authorization filters, and the handler all run, nothing is mocked by default. When the Chronicle testing package is referenced, it adds an in-memory event log automatically, so you can also assert on what was appended.

Reference `Cratis.Testing` (the meta-package) in your spec project.

## Do it

[Section titled “Do it”](#do-it)

1. **Instantiate the scenario** as a field, then `Execute` the command and assert on the `CommandResult`:

```csharp
   public class when_registering_an_author
   {
       readonly CommandScenario<RegisterAuthor> _scenario = new();

[Fact]
       public async Task should_succeed()
       {
           var result = await _scenario.Execute(new RegisterAuthor(AuthorId.New(), "Ada Lovelace"));
           result.ShouldBeSuccessful();
       }
   }
   ```

2. **Check validation without running the handler** using `Validate`:

```csharp
   [Fact]
   public async Task should_reject_a_blank_name()
   {
       var result = await _scenario.Validate(new RegisterAuthor(AuthorId.New(), string.Empty));
       result.ShouldHaveValidationErrors();
   }
   ```

3. **Register stubs or fakes** the handler depends on through `Services`, in the test constructor:

```csharp
   public when_registering_an_author() =>
       _scenario.Services.AddSingleton(_someDependency);
   ```

The `CommandResult` assertion helpers — `ShouldBeSuccessful`, `ShouldHaveValidationErrors`, `ShouldHaveValidationErrorFor("…")`, `ShouldNotBeAuthorized`, and more — read like sentences and print the failure reasons when they fail.

## See also

[Section titled “See also”](#see-also)

* [Command Scenarios](/arc/backend/testing/command-scenario/) — the full API and every assertion helper.
* [Testing Chronicle commands](/arc/backend/testing/chronicle/) — seed the read model state a command reads (from events or a pinned instance) and assert the events it appended.
* [Testing](/arc/backend/testing/) — the testing packages and the Chronicle in-memory event log.

# Use current state in a command

> Inject the read model Chronicle projected for a command's key straight into its validator, Provide, or Handle — and decide with it, without writing a query.

**Goal:** your command’s decision depends on what’s already true. Can this order be submitted? Is this name taken? What’s the current balance? The state you need is already projected into a read model — you just need it *inside* the command.

You don’t query for it. If the command carries a key, Arc has already resolved the read model for that key and will hand it to you as a parameter.

## The friction this removes

[Section titled “The friction this removes”](#the-friction-this-removes)

Without it, a command that needs current state has to go get it: inject a repository or `IReadModels`, resolve the key by hand, `await` a lookup, null-check the result. That’s four lines of plumbing before the first line of the actual decision — repeated in the validator *and* the handler, where the two can drift apart and answer differently.

Arc removes the fetch entirely. Declare the read model as a parameter and it arrives:

```csharp
[Command]
public record SettleLedger(LedgerId LedgerId)
{
    public LedgerSettled Handle(LedgerBalance balance) => new(balance.Balance);
}
```

`LedgerBalance` is a read model built from ledger events. Arc resolved it for `LedgerId`, and the validator for this same command gets the *same* instance — one fetch per command, shared.

## How the resolution works

[Section titled “How the resolution works”](#how-the-resolution-works)

The key the command already uses to append events is the key the read model is resolved by. Nothing extra to configure.

```
Key · EventSourceId · ICanProvideEventSourceId

found

never projected or removed

Command record

event source id

resolve by key

read model instance

null

CommandValidator

Provide method

Handle method
```

Two things follow from that shape, and both matter:

* **A key proves *which* instance, not *that* it exists.** The projection may never have been created, or may have been removed. Resolution can legitimately yield nothing.
* **All three positions share one instance.** The validator, `Provide()`, and `Handle()` resolve from the same command scope, so they cannot disagree about the state they’re looking at.

## Pick where the state is used

[Section titled “Pick where the state is used”](#pick-where-the-state-is-used)

| You want to…                       | Put the read model in        | Because                                                                                                                   |
| ---------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Reject the command with a message  | `CommandValidator<TCommand>` | Rules stay with the command’s other rules; the message reaches the UI as a validation error                               |
| Feed a value into the decision     | `Handle()`                   | The event you produce is computed *from* the state                                                                        |
| Combine it with fetched data first | `Provide()`                  | `Provide` acquires, `Handle` decides — see [Provide data to a command handler](/arc/scenarios/provide-data-to-a-command/) |

### Reject: put it in the validator

[Section titled “Reject: put it in the validator”](#reject-put-it-in-the-validator)

A validator constructor takes the read model like any other dependency:

```csharp
public class SettleLedgerValidator : CommandValidator<SettleLedger>
{
    public SettleLedgerValidator(LedgerBalance balance) =>
        RuleFor(command => command.LedgerId)
            .Must(_ => balance.Balance > 0)
            .WithMessage("Ledger has no funds to settle.");
}
```

The command never reaches `Handle()`, and the message surfaces in the UI through the generated proxy like any other validation error.

### Decide: put it in `Handle()`

[Section titled “Decide: put it in Handle()”](#decide-put-it-in-handle)

When the state is an *input* to the event rather than a gate on it, take it in the handler:

```csharp
[Command]
public record WithdrawFunds(AccountId AccountId, decimal Amount)
{
    public FundsWithdrawn Handle(AccountBalance balance) =>
        new(Amount, balance.Balance - Amount);
}
```

## Say what a missing read model means

[Section titled “Say what a missing read model means”](#say-what-a-missing-read-model-means)

This is the one decision the framework can’t make for you, so make it deliberately: **nullable means you handle absence, non-nullable means you require existence.**

Nullable — absence is a normal business condition, and the rule is written around it:

```csharp
public class RegisterCustomerValidator : CommandValidator<RegisterCustomer>
{
    public RegisterCustomerValidator(Customer? customer) =>
        RuleFor(_ => customer)
            .Null()
            .WithMessage("Customer is already registered");
}
```

Non-nullable — the projection is required, and its absence is a fault rather than an outcome. Arc fails the command with `ReadModelDoesNotExistForCommand` (HTTP 400) before your code runs, so you write the rule against the state directly:

```csharp
public class SubmitOrderValidator : CommandValidator<SubmitOrder>
{
    public SubmitOrderValidator(OrderReadModel order) =>
        RuleFor(_ => order.Status)
            .Equal(OrderStatus.ReadyForSubmission)
            .WithMessage("Only orders that are ready for submission can be submitted");
}
```

The analyzer warns ([ARC0006](/arc/backend/code-analysis/arc0006/)) on every non-nullable read model parameter — not because it’s wrong, but so the choice is a decision rather than an oversight.

Read models are eventually consistent

The instance you get reflects events processed *so far*. That is exactly right for gating on projected state (“this order isn’t ready”, “this account is frozen”), and wrong for an invariant that must hold under concurrent commands — two racing registrations can both read “name not taken”. For invariants, use a Chronicle [constraint](/chronicle/constraints/), which is enforced at append time.

## Which read models can be injected

[Section titled “Which read models can be injected”](#which-read-models-can-be-injected)

Any read model Chronicle can resolve **by key** — which means one with a Chronicle backing artifact:

* a fluent [`IProjectionFor<T>`](/chronicle/projections/) projection
* a model-bound projection (`[FromEvent<T>]`, `[SetFrom<T>]`, `[SetValue<T>]`)
* an [`IReducerFor<T>`](/chronicle/reducers/) reducer

You write the parameter identically in all three cases — the backing artifact is an implementation detail. Note that the `[ReadModel]` attribute **alone** does not make a type injectable: it’s an Arc query concept and can be backed by stores that have no key resolution. Backing decides, not the attribute.

## Test it without mocking

[Section titled “Test it without mocking”](#test-it-without-mocking)

Seed the state the command should observe, then execute. Either state the events behind it:

```csharp
void Establish() =>
    _scenario.Given
        .ForEventSource(_accountId)
        .Events(new MoneyDeposited(100m), new MoneyDeposited(50m));
```

…or pin the instance when the events aren’t the point:

```csharp
void Establish() =>
    _scenario.Given
        .ForEventSource(_accountId)
        .ReadModel(new AccountBalance(150m));
```

An unseeded event source resolves to `null`, exactly as in production. See [Testing with Chronicle](/arc/backend/testing/chronicle/) for the full harness.

## See also

[Section titled “See also”](#see-also)

* [Read models in commands](/arc/backend/chronicle/read-models/injecting-into-commands/) — the full reference for all three positions.
* [When resolution fails](/arc/backend/chronicle/read-models/failures/) — every error you can hit, and what it means.
* [Validate a command](/arc/scenarios/validate-a-command/) — the other three places a rule can live.
* [Resolving EventSourceId](/arc/backend/chronicle/resolving-event-source-id/) — how the key itself is found.

# Validate a command

> Reject malformed or duplicate input before a command produces an event — with value-type rules, command rules, and state-dependent business rules.

**Goal:** stop bad input from ever becoming an event. A blank name, a negative quantity, a duplicate email — you want the command rejected, with a clear reason, before `Handle()` runs.

## Validation runs before the handler

[Section titled “Validation runs before the handler”](#validation-runs-before-the-handler)

Arc runs validators *before* it invokes `Handle()`. A command that fails validation never appends anything and returns a `CommandResult` carrying the errors — and because the rules are extracted into the generated proxy, they also run on the client for instant feedback. There are three places a rule can live; reach for the narrowest one that fits.

## Do it

[Section titled “Do it”](#do-it)

1. **A rule that’s true of a value everywhere → validate the value type.** Write a `ConceptValidator<T>` and it applies to every command carrying that concept:

```csharp
   public class AuthorNameValidator : ConceptValidator<AuthorName>
   {
       public AuthorNameValidator() =>
           RuleFor(x => x.Value).NotEmpty().WithMessage("An author needs a name.");
   }
   ```

2. **A rule specific to one command → validate the command.** Use a `CommandValidator<TCommand>` (FluentValidation) for cross-field or command-only rules:

```csharp
   public class RegisterAuthorValidator : CommandValidator<RegisterAuthor>
   {
       public RegisterAuthorValidator() =>
           RuleFor(c => c.Name).NotEmpty().MaximumLength(200);
   }
   ```

For lightweight cases, data annotations like `[Required]` on the command record work too.

3. **A rule that depends on existing state → inject the read model.** Arc resolves the read model for this command’s key and hands it to whichever position asks for it — the validator, `Provide()`, or `Handle()`. Where you put the rule depends on whether it must hold under concurrency.

For an invariant that two simultaneous commands could both slip past — uniqueness is the classic one — guard it in `Handle()`, closest to the append, and return a typed error:

```csharp
   public Result<AuthorRegistered, ValidationResult> Handle(RegisteredAuthorName? existing) =>
       existing is not null && existing.Name != AuthorName.NotSet
           ? ValidationResult.Error("An author with that name is already registered.")
           : new AuthorRegistered(Name);
   ```

Even that guard is a *narrowing*, not a guarantee — for a hard invariant, enforce it with a Chronicle [constraint](/chronicle/constraints/), which is checked at append time.

Most state-dependent rules aren’t races, though. “This order isn’t ready to submit”, “this account is frozen”, “this role doesn’t exist” — these are gates on projected state, and they belong in the validator, where they sit with the command’s other rules and reach the UI as ordinary validation errors:

```csharp
   public class SubmitOrderValidator : CommandValidator<SubmitOrder>
   {
       public SubmitOrderValidator(OrderReadModel? order)
       {
           RuleFor(_ => order).NotNull().WithMessage("Order does not exist.");
           When(_ => order is not null, () =>
               RuleFor(_ => order!.Status)
                   .Equal(OrderStatus.ReadyForSubmission)
                   .WithMessage("Only orders that are ready for submission can be submitted."));
       }
   }
   ```

The nullable parameter is how you say a missing projection is a business condition rather than a fault — [Use current state in a command](/arc/scenarios/use-current-state-in-a-command/) covers that choice and all three positions in full.

A validator can also reach *outside* the command’s own state. It’s resolved through dependency injection, so it can take a collaborator and check with FluentValidation’s `MustAsync`:

```csharp
   public class RegisterAuthorValidator : CommandValidator<RegisterAuthor>
   {
       public RegisterAuthorValidator(IAuthorsCatalog authors)
       {
           RuleFor(c => c.Name).NotEmpty().MaximumLength(200);
           RuleFor(c => c)
               .MustAsync(async (command, ct) => !await authors.IsRegistered(command.Name))
               .WithMessage("An author with that name is already registered.");
       }
   }
   ```

A `MustAsync` rule runs on the server only — unlike the declarative rules, it can’t be extracted into the generated proxy.

Validators are discovered by convention — you never register them. The frontend surfaces the messages automatically; see [Execute a command from React](/arc/scenarios/run-a-command-from-react/).

## See also

[Section titled “See also”](#see-also)

* [Command Validation](/arc/backend/commands/command-validation/) and [Validation](/arc/backend/commands/validation/) — the full validation model.
* [Make it trustworthy](/arc/tutorial/validation/) — the same ideas, taught step by step.
* [Return a result or an error](/arc/scenarios/return-a-result-or-error/) — the `Result<,>` return shape used above.
* [Use current state in a command](/arc/scenarios/use-current-state-in-a-command/) — injecting projected state into a validator, `Provide()`, or `Handle()`.

# Troubleshooting

> Fixes for the issues that come up most when building with Arc — proxies, authorization, validation, and stale types.

Most Arc snags come down to a handful of causes. Here they are. If the slice uses the Chronicle integration, see [Chronicle troubleshooting](/chronicle/troubleshooting/) for event-store-specific issues.

## My frontend can’t find the generated proxy

[Section titled “My frontend can’t find the generated proxy”](#my-frontend-cant-find-the-generated-proxy)

Proxies are generated when the **backend builds**. If the import doesn’t resolve:

* Run `dotnet build` on the backend and confirm it succeeds — no proxies are emitted until the C# compiles.
* Check the command/query is discoverable: a `[Command]` record with a `Handle()` method, or a static query method on a `[ReadModel]`.
* Make sure proxy generation is targeting the right output folder for your frontend (see [Proxy Generation](/arc/backend/proxy-generation/)).

## I changed the C# but the TypeScript is stale

[Section titled “I changed the C# but the TypeScript is stale”](#i-changed-the-c-but-the-typescript-is-stale)

The proxies regenerate on build. Rebuild the backend; the frontend types update with it. If a renamed property doesn’t surface, you’ve found the feature working — the old name should now fail to compile until you update the call site.

## My command’s OK/Submit button stays disabled

[Section titled “My command’s OK/Submit button stays disabled”](#my-commands-oksubmit-button-stays-disabled)

The command isn’t considered valid. The usual cause: a required value is being set in `onBeforeExecute` instead of `initialValues`. `onBeforeExecute` runs at execution time — too late to affect validity — so the form never becomes valid. Put injected required values (like a parent id) in `initialValues`; reserve `onBeforeExecute` for generated values that don’t gate validity (like a new `Guid`). See [Building a form](/components/building-a-form/).

## My command returns 401 or 403

[Section titled “My command returns 401 or 403”](#my-command-returns-401-or-403)

That’s authorization. Check that:

* the caller is authenticated, and
* the caller has the role the command requires (`[Roles(...)]` on the command — or on the query method for a 403 on reads).

For local development you can generate a principal so you can exercise authorized endpoints without a full login — see [Identity](/arc/backend/identity/) and [Authorizing commands and queries](/arc/backend/authorizing-commands-and-queries/).

## My validation isn’t firing

[Section titled “My validation isn’t firing”](#my-validation-isnt-firing)

Arc discovers a `CommandValidator<TCommand>` by convention. Confirm the validator’s generic type matches the command exactly, and that any async rule that needs a dependency takes it via the validator’s constructor. See [Commands](/arc/backend/commands/).

## My query returns nothing

[Section titled “My query returns nothing”](#my-query-returns-nothing)

This is usually the read side, not proxy generation:

* Confirm the command wrote the document or entity you expect.
* Check any query predicate, especially ids passed through `[Key]`.
* If the query is observable, confirm the underlying store is configured for observation: MongoDB change streams or EF observed DbSets.

If the slice is backed by Chronicle, also check that the projection has caught up and maps the events you appended.

## See also

[Section titled “See also”](#see-also)

* [Backend](/arc/backend/) and [Frontend](/arc/frontend/) guides.
* [Chronicle troubleshooting](/chronicle/troubleshooting/) for optional event-store issues.

# Tutorial: Build a library, full-stack

> Build a small but real library app with Arc — typed commands and queries, validation, real-time React screens, and authorization — one chapter at a time.

Let’s build something real together: the back office for a small library. Librarians register authors, catalog the books each author wrote, and watch the catalog fill in live as they work. It’s a modest app — but by the time it’s done you’ll have used every part of Arc that a real full-stack feature needs, and you’ll understand *why* each part is shaped the way it is.

This isn’t a tour of one slice in isolation. We’ll build several features that lean on each other, the way a real app does — and at each step we’ll stop, look at what just happened, and only then move on. The thing Arc is really selling is that the whole loop — a C# command, the read model it updates, the query that serves it, and the React screen that calls both — stays **type-safe end to end**, with no hand-written API client in the middle. You’ll feel that pay off repeatedly.

Arc doesn’t care where your data lives. We’ll store it straight in a database — **MongoDB or EF Core**, your choice — so this tutorial can focus on CQRS and the generated proxy boundary. That is a teaching and adoption choice, not a claim that event sourcing is secondary: for information systems, we usually recommend Chronicle as the event-sourced backbone. The point is that CQRS can run with or without it.

Here’s the shape of what we’re heading toward, as an **[event model](/event-modeling/)** — the way you’d whiteboard a feature *before* deciding how to store it. Read it left to right: the librarian adds an author on a screen, the `RegisterAuthor` command records the business fact that an author was registered, the `Author` read model is updated, and the next screen lists it. Don’t worry if the pieces aren’t familiar yet — we’ll meet each one in turn.

```
UI/A: AuthorsUI/A: AuthorsC/RM: AuthorsC/RM: AuthorsStream: Authors
AddAuthor
RegisterAuthor

id: uuid, name: string
AuthorRegistered

name: string
Author
Authors
```

`AuthorRegistered` is the business **fact** in the model; it is not a storage decision. Over a plain database your command writes the `Author` read model directly. Each later feature (add books, list them) is another column of the same shape.

That’s *what* you’ll build. Here’s *how* Arc runs it — and the part that earns its place: you write the command and the query once in C#, and the build **generates the typed proxies** your React calls, so the frontend can’t drift from the backend. Over a database the path is direct:

```
Arc (C#)

React (TypeScript)

generated command proxy

writes

generated query proxy, live

Library screen

commands — RegisterAuthor · AddBook

read models — Author · BookOnShelf

queries

MongoDB / EF Core
```

The two diagrams are two views of the same feature: the event model is the **domain flow** you design, and the flowchart is the **typed boundary** the build wires up for you — generated C# → TypeScript proxies, no hand-written API client. That boundary is the heart of Arc; [Understanding the proxy boundary](/arc/understanding-the-proxy-boundary/) goes deeper on it.

## What you’ll build

[Section titled “What you’ll build”](#what-youll-build)

By the last chapter you’ll have a working library back office where a librarian can:

* **register an author** and see the list update the instant they confirm — no refresh,
* be **stopped from registering a blank or duplicate name**, with the reason shown right on the form,
* **add books** to an author and browse them,
* and do all of this behind **role-based authorization**, so only a librarian can change the catalog.

## What you’ll learn

[Section titled “What you’ll learn”](#what-youll-learn)

* The full Arc loop — **command → read model → query → React** — and how `dotnet build` keeps the two languages in sync.
* How to put **validation and business rules** on a command and have the failure surface in the UI through the generated proxy.
* How to model a **second feature that reads the first**, and read related data back.
* How **observable queries** keep a screen live with no polling.
* How to **authorize** commands and queries at the boundary.

## What you’ll need

[Section titled “What you’ll need”](#what-youll-need)

An Arc project running locally with a database. The [Get started](/arc/backend/getting-started/your-first-command/) guide gets you there: scaffold with `dotnet new cratis`, start the dependencies, and confirm `dotnet build` succeeds and the app runs. We use **MongoDB** for the worked examples and show the **EF Core** equivalent in tabs as we go — pick whichever you scaffolded with.

## The tour

[Section titled “The tour”](#the-tour)

1. **[Your first full-stack slice](/arc/tutorial/first-slice/)** — register an author from C# all the way to a live React screen, fully typed.
2. **[Make it trustworthy](/arc/tutorial/validation/)** — reject bad input with a validator and a uniqueness rule, and show the reason in the form.
3. **[Relate your slices](/arc/tutorial/books-and-relationships/)** — add books that belong to an author, and read them back.
4. **[Make it live](/arc/tutorial/real-time/)** — observable queries that update the screen the moment the data changes.
5. **[Decide who can do what](/arc/tutorial/authorization/)** — lock the catalog down with role-based authorization.

Each chapter ends where the next begins. By the end you’ll have a real full-stack feature — and the model to build your own. Ready? [Let’s build the first slice →](/arc/tutorial/first-slice/)

# 5. Decide who can do what

> Gate the catalog with role-based authorization on commands and queries, connect it to the signed-in user, and look back at the full-stack feature you built.

Our back office works, but it’s wide open: anyone who can reach it can register authors and add books. The last thing a real app needs is to decide *who is allowed*. We’ll add role-based authorization — and the nice part is that it’s declarative, so none of our `Handle()` methods or read models change. The rule lives at the boundary, where it belongs.

## Gate the commands

[Section titled “Gate the commands”](#gate-the-commands)

Authorization is a cross-cutting concern. You don’t want `if (user.IsLibrarian)` checks scattered through your logic — you want one attribute at the edge. Put `[Roles(...)]` on the command, and Arc checks the caller’s roles before the command runs:

1. **Require a role to change the catalog.** Only a librarian may register authors or add books:

```csharp
   [Command]
   [Roles(nameof(UserRole.Librarian))]
   public record RegisterAuthor(AuthorId Id, AuthorName Name)
   {
       public Task Handle(IMongoCollection<Author> authors) =>
           authors.InsertOneAsync(new Author(Id, Name));
   }
   ```

The same attribute goes on `AddBook`. Everything inside `Handle()` stays exactly as it was — the gate is applied around it.

## Gate the queries

[Section titled “Gate the queries”](#gate-the-queries)

The read side deserves the same protection — a public catalog might be fine, but an internal audit list is not. Query methods take the same attribute:

```csharp
[ReadModel]
public record Author(AuthorId Id, AuthorName Name)
{
    [Roles(nameof(UserRole.Librarian))]
    public static ISubject<IEnumerable<Author>> AllAuthors(IMongoCollection<Author> collection) =>
        collection.Observe();
}
```

The frontend respects it too

The generated proxies enforce the same rules — an unauthorized call fails the same way from React as from any other client. So you can drive your UI off identity as well: hide the “Add author” button when the signed-in user isn’t a librarian, and the command is *still* protected on the server if someone calls it anyway. See [frontend identity](/arc/frontend/react/identity/) for reading the current user’s roles in React.

## Where the roles come from

[Section titled “Where the roles come from”](#where-the-roles-come-from)

`UserRole.Librarian` is just a value you check against; the roles themselves come from the **authenticated identity**. Arc plugs into standard ASP.NET Core authentication, and you can enrich the identity with application-specific details — roles, tenant, preferences — through `IProvideIdentityDetails`. For local development you can generate a principal so you can exercise authorized endpoints without standing up a full login.

That’s a topic in its own right; the [Identity](/arc/backend/identity/) section walks through it, and the [Authorizing commands and queries](/arc/backend/authorizing-commands-and-queries/) recipe is the condensed how-to.

## Look back at what you built

[Section titled “Look back at what you built”](#look-back-at-what-you-built)

Five chapters ago we had nothing. Now we have a real full-stack library back office, running over a plain database — and you’ve used every part of the Arc loop and know *why* each one is shaped the way it is:

* **Chapter 1** — a full-stack slice: a `[Command]` with `Handle()` that writes, a `[ReadModel]` with its query, and a React screen calling both through generated, typed proxies.
* **Chapter 2** — trust: a `ConceptValidator` on the value type and a `CommandValidator` business rule, both surfaced in the UI through the generated proxy.
* **Chapter 3** — relationships: a second slice and a filtered query that reads one author’s catalog, no join.
* **Chapter 4** — life: observable queries as standing subscriptions, database to browser.
* **Chapter 5** — authorization: `[Roles(...)]` at the boundary, on both commands and queries, tied to the signed-in user.

The thing worth taking with you is the loop itself: **something happens (a command) → it writes state → that state is served (a query) → and React calls all of it, typed end to end.** Every feature you build from here is another turn of that loop in its own folder. You never go back and edit the last one to add the next.

And notice the boundary you proved: Arc did not need an event store for this CQRS loop. That is not an argument against event sourcing. For information systems, we usually reach for Chronicle as the default because history pays for itself. The point is architectural independence: CQRS can run over a plain database, and event sourcing can run without Arc, but they fit together extremely well.

From here, build another feature the same way, or take the next layer up: [Components](/components/) turns these generated commands and queries into higher-level screens, and the [Cratis Stack tour](/cratis-stack/) shows where Arc fits with the rest of the platform.

# 3. Relate your slices

> Add a second feature — books that belong to an author — and read each author's catalog back with a filtered, live query.

An author exists to have written things. So our second feature is **adding a book to an author’s catalog** — and it’s the first time two slices in our app relate to each other. A book belongs to an author; we’ll model that with a plain foreign key — the author’s id on the book — and read a catalog back with a **filtered** query.

Here’s the shape:

```
writes

live

AddBook (keyed by author)

Books

BooksForAuthor (filtered by AuthorId)

React: author → books
```

## The book slice

[Section titled “The book slice”](#the-book-slice)

1. **Strong types for the book.** Same discipline as before:

```csharp
   public record BookId(Guid Value) : ConceptAs<Guid>(Value)
   {
       public static BookId New() => new(Guid.NewGuid());
   }

public record BookTitle(string Value) : ConceptAs<string>(Value)
   {
       public static implicit operator BookTitle(string value) => new(value);
   }
   ```

2. **The command writes a book, tagged with its author.** `AddBook` carries the `AuthorId` it belongs to — and writes a `Book` carrying that id:

* MongoDB

```csharp
     [Command]
     public record AddBook(AuthorId AuthorId, BookId BookId, BookTitle Title)
     {
         public Task Handle(IMongoCollection<Book> books) =>
             books.InsertOneAsync(new Book(BookId, AuthorId, Title));
     }
     ```

* EF Core

```csharp
     [Command]
     public record AddBook(AuthorId AuthorId, BookId BookId, BookTitle Title)
     {
         public async Task Handle(LibraryDbContext db)
         {
             db.Books.Add(new Book(BookId, AuthorId, Title));
             await db.SaveChangesAsync();
         }
     }
     ```

## Read a catalog back, filtered

[Section titled “Read a catalog back, filtered”](#read-a-catalog-back-filtered)

The read model is just the book document — it carries the `AuthorId` it belongs to. The query takes the author’s id (Arc binds it by matching the parameter name) and returns only that author’s books, live:

* MongoDB

```csharp
  [ReadModel]
  public record Book(BookId Id, AuthorId AuthorId, BookTitle Title)
  {
      public static ISubject<IEnumerable<Book>> BooksForAuthor(AuthorId authorId, IMongoCollection<Book> books) =>
          books.Observe(b => b.AuthorId == authorId);
  }
  ```

* EF Core

```csharp
  [ReadModel]
  public record Book(BookId Id, AuthorId AuthorId, BookTitle Title)
  {
      public static ISubject<IEnumerable<Book>> BooksForAuthor(AuthorId authorId, LibraryDbContext db) =>
          db.Books.Observe(b => b.AuthorId == authorId);

// add the DbSet to LibraryDbContext: public DbSet<Book> Books => Set<Book>();
  }
  ```

The relationship is a filter

`Observe(b => b.AuthorId == authorId)` is the whole relationship: one collection of books, read back by the author they point at — and still live, because it’s an observed query. No join, no second store.

## Showing the catalog

[Section titled “Showing the catalog”](#showing-the-catalog)

`BooksForAuthor` takes an author id, so it’s a query *per author*. The list of authors comes from chapter 1’s `AllAuthors`; each row renders its own live catalog:

Catalog.tsx

```tsx
import { AllAuthors } from './Authors/Author';
import { BooksForAuthor } from './Books/Book';   // generated proxies

export const Catalog = () => {
    const [authors] = AllAuthors.use();
    return (
        <ul>
            {authors.data.map(a => (
                <li key={String(a.id)}>{a.name}<AuthorBooks authorId={String(a.id)} /></li>
            ))}
        </ul>
    );
};
```

Adding a book is a `CommandDialog<AddBook>`, exactly like `RegisterAuthor` — the only difference is that it carries the `authorId` of the author you’re adding to. Pass that in as an initial value:

AddBook.tsx

```tsx
<CommandDialog<AddBook>
    command={AddBook}
    title="Add book"
    okLabel="Add"
    initialValues={{ authorId, bookId: Guid.create() }}>
    <InputTextField<AddBook> value={i => i.title} title="Title" />
</CommandDialog>
```

Why initialValues, not onBeforeExecute

The `authorId` is context the form needs to be *valid* from the start, so it goes in `initialValues`. Values you compute at execution time and that don’t affect validity (like a generated id) can go in `onBeforeExecute` instead. See [Dialogs](/components/) for the full pattern.

## What you built

[Section titled “What you built”](#what-you-built)

* A second slice — `AddBook` — that tags each book with the author it belongs to.
* A **relationship as a foreign key + a filtered query**: `BooksForAuthor` reads exactly one author’s catalog, live, with no join.
* A React screen that composes the two: a list of authors, each rendering its own live catalog.

Two features, related, both live. We keep *saying* “it stays live” — next we’ll make that concrete and watch a screen update itself the instant the data changes. [Let’s make it live →](/arc/tutorial/real-time/)

# 1. Your first full-stack slice

> Build the library's first feature — register an author — from a C# command all the way to a live React screen, with the types kept in sync by the build.

Every app starts with one feature. Ours is **registering an author** — the first thing a librarian does before they can catalog a single book. It’s deliberately small, but building it touches the entire Arc loop: a command that expresses intent, the read model it updates, the query that serves it, and the React screen that calls both — all of it typed end to end.

In a layered app these would be files scattered across `Commands/`, `Handlers/`, and `ReadModels/`, and you’d jump between folders to follow one behavior. Arc doesn’t force a layout on you — but we recommend the **vertical-slice** approach: a folder per feature, with a folder per slice inside it, mirroring the columns of your event model. That’s how we’ll build here: everything below lives in one `Authors/` folder you read top to bottom. Here’s the slice we’re about to build:

```
Handle, writes

AllAuthors

generated proxy, live

RegisterAuthor command

database

Author read model

query, over HTTP

React list
```

## The backend half

[Section titled “The backend half”](#the-backend-half)

1. **Give the domain strong types.** Never thread raw `Guid`s and `string`s through your domain — wrap them so the compiler keeps them straight and your signatures document themselves:

```csharp
   public record AuthorId(Guid Value) : ConceptAs<Guid>(Value)
   {
       public static AuthorId New() => new(Guid.NewGuid());
   }

public record AuthorName(string Value) : ConceptAs<string>(Value)
   {
       public static implicit operator AuthorName(string value) => new(value);
   }
   ```

2. **Write the command — with `Handle()` on the record.** A command is a `record` marked `[Command]`. The behavior lives in a `Handle()` method **on the record itself**; there’s no separate handler class to hunt for. Here it writes the new author straight to the database:

* MongoDB

```csharp
     [Command]
     public record RegisterAuthor(AuthorId Id, AuthorName Name)
     {
         public Task Handle(IMongoCollection<Author> authors) =>
             authors.InsertOneAsync(new Author(Id, Name));
     }
     ```

* EF Core

```csharp
     [Command]
     public record RegisterAuthor(AuthorId Id, AuthorName Name)
     {
         public async Task Handle(LibraryDbContext db)
         {
             db.Authors.Add(new Author(Id, Name));
             await db.SaveChangesAsync();
         }
     }
     ```

`Handle()` returns `Task` because there’s nothing to report back — the write *is* the outcome. Arc injects the dependency it declares (the Mongo collection, or your `DbContext`) from the container.

3. **Declare the read model and its query.** The read model is just the shape you want to query, marked `[ReadModel]`. A static method **is** the query — return an observable so consumers get live updates:

* MongoDB

```csharp
     [ReadModel]
     public record Author(AuthorId Id, AuthorName Name)
     {
         public static ISubject<IEnumerable<Author>> AllAuthors(IMongoCollection<Author> collection) =>
             collection.Observe();
     }
     ```

* EF Core

```csharp
     [ReadModel]
     public record Author(AuthorId Id, AuthorName Name)
     {
         public static ISubject<IEnumerable<Author>> AllAuthors(LibraryDbContext db) =>
             db.Authors.Observe();
     }

// A BaseDbContext registered via WithEntityFrameworkCore — see the EF integration guide.
     public class LibraryDbContext(DbContextOptions<LibraryDbContext> options) : BaseDbContext(options)
     {
         public DbSet<Author> Authors => Set<Author>();
     }
     ```

Notice what you didn't write

That static `AllAuthors` method *is* your query — Arc serves it over HTTP automatically. No controller, no routing, no DTO. And it’s **live**: `.Observe()` watches the database’s change stream (MongoDB’s, or an [observed `DbSet`](/arc/backend/entity-framework/observing/)), so the instant the command writes, every subscribed browser re-renders.

4. **Set up the project, then build.** Two pieces make the full-stack loop work: a build-time **proxy generator** and the **host wiring**. Add the packages and tell the generator where to write proxies — next to your source, so each `.ts` lands beside the `.tsx` that imports it:

* MongoDB

Library.csproj

```xml
     <ItemGroup>
         <PackageReference Include="Cratis.Arc" Version="*" />
         <PackageReference Include="Cratis.Arc.MongoDB" Version="*" />
         <PackageReference Include="Cratis.Arc.ProxyGenerator.Build" Version="*" />
     </ItemGroup>
     <PropertyGroup>
         
         <CratisProxiesOutputPath>$(MSBuildThisFileDirectory)</CratisProxiesOutputPath>
         <CratisProxiesUseSourceFileAsOutputFile>true</CratisProxiesUseSourceFileAsOutputFile>
     </PropertyGroup>
     ```

Then wire the host. `AddCratisArc` registers Arc, `UseCratisMongoDB` points it at MongoDB, and `UseCratisArc` maps the command, query, and observable-query endpoints:

Program.cs

```csharp
     var builder = WebApplication.CreateBuilder(args);
     builder.AddCratisArc();
     builder.UseCratisMongoDB();
     builder.Services.AddControllers();

var app = builder.Build();
     app.UseRouting();
     app.MapControllers();
     app.UseCratisArc();          // maps the command, query, and observable-query endpoints

await app.RunAsync();
     ```

* EF Core

Library.csproj

```xml
     <ItemGroup>
         <PackageReference Include="Cratis.Arc" Version="*" />
         <PackageReference Include="Cratis.Arc.EntityFrameworkCore" Version="*" />
         <PackageReference Include="Cratis.Arc.ProxyGenerator.Build" Version="*" />
     </ItemGroup>
     <PropertyGroup>
         
         <CratisProxiesOutputPath>$(MSBuildThisFileDirectory)</CratisProxiesOutputPath>
         <CratisProxiesUseSourceFileAsOutputFile>true</CratisProxiesUseSourceFileAsOutputFile>
     </PropertyGroup>
     ```

Then wire the host. `WithEntityFrameworkCore` auto-discovers your `DbContext`, and `UseCratisArc` maps the endpoints:

Program.cs

```csharp
     var builder = WebApplication.CreateBuilder(args);
     builder.AddCratisArc(configureBuilder: arc => arc.WithEntityFrameworkCore());
     builder.Services.AddControllers();

var app = builder.Build();
     app.UseRouting();
     app.MapControllers();
     app.UseCratisArc();          // maps the command, query, and observable-query endpoints

await app.RunAsync();
     ```

```bash
   dotnet build
   ```

Building compiles your C# and — the part that matters most for the next half — **generates a TypeScript proxy** for `RegisterAuthor` and `AllAuthors` next to each slice. That’s what `CratisProxiesOutputPath` turns on; with it unset, `dotnet build` still succeeds but emits nothing. Your frontend is about to call them as if they were local, typed code.

Route config lives in two places

The proxy’s URL is baked in at build time from the `CratisProxies*` properties; the server maps routes from `ArcOptions` at runtime. They agree by default — but if you customize one (a route prefix, say), mirror it in the other or the generated client calls a route the server never mapped. See [proxy-generation configuration](/arc/backend/proxy-generation/) and [ASP.NET Core host configuration](/arc/backend/asp-net-core/configuration/).

## The frontend half

[Section titled “The frontend half”](#the-frontend-half)

The proxies now exist, generated *from your C#*. Normally this is exactly where type safety ends — you’d hand-write a `fetch`, redeclare the shapes in TypeScript, and hope the two stay in sync. We skip all of it. **None of this React changes whether the backend is MongoDB or EF Core.**

1. **Read the authors with the query proxy.** Because `AllAuthors` is an **observable** query, the `.use()` hook re-renders whenever the read model changes — live, no polling:

Authors.tsx

```tsx
   import { AllAuthors } from './Authors/Author';   // generated proxy

export const Authors = () => {
       const [authors] = AllAuthors.use();
       return (
           <ul>
               {authors.data.map(a => <li key={String(a.id)}>{a.name}</li>)}
           </ul>
       );
   };
   ```

2. **Register one with the command proxy.** `CommandDialog` runs a generated command — it instantiates it, renders the form fields and the confirm/cancel buttons, and disables confirm while it executes:

AddAuthor.tsx

Run the app, register an author, and the list updates the moment you confirm — you didn’t write a line of refresh logic. `AllAuthors.use()` is subscribed to the read model, so when the command writes its document, the screen re-renders itself.

One bit of dev wiring for live queries

Observable queries stream over **Server-Sent Events** by default; you can switch to **WebSockets** with the `queryTransportMethod` prop on the [`<Arc/>` context component](/arc/frontend/react/arc/). Either way, in local dev your Vite server needs to proxy `/api` and `/.cratis` through to the backend (with `ws: true` if you use the WebSocket transport) — otherwise the list loads but never updates live. The [Vite configuration](/arc/frontend/react/vite-configuration/) guide shows the exact `server.proxy` block.

## Where the type safety lives

[Section titled “Where the type safety lives”](#where-the-type-safety-lives)

Look at the accessor `i => i.name`. It isn’t a string you typed and hope matches — it’s a property on the generated `RegisterAuthor` type. Rename `Name` in the C# command, rebuild, and `i => i.name` stops compiling until you fix it. The whole feature is one thing expressed in two languages, and the build is what keeps them honest:

* C# — backend

```csharp
  [Command]
  public record RegisterAuthor(AuthorId Id, AuthorName Name)
  {
      public Task Handle(IMongoCollection<Author> authors) =>
          authors.InsertOneAsync(new Author(Id, Name));
  }
  ```

* TypeScript — frontend

```tsx
  // generated from the C# above — call it, don't redeclare it
  <CommandDialog<RegisterAuthor> command={RegisterAuthor} title="Add author">
      <InputTextField<RegisterAuthor> value={i => i.name} title="Name" />
  </CommandDialog>
  ```

## What you built

[Section titled “What you built”](#what-you-built)

In one folder, read top to bottom:

* a `[Command]` with `Handle()` — intent and implementation together, no handler class,
* a `[ReadModel]` whose query method is served over HTTP, live, and
* a **React screen** that reads and writes it through generated, typed proxies.

That’s a complete vertical slice, backend to browser, over a plain database. The next feature will be another folder just like it.

There’s one problem, though: right now a librarian can register an author with a blank name, or the same author twice, and nothing stops them. A real app has to say no. [Let’s make it trustworthy →](/arc/tutorial/validation/)

# 4. Make it live

> See why your screens already update themselves — observable queries are standing subscriptions that push every change from the database to React, with no polling and no refresh code.

We keep saying the catalog “stays live.” This chapter makes that concrete — and shows that you already built it, without writing a line of real-time plumbing.

## Why the screen already moves

[Section titled “Why the screen already moves”](#why-the-screen-already-moves)

Go back to every query we’ve written: each returns `…Observe(…)`, not a one-shot list. That `ISubject<…>` is a stream. On the C# side, Arc serves it as an observable query; on the React side, the generated `.use()` hook **subscribes** to it. So the data flow isn’t “fetch once and render” — it’s a standing subscription:

When a command writes, the database’s change stream notices, the observable query pushes the new value to every subscribed React component, and it re-renders. Open the app in two browser tabs, add a book in one, and watch it appear in the other — you wrote none of that plumbing. It falls out of returning `Observe()` and calling `.use()`.

Under the hood

The subscription rides Server-Sent Events: the browser holds an open connection and Arc pushes each new value down it. You don’t manage the connection, and you don’t poll. On the backend, the live signal comes from the database itself — MongoDB’s [change streams](/arc/backend/mongodb/observing-collections/) or an [observed `DbSet`](/arc/backend/entity-framework/observing/) watching for changes. If you ever want to watch the raw stream, you can — see [observable queries with cURL](/arc/backend/queries/using-observable-queries-with-curl/).

## What makes a query live

[Section titled “What makes a query live”](#what-makes-a-query-live)

Nothing special — just the return type. A one-shot query returns the data:

```csharp
public static IEnumerable<Author> AllAuthors(IMongoCollection<Author> authors) =>
    authors.Find(_ => true).ToList();
```

Make it return an `ISubject<…>` via `Observe()` instead, and the exact same method becomes a live subscription — the proxy and the React `.use()` adapt automatically:

```csharp
public static ISubject<IEnumerable<Author>> AllAuthors(IMongoCollection<Author> authors) =>
    authors.Observe();
```

That’s the whole switch between “load once” and “stay live.” You choose per query: a rarely-changing lookup can be a plain list; a screen the librarian watches should observe.

## What you built

[Section titled “What you built”](#what-you-built)

* A clear picture of **why your screens update themselves** — observable queries are standing subscriptions, database to browser.
* The one-line difference between a **one-shot** query and a **live** one — the return type, nothing else.

The catalog is live. There’s just one thing left before it’s a real back office: right now *anyone* can register authors and add books. Let’s decide who’s allowed. [Lock it down →](/arc/tutorial/authorization/)

# 2. Make it trustworthy

> Reject a blank or duplicate author name — first with a validator on the value type, then with a business rule that checks existing state — and watch the reason appear in the React form.

We left chapter 1 with a working slice and an honest problem: a librarian can register an author with a blank name, or the same author twice, and nothing stops them. A trustworthy app has to be able to say *no* — clearly, and as early as possible.

There are two different kinds of “no” here, and Arc handles them in two different places:

* **“That input is malformed.”** A blank name is wrong on its face — you don’t need to look at anything else to know it. That’s a *validation* rule, and it belongs on the value.
* **“That input collides with what already exists.”** A duplicate name is only wrong relative to the rest of the system. That’s a *business rule*, and it needs to consult state.

Let’s add both.

## Validate the value, once

[Section titled “Validate the value, once”](#validate-the-value-once)

Your first instinct might be to validate `Name` inside a `RegisterAuthor` validator. But think about it: *every* command that takes an `AuthorName` wants the same guarantee — never blank. Arc lets you state that rule **on the value type itself**, so it’s enforced everywhere an `AuthorName` is used, and you never write it twice.

1. **Write a `ConceptValidator` for the value type.** It reaches into the concept’s underlying `Value` and applies ordinary [FluentValidation](https://docs.fluentvalidation.net/) rules:

```csharp
   public class AuthorNameValidator : ConceptValidator<AuthorName>
   {
       public AuthorNameValidator()
       {
           RuleFor(x => x.Value).NotEmpty().WithMessage("An author needs a name.");
       }
   }
   ```

That’s the whole change. You don’t register it anywhere — Arc discovers validators by convention. From now on, any command carrying an `AuthorName` rejects a blank one before `Handle()` ever runs.

## Reject the duplicate against existing state

[Section titled “Reject the duplicate against existing state”](#reject-the-duplicate-against-existing-state)

Uniqueness is the harder kind of “no”, because it depends on what’s already there. Input validation can’t answer it — you have to look in the database. That’s a job for a **`CommandValidator`**, which validates a whole command and, because Arc constructs it from the container, can take the dependencies it needs to check state.

1. **Write a `CommandValidator` that asks the database.** A `MustAsync` rule looks for an author already carrying this name; if it finds one, the command is rejected:

* MongoDB

```csharp
     public class RegisterAuthorValidator : CommandValidator<RegisterAuthor>
     {
         public RegisterAuthorValidator(IMongoCollection<Author> authors)
         {
             RuleFor(c => c.Name)
                 .MustAsync(async (name, _) => !await authors.Find(a => a.Name == name).AnyAsync())
                 .WithMessage("An author with that name is already registered.");
         }
     }
     ```

* EF Core

```csharp
     public class RegisterAuthorValidator : CommandValidator<RegisterAuthor>
     {
         public RegisterAuthorValidator(LibraryDbContext db)
         {
             RuleFor(c => c.Name)
                 .MustAsync(async (name, ct) => !await db.Authors.AnyAsync(a => a.Name == name, ct))
                 .WithMessage("An author with that name is already registered.");
         }
     }
     ```

`Handle()` doesn’t change — it stays the clean write from chapter 1. The validator runs first; if it fails, `Handle()` never executes.

Keep the check honest with a unique index

A check-then-write has a race: two registrations at the same instant can both pass the validator. The validator is for a *friendly message*; back it with a real **unique index** on the name (a MongoDB unique index, or an EF `HasIndex(...).IsUnique()`) so the database is the final authority.

## The UI already knows

[Section titled “The UI already knows”](#the-ui-already-knows)

Here’s the part that feels like a gift. You didn’t touch the React code from chapter 1 — but the form now validates.

When you wrote the `ConceptValidator`, the proxy generator extracted that rule into the generated TypeScript too, so the `CommandDialog` runs it **on the client** and disables the confirm button on a blank name — no round trip. The uniqueness rule can’t run on the client (it has to look in the database), so it runs on the server; when it rejects, the message comes back through the same proxy and `CommandDialog` renders it against the form — *“An author with that name is already registered.”* — because the dialog wires command results to fields for you.

AddAuthor.tsx — unchanged from chapter 1

```tsx
<CommandDialog<RegisterAuthor> command={RegisterAuthor} title="Add author" okLabel="Add">
    <InputTextField<RegisterAuthor> value={i => i.name} title="Name" />
</CommandDialog>
```

One rule on the value type, one rule on the command, and both ends of the app honor them — because the validation, like the types, flows from one source.

## What you built

[Section titled “What you built”](#what-you-built)

* An `AuthorNameValidator` that guards the **value type**, enforced everywhere an `AuthorName` is used and run client-side through the generated proxy.
* A `RegisterAuthorValidator` **business rule** that checks existing state in the database, with a unique index behind it for the hard guarantee.
* A React form that surfaces both — client-side and server-side — with no extra frontend code.

Our author is trustworthy now. But an author with no books is a lonely thing. Next we’ll give them a catalog — a second feature that *relates* to this one. [Let’s add books →](/arc/tutorial/books-and-relationships/)

# Understanding identity and access

> Who the user is, what they are allowed to do, and whose data they can see — how Arc handles identity enrichment, role-based authorization on commands and queries, and multi-tenant isolation, with one identity model that reaches the React frontend.

Three questions run through every real application: **who is this user**, **what are they allowed to do**, and — if you serve more than one customer — **whose data are they allowed to see**. Arc answers all three at the boundary, so your command and query code stays about the domain, not about access checks. This page is the mental model; each section links to the reference that goes deeper.

## Who is the user — identity, enriched once

[Section titled “Who is the user — identity, enriched once”](#who-is-the-user--identity-enriched-once)

A token from your identity provider (Entra ID, Auth0, whatever) knows the basics — an id, a name, some claims. It does *not* know that this user is a *Librarian* who may edit the catalog. That domain knowledge lives in your system, and Arc gives you one place to add it.

You implement `IProvideIdentityDetails<TDetails>`. Arc calls it at ingress with the provider’s token, you enrich it with whatever your domain needs, and you say whether the user is allowed in at all:

```csharp
public class LibraryIdentityProvider(IMongoCollection<Member> members)
    : IProvideIdentityDetails<LibraryIdentity>
{
    public async Task<IdentityDetails> Provide(IdentityProviderContext context)
    {
        // Look the user up in your own data, keyed by the provider's id.
        var member = await members.Find(m => m.Subject == context.Id.Value).FirstOrDefaultAsync();
        if (member is null)
            return new IdentityDetails(false, LibraryIdentity.None);   // not authorized → 403

var identity = new LibraryIdentity(member.Id, member.Role, member.Name);
        return new IdentityDetails(true, identity);
    }
}
```

```
no

yes

Provider token — id · name · claims

IProvideIdentityDetails.Provide()

IsUserAuthorized?

HTTP 403

IdentityDetails — your domain identity

.cratis-identity cookie

Frontend — typed identity
```

Two things fall out of this design:

* **Authorization at the front door.** Returning `IsUserAuthorized: false` stops an unwanted user before a single command runs — Arc returns `403` and they never reach your app.
* **One identity, backend to browser.** The details you return are published as a `.cratis-identity` cookie and consumed, typed, on the React side — the same way commands and queries are. You enrich identity once and read it everywhere. (Details: [Identity](/arc/backend/identity/), [contracts](/arc/backend/identity/contracts/), and [on the frontend](/arc/frontend/react/identity/).)

This is where 'blocked', 'trial expired', and 'which tenant' belong

Anything you compute about the user up front — their role, whether they’re blocked, their tenant, their feature flags — belongs in the details payload. Compute it once here instead of re-deriving it in every handler.

## What can they do — authorize commands and queries

[Section titled “What can they do — authorize commands and queries”](#what-can-they-do--authorize-commands-and-queries)

Once you know who the user is, you gate *what they can do* with attributes, right on the command or query — no checks scattered through your logic:

```csharp
[Roles("Librarian")]                       // only a Librarian may register an author
[Command]
public record RegisterAuthor(AuthorId Id, AuthorName Name)
{
    public AuthorRegistered Handle() => new(Name);
}

[ReadModel]
public record Author(AuthorId Id, AuthorName Name)
{
    [AllowAnonymous]                        // the public catalog is open to everyone
    public static ISubject<IEnumerable<Author>> AllAuthors(IMongoCollection<Author> c) => c.Observe();
}
```

* `[Authorize]` requires an authenticated user; `[Roles("Librarian", "Admin")]` requires **at least one** of the listed roles; `[AllowAnonymous]` opens a specific endpoint back up.
* Apply them at the **class level** to cover everything and **override per method** for exceptions — secure by default, opt out where you mean it.
* A failure is automatic: `401` if authentication stops the request before Arc runs, `403` if Arc’s command or query pipeline rejects the signed-in user. Pipeline authorization failures are surfaced in the generated command/query result as `isAuthorized: false`, so the UI can react.

When a rule is about *this specific row* — “you can only edit your own profile” — that’s not an attribute, it’s a check inside `Handle()` against the current user. (Full matrix, claims access, and inheritance rules: [Authorization](/arc/backend/core/authorization/).)

## Whose data — multi-tenancy

[Section titled “Whose data — multi-tenancy”](#whose-data--multi-tenancy)

If one deployment serves many customers, *who* and *what* aren’t enough — you need *whose*. Arc treats the **tenant** as a first-class part of every request: it resolves a tenant id, keeps it in context for the whole request, and points tenant-aware stores at the right data.

The shape of it:

1. A **resolver** establishes the tenant for each request — from a claim, a header, a subdomain — *after* authentication, so a user can’t ask for a tenant they don’t belong to.
2. The tenant id is available everywhere through **tenant context**, so you never thread it by hand.
3. **Tenant-aware data stores** (a database per tenant, or a partition) keep one customer’s events and read models physically apart from another’s — isolation by construction, not by remembering to add a `WHERE tenantId =` to every query.

Resolve the tenant after you authenticate

Tenant id is sensitive. Resolve it from authenticated claims, validate membership, and never trust a raw header or query parameter — otherwise tenant isolation is one spoofed value away from breaking. In production, [Cratis AuthProxy](/authproxy/) can take this on at the edge: it strips spoofable identity and tenant headers from every inbound request, resolves the tenant after the user signs in, and validates it before the request reaches your app.

Set it up with [tenant resolvers](/arc/backend/tenancy/resolvers/), reach it through [tenant context](/arc/backend/tenancy/tenant-context/), and isolate storage with [database resolvers](/arc/backend/tenancy/database-resolvers/) — the [tenancy overview](/arc/backend/tenancy/) ties them together.

## Where to go next

[Section titled “Where to go next”](#where-to-go-next)

* [Identity](/arc/backend/identity/) — the provider flow, contracts, and multi-service topologies in full.
* [Authorization](/arc/backend/core/authorization/) — every attribute, the inheritance rules, and claims-based custom logic.
* [Tenancy](/arc/backend/tenancy/) — resolvers, context, and per-tenant data isolation.
* [Microsoft Identity headers](/arc/backend/asp-net-core/microsoft-identity/) — accepting the `x-ms-client-principal` family of HTTP headers from your ingress. Azure services emit them out of the box, but any identity provider or proxy can supply them.

# Understanding the proxy boundary

> How Cratis keeps your C# backend and your React frontend in lockstep — the generated, typed proxy boundary at the heart of full-stack type safety, and what keeps the two languages honest.

Every full-stack app has a seam down the middle: C# on one side, TypeScript on the other, HTTP in between. Normally *you* are the glue across that seam — you write a controller, hand-write a DTO, redeclare its shape in TypeScript, wrap it in a `fetch`, and then spend the rest of the project keeping both sides in agreement. Nothing tells you when they drift: a renamed field compiles happily on each side and fails in the browser at runtime.

Arc removes that seam. You write the command or query **once, in C#**, and the build generates the TypeScript your frontend calls. There’s no second declaration to keep in sync, because there’s no second declaration at all. This page is about *why that works* and *what keeps it honest* — the idea at the center of everything Cratis calls “full-stack type safety.”

## One source of truth

[Section titled “One source of truth”](#one-source-of-truth)

The thing to internalize: **your C# command and query records are the contract.** The TypeScript proxy isn’t a parallel definition you maintain — it’s a *projection* of the C# types, regenerated on every build. There is exactly one place the shape of `RegisterAuthor` is defined, and it’s the C# record.

```
dotnet build · Roslyn generator

import + call

HTTP — typed both ends

C# record — [Command] RegisterAuthor

generated TS proxy — RegisterAuthor

React — CommandDialog · .use()
```

Because the proxy is generated from the very types Arc uses to bind the incoming HTTP request, the client and the server *can’t* disagree about the wire format. The compiler — on **both** sides — is enforcing one contract.

## Walk the boundary

[Section titled “Walk the boundary”](#walk-the-boundary)

1. **Write the slice in C#.** A command is a record; the behavior lives in `Handle()` on the record. This is the only place the shape is declared:

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

2. **Build.** `dotnet build` runs the Arc proxy generator — a Roslyn source generator wired in as an MSBuild step. It reads your compiled assembly, finds every `[Command]`, every `[ReadModel]` query method, and the types and enums they touch, and writes a typed TypeScript proxy for each — mirroring your namespace folders, with an `index.ts` per folder.

3. **Import the proxy in React.** It’s already there, generated from the C# above — call it as if it were local, typed code:

```tsx
   import { RegisterAuthor } from './Authors/RegisterAuthor';   // generated

<CommandDialog command={RegisterAuthor} title="Add author">
       <InputTextField<RegisterAuthor> value={i => i.name} title="Name" />
   </CommandDialog>
   ```

## What keeps it honest

[Section titled “What keeps it honest”](#what-keeps-it-honest)

Here’s the payoff — and the whole reason the boundary is *generated* rather than written. Suppose you rename `Name` to `FullName` on the command:

* C# — backend

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

* TypeScript — frontend

```tsx
  // After `dotnet build`, the generated proxy has `fullName`, not `name`.
  // This line stops compiling until you fix it — caught at build, not in production:
  <InputTextField<RegisterAuthor> value={i => i.name} title="Name" />
  //                                         ^^^^ Property 'name' does not exist on RegisterAuthor
  ```

You didn’t run the app. You didn’t open the browser. The TypeScript compiler caught the drift the instant the contract changed, because the accessor `i => i.name` points at a property the regenerated type no longer has. That’s the difference between a generated boundary and a hand-written one: drift is a **compile error**, not a **production incident**.

The read side is just as honest

Rename a field on a `[ReadModel]`, rebuild, and every component reading it through the generated query proxy stops compiling the same way. The contract holds in both directions — commands you send and data you read.

## What gets generated

[Section titled “What gets generated”](#what-gets-generated)

Each build, Arc emits typed proxies for:

* **Commands** — a class you instantiate and execute (or hand to a `CommandDialog`), with every parameter — route, query string, body — flattened into typed properties.
* **Queries** — a proxy exposing a React `.use()` hook that returns the typed result with its loading and error state; **observable** queries return a live subscription that re-renders on change — no polling, no manual refresh.
* **Types and enums** — every complex type and enum your commands and queries reference, so nested shapes are typed too.
* **Identity details** — your custom identity type, so the signed-in user is typed on the frontend.

Each has a detailed reference: [Commands](/arc/backend/proxy-generation/commands/), [Queries](/arc/backend/proxy-generation/queries/), and [Identity details](/arc/backend/proxy-generation/identity-details/). The [frontend proxy-generation guide](/arc/frontend/react/proxy-generation/) shows the generated TypeScript for each, with the `.use()` and `useSuspense()` hooks.

## The transport disappears too

[Section titled “The transport disappears too”](#the-transport-disappears-too)

Types are only half of what the proxy absorbs. The other half is **how the call travels**. Your component never writes a URL, picks an HTTP verb, or opens a socket — it executes `RegisterAuthor` or renders `AllAuthors.use()`, and the proxy owns the wire. That makes the transport an implementation detail behind the boundary: today the calls ride HTTP, and if Arc carried them over something else — gRPC-Web, say — the proxy is where that would change, not your components.

The query system already cashes in on this freedom. A regular query executes as a plain HTTP request. An observable query streams — over WebSockets or Server-Sent Events, a choice you make once with the `queryTransportMethod` prop on the [`<Arc/>` context component](/arc/frontend/react/arc/), not in any component. And the same observable query can still be executed as a one-shot HTTP fetch by calling `perform()` on the proxy, when you want a snapshot instead of a subscription:

```tsx
const [authors] = AllAuthors.use();                  // live — streams over WebSockets or SSE
const snapshot = await new AllAuthors().perform();   // one-shot — a plain HTTP fetch, same proxy
```

One definition in C#, one proxy in TypeScript — and whether the data arrives as a response or a stream is the proxy’s concern, not yours. Tune the live transport in the [query configuration reference](/arc/frontend/react/queries/configuration/).

## It’s a build step, not a checkout

[Section titled “It’s a build step, not a checkout”](#its-a-build-step-not-a-checkout)

A few things follow from the proxies being *generated*, and they’re worth holding onto:

* **You never edit a generated file.** Treat the generated folder like build output — change the C#, rebuild, and the TypeScript follows.
* **The generator tracks what it made** and removes files for commands or queries you delete, so the generated tree doesn’t accumulate ghosts. (See [File index tracking](/arc/backend/proxy-generation/file-index-tracking/).)
* **The sequencing is fixed:** backend compiles → proxies generate → the frontend can reference them. For a single slice you can’t build the React half before the C# half compiles — which is exactly why the workflow is backend-first.

## Why this is the thing that matters

[Section titled “Why this is the thing that matters”](#why-this-is-the-thing-that-matters)

Plenty of frameworks give you CQRS, or an event store, or a component library. The proxy boundary is what makes Cratis **full-stack**: the type safety doesn’t stop at the edge of the backend — it runs all the way to the React component. It’s why a Cratis feature is *one* thing expressed in two languages, kept in agreement by the build instead of by discipline.

Ready to see it run? [Build your first command and query](/arc/backend/getting-started/your-first-command/), then [wire it into React](/arc/frontend/getting-started/) — and watch the same property name flow from C# all the way to the screen.

# Vertical slices

> Why a Cratis feature keeps its backend and frontend together in one folder — and why that beats organizing code by technical layer.

We strongly recommend organizing a Cratis application by **feature**, not by technical layer. Nothing in the framework enforces this — Arc discovers your commands and read models wherever they live — but we recommend it emphatically, because high cohesion and low coupling fall out of the shape almost for free. Everything for one behavior — the command that writes state, the read model and query that serve it, the React component that renders it, and the specs that prove it — lives together in a single folder. That folder is a **vertical slice**, and the slice folders inside a feature map directly onto the timeline an [event model](/event-modeling/) lays out.

This page explains *why*. If you want to see one built, the [capstone walkthrough](/build-a-full-app/) does exactly that.

## The pain it removes

[Section titled “The pain it removes”](#the-pain-it-removes)

In a layer-organized codebase, one feature is smeared across the tree:

```shell
❌ Organized by layer — "register author" touches five folders
Commands/RegisterAuthor.cs
Handlers/RegisterAuthorHandler.cs
Dtos/AuthorDto.cs
Clients/AuthorsClient.ts
web/src/features/authors/AddAuthor.tsx
```

To change how authors register, you open five folders, hold the whole layer cake in your head, and hope you didn’t miss a place. New contributors have to learn *every* layer before they can touch *one* feature.

A vertical slice puts the whole feature in one place:

```shell
✅ Organized by feature — one folder, read top to bottom
Authors/Registration/
├── Registration.cs        # command + Handle() + read model + query
├── AddAuthor.tsx          # the React screen
└── when_registering/      # the specs
```

You navigate by *what the software does*, not by *what kind of file it is*.

## Why the frontend and backend belong together

[Section titled “Why the frontend and backend belong together”](#why-the-frontend-and-backend-belong-together)

This is the part that surprises people coming from a layered or separate-repo world. Cratis deliberately keeps the C# backend and the React frontend of a feature side by side. Three reasons:

1. **A feature is one thing, and it spans the stack.** “Register an author” is not a backend task and a frontend task — it’s *one* behavior with a write side and a read side. The command, the query, and the form are different facets of the same change. They are conceived together, they change together, and a bug usually lives in the handoff between them. Keeping them adjacent means one mental context and, often, one pull request.

2. **Full-stack type safety binds them anyway.** Arc generates the TypeScript proxies for a command or query from your C# types. The frontend literally depends on the backend’s shapes — so when you rename a property in the command, the React code stops compiling until you fix it. Co-locating makes that feedback loop tight: the thing that broke is *right next to* the thing that changed, and the compiler points you straight at it. Separating them across folders or repos hides that relationship without removing it.

3. **High cohesion, low coupling — by construction.** Everything a feature needs is in its folder (cohesion); features don’t reach into each other’s internals, they communicate through commands, queries, and shared contracts (low coupling). Layering inverts this: it scatters one feature (low cohesion) and tempts every feature to share the same fat “service” or “models” layer (high coupling). Slices keep changes local, so you can build, change, and even delete a feature without ripping through unrelated code.

```
One feature folder

generated proxy

writes

query proxy

AddAuthor.tsx

RegisterAuthor.Handle()

MongoDB / EF Core

Author read model

Authors.tsx
```

None of this dictates your repository layout, though. The proxy generator writes the TypeScript wherever you point it — the `CratisProxiesOutputPath` MSBuild property in your backend project sets the output folder, which can just as well be a separate frontend folder or another checkout entirely. If your team keeps backend and frontend apart, Arc follows your structure and the type safety holds across the distance. We co-locate because the feedback loop in point 2 is at its tightest when the generated proxy sits next to the command it mirrors — a strong preference, not a requirement.

## What lives in a slice

[Section titled “What lives in a slice”](#what-lives-in-a-slice)

A single backend `.cs` file can hold the backend artifacts for the behavior — the `[Command]` with its `Handle()`, validators, and the `[ReadModel]` with its query methods. Alongside it sit the React component(s) that consume the generated proxies, and the specs. Arc’s convention-based discovery means none of it needs registration or wiring — the slice folder is self-contained and reads top to bottom.

## Slice types

[Section titled “Slice types”](#slice-types)

Not every slice does the same job. There are four kinds — the same building blocks an event model lays out on its timeline:

| Type             | Purpose                                                                                |
| ---------------- | -------------------------------------------------------------------------------------- |
| **State change** | Mutates state — a command that writes to MongoDB, EF Core, or an optional event store. |
| **State view**   | Serves current state through a queryable read model.                                   |
| **Automation**   | Runs side effects after a command or, with Chronicle, reacts to stored events.         |
| **Translation**  | Adapts input from one slice/system by triggering a command in another.                 |

## The one nuance

[Section titled “The one nuance”](#the-one-nuance)

Co-location is about a *behavior*, not duplication. Things genuinely shared between slices — a [concept](/fundamentals/) like `AuthorId`, a shared read model contract, or a domain fact used by more than one feature — move up to the feature root or a shared location, not copied into every slice. The rule of thumb: if it belongs to one behavior, it lives in that slice; if it’s truly shared, lift it just high enough to be shared and no higher.

## See also

[Section titled “See also”](#see-also)

* [Build a full-stack feature](/build-a-full-app/) — a slice built end to end.
* [Why Arc](/arc/why-arc/) — the framework that makes slices low-ceremony.
* [MediatR, MVC, and Arc](/arc/coming-from-mediatr-and-mvc/) — how this differs from layered controllers/handlers.

# Why Arc

> The problem Arc solves, why it leans on CQRS and proxy generation, and how it keeps a full-stack app type-safe end to end.

Building a modern full-stack application means making the same decisions over and over: how do commands get validated, how do queries get shaped, how does the React frontend learn the exact types the backend expects, and how do you keep all of it in sync as the code changes. Most teams answer these with a stack of libraries and a layer of hand-written glue — controllers, DTOs, fetch wrappers, validation duplicated on both sides.

Arc answers them once, with conventions, so you can spend your time on behavior instead of plumbing.

For Cratis, event sourcing is usually the default persistence architecture for information systems, and Chronicle is where that lives. Arc’s job is different: it gives you the CQRS boundary for information going into and out of the system, then generates the frontend contract from that boundary. CQRS and event sourcing fit together naturally, but one does not require the other.

## What Arc gives you

[Section titled “What Arc gives you”](#what-arc-gives-you)

* **Commands and queries as the unit of work.** A command is a record with a `Handle()` method — no separate handler class, no controller boilerplate. A query is a method on a read model. Arc maps them to HTTP automatically.
* **Generated TypeScript proxies.** Every command and query becomes a typed client your React code calls. Change a command’s shape in C# and the frontend types change with it — the compiler catches the mismatch, not your users.
* **Pluggable persistence.** Commands and queries read and write wherever you point them — [Chronicle](/arc/backend/chronicle/) for event-sourced information systems, or [MongoDB](/arc/backend/mongodb/) and [EF Core / SQL](/arc/backend/entity-framework/) for current-state slices. With Chronicle, every command is a transactional scope: the events it returns commit atomically — or not at all.
* **The cross-cutting concerns handled for you.** Validation, authorization, identity, multi-tenancy, OpenAPI, and MongoDB/EF Core integration are conventions, not assignments.

## Why CQRS and proxy generation

[Section titled “Why CQRS and proxy generation”](#why-cqrs-and-proxy-generation)

The two ideas reinforce each other. CQRS separates the thing you *do* (a command) from the thing you *see* (a query/read model), which keeps each side simple and independently optimizable. Proxy generation then makes that separation safe across the network: because the client is generated from the same C# types, there is no second source of truth to drift.

CQRS is often associated with event sourcing because events are a natural write-side model and projections are a natural read-side model. But CQRS is not event sourcing. Arc can put that boundary over Chronicle, MongoDB, or EF Core; Chronicle can store and process events without Arc.

```
generated proxy

writes

query proxy

React (Components)

Command.Handle()

MongoDB / EF Core

Read model
```

That diagram is the direct-database setup, useful for bounded current-state slices and for learning Arc in isolation. In the full Cratis loop, the [Chronicle integration](/arc/backend/chronicle/add-event-sourcing/) changes the write side to events without moving the query or React screen.

## Vertical slices, not layers

[Section titled “Vertical slices, not layers”](#vertical-slices-not-layers)

Arc doesn’t impose a folder structure, but it’s built to make one shine: organize the application by **feature**, with a folder per slice inside it — the shape [event modeling](/event-modeling/) gives you. Everything for one behavior — the command, the read model and query it serves, the React component that renders it, and the specs that prove it — then lives in one folder, and you read a feature top to bottom instead of hunting across `Commands/`, `Handlers/`, `DTOs`, and `Clients/`.

## Where to start

[Section titled “Where to start”](#where-to-start)

* Build your first feature in the [getting started](/arc/backend/getting-started/) guide.
* Walk the full database-backed path in the [Arc tutorial](/arc/tutorial/).
* Need the wider stack? [Why developers choose Cratis](/why-cratis/) shows how Arc, Chronicle, Components, and the tools fit together.

# Cratis Architecture Documentation

This documentation covers the Cratis Architecture analyzer package and its rule set.

* Start with the [code analysis overview](/architecture/codeanalysis/)
* Browse the complete [rule reference](/architecture/codeanalysis/rules/)

# Code Analysis

Cratis Architecture ships Roslyn analyzers that enforce architectural and coding conventions across Cratis codebases.

## Goals

[Section titled “Goals”](#goals)

* Keep architectural intent enforceable
* Surface violations as early as possible
* Give developers and agents clear, actionable feedback

## Rules Overview

[Section titled “Rules Overview”](#rules-overview)

| Rule ID                                                                                          | Title                                 | Severity | Description                                                                              |
| ------------------------------------------------------------------------------------------------ | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| [CRARCH0001](/architecture/codeanalysis/rules/crarch0001-exception-type-naming/)                 | Exception type naming                 | Warning  | Exception types must use domain terminology and avoid the generic Exception suffix       |
| [CRARCH0002](/architecture/codeanalysis/rules/crarch0002-no-built-in-exception-types/)           | No built-in exception types           | Warning  | Throwing framework exceptions hides domain intent                                        |
| [CRARCH0003](/architecture/codeanalysis/rules/crarch0003-no-postfixes-on-class-names/)           | No postfixes on class names           | Warning  | Class names must describe domain concepts, not technical roles                           |
| [CRARCH0004](/architecture/codeanalysis/rules/crarch0004-no-features-in-namespace/)              | No Features in namespace              | Warning  | Namespace paths should stay domain-oriented and avoid framework-driven structure names   |
| [CRARCH0005](/architecture/codeanalysis/rules/crarch0005-no-regions/)                            | No regions                            | Warning  | Region directives usually indicate files that need better separation of responsibilities |
| [CRARCH0006](/architecture/codeanalysis/rules/crarch0006-logging-via-loggermessage/)             | Logging via LoggerMessage             | Warning  | Structured, source-generated logging ensures consistency and better performance          |
| [CRARCH0007](/architecture/codeanalysis/rules/crarch0007-no-iserviceprovider-injection/)         | No IServiceProvider injection         | Warning  | Service locator patterns hide dependencies and make code harder to reason about          |
| [CRARCH0008](/architecture/codeanalysis/rules/crarch0008-use-is-null-checks/)                    | Use is null checks                    | Warning  | Pattern matching null checks are the preferred and consistent style                      |
| [CRARCH0009](/architecture/codeanalysis/rules/crarch0009-use-string-interpolation/)              | Use string interpolation              | Warning  | Interpolated strings are clearer and easier to maintain                                  |
| [CRARCH0010](/architecture/codeanalysis/rules/crarch0010-constructor-fan-out/)                   | Constructor fan-out                   | Warning  | Too many dependencies indicate excessive responsibility in one type                      |
| [CRARCH0011](/architecture/codeanalysis/rules/crarch0011-file-length-threshold/)                 | File length threshold                 | Warning  | Very large files are difficult to understand and maintain                                |
| [CRARCH0012](/architecture/codeanalysis/rules/crarch0012-async-void-forbidden/)                  | async void forbidden                  | Error    | async void methods hide failures and cannot be awaited in regular flows                  |
| [CRARCH0013](/architecture/codeanalysis/rules/crarch0013-no-blocking-on-async/)                  | No blocking on async                  | Warning  | Blocking asynchronous calls can cause deadlocks and reliability issues                   |
| [CRARCH0014](/architecture/codeanalysis/rules/crarch0014-no-test-types-in-production/)           | No test types in production           | Error    | Production assemblies must remain independent of test-only infrastructure                |
| [CRARCH0015](/architecture/codeanalysis/rules/crarch0015-static-class-naming-convention/)        | Static class naming convention        | Warning  | Static utility types follow strict naming conventions to improve discoverability         |
| [CRARCH0016](/architecture/codeanalysis/rules/crarch0016-unused-interfaces/)                     | Unused interfaces                     | Warning  | Speculative interfaces without implementations add unnecessary abstraction               |
| [CRARCH0017](/architecture/codeanalysis/rules/crarch0017-namespace-must-align-with-folder-path/) | Namespace must align with folder path | Warning  | Namespace and folder alignment improves navigability and consistency                     |
| [CRARCH0018](/architecture/codeanalysis/rules/crarch0018-avoid-concrete-type-injection/)         | Avoid concrete type injection         | Warning  | Constructor dependencies should favor abstractions for loose coupling                    |
| [CRARCH0019](/architecture/codeanalysis/rules/crarch0019-avoid-async-postfix-on-method-names/)   | Avoid Async postfix on method names   | Warning  | Method names should avoid unnecessary suffixes unless sync/async pairs exist             |
| [CRARCH0020](/architecture/codeanalysis/rules/crarch0020-handle-asynchronous-calls/)             | Handle asynchronous calls             | Warning  | Fire-and-forget calls can hide failures and produce nondeterministic behavior            |
| [CRARCH0021](/architecture/codeanalysis/rules/crarch0021-serializable-attribute-not-allowed/)    | Serializable attribute not allowed    | Warning  | Legacy serialization attributes are not part of modern Cratis architecture guidance      |
| [CRARCH0022](/architecture/codeanalysis/rules/crarch0022-private-modifier-not-allowed/)          | Private modifier not allowed          | Warning  | Private is implicit in C#, so explicit modifiers add noise                               |
| [CRARCH0023](/architecture/codeanalysis/rules/crarch0023-use-typed-logger-category/)             | Use typed logger category             | Warning  | Typed logger categories align log events with the producing type                         |
| [CRARCH0024](/architecture/codeanalysis/rules/crarch0024-loggermessage-container-conventions/)   | LoggerMessage container conventions   | Warning  | LoggerMessage methods must live in convention-based containers for consistency           |
| [CRARCH0025](/architecture/codeanalysis/rules/crarch0025-use-cratis-fundamentals-traces/)        | Use Cratis Fundamentals traces        | Warning  | Tracing should flow through Cratis Fundamentals abstractions for consistency             |
| [CRARCH0026](/architecture/codeanalysis/rules/crarch0026-use-cratis-fundamentals-metrics/)       | Use Cratis Fundamentals metrics       | Warning  | Metrics should use Cratis Fundamentals abstractions instead of raw instrument creation   |

# Rule Reference

This reference lists all diagnostics in `Cratis.Architecture.CodeAnalysis`.

| Rule                                                                                             | Title                                 | Severity | Description                                                                              |
| ------------------------------------------------------------------------------------------------ | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| [CRARCH0001](/architecture/codeanalysis/rules/crarch0001-exception-type-naming/)                 | Exception type naming                 | Warning  | Exception types must use domain terminology and avoid the generic Exception suffix       |
| [CRARCH0002](/architecture/codeanalysis/rules/crarch0002-no-built-in-exception-types/)           | No built-in exception types           | Warning  | Throwing framework exceptions hides domain intent                                        |
| [CRARCH0003](/architecture/codeanalysis/rules/crarch0003-no-postfixes-on-class-names/)           | No postfixes on class names           | Warning  | Class names must describe domain concepts, not technical roles                           |
| [CRARCH0004](/architecture/codeanalysis/rules/crarch0004-no-features-in-namespace/)              | No Features in namespace              | Warning  | Namespace paths should stay domain-oriented and avoid framework-driven structure names   |
| [CRARCH0005](/architecture/codeanalysis/rules/crarch0005-no-regions/)                            | No regions                            | Warning  | Region directives usually indicate files that need better separation of responsibilities |
| [CRARCH0006](/architecture/codeanalysis/rules/crarch0006-logging-via-loggermessage/)             | Logging via LoggerMessage             | Warning  | Structured, source-generated logging ensures consistency and better performance          |
| [CRARCH0007](/architecture/codeanalysis/rules/crarch0007-no-iserviceprovider-injection/)         | No IServiceProvider injection         | Warning  | Service locator patterns hide dependencies and make code harder to reason about          |
| [CRARCH0008](/architecture/codeanalysis/rules/crarch0008-use-is-null-checks/)                    | Use is null checks                    | Warning  | Pattern matching null checks are the preferred and consistent style                      |
| [CRARCH0009](/architecture/codeanalysis/rules/crarch0009-use-string-interpolation/)              | Use string interpolation              | Warning  | Interpolated strings are clearer and easier to maintain                                  |
| [CRARCH0010](/architecture/codeanalysis/rules/crarch0010-constructor-fan-out/)                   | Constructor fan-out                   | Warning  | Too many dependencies indicate excessive responsibility in one type                      |
| [CRARCH0011](/architecture/codeanalysis/rules/crarch0011-file-length-threshold/)                 | File length threshold                 | Warning  | Very large files are difficult to understand and maintain                                |
| [CRARCH0012](/architecture/codeanalysis/rules/crarch0012-async-void-forbidden/)                  | async void forbidden                  | Error    | async void methods hide failures and cannot be awaited in regular flows                  |
| [CRARCH0013](/architecture/codeanalysis/rules/crarch0013-no-blocking-on-async/)                  | No blocking on async                  | Warning  | Blocking asynchronous calls can cause deadlocks and reliability issues                   |
| [CRARCH0014](/architecture/codeanalysis/rules/crarch0014-no-test-types-in-production/)           | No test types in production           | Error    | Production assemblies must remain independent of test-only infrastructure                |
| [CRARCH0015](/architecture/codeanalysis/rules/crarch0015-static-class-naming-convention/)        | Static class naming convention        | Warning  | Static utility types follow strict naming conventions to improve discoverability         |
| [CRARCH0016](/architecture/codeanalysis/rules/crarch0016-unused-interfaces/)                     | Unused interfaces                     | Warning  | Speculative interfaces without implementations add unnecessary abstraction               |
| [CRARCH0017](/architecture/codeanalysis/rules/crarch0017-namespace-must-align-with-folder-path/) | Namespace must align with folder path | Warning  | Namespace and folder alignment improves navigability and consistency                     |
| [CRARCH0018](/architecture/codeanalysis/rules/crarch0018-avoid-concrete-type-injection/)         | Avoid concrete type injection         | Warning  | Constructor dependencies should favor abstractions for loose coupling                    |
| [CRARCH0019](/architecture/codeanalysis/rules/crarch0019-avoid-async-postfix-on-method-names/)   | Avoid Async postfix on method names   | Warning  | Method names should avoid unnecessary suffixes unless sync/async pairs exist             |
| [CRARCH0020](/architecture/codeanalysis/rules/crarch0020-handle-asynchronous-calls/)             | Handle asynchronous calls             | Warning  | Fire-and-forget calls can hide failures and produce nondeterministic behavior            |
| [CRARCH0021](/architecture/codeanalysis/rules/crarch0021-serializable-attribute-not-allowed/)    | Serializable attribute not allowed    | Warning  | Legacy serialization attributes are not part of modern Cratis architecture guidance      |
| [CRARCH0022](/architecture/codeanalysis/rules/crarch0022-private-modifier-not-allowed/)          | Private modifier not allowed          | Warning  | Private is implicit in C#, so explicit modifiers add noise                               |
| [CRARCH0023](/architecture/codeanalysis/rules/crarch0023-use-typed-logger-category/)             | Use typed logger category             | Warning  | Typed logger categories align log events with the producing type                         |
| [CRARCH0024](/architecture/codeanalysis/rules/crarch0024-loggermessage-container-conventions/)   | LoggerMessage container conventions   | Warning  | LoggerMessage methods must live in convention-based containers for consistency           |
| [CRARCH0025](/architecture/codeanalysis/rules/crarch0025-use-cratis-fundamentals-traces/)        | Use Cratis Fundamentals traces        | Warning  | Tracing should flow through Cratis Fundamentals abstractions for consistency             |
| [CRARCH0026](/architecture/codeanalysis/rules/crarch0026-use-cratis-fundamentals-metrics/)       | Use Cratis Fundamentals metrics       | Warning  | Metrics should use Cratis Fundamentals abstractions instead of raw instrument creation   |

# CRARCH0001 Exception type naming

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0001`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Exception types must use domain terminology and avoid the generic Exception suffix.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Exception type '{0}' must not end with 'Exception'`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Rename the exception type to a domain-focused name, such as `AuthorNotFound` instead of `AuthorNotFoundException`.

# CRARCH0002 No built-in exception types

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0002`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Throwing framework exceptions hides domain intent.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Throw custom domain exceptions instead of '{0}'`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Replace built-in exceptions with custom domain exceptions that describe the business error.

# CRARCH0003 No postfixes on class names

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0003`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Class names must describe domain concepts, not technical roles.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Class '{0}' must not end with postfix '{1}'`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Remove postfixes like `Async`, `Impl`, `Manager`, `Helper`, and `Service` from class names.

# CRARCH0004 No Features in namespace

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0004`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Namespace paths should stay domain-oriented and avoid framework-driven structure names.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Namespace '{0}' must not contain '.Features.'`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Remove the `.Features.` segment from the namespace and align it with the domain path.

# CRARCH0005 No regions

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0005`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Region directives usually indicate files that need better separation of responsibilities.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Avoid #region directives`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Split large types or methods into focused units instead of organizing with `#region`.

# CRARCH0006 Logging via LoggerMessage

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0006`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Structured, source-generated logging ensures consistency and better performance.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Use [LoggerMessage] generated methods instead of direct ILogger.Log* calls`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Define and use `[LoggerMessage]` methods in `*LogMessages` classes instead of direct log calls.

# CRARCH0007 No IServiceProvider injection

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0007`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Service locator patterns hide dependencies and make code harder to reason about.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Do not inject IServiceProvider; inject specific interfaces`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Inject explicit interfaces in constructors instead of `IServiceProvider`.

# CRARCH0008 Use is null checks

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0008`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Pattern matching null checks are the preferred and consistent style.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Use 'is null'/'is not null' instead of '== null'/'!= null'`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Rewrite null checks to use `is null` and `is not null`.

# CRARCH0009 Use string interpolation

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0009`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Interpolated strings are clearer and easier to maintain.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Use string interpolation instead of string.Format or concatenation`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Replace `string.Format` and string concatenation with interpolated strings.

# CRARCH0010 Constructor fan-out

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0010`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Too many dependencies indicate excessive responsibility in one type.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Constructor has {0} dependencies (maximum is 7)`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Refactor to reduce constructor dependencies to seven or fewer.

# CRARCH0011 File length threshold

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0011`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Very large files are difficult to understand and maintain.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`File has {0} effective lines (maximum is 400)`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Split the file into smaller focused types or helper abstractions once the threshold is exceeded.

# CRARCH0012 async void forbidden

* **Category:** Architecture
* **Default severity:** Error
* **Diagnostic ID:** `CRARCH0012`

## What it checks

[Section titled “What it checks”](#what-it-checks)

`async void` methods hide failures and cannot be awaited in regular flows.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Avoid async void methods outside event handlers`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Change `async void` methods to `async Task` unless the method is an event handler.

# CRARCH0013 No blocking on async

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0013`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Blocking asynchronous calls can cause deadlocks and reliability issues.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Avoid blocking async calls via .Result, .Wait(), or .GetAwaiter().GetResult()`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Use `await` instead of blocking APIs on tasks.

# CRARCH0014 No test types in production

* **Category:** Architecture
* **Default severity:** Error
* **Diagnostic ID:** `CRARCH0014`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Production assemblies must remain independent of test-only infrastructure.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Production code must not reference testing/specification types: '{0}'`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Remove references to testing and specification types from production code.

# CRARCH0015 Static class naming convention

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0015`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Static utility types follow strict naming conventions to improve discoverability.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Static class '{0}' must end with one of: {1}`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Rename static classes to end with `Extensions`, `Converters`, `Ids`, `WellKnown`, or `Defaults`.

# CRARCH0016 Unused interfaces

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0016`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Speculative interfaces without implementations add unnecessary abstraction.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Interface '{0}' has no concrete implementations`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Remove unused interfaces or provide concrete implementations where needed.

# CRARCH0017 Namespace must align with folder path

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0017`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Namespace and folder alignment improves navigability and consistency.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Namespace '{0}' should align with folder path '{1}'`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Update the namespace or move the file so namespace segments match folder structure.

# CRARCH0018 Avoid concrete type injection

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0018`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Constructor dependencies should favor abstractions for loose coupling.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Constructor dependency '{0}' should be an interface abstraction`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Inject interfaces instead of concrete classes. Types marked with `[ReadModel]` are exempt.

# CRARCH0019 Avoid Async postfix on method names

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0019`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Method names should avoid unnecessary suffixes unless sync/async pairs exist.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Method '{0}' should not end with 'Async' unless a synchronous '{1}' method also exists`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Rename methods to remove the `Async` suffix unless a synchronous counterpart exists.

# CRARCH0020 Handle asynchronous calls

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0020`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Fire-and-forget calls can hide failures and produce nondeterministic behavior.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Asynchronous call '{0}' must be handled by awaiting it or chaining a continuation`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Await task-returning calls or explicitly chain a continuation.

# CRARCH0021 Serializable attribute not allowed

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0021`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Legacy serialization attributes are not part of modern Cratis architecture guidance.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Type '{0}' must not be marked with [Serializable]`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Remove `[Serializable]` from types.

# CRARCH0022 Private modifier not allowed

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0022`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Private is implicit in C#, so explicit modifiers add noise.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Avoid explicit 'private' modifier`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Remove explicit `private` modifiers, except for property setters where it remains allowed.

# CRARCH0023 Use typed logger category

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0023`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Typed logger categories align log events with the producing type.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Inject ILogger<{0}> instead of '{1}'`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Inject `ILogger<TContainingType>` instead of non-generic logger forms.

# CRARCH0024 LoggerMessage container conventions

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0024`

## What it checks

[Section titled “What it checks”](#what-it-checks)

LoggerMessage methods must live in convention-based containers for consistency.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Type '{0}' with [LoggerMessage] methods must be an internal static partial *LogMessages class`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Move `[LoggerMessage]` methods into `internal static partial` classes with a `LogMessages` suffix.

# CRARCH0025 Use Cratis Fundamentals traces

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0025`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Tracing should flow through Cratis Fundamentals abstractions for consistency.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Avoid direct ActivitySource.StartActivity usage`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Use `IActivitySource<T>`, `IActivityScope<T>`, and `[Span]` generated methods instead of direct `ActivitySource.StartActivity` calls.

# CRARCH0026 Use Cratis Fundamentals metrics

* **Category:** Architecture
* **Default severity:** Warning
* **Diagnostic ID:** `CRARCH0026`

## What it checks

[Section titled “What it checks”](#what-it-checks)

Metrics should use Cratis Fundamentals abstractions instead of raw instrument creation.

## Diagnostic message

[Section titled “Diagnostic message”](#diagnostic-message)

`Avoid direct Meter.{0} usage`

## How to resolve

[Section titled “How to resolve”](#how-to-resolve)

Use `IMeter<T>`, `IMeterScope<T>`, and generated metric methods instead of creating meter instruments directly.

# Auth and compliance end to end

> How authentication, tenant resolution, Arc authorization, Chronicle compliance subjects, PII encryption, read models, and erasure fit together across the Cratis stack.

Security in a Cratis application is not one feature in one package. A request crosses the edge, becomes an Arc command or query, writes events through Chronicle, builds read models, and comes back to a React screen. Authentication, authorization, tenant isolation, and compliance each belong to a different part of that journey, and the stack is designed so each concern has one clear owner.

The short version: **AuthProxy authenticates and resolves tenant context, Arc authorizes the operation, Chronicle stores events in the right namespace and encrypts PII by compliance subject, and Arc releases PII before query results reach the client.**

```
Tenant-ID + identity

events + subject

Browser or API client

AuthProxy

authenticate + resolve tenant

Arc /.cratis/me

identity enrichment

Arc commands and queries

authorize operation

Chronicle

tenant namespace

Event log

PII encrypted by subject

Read models

encrypted at rest

Arc read-model release

decrypts for response

Components / React

typed result
```

## The edge owns authentication

[Section titled “The edge owns authentication”](#the-edge-owns-authentication)

Put [AuthProxy](/authproxy/) in front of your frontend and backend services when you want one place to own the browser and API edge. It handles OpenID Connect, OAuth providers, JWT bearer authentication, provider selection, invite onboarding, tenant resolution, and routing.

AuthProxy then forwards requests with the resolved tenant and identity context. In an Arc application, the identity-enrichment endpoint is `/.cratis/me`: AuthProxy calls it, Arc composes the domain-specific identity payload, and the frontend can consume the resulting identity state instead of making every service rediscover the user.

Authentication is not authorization

Authentication answers “who is calling?” Tenant resolution answers “which tenant are they acting in?” Authorization answers “can they run this operation?” Compliance answers “whose personal data is this, and how is it protected?”

## Arc owns operation-level access

[Section titled “Arc owns operation-level access”](#arc-owns-operation-level-access)

Arc applies authorization where the behavior is declared: commands and queries. Use ASP.NET Core authorization attributes, Arc’s `[Roles]` convenience attribute, and policy-based authorization on the command record or read-model query method that represents the operation.

That matters because authorization happens before the behavior runs. If a command is not authorized, its `Handle()` method is not executed. If a query is not authorized, the read is not performed. The generated frontend proxy receives authorization state as part of the command or query result, so screens can react without hand-written protocol glue.

Use edge authentication for entry, then command/query authorization for business operations. Do not rely on the UI hiding a button as the only access-control layer.

## Tenant context follows the request into Chronicle

[Section titled “Tenant context follows the request into Chronicle”](#tenant-context-follows-the-request-into-chronicle)

In a multi-tenant Cratis application, the tenant resolved at the edge becomes application context in Arc. When Arc is integrated with Chronicle, that tenant context is used as the Chronicle namespace. Events, projections, reducers, and read models for one tenant stay separated from another tenant without every command manually choosing a namespace.

This is the operational boundary:

| Concern                                     | Owner                              | Result                                                                                    |
| ------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------- |
| Resolve the tenant                          | AuthProxy or Arc tenancy resolvers | One tenant id for the request                                                             |
| Carry tenant through command/query handling | Arc                                | Commands, queries, filters, identity, and generated endpoints see the same tenant context |
| Isolate event-sourced state                 | Arc + Chronicle integration        | Chronicle uses the tenant as the event-store namespace                                    |

## Compliance subject decides the PII key

[Section titled “Compliance subject decides the PII key”](#compliance-subject-decides-the-pii-key)

Chronicle compliance uses a **subject** to identify whose protected data an event contains. That subject is the lookup key for PII encryption material. It is often a person or customer id; it is not always the authenticated user, and it is not always the aggregate id.

For example, an order event may be appended to an `OrderId` event source while the protected email address in the event belongs to a `CustomerId`. In that case the command should provide the customer as the Chronicle `Subject`. If no explicit subject is provided, Chronicle falls back to the event source id.

Arc’s Chronicle integration can resolve the subject from command return values, command properties, `ICanProvideSubject`, or a `[Subject]`-marked property. The rule of thumb is simple: **set the subject to the identity that owns the PII, not merely the thing being changed.**

## PII is protected at write and released at read

[Section titled “PII is protected at write and released at read”](#pii-is-protected-at-write-and-released-at-read)

Chronicle detects `[PII]` on event properties and on `ConceptAs<T>` value types. At append time, those values are encrypted under the subject’s key before they are stored in the event log.

Read models keep that protection:

| Read-model style   | How PII is tracked                                                                                              |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| Projection         | Chronicle can infer PII lineage from mapped event properties.                                                   |
| Reducer            | The read model must mark PII properties explicitly, because reducer logic is arbitrary C#.                      |
| Arc query response | Arc releases the read model before serving it, so clients receive decrypted values when the subject key exists. |

Managed read-model documents also carry Chronicle’s reserved `_subject` field so the correct key can be used during release. Do not model your own `_subject` property.

## Erasure is key deletion plus rebuild

[Section titled “Erasure is key deletion plus rebuild”](#erasure-is-key-deletion-plus-rebuild)

The event log can stay structurally immutable while protected values become unreadable. For GDPR-style erasure, Chronicle deletes the subject’s PII encryption key. After that, PII encrypted with that key cannot be decrypted.

For read models, finish the erasure by re-projecting or re-reducing affected models. Until then, stored read-model documents may still contain ciphertext. The key is gone, so the value is unreadable, but rebuilding the read model removes the remaining encrypted payload from the query store. If an entire event payload must be removed, combine key deletion with [event redaction](/chronicle/events/redaction/).

## What to decide up front

[Section titled “What to decide up front”](#what-to-decide-up-front)

| Decision           | Ask this                                                          | Start here                                                           |
| ------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
| Identity provider  | Where do browser users and API clients authenticate?              | [AuthProxy authentication](/authproxy/configuration/authentication/) |
| Tenant resolution  | Which host, claim, route, or configured value selects the tenant? | [AuthProxy tenancy](/authproxy/configuration/tenancy/)               |
| Operation access   | Which roles or policies can run each command or query?            | [Arc authorization](/arc/backend/core/authorization/)                |
| Compliance subject | Whose personal data does this event contain?                      | [Arc Chronicle subject](/arc/backend/chronicle/compliance/subject/)  |
| PII modeling       | Which event properties or concepts are personal data?             | [Chronicle compliance](/chronicle/compliance/)                       |
| Erasure            | What must be key-deleted, re-projected, or redacted?              | [Chronicle read models and PII](/chronicle/compliance/read-models/)  |

## Go deeper

[Section titled “Go deeper”](#go-deeper)

[AuthProxy ](/authproxy/)Authenticate users, resolve tenants, enrich identity, and route requests at the edge.

[Arc identity ](/arc/backend/identity/)Expose /.cratis/me and compose the identity details AuthProxy and the frontend consume.

[Arc authorization ](/arc/backend/core/authorization/)Authorize commands and queries with attributes, roles, and policies before behavior runs.

[Chronicle subject ](/arc/backend/chronicle/compliance/subject/)Set the compliance subject so PII is encrypted under the correct identity.

[Chronicle compliance ](/chronicle/compliance/)Understand PII annotations, per-subject encryption keys, read models, and erasure.

[Production readiness ](/production-readiness/)Review the operational checklist for TLS, secrets, storage, observability, and deployment.

# AuthProxy

> AuthProxy is a lightweight .NET gateway that sits in front of your services and handles the cross-cutting edges — authentication, multi-tenancy, identity enrichment, and invite-based onboarding — so your application code stays focused on the domain.

The Cratis Stack

## A gateway for the edges of your app

Every application eventually grows the same crop of edge concerns: who is this user, which tenant are they in, where does this request route, and how do you onboard someone who has been invited but doesn’t have an account yet. **AuthProxy** is a small .NET gateway that owns those edges — so each of your services can assume the request is already authenticated, already scoped to a tenant, and already enriched with identity.

## The friction it removes

[Section titled “The friction it removes”](#the-friction-it-removes)

Without a gateway, every service re-implements the same boilerplate: an OpenID Connect handshake, tenant resolution from the host or a claim, a call to fetch the user’s profile, the invite-acceptance flow. It’s repetitive, it drifts between services, and it’s exactly the kind of code you don’t want copy-pasted across a fleet.

AuthProxy is a [reverse proxy](https://microsoft.github.io/reverse-proxy/) (built on YARP) that you put in front of your backend and frontend services. It authenticates the request, resolves the tenant, enriches the identity, and *then* forwards the request to your service — with the tenant and identity attached as headers. Your services trust the proxy and read those headers.

```
/api/** + Tenant-ID + identity

/**

AuthProxy

Authenticate

(OIDC / JWT Bearer)

Resolve tenant

Enrich identity

(/.cratis/me)

Browser / client

Backend service

Frontend SPA
```

Standalone — not Cratis-only

AuthProxy is a plain ASP.NET Core service. It pairs naturally with [Arc](/arc/)’s identity model (it calls a `/.cratis/me` endpoint to enrich identity, which Arc exposes), but it sits in front of *any* backend and frontend you point it at.

## What it handles

[Section titled “What it handles”](#what-it-handles)

[ Authentication](/authproxy/configuration/authentication/)

[OpenID Connect and OAuth 2.0 (single or multi-provider), plus JWT Bearer. Unauthenticated requests are challenged or sent to a provider-selection page.](/authproxy/configuration/authentication/)

[ Authorization](/authproxy/configuration/authorization/)

[Require a claim — a role, a group, a GitHub organization or team — before any request is forwarded. Authenticating everyone is not the same as letting everyone in.](/authproxy/configuration/authorization/)

[ Identity enrichment](/authproxy/configuration/services/#identity-enrichment)

[Calls a `/.cratis/me` endpoint on your service and attaches the enriched identity to forwarded requests as a trusted header.](/authproxy/configuration/services/#identity-enrichment)

[ Multi-tenancy](/authproxy/configuration/tenancy/)

[Resolve the current tenant per request — from the host, a subdomain, a claim, the route, or a fixed value — with optional remote verification.](/authproxy/configuration/tenancy/)

[ Invites & lobby](/authproxy/configuration/lobby/)

[Invite-based onboarding with signed JWT tokens, plus an optional lobby service for users not yet assigned to a tenant.](/authproxy/configuration/lobby/)

## How the docs are organized

[Section titled “How the docs are organized”](#how-the-docs-are-organized)

There’s no code to write — AuthProxy is configured entirely through the `Cratis:AuthProxy` section of `appsettings.json` and runs as a container in front of your services. Each page under [Configuration](/authproxy/configuration/) takes one edge concern and walks through how AuthProxy handles it and how you configure it.

## Where to go next

[Section titled “Where to go next”](#where-to-go-next)

Start by putting the proxy in front of a service — the configuration reference covers the full `Cratis:AuthProxy` shape.

[ Configuration reference](/authproxy/configuration/)

[The complete `Cratis:AuthProxy` settings shape, service routing, and every topic below it.](/authproxy/configuration/)

[ Aspire hosting](/authproxy/aspire/)

[Wire AuthProxy into a .NET Aspire AppHost alongside your other services.](/authproxy/aspire/)

[ Identity & access in Arc](/arc/backend/core/authorization/)

[How Arc models identity and authorization on commands and queries — the `/.cratis/me` endpoint AuthProxy enriches from.](/arc/backend/core/authorization/)

# Aspire Hosting Integration

## Canonical provider identity

[Section titled “Canonical provider identity”](#canonical-provider-identity)

Use the canonical provider helpers when every downstream identity path must use one explicitly selected provider subject:

```csharp
authProxy.WithCanonicalOidcProvider(
    "Microsoft Entra",
    OidcProviderType.Microsoft,
    "https://login.microsoftonline.com/<tenant-id>/v2.0",
    clientId,
    clientSecret,
    "entra-workforce",
    "oid");
```

For OAuth providers, `WithCanonicalOAuthProvider` additionally requires the explicit issuer assigned to the authenticated user-information flow. The `WithOidcProvider` and `WithOAuthProvider` helpers retain legacy identity behavior.

The `Cratis.AuthProxy.Aspire` NuGet package adds first-class .NET Aspire support for AuthProxy. Instead of configuring environment variables by hand, you wire up authentication, tenancy, and service routing with a concise fluent API in your `AppHost`.

## Installation

[Section titled “Installation”](#installation)

```bash
dotnet add package Cratis.AuthProxy.Aspire
```

## Adding AuthProxy as a container resource

[Section titled “Adding AuthProxy as a container resource”](#adding-authproxy-as-a-container-resource)

This is the typical path for external consumers who run AuthProxy from Docker Hub:

```csharp
var authproxy = builder.AddAuthProxy("authproxy", tag: "latest")
    .WithHttpEndpoint(port: 8080)
    .WithBackend("main", apiResource)
    .WithFrontend("main", webResource)
    .WithOidcProvider(
        "Microsoft",
        OidcProviderType.Microsoft,
        authority: "https://login.microsoftonline.com/<tenant-id>/v2.0",
        clientId: "<client-id>",
        clientSecret: "<client-secret>")
    .WithHostTenantResolution();
```

`AddAuthProxy` creates an `AuthProxyResource` backed by the `cratis/authproxy` Docker Hub image. Pin `tag` to a specific release in production environments — the default `"latest"` is convenient for local development.

## Adding AuthProxy as a project resource

[Section titled “Adding AuthProxy as a project resource”](#adding-authproxy-as-a-project-resource)

When working inside the AuthProxy repository itself (or in a monorepo that includes AuthProxy source), use `AddProject` with the same extension methods:

```csharp
var authproxy = builder.AddProject<Projects.AuthProxy>("authproxy")
    .WithBackend("main", apiResource)
    .WithFrontend("main", webResource);
```

All `With*` methods work on any `IResourceBuilder<T> where T : IResourceWithEnvironment`, so you can mix container and project resources freely.

***

## Services

[Section titled “Services”](#services)

Use `WithBackend` and `WithFrontend` to register the resources that AuthProxy should proxy:

```csharp
authproxy
    .WithBackend("main", apiResource)
    .WithFrontend("main", webResource);
```

Both methods accept an optional `endpointName` parameter (defaults to `"http"`) that selects which endpoint from the target resource to forward to.

### Identity details resolution

[Section titled “Identity details resolution”](#identity-details-resolution)

For each service with a backend, AuthProxy calls `GET {baseUrl}/.cratis/me` after authentication to enrich the identity cookie. This behaviour is on by default. To disable it for a specific service, pass `resolveIdentityDetails: false` to `WithBackend`:

```csharp
authproxy
    .WithBackend("reporting", reportingApi, resolveIdentityDetails: false)
    .WithFrontend("reporting", reportingWeb);
```

See [Services](/authproxy/configuration/services/) for the underlying configuration model.

### Identity verification denials

[Section titled “Identity verification denials”](#identity-verification-denials)

After declaring a service’s identity endpoint as an authorization authority, you can make any denial end the caller’s local AuthProxy session:

```csharp
authproxy
    .WithIdentityVerification("main", IdentityVerificationMode.Required)
    .WithSessionTerminationOnIdentityDenial();
```

`WithSessionTerminationOnIdentityDenial` is global and composes deterministically across services: calling it more than once still writes the same enabled session setting. A denial clears AuthProxy’s local session before the existing `403` response; it does not initiate logout at the external identity provider. Omit the call to preserve the default behavior, where the authenticated session remains active after a denial.

See [Identity verification](/authproxy/configuration/services/#identity-enrichment) for the denial matrix and the direct configuration equivalent.

### Anonymous paths

[Section titled “Anonymous paths”](#anonymous-paths)

Declare the request paths on a service that should be served without a session — a magic-link landing page, a signed-token report, a public webhook receiver. Call `WithAnonymousPaths` once per service; each call accumulates entries:

```csharp
authproxy.WithAnonymousPaths("main", "/welcome", "/api/webhooks/payments");
```

Each entry is a rooted path prefix, matched case-insensitively on segment boundaries — `/welcome` covers `/welcome` and `/welcome/anything`, but not `/welcomex`. AuthProxy still strips inbound identity headers on these paths and the application remains responsible for authorizing them.

See [Anonymous paths](/authproxy/configuration/services/#anonymous-paths) for the full matching rules and what the flag does and does not change.

### Trusted proxies

[Section titled “Trusted proxies”](#trusted-proxies)

Declare the peers directly in front of AuthProxy, so their `X-Forwarded-For` and `X-Forwarded-Proto` are believed and everybody else’s are not:

```csharp
authproxy
    .WithTrustedProxies("10.0.0.0/8", "203.0.113.7")
    .WithForwardLimit(2);
```

`WithTrustedProxies` takes IP addresses and CIDR ranges and accumulates across calls; an entry that is neither is refused when the app host builds. `WithForwardLimit` is the number of hops a request legitimately passes through, and it decides which address ends up reported as the client — see [Trusted Proxies](/authproxy/configuration/trusted-proxies/) for how to choose it and what an untrusted caller can do while it is unset.

***

## Admission

[Section titled “Admission”](#admission)

Close the interactive contract, so AuthProxy answers nothing at all until a caller presents a capability the deployment’s own verifier admits:

```csharp
authproxy.WithCapabilityOnlyAdmission("https://members.example.com/admit");
```

That is the whole minimum — the verifier URL has no default, because the verifier is your service and inventing an address for it would mean a misconfigured deployment silently calling something else. Everything else does:

```csharp
authproxy.WithCapabilityOnlyAdmission(
    verifierUrl: "https://members.example.com/admit",
    path: "/enter",                            // default "/.cratis/admission"
    maximumLength: 512,                        // default 4096 bytes
    entryLifetime: TimeSpan.FromMinutes(30));  // default 20 minutes
```

| Parameter       | Required | Description                                                                     |
| --------------- | -------- | ------------------------------------------------------------------------------- |
| `verifierUrl`   | ✓        | Absolute `http`/`https` URL that decides whether a presented capability admits. |
| `path`          | –        | The one path a capability may be presented on.                                  |
| `maximumLength` | –        | The largest capability, in bytes, AuthProxy will read.                          |
| `entryLifetime` | –        | How long an admitted browser stays admitted.                                    |

Do not shorten `entryLifetime` below fifteen minutes: ASP.NET Core allows that long at the identity provider, so a shorter entry expires while the handshake is still live and the caller comes back to a `404` with nothing anywhere to diagnose it from.

It cannot be combined with `WithInvite` — AuthProxy refuses the combination at startup rather than silently ordering two capability mechanisms. Without this call nothing changes: the default mode is `Public`, which is how every release before it behaved.

See [Admission](/authproxy/configuration/admission/) for the verifier request/response contract, what an operator should expect to observe, and the `/.cratis/token` caveat for machine clients.

***

## Authentication

[Section titled “Authentication”](#authentication)

### OIDC providers

[Section titled “OIDC providers”](#oidc-providers)

```csharp
authproxy.WithOidcProvider(
    name: "Contoso AD",
    type: OidcProviderType.Microsoft,
    authority: "https://login.microsoftonline.com/<tenant-id>/v2.0",
    clientId: "<client-id>",
    clientSecret: "<client-secret>",
    scopes: ["api://my-api/.default"]);
```

Call `WithOidcProvider` once per provider. Multiple calls produce a provider-selection page.

The `OidcProviderType` enum contains well-known provider brands:

| Value       | Description                                        |
| ----------- | -------------------------------------------------- |
| `Custom`    | Generic / unknown provider.                        |
| `Microsoft` | Microsoft Identity Platform (Azure AD / Entra ID). |
| `Google`    | Google Identity.                                   |
| `GitHub`    | GitHub OAuth / OIDC.                               |
| `Apple`     | Apple Sign-In.                                     |

### OAuth 2.0 (non-OIDC) providers

[Section titled “OAuth 2.0 (non-OIDC) providers”](#oauth-20-non-oidc-providers)

For providers that do not expose an OIDC discovery document, use `WithOAuthProvider`:

```csharp
authproxy.WithOAuthProvider(
    name: "GitHub",
    type: OidcProviderType.GitHub,
    authorizationEndpoint: "https://github.com/login/oauth/authorize",
    tokenEndpoint: "https://github.com/login/oauth/access_token",
    userInformationEndpoint: "https://api.github.com/user",
    clientId: "<client-id>",
    clientSecret: "<client-secret>",
    scopes: ["user:email"],
    claimMappings: new Dictionary<string, string>
    {
        ["sub"] = "id",
        ["name"] = "login",
        ["email"] = "email"
    },
    authorizationParameters: new Dictionary<string, string>
    {
        ["prompt"] = "select_account"
    });
```

`authorizationParameters` adds provider-specific, static values to every authorization request without changing the endpoint URL. AuthProxy rejects parameters owned by the OAuth handler, including `state`, `redirect_uri`, `client_id`, `scope`, `response_type`, and PKCE parameters, so configured values cannot replace correlation or callback data.

For invitation acceptance, also configure the OAuth provider’s `VerifiedEmailEndpoint` as `https://api.github.com/user/emails` through AuthProxy configuration. The `user:email` scope shown above lets AuthProxy establish exactly one primary verified address instead of trusting the nullable address on `/user`.

See [Authentication](/authproxy/configuration/authentication/) for the full configuration reference.

For an invite system that creates or links accounts, enable signed two-stage attestations after calling `WithInvite`:

```csharp
authproxy.WithSignedInvitationAttestations(
    stageUrl: "https://lobby.example.com/_invite/stage",
    issuer: "https://auth.example.com",
    audience: "ada-lobby",
    keyId: "invite-2026-08",
    privateKeyPem: invitationSigningKey);
```

Load `invitationSigningKey` from a secret provider and configure the invitation authority with only the matching public key. Signed attestations also require recipient binding — call [`WithInviteEmailBinding`](#binding-an-invitation-to-the-invited-email) with a non-empty claim and pass a `tenantClaim` to `WithInvite`, or AuthProxy fails options validation at startup. See [Invitation to Organization](/authproxy/configuration/lobby/invitation-to-organization/) for the claims, two calls, verification rules, and rotation sequence.

***

## Tenant resolution

[Section titled “Tenant resolution”](#tenant-resolution)

Add one or more resolution strategies. They run in order until a tenant is matched:

| Method                                    | Strategy                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------- |
| `WithHostTenantResolution()`              | Matches the request host against configured tenant domains.                     |
| `WithSubHostTenantResolution()`           | Derives the tenant from the first subdomain (e.g. `acme.example.com` → `acme`). |
| `WithClaimTenantResolution(claimType?)`   | Reads a claim from the authenticated user.                                      |
| `WithRouteTenantResolution(pattern)`      | Extracts a source identifier from the request path by regex.                    |
| `WithSpecifiedTenantResolution(tenantId)` | Pins all requests to one fixed tenant (single-tenant deployments).              |
| `WithDefaultTenantResolution(tenantId)`   | Fallback when no other strategy resolves a tenant.                              |
| `WithSelectionTenantResolution()`         | Reads the tenant from the cookie set by the tenant-selection page.              |

```csharp
authproxy
    .WithSubHostTenantResolution()
    .WithDefaultTenantResolution("lobby");
```

See [Tenancy](/authproxy/configuration/tenancy/) for detailed strategy documentation.

### Tenant verification

[Section titled “Tenant verification”](#tenant-verification)

After resolution, AuthProxy can confirm the tenant exists by calling your back-end. You can pass a raw URL template or reference an Aspire service resource directly:

```csharp
// Raw URL template
authproxy.WithTenantVerification("https://platform.example.com/api/tenants/{tenantId}");

// Aspire resource reference — endpoint is resolved automatically
authproxy.WithTenantVerification(platformApi, "/api/tenants/{tenantId}");
```

AuthProxy issues a `GET` to the resolved URL. A `200` response lets the request proceed; `404` or any error serves the `tenant-not-found.html` page.

***

## Tenant selection

[Section titled “Tenant selection”](#tenant-selection)

When users can be members of more than one tenant, the `Selection` strategy presents a tenant-selection page after login. You can pass a raw URL or reference an Aspire service resource:

```csharp
// Raw URL
authproxy.WithSelectionTenantResolution(
    tenantsEndpoint: "https://platform.example.com/api/tenants/selectable");

// Aspire resource reference — endpoint is resolved automatically
authproxy.WithSelectionTenantResolution(platformApi, "/api/tenants/selectable");
```

AuthProxy calls the endpoint after login and, if more than one tenant is returned, serves the built-in `select-tenant.html` page. If only one tenant is returned the selection page is skipped and the user is redirected immediately.

The endpoint must return a JSON array of `{ "id": "...", "name": "..." }` objects.

See [Tenant Selection Page](/authproxy/configuration/tenant-selection/) for details on building a custom selection page and the full flow.

***

## Invites, registration and lobby

[Section titled “Invites, registration and lobby”](#invites-registration-and-lobby)

### Core invite configuration

[Section titled “Core invite configuration”](#core-invite-configuration)

Configure the invite system with the RSA public key and exchange endpoint. You can pass a raw URL or reference an Aspire service resource for the exchange endpoint:

```csharp
// Raw URL
authproxy.WithInvite(
    publicKeyPem: File.ReadAllText("invite-public-key.pem"),
    exchangeUrl: "https://studio.example.com/internal/invites/exchange",
    issuer: "https://studio.example.com",
    audience: "authproxy",
    tenantClaim: "tenant_id",
    subjectAlreadyExistsUrl: "https://app.example.com/errors/account-already-exists");

// Aspire resource reference — exchange endpoint URL is resolved automatically
authproxy.WithInvite(
    publicKeyPem: File.ReadAllText("invite-public-key.pem"),
    exchangeServiceResource: studioApi,
    exchangeRoute: "/internal/invites/exchange",
    issuer: "https://studio.example.com",
    tenantClaim: "tenant_id");
```

| Parameter                 | Required | Description                                                                                |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `publicKeyPem`            | ✓        | PEM-encoded RSA public key to verify invite token signatures.                              |
| `exchangeUrl`             | ✓        | Endpoint called after login to exchange the invite token.                                  |
| `issuer`                  | –        | Expected `iss` claim. Omit to skip issuer validation.                                      |
| `audience`                | –        | Expected `aud` claim. Omit to skip audience validation.                                    |
| `tenantClaim`             | –        | Claim that carries the tenant ID for tenant-issued invite detection.                       |
| `subjectAlreadyExistsUrl` | –        | Redirect URL when the exchange endpoint returns HTTP 409. Omit to serve the built-in page. |

### Binding an invitation to the invited email

[Section titled “Binding an invitation to the invited email”](#binding-an-invitation-to-the-invited-email)

By default an invite is a bearer token: any subject who signs in holding it can redeem it. To bind it to the address it was issued to, name the claim in the invite token that carries that address:

```csharp
authproxy.WithInviteEmailBinding("invited_email");
```

Compose this after either `WithInvite` overload. AuthProxy then compares that claim against the email evidence the identity provider supplied for the signed-in session, before the second-stage exchange runs. When the provider offers no usable address, the invite is rejected with `invitation-email-unavailable.html`; when the address differs from the invited one — or the provider explicitly reports `email_verified=false` — with `invitation-email-mismatch.html`.

Omitting the call, or passing an empty claim, writes nothing and retains the released default of no recipient binding.

### Claim forwarding

[Section titled “Claim forwarding”](#claim-forwarding)

To propagate invite-token claims into the principal sent to `/.cratis/me` endpoints, call `WithInviteClaimForwarding` once per claim:

```csharp
authproxy
    .WithInviteClaimForwarding("organization_id", toClaimType: "organization")
    .WithInviteClaimForwarding("invited_by");
```

When `toClaimType` is omitted the original claim type is preserved.

### Lobby

[Section titled “Lobby”](#lobby)

The lobby is the service users are redirected to when no tenant can be resolved — typically an onboarding application. At minimum, configure the lobby frontend:

```csharp
authproxy
    .WithLobbyFrontend(lobbyResource)
    .WithLobbyBackend(lobbyApiResource);   // optional
```

`WithLobbyFrontend` and `WithLobbyBackend` both accept an optional `endpointName` parameter (defaults to `"http"`).

### Registration

[Section titled “Registration”](#registration)

To send users through the AuthProxy registration bootstrap flow, configure a lobby registration URL:

```csharp
authproxy.WithLobbyRegistration(lobbyResource, "/register");

// or use a raw URL
authproxy.WithLobbyRegistration("https://lobby.example.com/register");
```

This sets `Cratis:AuthProxy:Invite:Lobby:Registration:BaseUrl`. Users who visit `/register` authenticate through AuthProxy and are then redirected to that registration URL.

See [Lobby](/authproxy/configuration/lobby/) for the onboarding flow walkthroughs.

# Configuration

Cratis AuthProxy is configured entirely through the `Cratis:AuthProxy` section of `appsettings.json` (or equivalent environment variables using the `Cratis__AuthProxy__` prefix).

```json
{
  "Cratis": {
    "AuthProxy": {
      "Authentication": { ... },
      "Authorization": { ... },
      "Admission": { ... },
      "TenantResolutions": [ ... ],
      "TenantVerification": { ... },
      "Tenants": { ... },
      "Services": { ... },
      "Ingress": { ... },
      "Invite": { ... },
      "Management": { ... },
      "PagesPath": "",
      "DataProtectionKeysPath": ""
    }
  }
}
```

| Topic                                                                | Description                                                                                                                                               |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Authentication](/authproxy/configuration/authentication/)           | OIDC providers, OAuth 2.0 providers such as GitHub, and JWT Bearer configuration.                                                                         |
| [Authorization](/authproxy/configuration/authorization/)             | Requiring a claim — a role, a group, a GitHub organization or team — before any request is forwarded.                                                     |
| [Admission](/authproxy/configuration/admission/)                     | Answering nothing at all until a caller presents a capability your own verifier admits, for a deployment whose existence is not meant to be discoverable. |
| [Tenancy](/authproxy/configuration/tenancy/)                         | How the auth proxy resolves the current tenant from each request, and how to verify tenant existence.                                                     |
| [Tenant Selection Page](/authproxy/configuration/tenant-selection/)  | How selection-based tenant resolution works and how to build/override `select-tenant.html`.                                                               |
| [Trusted Proxies](/authproxy/configuration/trusted-proxies/)         | Which callers may speak for the client through `X-Forwarded-For` and `X-Forwarded-Proto`, and how many hops to follow.                                    |
| [Services](/authproxy/configuration/services/)                       | Routing requests to backend and frontend services.                                                                                                        |
| [Management Listener](/authproxy/configuration/management-listener/) | An opt-in private listener carrying liveness and readiness endpoints, so a probe tests more than “a process accepted a socket”.                           |
| [Lobby](/authproxy/configuration/lobby/)                             | Invite and registration flows that hand users off to the lobby experience.                                                                                |
| [Well-Known Pages](/authproxy/configuration/well-known-pages/)       | Built-in HTML pages (provider selection, errors, tenant not found) and how to override them via a mounted volume.                                         |

# Admission

AuthProxy’s sign-in surface is public by design. The provider list at `/.cratis/providers`, the per-provider challenge endpoints, the selection page and every asset behind it all answer a caller who has never signed in — because a person who has never signed in has to reach them in order to sign in at all.

That is right for a deployment whose front door is meant to be found. It is wrong for one whose *existence* is not meant to be discoverable: the provider list names the identity providers the organization trusts, the challenge endpoint confirms whether a named provider is configured, and every one of them says an AuthProxy is here.

**Admission** is the switch between those two deployments. In `CapabilityOnly` mode nothing at all is answered until a caller presents a capability the deployment’s own verifier admits.

***

## The shape of it

[Section titled “The shape of it”](#the-shape-of-it)

```
Your serviceYour verifierAuthProxyCallerYour serviceYour verifierAuthProxyCallerGET /anything404 Not FoundPOST /.cratis/admission (capability in the body)POST {capability, transaction, challenge}{admitted, transaction, challenge}204 + entry cookieGET /anything (with the entry cookie)forwarded, exactly as it always was
```

Everything downstream of the gate is unchanged. An admitted caller meets exactly the authentication, authorization, tenancy and routing they would have met with admission switched off — admission decides whether there is anything here to reach, not who may reach it.

***

## Turning it on

[Section titled “Turning it on”](#turning-it-on)

Name a mode and a verifier. Everything else has a default.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Admission": {
        "Mode": "CapabilityOnly",
        "Capability": {
          "VerifierUrl": "https://members.example.com/admit"
        }
      }
    }
  }
}
```

With Aspire:

```csharp
builder.AddAuthProxy("authproxy")
       .WithCapabilityOnlyAdmission("https://members.example.com/admit");
```

**Leaving the section out changes nothing.** The default mode is `Public`, which is what every release before this behaved as. This is an opt-in posture, not a hardening of the default — turning it on closes a contract that other deployments depend on being open.

***

## Settings

[Section titled “Settings”](#settings)

| Setting                    | Default              | Meaning                                                                                                                  |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Mode`                     | `Public`             | `Public` or `CapabilityOnly`. Anything else is refused at startup.                                                       |
| `Capability:VerifierUrl`   | *(none)*             | The absolute `http`/`https` URL that decides whether a presented capability admits. **Required** under `CapabilityOnly`. |
| `Capability:Path`          | `/.cratis/admission` | The one path a capability may be presented on.                                                                           |
| `Capability:MaximumLength` | `4096`               | The largest capability, in bytes, AuthProxy will read from a presentation.                                               |
| `EntryLifetime`            | `00:20:00`           | How long an admitted browser stays admitted.                                                                             |

There is deliberately **no default verifier URL**. A verifier is your own service, and inventing an address for it would mean a misconfigured deployment silently calling something else.

***

## The verifier contract

[Section titled “The verifier contract”](#the-verifier-contract)

This is the whole of what a deployment has to implement. AuthProxy is deliberately not the authority on what a capability means — it reads a value, carries it here, and does what it is told, so issuance, revocation, single use, expiry and every other rule stay entirely on your side of the call.

### The request

[Section titled “The request”](#the-request)

`POST` to `VerifierUrl`, `Content-Type: application/json`:

```json
{
  "capability": "the exact value the caller presented, uninterpreted",
  "transaction": "3f9c0a1b7e2d4c6f4a2e8d1c0b7a6934…",
  "challenge": "8b1d5e7a0c3f29417d6b4e2a9c8f0135…"
}
```

`transaction` and `challenge` are two independent 256-bit values AuthProxy mints per presentation and never reuses. They are opaque to you.

### The reply

[Section titled “The reply”](#the-reply)

`200 OK`, `Content-Type: application/json`:

```json
{
  "admitted": true,
  "transaction": "3f9c0a1b7e2d4c6f4a2e8d1c0b7a6934…",
  "challenge": "8b1d5e7a0c3f29417d6b4e2a9c8f0135…"
}
```

**Echo both values back exactly**, or the answer is refused. A reply that does not name the exact presentation it belongs to is not an answer to it, and treating it as one would let a reply meant for some other presentation admit this caller. The comparison is fixed-time.

Any other field you send is read past and ignored. Nothing you return is stored, forwarded or sealed into the browser — the entry cookie carries the two values AuthProxy authored and an expiry, and nothing else, so its size is one you cannot influence.

### Every other outcome is a refusal

[Section titled “Every other outcome is a refusal”](#every-other-outcome-is-a-refusal)

| What your verifier did                    | What AuthProxy does                        |
| ----------------------------------------- | ------------------------------------------ |
| `{"admitted": true}` echoing both values  | Admits                                     |
| `{"admitted": false}`                     | Refuses                                    |
| Echoed the wrong transaction or challenge | Refuses                                    |
| Answered a non-`2xx` status               | Refuses                                    |
| Answered a body that will not parse       | Refuses                                    |
| Answered with a redirect                  | Refuses — the redirect is **not** followed |
| Could not be reached                      | Refuses                                    |
| Took longer than **5 seconds**            | Refuses                                    |
| Threw anything at all                     | Refuses                                    |

Failing closed is the point: a verifier outage that let callers in would make the whole mode worth nothing. The corollary is that **a verifier outage is a full outage** — nobody new is admitted while it lasts, though browsers already holding a live entry keep working until it expires.

The redirect row is deliberate. `VerifierUrl` is constrained at startup to one absolute `http`/`https` URL, and following a `3xx` would hand that constraint back to whoever answers it — an anonymous POST would become an AuthProxy-originated POST to any internally reachable host, carrying the caller’s capability in the body.

***

## What the caller does

[Section titled “What the caller does”](#what-the-caller-does)

One `POST`, with the capability as the **raw request body**:

```bash
curl -i -X POST https://app.example.com/.cratis/admission \
     --data-binary 'the-capability-value'
```

```http
HTTP/1.1 204 No Content
Set-Cookie: .cratis-entry=…; max-age=1200; path=/; samesite=lax; httponly; secure
```

The capability is read from the body and **from nowhere else** — not a path segment, not a query parameter, not a header, not a cookie. Every one of those is a place a value ends up written into an access log, a proxy’s cache key or a browser’s history, and a bearer value that admits a caller has no business in any of them.

The answer carries no body. What the browser needs is the cookie.

### Anything else is the uniform refusal

[Section titled “Anything else is the uniform refusal”](#anything-else-is-the-uniform-refusal)

A `GET` to the presentation path, a body over `MaximumLength`, an empty body, a capability the verifier refused, a verifier that never answered — all of them produce the identical `404`, the same one an unknown path produces. The endpoint is not a probe for whether the mode is on.

***

## Entry lifetime

[Section titled “Entry lifetime”](#entry-lifetime)

`EntryLifetime` bounds one interactive entry — choosing a provider, completing the round-trip to the identity provider, and coming back — not a session. The session cookie the sign-in produces has its own, much longer, lifetime and is unaffected.

The default is **twenty minutes**, and the number is not arbitrary. ASP.NET Core’s own `RemoteAuthenticationOptions.RemoteAuthenticationTimeout` allows **fifteen minutes** at the provider, and enrolling in MFA, resetting a password or working through a consent screen routinely uses them. An entry shorter than that expires while the framework still considers the handshake live, and the caller comes back to a `404` with no way to recover and — by design — nothing in any response or log to diagnose it from.

**Do not set `EntryLifetime` below fifteen minutes.** If you shorten it, shorten `RemoteAuthenticationTimeout` to match.

When an entry does expire, the caller presents a new capability. That is the recovery path, and it is worth making sure whoever hands out capabilities can hand out another one.

***

## What a refusal looks like

[Section titled “What a refusal looks like”](#what-a-refusal-looks-like)

Every refusal is the same refusal, byte for byte:

```http
HTTP/1.1 404 Not Found
Content-Length: 9
Content-Type: text/plain; charset=utf-8
Cache-Control: no-store

Not Found
```

No `Server` header, no `WWW-Authenticate`, no `Allow`, no `Location`, no `Set-Cookie`, no branded error page. Response headers queued by anything upstream are cleared rather than added to, so a challenge or a cookie an earlier decision produced cannot survive into a refusal and make it distinguishable. Every route and every method answers this — including the paths AuthProxy itself owns, and including a management-listener path offered to the public listener.

### What it does not hide

[Section titled “What it does not hide”](#what-it-does-not-hide)

The claim is that the **content** of the answers is indistinguishable, not that every observable is.

* **Timing.** A presentation on `Capability:Path` costs a verifier round-trip that no other path costs — on loopback, roughly 1.1 ms against 0.5 ms, and up to the full five-second budget when the verifier hangs. The presentation path is therefore discoverable by timing.
* **`MaximumLength`.** An over-length body is refused *before* the round-trip starts, so the configured bound is discoverable by binary search against that timing difference.

Neither is addressed, and deliberately so: closing them would mean padding every refusal to the slowest one, which buys an attacker learning where a path is that already answers nothing, at a real cost in availability. Treat an unguessable `Capability:Path` as one less thing to notice, never as the control.

***

## What an operator should expect to observe

[Section titled “What an operator should expect to observe”](#what-an-operator-should-expect-to-observe)

The hardest part of running a closed deployment is that it is designed to say nothing, so know in advance what the signals are.

| Symptom                                                                 | What it means                                                                                                                               |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Every request answers `404`, including yours                            | Working as configured. Present a capability.                                                                                                |
| The process refuses to start, naming `Admission:Capability:VerifierUrl` | The mode is on and no verifier is named. This is the one misconfiguration that cannot announce itself later.                                |
| The process refuses to start, naming `Admission:Mode`                   | The mode is neither `Public` nor `CapabilityOnly`. A value outside the enum binds silently, so it is refused rather than treated as either. |
| A presentation answers `404` instead of `204`                           | The verifier refused, was unreachable, timed out, or answered about a different presentation. Which one is in **your log**, at `Warning`.   |
| Admission worked, then everything answers `404` again                   | The entry expired, or the deployment’s Data Protection key ring changed.                                                                    |

AuthProxy’s own logs are deliberately parameterless — a capability is a bearer value and the presentation path names the deployment’s closed door, so neither ever reaches a log sink. The four messages are:

* `Debug` — a presented capability was refused by the verifier.
* `Warning` — the verifier could not be reached, or did not answer in time.
* `Warning` — the verifier answered about a different presentation than the one it was asked about.
* `Error` — no verifier is configured, so nothing can be admitted.

The detail you need for a specific presentation is on the verifier’s side, where you own it.

### Data Protection

[Section titled “Data Protection”](#data-protection)

The entry cookie is sealed with the application’s ASP.NET Core Data Protection key ring, under a purpose of its own. A deployment that does not persist its keys issues a new key ring on every restart, which invalidates every outstanding entry — set [`DataProtectionKeysPath`](/authproxy/configuration/authentication/) to a persistent volume, and share it across replicas, or every instance will refuse the entries the others issued.

***

## What this changes elsewhere

[Section titled “What this changes elsewhere”](#what-this-changes-elsewhere)

### `AnonymousPaths` do not apply

[Section titled “AnonymousPaths do not apply”](#anonymouspaths-do-not-apply)

A path a service declares in [`AnonymousPaths`](/authproxy/configuration/services/#anonymous-paths) is still closed to an unadmitted caller. That is not an oversight — the whole point of the mode is that nothing is answered before admission, and `AnonymousPaths` is a statement about *authentication*, one layer further in.

For a deployment that needs a genuinely public surface *and* a closed one, run two deployments. See [Public application surfaces](/authproxy/configuration/public-surfaces/).

### Unauthenticated responses do not apply either

[Section titled “Unauthenticated responses do not apply either”](#unauthenticated-responses-do-not-apply-either)

The `401`/`403`/selection-page rules in [Unauthenticated responses](/authproxy/configuration/unauthenticated-responses/) describe what happens *after* admission. To an unadmitted caller there is only the uniform `404`.

This includes probes. A liveness or readiness probe pointed at any application path gets `404` on a closed deployment — use the [management listener](/authproxy/configuration/management-listener/), whose port is separate and whose endpoints are not gated by admission.

### `Invite` cannot be combined with it

[Section titled “Invite cannot be combined with it”](#invite-cannot-be-combined-with-it)

`CapabilityOnly` and an `Invite` section together are refused at startup. Two capability mechanisms in one deployment is a misconfiguration: an invitation is a capability with its own issuance, its own browser state and its own refusals, and it would be reached only through a door admission has already closed. Refusing the combination keeps the option of unifying them later open, rather than freezing whichever precedence happened to ship.

### The token endpoint needs an entry too

[Section titled “The token endpoint needs an entry too”](#the-token-endpoint-needs-an-entry-too)

`/.cratis/token` is mapped when any service declares client credentials — but on a closed deployment it sits behind the gate like everything else, so a machine client has to present a capability first and send the resulting entry cookie with its token request. That is a two-step nobody expects from an OAuth token endpoint.

If your closed deployment serves machine clients, either give them a capability as part of provisioning, or front them with a deployment left in `Public` mode. A closed deployment where no service declares client credentials does not get the endpoint at all.

***

## What is refused at startup

[Section titled “What is refused at startup”](#what-is-refused-at-startup)

Each of these would otherwise start cleanly and then refuse every caller alive, with a `404` that says nothing about why:

| Configuration                                              | Why it is refused                                                                                                                                              |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Mode` outside the enum (including a number)               | A name the binder cannot parse already refuses to start; a number binds silently and would leave the gate inert or the deployment closed with nothing checked. |
| `CapabilityOnly` with no `VerifierUrl`                     | Nothing can ever be admitted.                                                                                                                                  |
| A `VerifierUrl` that is not an absolute `http`/`https` URL | An absolute filesystem path parses as an absolute URI on Unix, so the scheme is named rather than merely parsed.                                               |
| A `Capability:Path` that is not rooted                     | Matches no request, so nothing can ever be presented.                                                                                                          |
| `Capability:MaximumLength` of zero or less                 | A bound of nothing refuses every capability.                                                                                                                   |
| `EntryLifetime` of zero or less                            | An entry that has expired before it is issued admits nobody.                                                                                                   |
| `CapabilityOnly` together with `Invite`                    | Two capability mechanisms in one deployment.                                                                                                                   |

# Authentication

AuthProxy supports three authentication modes that can be active simultaneously:

* **Interactive browser sessions** – OpenID Connect (OIDC) with a cookie.
* **Machine-to-machine / API** – JWT Bearer tokens from an external identity provider.
* **Back-channel client credentials** – service-owned client credentials verified by the target service itself.

***

## OIDC providers

[Section titled “OIDC providers”](#oidc-providers)

Configure one or more OpenID Connect providers under `Cratis:AuthProxy:Authentication:OidcProviders`.

**Single provider** – the auth proxy challenges unauthenticated browser requests directly with that provider:

**Multiple providers** – the auth proxy redirects unauthenticated browser requests to a built-in provider-selection page (`/.cratis/select-provider`) so the user can choose which provider to log in with:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Authentication": {
        "OidcProviders": [
          {
            "Name": "Microsoft",
            "Type": "Microsoft",
            "Authority": "https://login.microsoftonline.com/<tenant-id>/v2.0",
            "ClientId": "<client-id>",
            "ClientSecret": "<client-secret>",
            "Scopes": []
          },
          {
            "Name": "Google",
            "Type": "Google",
            "Authority": "https://accounts.google.com",
            "ClientId": "<client-id>",
            "ClientSecret": "<client-secret>",
            "Scopes": []
          }
        ]
      }
    }
  }
}
```

Each provider generates a dedicated login endpoint at `/.cratis/login/{scheme}`. The scheme name is derived from the provider `Name` by lowercasing and replacing spaces with hyphens (e.g. `"My Provider"` → `/.cratis/login/my-provider`).

Both behaviors above — the direct challenge and the selection page — apply to **browser navigations**. A caller that is not navigating to a page is refused with `401` instead, so the rejection is visible to a client that checks the status code. See [Unauthenticated responses](/authproxy/configuration/unauthenticated-responses/).

### Tenant-aware authentication state

[Section titled “Tenant-aware authentication state”](#tenant-aware-authentication-state)

When authentication starts from a tenant-scoped request, AuthProxy stores tenant resolution metadata in the protected authentication `state` value:

* Tenant ID
* Tenant resolution strategy
* Strategy-specific metadata (for `SubHost`, the configured `ParentHost`)

On callback (`/signin-{scheme}`), AuthProxy reads this state and re-applies strategy behavior before finishing sign-in. For `SubHost`, AuthProxy reconstructs the tenant URL and redirects back to that tenant host.

Example flow:

1. Request arrives at `https://some-tenant.cratis.studio/`
2. AuthProxy resolves tenant `some-tenant` via `SubHost`
3. Challenge is sent with protected state containing tenant metadata
4. Provider redirects back to `https://auth.cratis.studio/signin-github?...&state=...`
5. AuthProxy restores tenant metadata from state
6. AuthProxy redirects to `https://some-tenant.cratis.studio/` (original return URL preserved)

This allows a common callback endpoint while still restoring tenant-specific behavior after sign-in.

### OidcProviderConfig properties

[Section titled “OidcProviderConfig properties”](#oidcproviderconfig-properties)

| Property       | Type       | Description                                                                                  |
| -------------- | ---------- | -------------------------------------------------------------------------------------------- |
| `Name`         | `string`   | Display name shown on the login selection page.                                              |
| `Type`         | `string`   | Provider type hint (`Microsoft`, `Google`, or `Custom`).                                     |
| `Authority`    | `string`   | OIDC authority URL.                                                                          |
| `ClientId`     | `string`   | OAuth 2.0 client ID.                                                                         |
| `ClientSecret` | `string`   | OAuth 2.0 client secret.                                                                     |
| `Scopes`       | `string[]` | Additional scopes to request (beyond `openid`, `profile`, `email`).                          |
| `ResponseMode` | `string`   | How the provider returns the authorization code: `Query` (default) or `FormPost`. See below. |

#### Response mode and the handshake cookies

[Section titled “Response mode and the handshake cookies”](#response-mode-and-the-handshake-cookies)

The handshake only completes when the provider callback carries the correlation cookie, and that cookie is `SameSite=Lax` — which a browser attaches to a top-level GET and withholds from a cross-site POST. The default `Query` response mode therefore has the provider return the authorization code in a top-level GET redirect, and the handshake cookies stay `Lax`.

Some providers mandate a form POST callback — Apple whenever the `name` or `email` scopes are requested. Setting `ResponseMode` to `FormPost` opts that provider into it, which also switches that provider’s correlation and nonce cookies to `SameSite=None; Secure` — a cross-site POST only ever carries `None` cookies, and `None` requires HTTPS. Do not choose `FormPost` for providers that support `Query`; it trades away the `Lax` hardening for nothing.

### Canonical federated identity

[Section titled “Canonical federated identity”](#canonical-federated-identity)

Provider registrations can opt into a stable, provider-aware account tuple. Without this section, AuthProxy preserves its legacy claim-selection and payload behavior, except that the reserved `urn:cratis:identity:*` namespace is always removed from fresh legacy callbacks before session storage.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Authentication": {
        "OidcProviders": [
          {
            "Name": "Microsoft Entra",
            "Type": "Microsoft",
            "Authority": "https://login.microsoftonline.com/<tenant-id>/v2.0",
            "ClientId": "<client-id>",
            "ClientSecret": "<client-secret>",
            "CanonicalIdentity": {
              "ProviderKey": "entra-workforce",
              "SubjectClaimType": "oid"
            }
          }
        ]
      }
    }
  }
}
```

| Property                                     | Applies to     | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `InvitationCompletionEnabled`                | OIDC and OAuth | Opts this provider into signed invitation completion. Defaults to `false`; ordinary sign-in remains available. Enable only when the provider can produce the exact verified email evidence below.                                                                                                                                                                                                                                         |
| `InvitationIdentityBindingCompletionEnabled` | OIDC and OAuth | Opts this provider into signed invitations already bound by the invitation issuer to an immutable provider subject. Defaults to `false`. This mode does not infer email ownership; enable it only for a tenant-scoped immutable subject and framework-validated issuer.                                                                                                                                                                   |
| `ProviderKey`                                | OIDC and OAuth | Stable lowercase ASCII key, independent of display name and authentication scheme. Keys must be unique across configured providers.                                                                                                                                                                                                                                                                                                       |
| `SubjectClaimType`                           | OIDC and OAuth | Exact claim type on the resulting authenticated `ClaimsPrincipal` that supplies the subject. Exactly one nonempty value is required, and the claim type must be outside the entire case-insensitive `urn:cratis:identity:*` namespace reserved for AuthProxy-authored metadata. There is no fallback to `sub`, name, username, or email. For OAuth user-info fields, map the raw JSON field to this principal claim with `ClaimMappings`. |
| `EmailClaimType`                             | OIDC and OAuth | Exact provider-derived claim used for a signed invitation attestation. Defaults to `email`; exactly one address-shaped value is required during invitation completion.                                                                                                                                                                                                                                                                    |
| `EmailVerifiedClaimType`                     | OIDC and OAuth | Exact provider-derived boolean claim proving ownership of `EmailClaimType`. Defaults to `email_verified`; only one value equal to `true` is accepted.                                                                                                                                                                                                                                                                                     |
| `AssuranceClaimType`                         | OIDC and OAuth | Exact provider-derived assurance claim. Defaults to `acr`; it must be present exactly once for invitation completion.                                                                                                                                                                                                                                                                                                                     |
| `Issuer`                                     | OAuth only     | Explicit absolute HTTPS issuer assigned to the authenticated user-info flow. OIDC providers must omit it because AuthProxy uses the issuer from the framework-validated OIDC token.                                                                                                                                                                                                                                                       |

An identity-bound invitation carries both `recipient_provider_key` and `recipient_identity_binding` in the signed invitation capability. AuthProxy accepts only one exact 43-character base64url SHA-256 binding, restricts provider selection to the exact canonical provider key, and completes only through a provider explicitly opted into `InvitationIdentityBindingCompletionEnabled`. AuthProxy treats the binding as opaque: the invitation authority must independently recompute and compare it from the attested provider key, validated issuer, and immutable subject. For Microsoft Entra, use a tenant-specific authority and `SubjectClaimType=oid`; never substitute email, `preferred_username`, or the mutable display name for the object identifier.

For OAuth, `SubjectClaimType` names the claim after the configured user-info claim actions have run, not the raw JSON property returned by the provider. This complete example maps the raw user-info `id` field to a principal `sub` claim and then selects that `sub` claim as the canonical subject:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Authentication": {
        "OAuthProviders": [
          {
            "Name": "GitHub Enterprise",
            "Type": "GitHub",
            "AuthorizationEndpoint": "https://github.example.com/login/oauth/authorize",
            "TokenEndpoint": "https://github.example.com/login/oauth/access_token",
            "UserInformationEndpoint": "https://github.example.com/api/user",
            "VerifiedEmailEndpoint": "https://github.example.com/api/user/emails",
            "ClientId": "<client-id>",
            "ClientSecret": "<client-secret>",
            "Scopes": ["read:user", "user:email"],
            "ClaimMappings": {
              "sub": "id"
            },
            "CanonicalIdentity": {
              "ProviderKey": "github-workforce",
              "SubjectClaimType": "sub",
              "Issuer": "https://github.example.com"
            }
          }
        ]
      }
    }
  }
}
```

Given a user-info response such as `{ "id": 12345, "login": "octocat" }`, the mapping produces the principal claim `sub=12345`; canonical resolution reads that resulting `sub` claim. Without the mapping, setting `SubjectClaimType` to `sub` fails closed because no such principal claim exists.

For OAuth providers such as GitHub whose ordinary user-information response can omit private addresses, configure `VerifiedEmailEndpoint`. AuthProxy calls it with the provider access token and accepts exactly one JSON-array entry whose `primary` and `verified` properties are both `true` and whose `email` property is nonempty. It replaces any ordinary user-information email with that verified value and writes the configured email-verification claim as `true`. A malformed, ambiguous, missing, or non-success response establishes no invitation email evidence. Request the provider scope needed by that endpoint (`user:email` for GitHub).

When a provider supplies no configured assurance claim, AuthProxy records the successfully completed protocol as `oidc` or `oauth` in `AssuranceClaimType`. A provider-supplied value such as OIDC `acr` takes precedence. These values describe authentication assurance only; they do not grant application roles or membership.

AuthProxy normalizes issuer scheme and host casing, removes a default port and trailing slash, and rejects userinfo, query strings, and fragments. Plain HTTP is accepted only for a loopback development issuer. The stable account key is the complete `(providerKey, normalizedIssuer, subject)` tuple. A raw subject is not globally unique: two providers can issue the same value, and some providers issue pairwise or client-specific subjects that change when the client registration changes.

For Microsoft Entra workforce accounts, configure `SubjectClaimType` as `oid` when the tenant object ID is the intended account identifier. Do not use `preferred_username`, `upn`, or email as a subject. Those values are mutable and can be reassigned. For a provider where `sub` is the intended client-specific identifier, configure `sub` explicitly.

After a fresh provider callback, AuthProxy removes case-insensitive collisions with its reserved claims and adds exactly one AuthProxy-authored set:

* `urn:cratis:identity:provider-key`
* `urn:cratis:identity:issuer`
* `urn:cratis:identity:subject`

The canonical subject also becomes `ClientPrincipal.UserId` and therefore the `x-ms-client-principal-id` value. Provider and issuer travel in the base64 client principal’s claim list; downstream Arc applications receive those claims even though Arc does not preserve the client principal’s `identityProvider` JSON property. The same tuple is posted by invitation exchange, credential linking, and sign-in notification.

`x-ms-client-principal-id` is therefore the provider’s raw subject value, not a globally unique account key. Do not key cross-provider data or authorization by that header alone. Consumers that need the stable account identity must use all three reserved canonical claims as the `(providerKey, normalizedIssuer, subject)` tuple.

#### Canonical session continuity

[Section titled “Canonical session continuity”](#canonical-session-continuity)

A successful canonical browser sign-in binds the authentication cookie to the static provider registration that issued it. AuthProxy writes an opaque, versioned registration fingerprint into the protected authentication ticket for a normal sign-in callback. A credential-link callback does not create or replace a session, so it does not write this fingerprint.

AuthProxy recalculates the fingerprint whenever it validates the cookie. The user must authenticate again if any of these registration inputs changed:

* Provider protocol (`OIDC` or `OAuth`) or derived authentication scheme
* Canonical `ProviderKey` or `SubjectClaimType`
* Configured client ID or the effective client ID on the named authentication handler
* For OIDC, `Authority` or the effective `MetadataAddress`
* For OAuth, the normalized configured canonical `Issuer`; both the configured provider value and the effective named-handler value for `AuthorizationEndpoint`, `TokenEndpoint`, and `UserInformationEndpoint`; every configured `ClaimMappings` key/value pair; and both configured and effective authorization parameters. Collection order does not affect the fingerprint.

The fingerprint contains no subject, email, claims, tokens, client secret, or other PII or secret input. It is an internal continuity marker, not an account identifier and not a claim forwarded to downstream services.

OIDC issuers are different from static registration. AuthProxy records the issuer from the framework-validated token in each canonical session, but does not include that runtime issuer in the registration fingerprint. An unchanged multi-tenant OIDC registration can therefore accept sessions whose validated issuers differ by tenant. For OAuth, there is no validated ID-token issuer: the explicit canonical `Issuer` is static configuration, is checked again during cookie validation, and changing it forces reauthentication.

The backward-compatibility carve-out applies only to a true legacy cookie: it has neither a claim in the case-insensitive `urn:cratis:identity:*` namespace nor a canonical registration fingerprint, and its recorded authentication scheme does not currently resolve to a canonical provider. AuthProxy accepts that cookie without applying canonical continuity. If a marker-free cookie’s recorded scheme now resolves to a canonical provider, AuthProxy rejects it and signs out the cookie session so the user establishes the canonical tuple through a fresh provider callback. A cookie that carries either canonical marker is likewise rejected and signed out when its canonical tuple or fingerprint is missing, malformed, or mismatched.

Canonical identity proves provider authentication metadata only. Applications still decide membership, roles, scopes, and authorization. AuthProxy identity headers are authenticated by deployment topology, not by a per-request signature: prevent clients from reaching downstream services directly. Before forwarding any request, AuthProxy removes all inbound `x-ms-client-principal`, `x-ms-client-principal-id`, and `x-ms-client-principal-name` values. It writes exact trusted replacements only when it has an authenticated principal, so an unauthenticated caller cannot smuggle identity headers downstream.

***

## OAuth 2.0 providers

[Section titled “OAuth 2.0 providers”](#oauth-20-providers)

Not every provider publishes an OpenID Connect discovery document. GitHub is the common one that does not, so it is configured under `Cratis:AuthProxy:Authentication:OAuthProviders` with its endpoints named explicitly instead of discovered from an authority:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Authentication": {
        "OAuthProviders": [
          {
            "Name": "GitHub",
            "Type": "GitHub",
            "AuthorizationEndpoint": "https://github.com/login/oauth/authorize",
            "TokenEndpoint": "https://github.com/login/oauth/access_token",
            "UserInformationEndpoint": "https://api.github.com/user",
            "ClientId": "<client-id>",
            "ClientSecret": "<client-secret>",
            "Scopes": [ "read:user", "user:email" ],
            "ClaimMappings": {
              "sub": "id",
              "name": "name",
              "preferred_username": "login",
              "email": "email"
            },
            "AuthorizationParameters": {
              "prompt": "select_account"
            }
          }
        ]
      }
    }
  }
}
```

OAuth providers sit alongside OIDC providers in every other respect: they appear on the provider-selection page, they get a login endpoint at `/.cratis/login/{scheme}`, and the count of both together decides whether an unauthenticated browser is challenged directly or offered a choice.

`ClaimMappings` is what turns the provider’s user-info JSON into claims — the key is the claim type to create, the value is the field to read it from. The mapping above produces the claims AuthProxy reads when it builds the forwarded principal.

`AuthorizationParameters` adds provider-specific, static values to each authorization request. The example asks GitHub to show account selection instead of silently reusing the active provider session. Keep request policy here rather than appending it to `AuthorizationEndpoint`, so the endpoint remains the provider endpoint. AuthProxy rejects keys owned by the OAuth handler, case-insensitively: `client_id`, `scope`, `response_type`, `redirect_uri`, `state`, `code_challenge`, and `code_challenge_method`. This preserves the framework-generated callback, correlation state, and PKCE values.

Note

OAuth 2.0 has no standard end-session endpoint, so signing out of an OAuth-established session clears the local session only — the user stays signed in at the provider. See [Logout](/authproxy/configuration/logout/).

### OAuthProviderConfig properties

[Section titled “OAuthProviderConfig properties”](#oauthproviderconfig-properties)

| Property                  | Type       | Description                                                                                                                                                                                                                 |
| ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`                    | `string`   | Display name shown on the login selection page, and the source of the scheme name.                                                                                                                                          |
| `Type`                    | `string`   | Provider brand (`GitHub`, `Microsoft`, `Google`, `Apple`, or `Custom`). Picks the logo, and for GitHub also enables [organization and team claims](/authproxy/configuration/authorization/#github-organizations-and-teams). |
| `AuthorizationEndpoint`   | `string`   | The OAuth 2.0 authorization endpoint URL.                                                                                                                                                                                   |
| `TokenEndpoint`           | `string`   | The OAuth 2.0 token endpoint URL.                                                                                                                                                                                           |
| `UserInformationEndpoint` | `string`   | The user-information (profile) API endpoint URL.                                                                                                                                                                            |
| `ClientId`                | `string`   | OAuth 2.0 client ID.                                                                                                                                                                                                        |
| `ClientSecret`            | `string`   | OAuth 2.0 client secret.                                                                                                                                                                                                    |
| `Scopes`                  | `string[]` | Scopes to request. Adding `read:org` to a GitHub provider also adds organization and team claims to the session.                                                                                                            |
| `ClaimMappings`           | `object`   | Claim type → user-info JSON field name.                                                                                                                                                                                     |
| `AuthorizationParameters` | `object`   | Static authorization-request parameter → value. Framework-owned OAuth parameters are rejected at startup.                                                                                                                   |

Configuring a provider decides *who can sign in*, which on a public provider is everybody. To decide who may then get through, see [Authorization](/authproxy/configuration/authorization/).

***

## Session lifetime and re-validation

[Section titled “Session lifetime and re-validation”](#session-lifetime-and-re-validation)

Interactive browser sessions are cookie-based, and every cookie AuthProxy issues for identity or tenant context is **session-scoped or short-lived** — closing the browser ends them. On top of that, `Cratis:AuthProxy:Session` bounds what a browser session that never closes may keep:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Session": {
        "Lifetime": "12:00:00",
        "SlidingExpiration": false,
        "TerminateOnIdentityDenial": false,
        "IdentityRevalidationInterval": "00:10:00",
        "TenantRevalidationInterval": "00:10:00"
      }
    }
  }
}
```

| Property                       | Default    | Description                                                                                                                                                                                                                                                                                  |
| ------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Lifetime`                     | `12:00:00` | Absolute lifetime of the authentication ticket. When it elapses the user must re-authenticate with the identity provider, even in a browser session that never closed.                                                                                                                       |
| `SlidingExpiration`            | `false`    | Whether activity extends the ticket lifetime. Disabled by default so `Lifetime` is a hard bound.                                                                                                                                                                                             |
| `TerminateOnIdentityDenial`    | `false`    | Whether an identity-verification denial ends the local AuthProxy session before serving the forbidden response. This signs out of AuthProxy and clears its session cookies; it does not log the caller out of the external identity provider.                                                |
| `IdentityRevalidationInterval` | `00:10:00` | How long a resolved authorization is remembered before the identity details — and the authorization they represent — are re-resolved against the services. Zero or negative falls back to ten minutes.                                                                                       |
| `TenantRevalidationInterval`   | `00:10:00` | How long a tenant selected through the [tenant-selection flow](/authproxy/configuration/tenant-selection/) is trusted before it is re-validated against `TenantsEndpoint`, so revoked tenant access takes effect without per-request backend calls. Zero or negative disables re-validation. |

The authentication cookie itself carries no persistent `Expires` — the browser drops it when the session ends — and is `HttpOnly`, `SameSite=Lax`, and marked `Secure` whenever the site is served over HTTPS. Re-validation is cached in memory per instance, so within an interval no extra backend calls are made; when the interval lapses, a single backend round-trip refreshes the cached identity or tenant context.

### The two identity cookies

[Section titled “The two identity cookies”](#the-two-identity-cookies)

The resolved identity is written to two cookies, and the split is a security boundary rather than an implementation detail:

| Cookie                           | Readable by script | Contents                     | Role                                                                                                                    |
| -------------------------------- | ------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `.cratis-identity`               | Yes                | Base64 JSON identity details | Lets a frontend render the signed-in user without a round-trip. **Never** treated by AuthProxy as evidence of anything. |
| `.cratis-identity-authorization` | No (`HttpOnly`)    | A sealed, unforgeable record | Carries the authorization decision that is allowed to skip the `/.cratis/me` call on later requests.                    |

Because `.cratis-identity` is deliberately script-readable, anything a client can write must not decide authorization — so the decision lives in the sealed cookie instead. It is protected with ASP.NET data protection and bound to the user and tenant it was issued for, and its expiry is carried *inside* the sealed value rather than left to the cookie’s `Max-Age`, which a non-browser client is free to ignore. A record that cannot be unsealed (for example after a data-protection key rotation) is not a failure: the caller is simply re-authorized against the services.

AuthProxy still reads unexpired version-one authorization records issued for legacy identities. That legacy format separated the expiry, raw subject, and tenant with `|`, so compatibility is limited to presented legacy subjects and tenant IDs that do not contain that delimiter. A delimiter-bearing value is rejected and the caller is re-authorized. Current version-two records use structured fields and do not inherit this legacy restriction.

Deployments running more than one AuthProxy instance should configure a shared `DataProtectionKeysPath` so a record sealed by one instance can be read by the others; without it each instance re-resolves identity for callers whose record it did not issue.

***

## Forwarded identity headers

[Section titled “Forwarded identity headers”](#forwarded-identity-headers)

Once a request is authenticated, AuthProxy tells the backend who is calling. It does that with four headers, written on every proxied request and on every `/.cratis/me` call — and it strips any inbound copy first, so a backend can treat them as proof rather than as a claim.

| Header                        | Carries                                          | Encoding                                                           |
| ----------------------------- | ------------------------------------------------ | ------------------------------------------------------------------ |
| `x-ms-client-principal`       | The full client principal as base64-encoded JSON | Always base64, so always US-ASCII                                  |
| `x-ms-client-principal-id`    | The provider-local subject                       | Verbatim, or RFC 8187 — no sibling announces which                 |
| `x-ms-client-principal-name`  | The display name (`userDetails`)                 | Verbatim, or RFC 8187 when it cannot travel verbatim               |
| `x-ms-client-principal-name*` | The RFC 8187 form of the display name            | Present **exactly** when the plain header carries an encoded value |
| `Tenant-ID`                   | The resolved tenant                              | Verbatim, or RFC 8187 — no sibling announces which                 |

### Every header value is US-ASCII

[Section titled “Every header value is US-ASCII”](#every-header-value-is-us-ascii)

A display name is whatever the identity provider says it is, and providers say things like `Søren Wærstad`, `Ольга Иванова`, `田中太郎`. An HTTP header field is octets, and .NET refuses to write a character above `U+007F` to one — it throws before a byte reaches the socket. So a name outside US-ASCII did not arrive garbled at the backend; the proxied request failed at the gateway and the identity-endpoint call failed silently, and the person could not use the application at all.

AuthProxy now guarantees that every value it writes is printable US-ASCII. A value that already is one — and that could not be mistaken for an encoded one, see below — is sent **byte for byte unchanged**, so if your users’ names are ASCII nothing about the wire format changes and no extra header appears. Anything else is sent as an [RFC 8187](https://www.rfc-editor.org/rfc/rfc8187) `ext-value`: percent-encoded UTF-8 behind a self-describing `UTF-8''` prefix.

```http
x-ms-client-principal-name: UTF-8''S%C3%B8ren%20W%C3%A6rstad
x-ms-client-principal-name*: UTF-8''S%C3%B8ren%20W%C3%A6rstad
```

The starred sibling is the same idiom `Content-Disposition` uses to pair `filename` with `filename*` (RFC 6266 §4.3). Its **presence is the signal**: when `x-ms-client-principal-name*` is there, the plain header carries an encoded value; when it is absent, the plain header is the name verbatim. The plain header is always populated either way, so a backend that gates on the three headers being present keeps working untouched.

Because the encoder emits only RFC 8187 `attr-char` octets, an encoded value can never contain `CR`, `LF` or `NUL`. That alone is not the whole guarantee, though, because a consumer that *decodes* can reconstruct whatever the encoding hid. A name a person chose to write as `UTF-8''victim%0D%0AX-Admin:%20true` is printable US-ASCII from end to end, so it would travel verbatim — and a backend that decided to decode because the value *looked* encoded would get a carriage return, a line feed and a header of the caller’s choosing back out of it.

So the rule is not “encode what ASCII cannot carry”, it is **encode anything that could be mistaken for an encoded value**. A value beginning with `UTF-8''` is itself encoded, however ordinary the rest of it is, and the sibling header is emitted for it. Decoding it returns the literal name the person typed. The guarantee that follows is precise:

> Decode exactly the values the sibling header announces, exactly once, and no identity value can put `CR`, `LF` or `NUL` into a header on your side.

No realistic display name begins with `UTF-8''`, so nothing about ordinary traffic changes.

Note

The sibling header exists only for `x-ms-client-principal-name`. `x-ms-client-principal-id` and `Tenant-ID` go through the same encoder — a value outside US-ASCII on either is sent as an `ext-value` — but nothing announces it, so for those two headers the `UTF-8''` prefix is the only signal there is. That is deliberate: a subject and a tenant identifier are values your identity provider and your configuration issue, not values a person types, so treat them as opaque and forward them rather than decoding them. If you do decode one, decode it once and treat the result as data, never as a header.

### `x-ms-client-principal` is the canonical value

[Section titled “x-ms-client-principal is the canonical value”](#x-ms-client-principal-is-the-canonical-value)

The base64 principal is the source of truth for identity. Its `userDetails` property is the exact original name — every code point, no encoding, no normalization — because base64 was never subject to the ASCII limit in the first place.

Read `userDetails` when you need the name itself. Read `x-ms-client-principal-name` when you want a convenient header and can either accept the encoded form or decode it. Cratis Arc already takes the first route: its Microsoft Identity Platform handler builds the user from the base64 principal, so an Arc backend behind AuthProxy sees exact Unicode names with no changes on its side.

```csharp
// Decoding the header form yourself, when you are not on Arc.
// Gate on the sibling header, never on the prefix: the sibling is what AuthProxy states, and the
// prefix is only what the value looks like. A name a person typed as "UTF-8''..." looks encoded
// and is not, and decoding it because it looked encoded is how a display name becomes a header.
var name = request.Headers["x-ms-client-principal-name"].ToString();
if (request.Headers.ContainsKey("x-ms-client-principal-name*"))
{
    name = Uri.UnescapeDataString(name["UTF-8''".Length..]);
}
```

Decode once, and once only. The result is the person’s name, and a name is data — put it in a model, a log field or a response body, never back into a header.

***

## JWT Bearer (API)

[Section titled “JWT Bearer (API)”](#jwt-bearer-api)

For machine-to-machine calls, configure a JWT Bearer handler:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Authentication": {
        "JwtBearer": {
          "Authority": "https://login.microsoftonline.com/<tenant-id>/v2.0",
          "Audience": "<api-audience>"
        }
      }
    }
  }
}
```

***

## Back-channel client credentials

[Section titled “Back-channel client credentials”](#back-channel-client-credentials)

AuthProxy can also issue bearer tokens itself after a proxied service verifies the supplied client credentials over a private back channel.

1. The client sends `POST /.cratis/token`

2. The request body uses standard OAuth form fields:

* `grant_type=client_credentials`
   * `service=<service-key>` (optional when only one service has client credentials configured)
   * `client_id=<client-id>`
   * `client_secret=<client-secret>`

3. AuthProxy calls the configured downstream verification endpoint with a JSON payload:

```json
{
  "service": "portal",
  "routePrefix": "/api",
  "clientId": "orders-api",
  "clientSecret": "<client-secret>"
}
```

1. Any `2xx` response mints a bearer token scoped to that service and route prefix
2. Any `4xx` response rejects the credentials
3. Any `5xx` response is treated as a downstream verification failure

Successful responses from `/.cratis/token` look like this:

```json
{
  "access_token": "<authproxy-issued-token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<authproxy-issued-refresh-token>"
}
```

The issued bearer token can then be used on the configured route prefix (for example `/api/**`). AuthProxy validates that the token is used against the same configured service and route before forwarding the request.

### Resolving a tenant from the verification response

[Section titled “Resolving a tenant from the verification response”](#resolving-a-tenant-from-the-verification-response)

The `2xx` response from the verification endpoint may optionally include a JSON body with a `tenant` property:

```json
{
  "tenant": "acme"
}
```

When present, AuthProxy embeds that value in the minted access token (and any refresh token issued alongside it) as a `cratis/tenant` claim. The claim travels with the token for its entire lifetime, so every subsequent request authenticated with that token carries it.

To have AuthProxy resolve the tenant and set the `Tenant-ID` header on proxied requests, add a `Claim` [tenant resolution strategy](/authproxy/configuration/tenancy/#claim-strategy-options) pointing at that claim type:

```json
{
  "Cratis": {
    "AuthProxy": {
      "TenantResolutions": [
        { "Strategy": "Claim", "Options": { "ClaimType": "cratis/tenant" } }
      ]
    }
  }
}
```

Like every other `Claim`-resolved value, the tenant returned by the verification endpoint is matched against the `SourceIdentifiers` configured for each entry in `Cratis:AuthProxy:Tenants` — it is not used directly as the Cratis tenant ID unless a tenant also lists it as one of its own source identifiers. See [Tenant registry](/authproxy/configuration/tenancy/#tenant-registry) for how that mapping works.

### Refreshing a token

[Section titled “Refreshing a token”](#refreshing-a-token)

A client can exchange a refresh token for a new access token without resupplying its client credentials:

1. The client sends `POST /.cratis/token`

2. The request body uses:

* `grant_type=refresh_token`
   * `refresh_token=<refresh-token>`

3. AuthProxy validates the refresh token and, if it is still valid, mints a new access token and a new refresh token for the same service, client, and tenant — the response shape is identical to the one shown above.

Refresh tokens are valid for 30 days and are not re-verified against the downstream service on refresh — since the client secret is not resent, AuthProxy trusts the refresh token itself rather than calling back to the target service. There is no revocation list: a leaked refresh token remains usable until it naturally expires, so treat it as a credential and keep its exposure to the same standard as a client secret.

An expired or unrecognized refresh token is rejected with `401 Unauthorized` and `error: "invalid_grant"`. Refresh tokens cannot be used as access tokens (and vice versa) — each is protected separately, so presenting one where the other is expected is always rejected.

### Data Protection keys and horizontal scaling

[Section titled “Data Protection keys and horizontal scaling”](#data-protection-keys-and-horizontal-scaling)

The authentication cookie and AuthProxy-issued client-credentials access and refresh tokens are all encrypted using ASP.NET Core Data Protection. By default, keys are not shared across instances. Running more than one AuthProxy replica, or needing sessions and client-credentials tokens to survive a restart, requires mounting a persistent, shared volume and pointing `Cratis:AuthProxy:DataProtectionKeysPath` at it:

```json
{
  "Cratis": {
    "AuthProxy": {
      "DataProtectionKeysPath": "/mnt/dataprotection-keys"
    }
  }
}
```

Without this, a client-credentials token minted by one replica will fail to validate on another, and all outstanding tokens and sessions are invalidated on every restart.

# Authorization

Authentication tells you *who* is knocking. On a public host that is not the same as deciding whether they may come in.

Put AuthProxy on the internet with GitHub sign-in and the sign-in works — for everybody. Every GitHub account on earth is a real, verified identity, so every one of them completes the handshake and lands on your application. The application is now responsible for turning away people it has never heard of, on every endpoint, forever, and the first mistake is a stranger inside.

`Cratis:AuthProxy:Authorization` makes the proxy the **first gate**: an authenticated caller who does not carry what you require never reaches a service at all.

It is off unless you turn it on. Declare nothing and AuthProxy behaves exactly as it always has.

***

## Declaring a requirement

[Section titled “Declaring a requirement”](#declaring-a-requirement)

A requirement names a claim, and optionally the values you accept:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Authorization": {
        "RequiredClaims": [
          { "Claim": "urn:github:organization", "AnyOf": [ "Cratis" ] }
        ]
      }
    }
  }
}
```

An authenticated caller carrying `urn:github:organization` with the value `Cratis` gets through. Anyone else — signed in or not, and no matter which provider signed them in — is answered with the [not-authorized page](#what-a-refused-caller-sees) and goes no further.

Leave `AnyOf` out to require only that the claim is **present**:

```json
{ "Claim": "urn:example:entitlement" }
```

That is the right shape when the identity provider already emits the claim only for the people who should get in, and enumerating the acceptable values in the proxy would mean restating — and then maintaining — a decision the provider has already made.

Values are compared **case-insensitively**, and surrounding whitespace is trimmed. Organization names, team slugs and role names are case-insensitive in the systems they come from, and `Cratis` versus `cratis` is not a distinction worth locking a deployment out over.

***

## All of the claims, any of the values

[Section titled “All of the claims, any of the values”](#all-of-the-claims-any-of-the-values)

Two axes, and they compose in opposite directions. Say them out loud before you write them:

|                                       | Means                     | Reads as |
| ------------------------------------- | ------------------------- | -------- |
| Several entries in `RequiredClaims`   | **All** must be satisfied | *and*    |
| Several values in one entry’s `AnyOf` | **Any one** satisfies it  | *or*     |

So “in the `Cratis` organization **and** on the `planner` team” is two entries:

```json
"RequiredClaims": [
  { "Claim": "urn:github:organization", "AnyOf": [ "Cratis" ] },
  { "Claim": "urn:github:team", "AnyOf": [ "Cratis/planner" ] }
]
```

…while “on **either** of these two teams” is one entry with two values:

```json
"RequiredClaims": [
  { "Claim": "urn:github:team", "AnyOf": [ "Cratis/planner", "Cratis/operations" ] }
]
```

The distinction matters because the wrong reading fails in the dangerous direction. If entries were an *or*, adding a team requirement next to an organization requirement would **widen** access — to anyone in the organization *or* on that team in any organization — which is the opposite of what you meant by adding it.

Note

A requirement whose `Claim` is blank refuses to start. It could never be satisfied, so applying it would refuse every caller, and dropping it would silently leave the gate open. AuthProxy fails at startup instead, naming the exact configuration key — which is the one moment somebody is watching.

***

## Narrowing one service

[Section titled “Narrowing one service”](#narrowing-one-service)

The same section on a service applies to requests routed to that service, **in addition to** whatever the root requires:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Authorization": {
        "RequiredClaims": [
          { "Claim": "urn:github:organization", "AnyOf": [ "Cratis" ] }
        ]
      },
      "Services": {
        "portal": {
          "Frontend": { "BaseUrl": "http://portal-web:3000/" },
          "Backend": { "BaseUrl": "http://portal:8080/" }
        },
        "admin": {
          "Frontend": { "BaseUrl": "http://admin-web:3000/" },
          "Authorization": {
            "RequiredClaims": [
              { "Claim": "urn:github:team", "AnyOf": [ "Cratis/operations" ] }
            ]
          }
        }
      }
    }
  }
}
```

Everyone reaching either service is in the `Cratis` organization; only the operations team reaches `admin`.

A service can therefore **narrow** who reaches it, never widen it. The alternative — a service section replacing the root’s — would turn the root into a default rather than a floor, so a section written to add an extra check would quietly drop the organization check, and a service added later with no section at all would be the way in.

Which service a request targets is worked out the same way the [route table](/authproxy/configuration/services/) works it out: the single configured service when there is only one, otherwise the `Service-ID` header or the `service` query parameter. A request in a multi-service deployment that names neither reaches no service route either, so only the root requirements apply to it.

***

## GitHub organizations and teams

[Section titled “GitHub organizations and teams”](#github-organizations-and-teams)

This is the case the feature was built for, and it needs one extra thing.

GitHub’s user endpoint — `https://api.github.com/user`, the one you configure as `UserInformationEndpoint` — returns a profile and **nothing about membership**. There is no organization field to map to a claim, so no amount of `ClaimMappings` produces one. Membership lives behind `/user/orgs` and `/user/teams`, and reading those requires the `read:org` scope.

**Ask for `read:org` and AuthProxy fetches it for you**, once, while the sign-in completes, and adds it to the session as claims:

| Claim                     | Value                           | Example          |
| ------------------------- | ------------------------------- | ---------------- |
| `urn:github:organization` | The organization’s GitHub login | `Cratis`         |
| `urn:github:team`         | `organization/team-slug`        | `Cratis/planner` |

One claim per organization and one per team. The team slug is the name in the team’s URL — `github.com/orgs/Cratis/teams/planner` is the slug `planner`. It is qualified by its organization because a slug is only unique within one: two organizations may both have a `developers` team, and an unqualified claim would let membership of either satisfy a requirement written for one.

The scope **is** the opt-in. There is no second switch to forget, and no way for the two to disagree. Without `read:org` nothing extra is requested, no extra call is made, and sign-in is exactly what it was.

Here is a complete configuration restricting a host to the `planner` team in the `Cratis` organization:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Authentication": {
        "OAuthProviders": [
          {
            "Name": "GitHub",
            "Type": "GitHub",
            "AuthorizationEndpoint": "https://github.com/login/oauth/authorize",
            "TokenEndpoint": "https://github.com/login/oauth/access_token",
            "UserInformationEndpoint": "https://api.github.com/user",
            "ClientId": "<client-id>",
            "ClientSecret": "<client-secret>",
            "Scopes": [ "read:user", "user:email", "read:org" ],
            "ClaimMappings": {
              "sub": "id",
              "name": "name",
              "preferred_username": "login",
              "email": "email"
            }
          }
        ]
      },
      "Authorization": {
        "RequiredClaims": [
          { "Claim": "urn:github:organization", "AnyOf": [ "Cratis" ] },
          { "Claim": "urn:github:team", "AnyOf": [ "Cratis/planner" ] }
        ]
      }
    }
  }
}
```

A few things worth knowing before you deploy it:

* **The claims are added at sign-in, not per request.** They live in the authentication cookie, so membership revoked at GitHub takes effect when the session ends — bound by `Cratis:AuthProxy:Session:Lifetime`, twelve hours by default. Shorten it if you need revocation to bite sooner.
* **The application gets them too.** They travel on the forwarded `x-ms-client-principal` header like every other claim, so your service can read organization and team membership without ever calling GitHub.
* **A failed read never breaks the sign-in.** If GitHub is unreachable, or the token lacks the scope, the claims are simply absent — which the gate then refuses, with an explanation. That is the closed direction, reached gently.
* **Membership is read in pages of 100, up to five pages.** Well past any plausible allow-list, and the bound keeps a sign-in someone is waiting on from turning into an unbounded crawl.
* **`Type` must be `GitHub`.** It is what selects the logo on the provider-selection page, and what tells AuthProxy these endpoints are GitHub’s.

GitHub Enterprise works without further configuration: the membership endpoints are derived from whatever `UserInformationEndpoint` you configured, so `https://github.example.com/api/v3/user` resolves its own `/user/orgs` and `/user/teams`.

***

## What a refused caller sees

[Section titled “What a refused caller sees”](#what-a-refused-caller-sees)

The [`not-authorized.html`](/authproxy/configuration/well-known-pages/) page, at `403`, with a **Sign out** link.

Both halves are deliberate. A redirect back to the identity provider — the reflex for “not allowed” — is wrong here: the caller *is* signed in, so they would sign in again as the same person and loop forever. And `403` is a status a `fetch()` or a command-line client can act on, so browsers and non-browsers get the same honest answer.

The sign-out link matters because it is the only way forward. Someone who signed in with a personal account by mistake is otherwise stuck looking at a page that will not change. Override the page — brand it, tell people who to ask for access — by mounting a pages directory; see [Well-Known Pages](/authproxy/configuration/well-known-pages/).

Every refusal is logged at warning level with the claim that was not satisfied and the path that was requested. The claim **type** only — never the value the caller carried, which would put an identity in the log to record that it was turned away.

***

## What is never gated

[Section titled “What is never gated”](#what-is-never-gated)

Three things pass through untouched, and each for a reason worth knowing:

* **Callers with no session.** They are refused — or sent to sign in — by the machinery that already does that. This gate is about who a signed-in caller *is*, not whether there is one.
* **The authentication endpoints themselves** — `/.cratis/providers`, `/.cratis/login/{scheme}`, the provider callbacks, `/.cratis/logout` and the `/_pages` assets. Gating the only route to acquiring the claims on already having them is a door locked from the inside.
* **Paths a service declares in [`AnonymousPaths`](/authproxy/configuration/public-surfaces/).** This is the one that surprises people, so be clear about it: a declared path exists precisely for callers with **no session** — a webhook receiver, a magic-link landing page — and a caller with no session carries no claims to satisfy anything with. Gating them would refuse every one of them, and a payment provider posting a webhook would get a `403` it can do nothing about. A declared anonymous path is public; requiring a claim somewhere else does not quietly un-declare it.

Note

That last point cuts both ways. If a path is declared anonymous, this gate will not protect it — so declare the narrowest prefix that works, and let the application authorize what it serves there.

***

## Environment variables

[Section titled “Environment variables”](#environment-variables)

Everything above is settable purely through environment variables, which is how AuthProxy is normally deployed. Array entries are indexed:

```bash
Cratis__AuthProxy__Authorization__RequiredClaims__0__Claim=urn:github:organization
Cratis__AuthProxy__Authorization__RequiredClaims__0__AnyOf__0=Cratis
Cratis__AuthProxy__Authorization__RequiredClaims__1__Claim=urn:github:team
Cratis__AuthProxy__Authorization__RequiredClaims__1__AnyOf__0=Cratis/planner
```

Per service, the same list moves under the service key:

```bash
Cratis__AuthProxy__Services__admin__Authorization__RequiredClaims__0__Claim=urn:github:team
Cratis__AuthProxy__Services__admin__Authorization__RequiredClaims__0__AnyOf__0=Cratis/operations
```

Indices must start at `0` and not skip — a gap truncates the list where the gap is, silently dropping every requirement after it.

From a .NET Aspire app host, the same thing is expressed as builder calls:

```csharp
builder.AddAuthProxy("authproxy")
    .WithRequiredClaim("urn:github:organization", "Cratis")
    .WithRequiredClaim("urn:github:team", "Cratis/planner")
    .WithRequiredClaimForService("admin", "urn:github:team", "Cratis/operations");
```

Repeated calls append, so requirements can be declared wherever they belong in the app host rather than all in one place.

***

## Settings reference

[Section titled “Settings reference”](#settings-reference)

| Property                               | Type                 | Description                                                                                                                                                                |
| -------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization.RequiredClaims`         | `ClaimRequirement[]` | Requirements every authenticated caller must satisfy. **All** of them must hold. Empty (the default) authorizes nobody away — the proxy authenticates without authorizing. |
| `Authorization.RequiredClaims[].Claim` | `string`             | The claim type the caller must carry. Blank fails startup.                                                                                                                 |
| `Authorization.RequiredClaims[].AnyOf` | `string[]`           | Values that satisfy the requirement, compared case-insensitively. Empty requires only that the claim is present.                                                           |
| `Services.<key>.Authorization`         | `Authorization`      | The same shape, applied to requests routed to that service **in addition to** the root’s.                                                                                  |

***

## Checking it works

[Section titled “Checking it works”](#checking-it-works)

Sign in with an account that qualifies and one that does not. The second should land on the not-authorized page at `403`, and nothing should reach your backend — no request, and no `/.cratis/me` identity call either, because the refusal happens before both.

If a qualifying account is also refused, the requirement and the claim disagree. Read the warning in the proxy’s log: it names the claim that was not satisfied. For GitHub, the usual causes are the `read:org` scope missing from `Scopes`, a team named by its display name rather than its URL slug, or a team written without its `organization/` prefix.

If *nobody* is refused, no requirement bound at all. Check the indices in the environment variables — a skipped index truncates the list.

Next: [Public Application Surfaces](/authproxy/configuration/public-surfaces/) for the paths this gate deliberately leaves open, and [Authentication](/authproxy/configuration/authentication/) for the providers it gates.

# Custom Error Pages

AuthProxy serves user-friendly HTML pages for error conditions instead of bare HTTP status codes. Every error page can be **overridden** by mounting a directory of custom pages into the container.

***

## Built-in pages

[Section titled “Built-in pages”](#built-in-pages)

The following pages are included with AuthProxy and are served automatically when the corresponding condition is detected:

***

## Overriding pages

[Section titled “Overriding pages”](#overriding-pages)

Mount a directory into the container and point `Cratis:AuthProxy:PagesPath` at the mount path. AuthProxy looks up each page by its conventional file name inside that directory. Any page file that is present overrides the built-in default; missing files fall back to the built-in version.

```json
{
  "Cratis": {
    "AuthProxy": {
      "PagesPath": "/mnt/pages"
    }
  }
}
```

Equivalent environment variable:

```plaintext
Cratis__AuthProxy__PagesPath=/mnt/pages
```

### Container mount example (Docker Compose)

[Section titled “Container mount example (Docker Compose)”](#container-mount-example-docker-compose)

```yaml
services:
  authproxy:
    image: cratis/authproxy:latest
    volumes:
      - ./my-pages:/mnt/pages
    environment:
      Cratis__AuthProxy__PagesPath: /mnt/pages
```

### Page assets

[Section titled “Page assets”](#page-assets)

Pages can reference stylesheets, images, and other assets.\
Place asset files in the same pages directory — they are served at the `/_pages/` URL prefix.

```html

<link rel="stylesheet" href="/_pages/styles.css" />
<img src="/_pages/logo.svg" alt="Logo" />
```

***

## Invitation error pages

[Section titled “Invitation error pages”](#invitation-error-pages)

Invitation error pages use **full descriptive names** rather than numeric HTTP status codes because they represent application-level conditions, not generic HTTP errors.

### `invitation-expired.html`

[Section titled “invitation-expired.html”](#invitation-expiredhtml)

Served when a user follows an `/invite/<token>` link whose JWT has a valid signature but has passed its `exp` claim. The user should request a fresh invitation.

### `invitation-invalid.html`

[Section titled “invitation-invalid.html”](#invitation-invalidhtml)

Served when the token on an `/invite/<token>` link is malformed, carries an invalid signature, or cannot be parsed at all. This typically indicates a truncated or otherwise corrupted link.

### `invitation-select-provider.html`

[Section titled “invitation-select-provider.html”](#invitation-select-providerhtml)

Served when a valid invite link is followed and **two or more** identity providers are configured. Before serving the page, AuthProxy injects the `.cratis-providers` cookie (see below) so the page can render a sign-in button for each available provider without an additional HTTP round-trip.

The built-in page reads the cookie with JavaScript and renders one sign-in button per provider. You can override it with a custom branded version by placing your own `invitation-select-provider.html` in the configured pages directory.

### `invitation-subject-already-exists.html`

[Section titled “invitation-subject-already-exists.html”](#invitation-subject-already-existshtml)

Served during Phase 2 (post-login invite exchange) when the exchange endpoint returns HTTP 409 Conflict, indicating that the authenticated user’s subject is already associated with an existing account. The user should sign in with their existing account rather than completing the invitation again.

If you prefer to redirect users to a custom URL instead of serving this page, configure `Invite.SubjectAlreadyExistsUrl` (see [Invitation for Creating Organization](/authproxy/configuration/lobby/invitation-for-creating-organization/#configuration)).

### `invitation-email-unavailable.html`

[Section titled “invitation-email-unavailable.html”](#invitation-email-unavailablehtml)

Served during Phase 2 when `Invite.EmailClaim` binds the invitation to an address but the identity provider supplied no authenticated-session email address. This is not evidence that the invitee used the wrong account; it means AuthProxy has no address to compare. Customize this page to help the user choose a provider or account that exposes an address.

### `invitation-email-mismatch.html`

[Section titled “invitation-email-mismatch.html”](#invitation-email-mismatchhtml)

Served during Phase 2 when the provider supplied an address different from the invited address, or explicitly reported `email_verified=false`. An absent `email_verified` claim is not universal proof of ownership and is forwarded as `null`; OAuth providers do not currently map that claim. See [Invitation to Organization](/authproxy/configuration/lobby/invitation-to-organization/) for the complete binding behavior.

***

## Provider info cookie (`.cratis-providers`)

[Section titled “Provider info cookie (.cratis-providers)”](#provider-info-cookie-cratis-providers)

When AuthProxy serves the `invitation-select-provider.html` page it sets a short-lived, **non-HTTP-only** cookie named `.cratis-providers`. The cookie value is a URL-encoded JSON array where each element describes one configured identity provider:

```json
[
  {
    "name": "Microsoft",
    "type": "Microsoft",
    "loginUrl": "/.cratis/login/microsoft"
  },
  {
    "name": "Google",
    "type": "Google",
    "loginUrl": "/.cratis/login/google"
  }
]
```

| Field      | Description                                                                      |
| ---------- | -------------------------------------------------------------------------------- |
| `name`     | Display name of the provider (from `Authentication:OidcProviders[].Name`).       |
| `type`     | Provider type hint — `Microsoft`, `Google`, `GitHub`, `Apple`, or `Custom`.      |
| `loginUrl` | AuthProxy-relative URL that initiates the OIDC/OAuth challenge for the provider. |

A custom `invitation-select-provider.html` page can read this cookie with JavaScript:

```javascript
function getCookie(name) {
    var match = document.cookie.match(new RegExp('(?:^|; )' + name + '=([^;]*)'));
    return match ? decodeURIComponent(match[1]) : null;
}

var providers = JSON.parse(getCookie('.cratis-providers') || '[]');
providers.forEach(function(provider) {
    var a = document.createElement('a');
    a.href = provider.loginUrl;
    a.textContent = 'Sign in with ' + provider.name;
    document.getElementById('providers').appendChild(a);
});
```

***

## Tenant not found

[Section titled “Tenant not found”](#tenant-not-found)

`tenant-not-found.html` is served when tenant verification is enabled and the platform reports that the resolved tenant ID does not exist. See [Tenant verification](/authproxy/configuration/tenancy/#tenant-verification) for how to configure the verification endpoint.

***

## Tenant selection page

[Section titled “Tenant selection page”](#tenant-selection-page)

`select-tenant.html` is served when the `Selection` tenant-resolution strategy is configured and no `.cratis-tenant` cookie is present for the authenticated user.

See [Tenant Selection Page](/authproxy/configuration/tenant-selection/) for:

* `TenantsEndpoint` configuration
* `.cratis-tenants` cookie schema (`id`, `name`)
* `/.cratis/select-tenant` selection callback behavior
* full custom-page example

# Failed Sign-ins

A sign-in that leaves AuthProxy for an identity provider can come back broken: the provider round-trip fails validation (a stale correlation cookie, an expired state in another tab, a replayed callback URL), or the person cancels the sign-in at the provider. AuthProxy never surfaces any of these as an error page — the browser is redirected back to the provider-selection page (`/.cratis/select-provider`) with a machine-readable reason, and the transient handshake cookies that poison retries are cleared along the way.

***

## The `reason` parameter

[Section titled “The reason parameter”](#the-reason-parameter)

The selection page is opened with a `reason` query-string parameter describing what happened:

| Reason            | Meaning                                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `remote-failure`  | The provider callback could not be validated — correlation failed, the OAuth state was missing or invalid, or the provider reported an error. |
| `access-denied`   | The identity provider reported that access was denied — typically the person cancelled the sign-in or declined the consent prompt.            |
| `invalid-session` | An authenticated session could no longer be turned into a forwardable identity, so it was terminated and a fresh sign-in is required.         |

The bundled `select-provider.html` shows a matching message above the provider buttons; a custom page (see [Well-Known Pages](/authproxy/configuration/well-known-pages/)) can rely on the same contract. When the original destination is known it is carried along in `returnUrl` (validated as same-site relative), so a successful retry still lands where the person was heading.

With a **single** configured provider a failed sign-in still lands on the selection page rather than being challenged again automatically — an immediate re-challenge would loop straight back into the very handshake that failed. The person sees the reason and retries deliberately.

***

## Handshake-cookie hygiene

[Section titled “Handshake-cookie hygiene”](#handshake-cookie-hygiene)

Every provider handshake writes transient correlation and nonce cookies (`.AspNetCore.Correlation.*`, `.AspNetCore.OpenIdConnect.Nonce.*`). Abandoned and half-cleared handshakes leave them behind, and a browser full of stale handshake cookies is exactly what makes the next sign-in fail correlation. AuthProxy clears every one it can see:

* on **every failed** provider callback (this page’s redirect),
* on **every successful** provider callback — one successful sign-in heals a poisoned browser,
* on [logout](/authproxy/configuration/logout/).

On the provider callback path the deletion is issued for both the root path and the callback path itself, which also reaches cookies written by older AuthProxy versions that scoped them to the callback path — those are invisible to the logout endpoint and would otherwise accumulate forever.

***

## Sessions that cannot be forwarded

[Section titled “Sessions that cannot be forwarded”](#sessions-that-cannot-be-forwarded)

A proxied request must either carry the full identity headers or not be proxied at all. Authorization guarantees that a protected route is only reached by an authenticated session, but building the forwardable client principal can still fail closed — for example when [canonical identity](/authproxy/configuration/authentication/#canonical-federated-identity) resolution refuses the session after a configuration change. Instead of forwarding such a request with no identity headers (which the backend refuses, leaving the application blank while the person is “signed in”), AuthProxy terminates the session — signing out and clearing every AuthProxy cookie — and answers:

* a browser navigation with a redirect to the selection page carrying `reason=invalid-session` and the original destination as `returnUrl`;
* any other caller with `401 Unauthorized`.

Routes a service declares in `AnonymousPaths` are exempt — they are proxied without identity by design.

# Provider Selection Pages

When multiple identity providers are configured, AuthProxy serves a provider-selection page so the user can choose which provider to sign in with. Two pages serve this role depending on the flow that triggered them:

| Page                              | Triggered by                                                          |
| --------------------------------- | --------------------------------------------------------------------- |
| `select-provider.html`            | Direct navigation to a protected resource when not yet authenticated. |
| `invitation-select-provider.html` | Following a valid invite link.                                        |

Both pages work identically — they receive provider data via the `.cratis-providers` cookie and can be overridden in the same way. The built-in versions are functional but minimally styled. This guide explains how to replace either or both with fully branded custom pages.

***

## How AuthProxy injects provider data

[Section titled “How AuthProxy injects provider data”](#how-authproxy-injects-provider-data)

Before serving either page, AuthProxy sets a short-lived, **non-HTTP-only** cookie named `.cratis-providers`. The value is a URL-encoded JSON array — one entry per configured identity provider:

```json
[
  {
    "name": "Contoso AD",
    "type": "Microsoft",
    "loginUrl": "/.cratis/login/contoso-ad"
  },
  {
    "name": "GitHub",
    "type": "GitHub",
    "loginUrl": "/.cratis/login/github"
  }
]
```

### Cookie fields

[Section titled “Cookie fields”](#cookie-fields)

| Field      | Type     | Description                                                                                                                                                                                                        |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`     | `string` | Human-readable display name taken from `Authentication:OidcProviders[].Name`.                                                                                                                                      |
| `type`     | `string` | Provider brand — `Microsoft`, `Google`, `GitHub`, `Apple`, or `Custom`. Use this to pick logos or apply brand-specific styling.                                                                                    |
| `loginUrl` | `string` | AuthProxy-relative URL that initiates the OIDC/OAuth challenge for this provider. Navigating to this URL starts the login flow and, after a successful login, redirects the user back to the original destination. |

The cookie expires after 15 minutes and is deleted automatically by the browser after that time.

***

## Reading the cookie

[Section titled “Reading the cookie”](#reading-the-cookie)

The cookie is not HTTP-only so your page’s JavaScript can access it directly via `document.cookie`. The value is URL-encoded, so decode it before parsing:

```javascript
/**
 * Returns the decoded value of the named cookie, or null if it is not present.
 */
function getCookie(name) {
    var pattern = new RegExp('(?:^|; )' +
        name.replace(/([.*+?^=!:${}()|[\]\/\\])/g, '\\$1') + '=([^;]*)');
    var match = document.cookie.match(pattern);
    return match ? decodeURIComponent(match[1]) : null;
}

var providersJson = getCookie('.cratis-providers');
var providers = providersJson ? JSON.parse(providersJson) : [];
```

***

## Minimum viable custom page

[Section titled “Minimum viable custom page”](#minimum-viable-custom-page)

A custom page only needs to:

1. Read the `.cratis-providers` cookie.
2. Render a clickable sign-in element whose `href` is the provider’s `loginUrl`.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Sign In</title>
  <link rel="stylesheet" href="/_pages/brand.css" />
</head>
<body>
  <main id="content">
    <h1>Choose how you want to sign in</h1>
    <ul id="providers"></ul>
    <p id="error" hidden>
      Unable to load sign-in options.
      Please try again or contact support.
    </p>
  </main>

var json = getCookie('.cratis-providers');
      var providers;

try { providers = JSON.parse(json); } catch (_) { providers = null; }

if (!providers || providers.length === 0) {
        document.getElementById('error').hidden = false;
        return;
      }

var list = document.getElementById('providers');
      providers.forEach(function (provider) {
        var li = document.createElement('li');
        var a  = document.createElement('a');
        a.href        = provider.loginUrl;
        a.textContent = 'Sign in with ' + provider.name;
        a.className   = 'provider-btn provider-btn--' + provider.type.toLowerCase();
        li.appendChild(a);
        list.appendChild(li);
      });
    }());
  </script>
</body>
</html>
```

> **Note:** Assets placed in the same pages directory are served at the `/_pages/` URL prefix. The `brand.css` reference above assumes `brand.css` lives alongside your custom page.

The same HTML template works for both `select-provider.html` and `invitation-select-provider.html`. You can use identical files, or tailor each one — for example, showing “You have been invited” in the invitation variant and “Sign in to continue” in the direct-access variant.

***

## Deploying custom pages

[Section titled “Deploying custom pages”](#deploying-custom-pages)

1. Create the HTML file(s) named exactly `select-provider.html` and/or `invitation-select-provider.html`.
2. Place any CSS, images, or other assets in the same directory.
3. Mount the directory into your container and point `Cratis:AuthProxy:PagesPath` at the mount path:

docker-compose.yml

```yaml
services:
  authproxy:
    image: cratis/authproxy:latest
    volumes:
      - ./my-pages:/mnt/pages
    environment:
      Cratis__AuthProxy__PagesPath: /mnt/pages
```

AuthProxy resolves each page file by name — if a file exists in the configured `PagesPath` it is used; otherwise the built-in default is served.

***

## Using the `type` field for branded buttons

[Section titled “Using the type field for branded buttons”](#using-the-type-field-for-branded-buttons)

The `type` value maps to the `OidcProviderType` enum. Use it to apply provider-specific logos or colors:

```javascript
var LOGOS = {
  Microsoft: '/_pages/icons/microsoft.svg',
  Google:    '/_pages/icons/google.svg',
  GitHub:    '/_pages/icons/github.svg',
  Apple:     '/_pages/icons/apple.svg',
  Custom:    '/_pages/icons/generic.svg'
};

providers.forEach(function (provider) {
  var a   = document.createElement('a');
  a.href  = provider.loginUrl;

var img    = document.createElement('img');
  img.src    = LOGOS[provider.type] || LOGOS.Custom;
  img.alt    = provider.name;
  img.width  = 20;
  img.height = 20;

a.appendChild(img);
  a.appendChild(document.createTextNode(' Sign in with ' + provider.name));
  document.getElementById('providers').appendChild(a);
});
```

***

## Complete flow reference

[Section titled “Complete flow reference”](#complete-flow-reference)

### Direct access flow (`select-provider.html`)

[Section titled “Direct access flow (select-provider.html)”](#direct-access-flow-select-providerhtml)

```plaintext
User navigates to protected resource
        │
        ▼
Unauthenticated request detected
        │
        ├─ Single provider ──► redirect to /.cratis/login/<scheme>
        │
        └─ Multiple providers
                │
                ▼
  Set .cratis-providers cookie
  Serve select-provider.html
                │
                │ User clicks provider
                ▼
  GET /.cratis/login/<scheme>
                │
                ▼
      OIDC/OAuth challenge
                │
                ▼
      Redirect to original resource
```

### Invitation flow (`invitation-select-provider.html`)

[Section titled “Invitation flow (invitation-select-provider.html)”](#invitation-flow-invitation-select-providerhtml)

```plaintext
User clicks invite link
        │
        ▼
GET /invite/<token>
        │
        ├─ Token invalid/expired ──► invitation-invalid.html / invitation-expired.html
        │
        └─ Token valid
                │
                ├─ Single provider, not signed in ──► redirect to /.cratis/login/<scheme>
                │
                └─ Multiple providers, or already signed in
                        │
                        ▼
          Set .cratis-providers cookie
          Serve invitation-select-provider.html
                        │
                        │ User clicks provider
                        ▼
          GET /.cratis/login/<scheme>
                        │
                        ▼
              OIDC/OAuth challenge
                        │
                        ▼
              POST-login exchange
                        │
                        ▼
              Redirect to lobby / application
```

### Callers who are already signed in

[Section titled “Callers who are already signed in”](#callers-who-are-already-signed-in)

An invitation is completed only with the identity that authenticated **for that invitation**. A session the browser was already carrying — from an earlier sign-in, possibly with a different provider — never completes one, even though it is a perfectly valid session: the organization would be bound permanently to an account the person did not choose for it.

Such a caller is therefore always shown `invitation-select-provider.html`, even where only one provider is configured, and the invitation completes with whatever identity comes back from the provider they pick. Picking the provider they are already signed in with normally costs no more than a redirect, because the identity provider still has its own session.

The pending invitation is left in place while this happens, so nothing is lost — it stays valid for the lifetime of the `.cratis-invite` cookie.

# Credential Linking

AuthProxy can let an **already signed-in** user prove control of an additional identity-provider login and associate it with their existing account — without ever replacing their current session. This is the proof-of-control building block behind an application’s “add a credential” feature.

```plaintext
GET /.cratis/link?token=<one-time-link-token>                                  → embeddable provider-selection page
GET /.cratis/link/{scheme}?returnUrl=<relative-url>&token=<one-time-link-token> → challenge for one provider
GET /.cratis/link/complete                                                     → completion page
```

It is deliberately **not** the same as `/.cratis/login/{scheme}`: login signs the authenticated identity into the primary session cookie (which, for a second identity, would swap who the user is — effectively logging them out of the original account). The link flow authenticates the second provider, captures its subject, and hands that subject to the application, all while leaving the primary session untouched.

***

## Embedding the flow in the application

[Section titled “Embedding the flow in the application”](#embedding-the-flow-in-the-application)

The flow is designed to run inside a **modal iframe** on the application’s own page. There is one hard constraint it is built around: the provider leg cannot be framed. External identity providers (`login.microsoftonline.com`, `accounts.google.com`, …) send `X-Frame-Options: DENY` / `frame-ancestors 'none'` on their sign-in pages, so any challenge honored inside an iframe leaves a dead frame. The flow is therefore split:

* **The iframe shows AuthProxy pages only.** The application embeds `/.cratis/link?token=…` — the provider-selection page. It lists the configured providers and, on a click, opens `/.cratis/link/{scheme}` with `window.open` — a separate **top-level** window where the provider authenticates. AuthProxy enforces this shape server-side: a navigation to `/.cratis/link/{scheme}` whose `Sec-Fetch-Dest` says it is framed is answered with the selection page instead of a challenge.
* **The provider window reports back over a `BroadcastChannel`.** The completion page (`/.cratis/link/complete`, where the flow ends by default) and the failure page broadcast `{ type: 'cratis:credential-link-complete' }` / `{ type: 'cratis:credential-link-failed' }` on the same-origin channel `cratis.credential-link` — deliberately not `window.opener`, which an identity provider’s `Cross-Origin-Opener-Policy` can sever mid-flow. The completion window then closes itself.
* **The framed page signals the parent with `postMessage`.** On either outcome the selection page forwards the message to `window.parent`, targeted at the configured embed ancestor origins (never `*`), so the application can close its modal and refresh — or leave the modal open for a retry after a failure.

Embedding is **off by default**. The link pages send `Content-Security-Policy: frame-ancestors 'none'` (plus `X-Frame-Options: DENY`) until the deployment names the origins allowed to frame them:

```plaintext
Cratis__AuthProxy__Link__EmbedAncestors__0=self
```

`self` means the proxy’s own origin — the common case, where the application is served through the proxy. Additional entries may name other origins (e.g. `https://app.example.com`). This setting opens the **link pages only**; sign-in and selection pages always refuse framing, and proxied application responses are never touched.

Opening `/.cratis/link/{scheme}` directly in a popup or top-level redirect — the pre-embedding shape — still works exactly as before.

***

## How it works

[Section titled “How it works”](#how-it-works)

1. **The application mints a one-time link token.** When the user starts “add a credential”, the application issues a short-lived, single-use token bound to that signed-in user, and opens the popup at `/.cratis/link/{scheme}?returnUrl=…&token=…`. The `scheme` is a configured provider scheme (the same value used by `/.cratis/login/{scheme}`, e.g. `github`).
2. **AuthProxy challenges the provider.** The request must come from an authenticated session (an anonymous request is rejected with `401`; an unknown scheme with `404`; a missing token with `400`). AuthProxy starts an OAuth/OIDC challenge for the requested scheme, carrying a link-mode marker and the link token through the authentication properties.
3. **On the provider callback the identity is captured, not signed in.** Instead of writing the primary authentication cookie, AuthProxy reads the freshly authenticated `subject` (and identity provider) and `POST`s them to the configured [`ExchangeUrl`](#configuration), authenticated with the link token as the bearer credential — exactly mirroring the [invite exchange](/authproxy/configuration/lobby/invitation-to-organization/). The user’s original session is preserved.
4. **AuthProxy ends the flow — completion only when the exchange succeeded.** On success the browser is redirected to the supplied `returnUrl`, or to the flow’s own completion page (`/.cratis/link/complete`) when none was supplied — which broadcasts the outcome and closes the window. If the exchange did not succeed — the endpoint is not configured, the link token or the provider subject could not be resolved, the endpoint was unreachable, or the application answered with a non-2xx status — the browser receives a generic link-failure page with HTTP `403` instead, and never the completion redirect. The page is the same for every cause, so it reveals nothing about which one occurred; the cause is logged for the operator. A failed provider round-trip (correlation failure, provider error, the person cancelling) ends on the same failure page — never on the sign-in selection page, whose full sign-ins would offer to replace the very session the link was preserving. In every case the user’s primary session is left exactly as it was.

The request body posted to `ExchangeUrl` depends on whether the selected provider opts into [canonical federated identity](/authproxy/configuration/authentication/#canonical-federated-identity).

Legacy providers keep the existing body:

```json
{ "subject": "<provider subject>", "identityProvider": "<issuer / provider>" }
```

Canonical providers add the stable provider-aware identity fields:

with `Authorization: Bearer <one-time-link-token>`.

Canonical identity is opt-in per provider. During migration, the application endpoint must accept both bodies. For a canonical body, bind the account with the complete `(providerKey, issuer, subject)` tuple; never treat `subject` alone or the compatibility `identityProvider` field as the stable account key. The tuple records provider authentication metadata only. The application still decides whether that identity may link a credential to the current account.

***

## The `returnUrl` parameter

[Section titled “The returnUrl parameter”](#the-returnurl-parameter)

`returnUrl` is echoed back to the browser after the link completes, so it is constrained to a **same-site relative path** (a single leading `/`, but not `//`). Anything else — including an absolute URL to another origin — falls back to the flow’s own completion page (`/.cratis/link/complete`), so the endpoint can never be turned into an open redirect. Omitting `returnUrl` lands on the completion page too, which is the right default for the embedded flow.

***

## Configuration

[Section titled “Configuration”](#configuration)

Set the application endpoint that records the freshly authenticated subject under `Cratis:AuthProxy:Link:ExchangeUrl`. It is the link counterpart of `Cratis:AuthProxy:Invite:ExchangeUrl`.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Link": {
        "ExchangeUrl": "https://studio.example.com/api/internal/identity-providers/link",
        "EmbedAncestors": ["self"]
      }
    }
  }
}
```

Equivalent environment variables:

```plaintext
Cratis__AuthProxy__Link__ExchangeUrl=https://studio.example.com/api/internal/identity-providers/link
Cratis__AuthProxy__Link__EmbedAncestors__0=self
```

`EmbedAncestors` names the origins allowed to embed the link pages in an iframe (see [Embedding the flow in the application](#embedding-the-flow-in-the-application)); when empty — the default — the link pages refuse framing entirely.

When `ExchangeUrl` is empty or the `Link` section is absent, there is nowhere to post the subject, so the link callback cannot complete: the browser receives the generic link-failure page (HTTP `403`) rather than the completion redirect. The flow is effectively disabled, and it fails visibly rather than reporting success for a link that was never recorded.

> **Security.** The JSON callback body is not signed. The one-time bearer token binds the operation to the signed-in application user, but it does not by itself prove that AuthProxy sent the HTTP request. Keep `ExchangeUrl` network-isolated from public traffic or authenticate AuthProxy separately at the application endpoint. Keep the token short-lived and single-use, and never turn successful provider authentication into application authorization without applying the application’s own linking policy.

# Lobby

AuthProxy uses the lobby to finish onboarding when a user cannot enter the application directly after authentication.

Use the lobby documentation based on the onboarding outcome you need:

* [Invitation for Creating Organization](/authproxy/configuration/lobby/invitation-for-creating-organization/) — invite a user who should create a new organization after they sign in.
* [Invitation to Organization](/authproxy/configuration/lobby/invitation-to-organization/) — invite a user directly into an existing organization.
* [Registration](/authproxy/configuration/lobby/registration/) — let a user start a self-serve registration flow that ends in organization creation. If the user should join an existing organization, invite them instead.

## Shared configuration

[Section titled “Shared configuration”](#shared-configuration)

All lobby-related settings live under `Cratis:AuthProxy:Invite:Lobby`:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Invite": {
        "Lobby": {
          "Frontend": { "BaseUrl": "http://lobby-service:3000/" },
          "Backend": { "BaseUrl": "http://lobby-service:8080/" },
          "Registration": { "BaseUrl": "http://lobby-service:3000/register" }
        }
      }
    }
  }
}
```

The `Lobby` object uses the standard [`Service`](/authproxy/configuration/services/) shape.

| Property               | Type     | Description                                                                    |
| ---------------------- | -------- | ------------------------------------------------------------------------------ |
| `Frontend.BaseUrl`     | `string` | URL used for lobby redirects after onboarding or when tenant resolution fails. |
| `Backend.BaseUrl`      | `string` | Optional backend API URL for the lobby service.                                |
| `Registration.BaseUrl` | `string` | Optional URL used after `GET /register` completes successfully.                |

## Lobby fallback

[Section titled “Lobby fallback”](#lobby-fallback)

Tenant resolution runs before invite and registration handling.

When AuthProxy cannot resolve a tenant and a lobby frontend is configured, it redirects the user to `Lobby.Frontend.BaseUrl` unless the request is already an onboarding bootstrap path such as `/invite/<token>` or `/register`.

# Invitation for Creating Organization

Use this flow when you invite a user who should create a new organization after they authenticate. AuthProxy validates and stages the invite with the Lobby invitation authority, authenticates the recipient, completes the staged transaction with a signed attestation, and then sends the user to the Lobby frontend.

## Flow

[Section titled “Flow”](#flow)

1. The user opens `https://your-authproxy/invite/<token>`.

2. AuthProxy validates the signed JWT invite token.

3. AuthProxy generates an independent transaction and challenge, signs an `invite-stage` attestation, and calls `Invite.StageUrl`. The Lobby invitation authority validates the exact capability, persists only its hash and bounded transaction state, and discards the raw token.

4. AuthProxy protects the staged state and invite token in short-lived HTTP-only cookies.

* With one configured identity provider, AuthProxy challenges that provider immediately.
   * With multiple providers, AuthProxy serves `invitation-select-provider.html` so the user can choose how to sign in.

5. After successful provider authentication, AuthProxy re-validates the token and protected transaction bindings, derives canonical provider identity from the authenticated ticket, and calls `Invite.ExchangeUrl` with a signed `invite-complete` attestation. The JSON body contains only the opaque transaction ID.

6. The same Lobby invitation authority verifies and atomically consumes the transaction and attestation ID. If it succeeds, AuthProxy redirects the user to `Invite.Lobby.Frontend.BaseUrl`.

This flow is the right fit when the invited user is not entering an already-resolved tenant.

## Configuration

[Section titled “Configuration”](#configuration)

```json
{
  "Cratis": {
    "AuthProxy": {
      "Invite": {
        "PublicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
        "Issuer": "https://ada.example.com",
        "Audience": "authproxy",
        "StageUrl": "https://lobby.example.com/_invite/stage",
        "ExchangeUrl": "https://lobby.example.com/_invite/exchange",
        "TenantClaim": "tenant_id",
        "EmailClaim": "email",
        "Attestation": {
          "Issuer": "https://auth.example.com",
          "Audience": "ada-lobby",
          "ActiveKeyId": "invite-2026-08",
          "Lifetime": "00:01:00",
          "SigningKeys": [
            {
              "KeyId": "invite-2026-08",
              "PrivateKeyPem": "<load-from-secret-provider>"
            }
          ]
        },
        "SubjectAlreadyExistsUrl": "https://app.example.com/errors/account-already-exists",
        "AppendInvitationIdToQueryString": true,
        "InvitationIdQueryStringKey": "invitationId",
        "ClaimsToForward": [
          { "FromClaimType": "organization_id", "ToClaimType": "organization" },
          { "FromClaimType": "invited_by" }
        ],
        "Lobby": {
          "Frontend": { "BaseUrl": "http://lobby-service:3000/" },
          "Backend": { "BaseUrl": "http://lobby-service:8080/" }
        }
      }
    }
  }
}
```

| Property                          | Type                      | Description                                                                                                                                                                   |
| --------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PublicKeyPem`                    | `string`                  | PEM-encoded RSA public key used to verify invite token signatures.                                                                                                            |
| `Issuer`                          | `string`                  | Expected `iss` claim. Leave empty to skip issuer validation.                                                                                                                  |
| `Audience`                        | `string`                  | Expected `aud` claim. Leave empty to skip audience validation.                                                                                                                |
| `StageUrl`                        | `string`                  | Absolute URL of the Lobby invitation authority’s staging endpoint.                                                                                                            |
| `ExchangeUrl`                     | `string`                  | Absolute URL of the same Lobby invitation authority’s completion endpoint.                                                                                                    |
| `TenantClaim`                     | `string`                  | Claim containing the tenant that owns the invitation. Required by the signed protocol.                                                                                        |
| `EmailClaim`                      | `string`                  | Claim type used by the exclusive email-recipient mode. The signed capability must contain exactly one value of this claim or the immutable provider-binding pair, never both. |
| `Attestation`                     | `object`                  | RS256 issuer, audience, active key, private signing-key set, and 10–60-second lifetime used for the two internal calls.                                                       |
| `SubjectAlreadyExistsUrl`         | `string`                  | Redirect target when the exchange endpoint returns HTTP 409. Leave empty to serve `invitation-subject-already-exists.html`.                                                   |
| `AppendInvitationIdToQueryString` | `bool`                    | Appends `jti` from the invite token to the lobby redirect URL when enabled.                                                                                                   |
| `InvitationIdQueryStringKey`      | `string`                  | Query-string key used when appending the invitation ID.                                                                                                                       |
| `ClaimsToForward`                 | `InviteClaimForwarding[]` | Claim mappings forwarded from the invite token into the identity details request.                                                                                             |
| `Lobby.Frontend.BaseUrl`          | `string`                  | Lobby URL used after a successful invite exchange.                                                                                                                            |

## Signed protocol

[Section titled “Signed protocol”](#signed-protocol)

Creating-organization and existing-organization invitations use the same signed two-stage Lobby protocol. See [Signed protocol](/authproxy/configuration/lobby/invitation-to-organization/#signed-protocol) for the exact stage and completion bodies, attestation claims, exclusive recipient modes, verification rules, key rotation, and compatibility contract.

The browser never authors provider identity. Both internal calls are authenticated by short-lived AuthProxy attestations, and the completion body contains no email, provider, issuer, or subject fields.

> **Legacy compatibility.** Omitting `Invite.Attestation` retains the released unsigned JSON exchange. That mode is not sufficient authority for creating or linking an account and must not be used for production onboarding.

## Invite claim forwarding

[Section titled “Invite claim forwarding”](#invite-claim-forwarding)

When `ClaimsToForward` is configured and a pending invite cookie exists, AuthProxy reads the configured invite-token claims and adds them to the principal payload sent to each `/.cratis/me` identity details endpoint.

* Existing identity-provider claims are preserved.
* Mapped invite claims are appended if present.
* If `ToClaimType` is empty, AuthProxy uses `FromClaimType`.

## Invite token format

[Section titled “Invite token format”](#invite-token-format)

Invite tokens are JWTs signed with an RSA private key held by the issuing service. AuthProxy only needs the matching public key to validate the signature.

Recommended claims:

| Claim                                                   | Description                                                                                                                            |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `iss`                                                   | Issuer. Must match `Invite.Issuer` when configured.                                                                                    |
| `aud`                                                   | Audience. Must match `Invite.Audience` when configured.                                                                                |
| `exp`                                                   | Expiry time. Expired tokens are rejected.                                                                                              |
| `jti`                                                   | Unique invitation identifier. Required by the signed protocol.                                                                         |
| `tenant_id`                                             | Tenant that owns the invitation, using the configured `TenantClaim` name.                                                              |
| `email`                                                 | Exactly one invited address for email-recipient mode, using the configured `EmailClaim` name.                                          |
| `recipient_provider_key` + `recipient_identity_binding` | Exact provider key and 43-character opaque binding for immutable identity mode. Both are required together and `email` must be absent. |

## Error handling

[Section titled “Error handling”](#error-handling)

AuthProxy serves dedicated pages for each invitation error:

| Page file                                | Condition                                                                                                                                     | HTTP status |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `invitation-expired.html`                | The token signature is valid, but the `exp` claim is in the past.                                                                             | 401         |
| `invitation-invalid.html`                | The token is malformed or has an invalid signature.                                                                                           | 401         |
| `invitation-select-provider.html`        | The token is valid and multiple identity providers are configured.                                                                            | 200         |
| `invitation-subject-already-exists.html` | The authenticated subject is already associated with an existing account.                                                                     | 409         |
| `invitation-email-unavailable.html`      | Legacy unsigned mode only: email binding is enabled, but the provider supplied no authenticated-session address.                              | 403         |
| `invitation-email-mismatch.html`         | Legacy unsigned mode only: email binding is enabled, and the provider supplied another address or explicitly reported `email_verified=false`. | 403         |

See [Error pages](/authproxy/configuration/error-pages/) for customization details and [Custom Invitation Provider-Selection Page](/authproxy/configuration/invitation-provider-selection/) for a full branded provider-selection walkthrough.

# Invitation to Organization

Use this flow when you invite a user into an organization that already exists. AuthProxy still uses the standard `/invite/<token>` bootstrap, but the invite token carries tenant information so the user can continue directly into the application instead of being sent to the lobby.

## Flow

[Section titled “Flow”](#flow)

1. The user opens `https://your-authproxy/invite/<token>`.
2. AuthProxy validates the token, creates an independent 256-bit transaction and challenge, and calls `Invite.StageUrl`. The signed `invite-stage` attestation binds those values to the exact capability hash, invitation ID, and tenant before provider authentication starts.
3. AuthProxy protects the pending state in an HTTP-only cookie and binds it into the provider’s protected challenge state. A browser can carry the values but cannot author or substitute them.
4. After login, AuthProxy **re-validates the token** (signature, issuer, audience, and lifetime), the protected pending state, and the provider challenge binding.
5. AuthProxy requires one canonical provider identity, one provider-derived email with an exact verified value of `true`, one provider-derived assurance value, and the authentication-ticket issue time.
6. AuthProxy calls `Invite.ExchangeUrl` with a signed `invite-complete` attestation. The JSON body contains only the opaque transaction ID; the browser and request body never supply identity authority.
7. AuthProxy compares the configured `Invite.TenantClaim` from the token with the resolved tenant for the request.
8. If the tenant IDs match, AuthProxy skips the lobby redirect and continues to the target service.

If the tenant IDs do not match, or AuthProxy cannot resolve a tenant for the request, the invite is treated like lobby onboarding and falls back to the configured lobby behavior.

## Configuration

[Section titled “Configuration”](#configuration)

```json
{
  "Cratis": {
    "AuthProxy": {
      "Invite": {
        "StageUrl": "https://lobby.example.com/_invite/stage",
        "ExchangeUrl": "https://lobby.example.com/_invite/exchange",
        "TenantClaim": "tenant_id",
        "EmailClaim": "email",
        "Attestation": {
          "Issuer": "https://auth.example.com",
          "Audience": "ada-lobby",
          "ActiveKeyId": "invite-2026-08",
          "Lifetime": "00:01:00",
          "SigningKeys": [
            {
              "KeyId": "invite-2026-08",
              "PrivateKeyPem": "<load-from-secret-provider>"
            }
          ]
        },
        "Lobby": {
          "Frontend": { "BaseUrl": "http://lobby-service:3000/" }
        }
      }
    }
  }
}
```

| Property                  | Type       | Description                                                                                                                      |
| ------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `StageUrl`                | `string`   | Absolute URL of the Lobby invitation authority’s pre-authentication staging endpoint. Required when `Attestation` is configured. |
| `ExchangeUrl`             | `string`   | Absolute URL of the same Lobby invitation authority’s completion endpoint.                                                       |
| `TenantClaim`             | `string`   | Claim in the invite token that contains the tenant ID.                                                                           |
| `EmailClaim`              | `string`   | Claim in the invite token that contains the invited email. Required by the signed protocol.                                      |
| `Attestation.Issuer`      | `string`   | Exact issuer the invitation authority validates.                                                                                 |
| `Attestation.Audience`    | `string`   | Exact invitation-authority audience.                                                                                             |
| `Attestation.ActiveKeyId` | `string`   | Key ID used for newly signed attestations.                                                                                       |
| `Attestation.SigningKeys` | `array`    | RSA private signing keys. Load private PEM values from a secret provider; pin only the matching public keys downstream.          |
| `Attestation.Lifetime`    | `TimeSpan` | Short-lived token lifetime from 10 through 60 seconds. Defaults to 60 seconds.                                                   |
| `Lobby.Frontend.BaseUrl`  | `string`   | Fallback redirect if the invite cannot continue directly into the organization.                                                  |

## Signed protocol

[Section titled “Signed protocol”](#signed-protocol)

The staging call uses `Authorization: Bearer <stage-attestation>` and this bounded body:

```json
{
  "invitationTransaction": "<opaque transaction>",
  "invitationToken": "<exact signed invitation capability>",
  "invitationChallenge": "<independent opaque challenge>"
}
```

The completion call uses `Authorization: Bearer <complete-attestation>` and a body with no identity fields:

```json
{
  "invitationTransaction": "<opaque transaction>"
}
```

Both RS256 JWTs require `kid`, `iss`, `aud`, `jti`, `iat`, `nbf`, and `exp`. They bind `purpose`, `tenant_id`, `invitation_id`, `invitation_transaction`, `invitation_challenge`, and `capability_hash`. Every completion attestation additionally carries `provider_key`, `provider_issuer`, `provider_subject`, `assurance`, and `authenticated_at`. Email-targeted completion also carries `email` and `email_verified=true`.

The same Lobby invitation authority owns both endpoints. It must independently validate the raw invitation during staging, compare its exact SHA-256 hash to `capability_hash`, persist no raw capability, and atomically consume the transaction and complete-attestation `jti` exactly once. It must reject a wrong purpose, signature, key ID, issuer, audience, lifetime, tenant, invitation, transaction, challenge, or capability hash.

Configure [canonical federated identity](/authproxy/configuration/authentication/#canonical-federated-identity) for every provider. The selected email, verification, and assurance claim types must name provider-derived claims. Missing, duplicate, empty, unverified, or ambiguous evidence fails closed before the completion endpoint is called. Set `CanonicalIdentity.InvitationCompletionEnabled=true` only for providers that can supply that evidence. Signed invitation provider selection hides every other provider while leaving it available for ordinary sign-in. Microsoft Entra commonly omits `email_verified`; do not enable it unless the tenant maps an equivalent trustworthy custom claim and configures its exact claim type. AuthProxy never promotes `email` or `preferred_username` to verified evidence implicitly.

Every signed invitation must select exactly one recipient-authority mode: either one nonempty invited-email claim, or the exact immutable provider-binding pair below. Missing, duplicate, partial, or mixed recipient claims are rejected before staging and again before completion.

For a recipient already known by immutable provider identity, the signed invitation may carry both `recipient_provider_key` and `recipient_identity_binding`. The binding is a canonical 43-character base64url HMAC-SHA-256 value over the provider key, tenant-specific validated issuer, and immutable provider subject using the invitation authority’s documented length-delimited input format. AuthProxy validates the claim shape, restricts the chooser and callback to the exact provider key, and emits the provider key, validated issuer, subject, assurance, and authentication time without inventing email evidence. The invitation authority remains responsible for independently recomputing the opaque binding and comparing it to the staged capability before atomic consumption. Enable this route with `CanonicalIdentity.InvitationIdentityBindingCompletionEnabled=true`; email-targeted invitations continue to require `InvitationCompletionEnabled=true` and exact verified-email evidence.

For Microsoft Entra identity-bound invitations, configure a tenant-specific authority and `CanonicalIdentity.SubjectClaimType=oid`. The framework-validated tenant issuer plus immutable object ID is the identity tuple; `email` and `preferred_username` are not substitutes.

> **Compatibility.** Omitting `Invite.Attestation` retains the released unsigned JSON exchange for existing deployments. That legacy mode is not sufficient authority for creating or linking an account. Enable the signed protocol before an application treats invitation completion as identity proof.

## Rotate signing keys

[Section titled “Rotate signing keys”](#rotate-signing-keys)

1. Add the new public key to the invitation authority’s pinned verification set.
2. Add the new private key and key ID to `SigningKeys` without changing `ActiveKeyId`.
3. Deploy both sides, then switch `ActiveKeyId`.
4. Keep the previous public key until every token it signed has expired, then remove the old key from both sides.

AuthProxy selects exactly one active key and always writes its `kid`. It never logs private key material or attestation payloads.

## Requirements

[Section titled “Requirements”](#requirements)

* The invite token must include the claim configured in `Invite.TenantClaim`.
* The request must resolve to the same tenant value after authentication.
* The invitation link should use the same host and route shape that the organization’s normal traffic uses so tenant resolution produces the expected value.

## When to use another flow

[Section titled “When to use another flow”](#when-to-use-another-flow)

* If the invited user should create a new organization, use [Invitation for Creating Organization](/authproxy/configuration/lobby/invitation-for-creating-organization/).
* If the user should self-register and create an organization without an invite, use [Registration](/authproxy/configuration/lobby/registration/).

# Registration

Use registration when a user should create a new organization without receiving an invite first. Users who are joining an existing organization should use an invitation flow instead.

## Flow

[Section titled “Flow”](#flow)

1. The user opens `https://your-authproxy/register`.

2. AuthProxy stores a short-lived HTTP-only registration cookie.

3. AuthProxy starts authentication.

* With one configured identity provider, AuthProxy challenges that provider directly.
   * With multiple providers, AuthProxy redirects to the standard login page so the user can choose a provider.

4. After a successful login, AuthProxy deletes the registration cookie.

5. AuthProxy redirects the user to `Invite.Lobby.Registration.BaseUrl`.

The `/register` path is only active when `Invite.Lobby.Registration.BaseUrl` is configured.

## Configuration

[Section titled “Configuration”](#configuration)

```json
{
  "Cratis": {
    "AuthProxy": {
      "Invite": {
        "Lobby": {
          "Registration": { "BaseUrl": "https://lobby.example.com/register" }
        }
      }
    }
  }
}
```

| Property                     | Type     | Description                                                                                               |
| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `Lobby.Registration.BaseUrl` | `string` | Absolute URL for the lobby registration experience that creates the organization after AuthProxy sign-in. |

## Aspire

[Section titled “Aspire”](#aspire)

When you configure AuthProxy through Aspire, set the registration destination with `WithLobbyRegistration(...)`:

```csharp
authproxy.WithLobbyRegistration(lobbyResource, "/register");

// or use a raw URL
authproxy.WithLobbyRegistration("https://lobby.example.com/register");
```

This sets `Cratis:AuthProxy:Invite:Lobby:Registration:BaseUrl`.

# Logout

AuthProxy exposes a well-known logout endpoint that ends the current session and returns the user to a validated destination:

```plaintext
GET /.cratis/logout?redirect=<absolute-url>
```

The endpoint is anonymous — it works even when the session is already invalid — and is handled before the authentication challenge stages, so it never bounces the user to a login provider.

***

## Full-chain logout

[Section titled “Full-chain logout”](#full-chain-logout)

A plain cookie logout leaves the user signed in at the identity provider, so the next visit silently re-authenticates. To avoid that, AuthProxy performs a **full-chain logout**: it ends the session both locally *and* at the identity provider using OIDC [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html).

When the session was established through an **OIDC provider**, a logout request:

1. Reads the stored `id_token` and the provider the session was established with from the authentication cookie, and clears the local session (see [What it clears](#what-it-clears)).

2. Redirects (`302 Found`) the browser to that provider’s **end-session endpoint** (discovered from the provider’s OpenID configuration) with:

* `id_token_hint` — the stored `id_token`, so the provider knows which session to end.
   * `post_logout_redirect_uri` — AuthProxy’s own callback, `/.cratis/logout/callback`.

The validated final `redirect` target is carried across the round-trip in a short-lived, HTTP-only cookie (`.cratis-logout`) rather than in the URL.

3. The identity provider ends its own session and redirects back to `/.cratis/logout/callback`.

4. The callback clears every AuthProxy cookie again (idempotent) and redirects (`302 Found`) to the validated final `redirect` target.

> **Register the callback with each OIDC provider.** `post_logout_redirect_uri` must be allow-listed at the provider, so register `https://<your-proxy-host>/.cratis/logout/callback` as a permitted post-logout redirect URI for every OIDC application.

### OAuth 2.0 providers (e.g. GitHub)

[Section titled “OAuth 2.0 providers (e.g. GitHub)”](#oauth-20-providers-eg-github)

OAuth 2.0 providers have no standard OIDC end-session endpoint and cannot be force-logged-out via a redirect. When the session was established through an OAuth provider — or when there is no active OIDC session, or the provider’s discovery document advertises no end-session endpoint — AuthProxy falls back to a **local-only logout**: it clears its own cookies and redirects straight to the validated `redirect` target. The user’s session at the OAuth provider is left untouched, so a later visit may still re-authenticate silently without asking for credentials. This is a limitation of the OAuth providers, not of AuthProxy.

***

## What it clears

[Section titled “What it clears”](#what-it-clears)

Both the local logout and the post-logout callback:

1. Sign the user out of the authentication cookie (`.Cratis.AuthProxy.Auth.v2`), including any chunked variants.

2. Delete every AuthProxy session cookie:

* `.cratis-identity`
   * `.cratis-identity-authorization`
   * `.cratis-tenant`
   * `.cratis-tenants`
   * `.cratis-invite`
   * `.cratis-invite-state`
   * `.cratis-registration`
   * `.cratis-providers`

3. Delete every transient sign-in handshake cookie the browser sent (`.AspNetCore.Correlation.*`, `.AspNetCore.OpenIdConnect.Nonce.*`) — the leftovers of abandoned handshakes that would otherwise poison the next sign-in. See [Failed Sign-ins](/authproxy/configuration/failed-sign-ins/#handshake-cookie-hygiene).

4. Delete any **additional cookies** the deployment configured under `Cratis:AuthProxy:Logout:AdditionalCookies` — cookies AuthProxy does not issue itself but that must not survive a logout. See [Clearing additional cookies](#clearing-additional-cookies).

The `.cratis-logout` carry cookie is deleted by the callback once the final target has been read from it.

After logout nothing of the session survives, so the next visit to a protected resource lands on the provider-selection page (or the single provider’s login) rather than silently reusing anything local. Whether the *identity provider* still remembers the user is governed by the full-chain behavior above.

***

## The `redirect` parameter

[Section titled “The redirect parameter”](#the-redirect-parameter)

The post-logout destination is supplied as an **absolute URL** in the `redirect` query-string parameter, for example:

```plaintext
/.cratis/logout?redirect=https://cratis.studio
```

Because the target is absolute, it cannot be validated with the relative-URL check used elsewhere. Instead it is matched against an **allow-list of origins** so neither the endpoint nor its callback can be turned into an open redirect. The target is validated on both legs of the round-trip. A target is allowed when its origin (scheme + host + port) matches any of:

* The proxy’s **own public origin** as seen by the browser (derived from the request, honoring `X-Forwarded-Proto`). This covers redirecting back to the site the user is already on.
* Any configured **service frontend** (`Cratis:AuthProxy:Services:<name>:Frontend:BaseUrl`).
* The configured **lobby frontend** (`Cratis:AuthProxy:Invite:Lobby:Frontend:BaseUrl`).
* Any origin listed in **`Cratis:AuthProxy:Logout:AllowedRedirectOrigins`** (see below).

Same-site **relative** URLs (a single leading `/`, but not `//`) are always allowed.

If `redirect` is missing, empty, or fails validation, AuthProxy falls back to the application root (`/`).

***

## Allowing additional post-logout origins

[Section titled “Allowing additional post-logout origins”](#allowing-additional-post-logout-origins)

The implicit origins above cover redirecting back to the app itself, but a deployment often wants to send the user somewhere else after logout — for example a separate marketing or landing site that is neither the proxy’s own origin nor a configured frontend. List those origins under `Cratis:AuthProxy:Logout:AllowedRedirectOrigins`. Each entry is an absolute origin (scheme + host, optionally a port) with no path; malformed or non-HTTP(S) entries are ignored.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Logout": {
        "AllowedRedirectOrigins": [
          "https://cratis.studio"
        ]
      }
    }
  }
}
```

Equivalent environment variables (one indexed key per entry):

```plaintext
Cratis__AuthProxy__Logout__AllowedRedirectOrigins__0=https://cratis.studio
```

With the example above, `GET /.cratis/logout?redirect=https://cratis.studio` is permitted even when the app itself is served from a different host such as `https://app.cratis.studio`.

***

## Clearing additional cookies

[Section titled “Clearing additional cookies”](#clearing-additional-cookies)

Logout clears every cookie *AuthProxy* issues — but a deployment often runs sibling authentication infrastructure whose cookies AuthProxy knows nothing about. The classic case is a separate [oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/) guarding an admin app whose session cookie was scoped to the **parent domain** (e.g. `_oauth2_proxy_admin` on `.cratis.studio`): every browser that ever signed in there sends it on every `*.cratis.studio` request, and it survives AuthProxy’s logout — leaving the user half-signed-in from the application’s point of view.

List such cookies under `Cratis:AuthProxy:Logout:AdditionalCookies` and the session-termination sweep deletes them too. Each entry has:

* **`Name`** *(required)* — the exact cookie name. Matching is by exact name only; there is no prefix or wildcard support.
* **`Domain`** *(optional)* — the domain the cookie was scoped to, e.g. `.cratis.studio`. When set, the deletion is issued **for that domain as well as the request host** — necessary because a host-scoped deletion cannot touch a parent-domain cookie. Deleting for a parent domain of the current host is legal, which is exactly what makes this work. Leave it out for a cookie scoped to the request host itself.

Deletions are issued at the root path (`Path=/`) with the `Secure` attribute mirroring the request scheme, so they reliably match how such cookies are typically written.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Logout": {
        "AdditionalCookies": [
          {
            "Name": "_oauth2_proxy_admin",
            "Domain": ".cratis.studio"
          }
        ]
      }
    }
  }
}
```

Equivalent environment variables (one indexed entry per cookie):

```plaintext
Cratis__AuthProxy__Logout__AdditionalCookies__0__Name=_oauth2_proxy_admin
Cratis__AuthProxy__Logout__AdditionalCookies__0__Domain=.cratis.studio
```

The configured cookies are cleared everywhere the session is terminated:

* the logout endpoint (both legs of a full-chain logout), and
* the sign-in sweep that runs when a provider callback completes — so a **fresh sign-in also heals** a browser still carrying the stale cookie, without requiring the user to log out first.

This is a cleanup mechanism for cookies that linger after the owning deployment has been fixed (for example, until an old parent-domain cookie expires) — it does not log the user out of the system that issued the cookie.

***

## Example

[Section titled “Example”](#example)

A “Log out” control in the application simply navigates the browser to the endpoint:

```html
<a href="/cratis/logout/?redirect=https://cratis.studio">Log out</a>
```

For an OIDC session the browser is taken through the provider’s end-session endpoint and back via the callback; for an OAuth session it lands on the target directly. Either way the user ends up on the target unauthenticated at AuthProxy, and requesting a protected resource then triggers the normal login flow.

# Management Listener

AuthProxy answers nothing about itself. There is no health endpoint, no readiness endpoint, no metrics path — every port it opens is the internet-facing one, and every request on it goes through authentication, tenancy and the reverse proxy. That is the right default for a proxy whose whole job is to be the front door, and it leaves a deployment with nothing to probe.

The management listener is the opt-in answer: a **second, private socket** carrying two endpoints and nothing else.

***

## What a probe is actually testing today

[Section titled “What a probe is actually testing today”](#what-a-probe-is-actually-testing-today)

Without it, there are two things a deployment can point a probe at, and neither one says what it looks like it says.

| Probe                                                                                                                 | What it proves                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A TCP socket check                                                                                                    | A process accepted a connection. Nothing about whether configuration bound, whether the Data Protection key ring initialized, or whether a single authenticated request could be served.  |
| An HTTP GET at an application path declared in [`AnonymousPaths`](/authproxy/configuration/services/#anonymous-paths) | The proxy *and* that application are both working. Genuinely useful — but it fails when the application is down, which is not the same question as whether the proxy should be restarted. |

The gap is the middle case: an AuthProxy that starts, listens, and cannot serve anybody. A key ring that will not initialize is exactly that — the process is healthy by every external sign, and every authenticated request fails, because the key ring is what encrypts the session cookie and every AuthProxy-issued token. A TCP probe reports it healthy and keeps sending it traffic.

***

## Turning it on

[Section titled “Turning it on”](#turning-it-on)

Name a port. Everything else has a default.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Management": {
        "Port": 9110
      }
    }
  }
}
```

That opens `http://127.0.0.1:9110` alongside the listener AuthProxy already serves traffic on, and answers two paths there:

| Path            | Answers                                                           |
| --------------- | ----------------------------------------------------------------- |
| `/health/live`  | `200` whenever the request loop is servicing requests.            |
| `/health/ready` | `200` when this instance can serve traffic, `503` when it cannot. |

With Aspire:

```csharp
builder.AddAuthProxy("authproxy")
       .WithManagementListener(9110);
```

**Leaving the section out changes nothing.** No second socket is opened, neither path exists, and AuthProxy binds exactly what it binds without this feature. This is a pure addition — there is nothing to migrate.

***

## Settings

[Section titled “Settings”](#settings)

| Setting       | Default         | Meaning                                                                                             |
| ------------- | --------------- | --------------------------------------------------------------------------------------------------- |
| `Port`        | *(none)*        | The port the listener binds. **Required** — declaring the section without it is refused at startup. |
| `BindAddress` | `127.0.0.1`     | The address it binds.                                                                               |
| `LivePath`    | `/health/live`  | The path answering liveness.                                                                        |
| `ReadyPath`   | `/health/ready` | The path answering readiness.                                                                       |

There is deliberately **no default port**. A port is a fact about your deployment: a value invented here would either collide with something you run or turn a private surface into a well-known one.

The listener defaults to **loopback**, which is what makes it private. In Kubernetes that is reachable by the kubelet’s probes and by a sidecar in the same pod, and by nothing on the network. Widening `BindAddress` publishes both endpoints to everything that can route to the address — do it only when the probe genuinely runs elsewhere, and put a network policy in front of it.

***

## Liveness and readiness answer different questions

[Section titled “Liveness and readiness answer different questions”](#liveness-and-readiness-answer-different-questions)

This distinction is the whole point of having two endpoints, and getting it backwards causes outages.

**Liveness consults nothing.** No dependency is resolved, no I/O is performed. It answers `200` for as long as the process is servicing requests — including while storage, the identity provider and every backend are unreachable. An orchestrator *restarts* what fails a liveness probe, so a liveness answer that depended on a dependency would turn somebody else’s outage into a restart loop of the one component that was still working.

**Readiness verifies local capability only.** Today that means one thing: a `Protect`/`Unprotect` round-trip through Data Protection, which is the only mechanism that forces the key ring to initialize and proves it against the configured [`DataProtectionKeysPath`](/authproxy/configuration/authentication/). It is re-run on every call and no answer is cached, so a key ring that becomes unusable — a volume unmounted, a permission revoked — changes the answer.

Readiness deliberately calls **no backend**, no `/.cratis/me` endpoint, no tenant-verification URL and no OIDC authority. A deployment whose every backend is down still becomes ready, because pulling the proxy out of rotation during a backend outage removes the component that would have served the error page.

***

## The endpoints are on that listener and nowhere else

[Section titled “The endpoints are on that listener and nowhere else”](#the-endpoints-are-on-that-listener-and-nowhere-else)

Both directions are enforced, and both matter.

* **The management paths answer only on the management port.** Asking the public listener for `/health/live` gets the same `404` any unknown path gets. The private surface is not reachable from the internet, whatever the request claims.
* **The management port answers only the management paths.** Anything else on it — `/`, an API path, `/.cratis/providers`, a path you declared anonymous, a bundled asset — gets that same `404`, and is never handed to the middleware pipeline or the reverse proxy. Whatever can reach this port bypassed the ingress by definition; it does not get to use it as a way around authentication.

Isolation is decided by **the socket the request was accepted on**, not by the `Host` header. ASP.NET’s own port-scoping convention (`RequireHost("*:9110")`) matches that header, and a header is whatever the caller typed — a request to the public listener carrying `Host: anything:9110` would otherwise be served from the private surface.

### Your application keeps its own `/health`

[Section titled “Your application keeps its own /health”](#your-application-keeps-its-own-health)

Nothing under `/health` is reserved globally. A service that serves its own health path and declares it in [`AnonymousPaths`](/authproxy/configuration/services/#anonymous-paths) keeps having it proxied exactly as before:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Services": {
        "main": {
          "AnonymousPaths": ["/health"]
        }
      }
    }
  }
}
```

The one exception is the two exact management paths themselves. If your application serves something at `/health/live` or `/health/ready` and you want both, point the management listener elsewhere:

```json
{
  "Management": {
    "Port": 9110,
    "LivePath": "/internal/alive",
    "ReadyPath": "/internal/serving"
  }
}
```

***

## What the endpoints say

[Section titled “What the endpoints say”](#what-the-endpoints-say)

Very little, on purpose. A management endpoint is reachable without a credential by design, so everything it says is said to whoever can reach the port.

Every answer is a short fixed body — `live`, `ready`, `not ready`, or the deployment’s uniform `Not Found` for the `404` — and names no provider, tenant, backend address, filesystem path, key identifier, version or assembly. A failing readiness answer discloses no more than a succeeding one: the reason is written to the log, where an operator reads it and a caller does not.

No answer carries `Set-Cookie` or `WWW-Authenticate`, and AuthProxy never names Kestrel in a `Server` header on any response, whether or not this listener is open.

The `404` is deliberately the *same* refusal the rest of the proxy writes, down to the byte. This middleware runs ahead of the [admission](/authproxy/configuration/admission/) gate, so a management path offered to the **public** listener is refused here and never reaches it — and a refusal of its own shape would tell an unadmitted caller that an AuthProxy is here, that it has a management listener, and what its paths are called.

***

## What is refused at startup

[Section titled “What is refused at startup”](#what-is-refused-at-startup)

The failure mode this feature has to avoid is a deployment that looks configured and answers no probe. Each of these is named at startup, pointing at the exact key:

| Configuration                                   | Why it is refused                                                                                         |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| The section with no `Port`                      | No listener opens, so every probe fails to connect — which reads exactly like the application being down. |
| A `Port` the public listener already binds      | A private listener that shares the public one is not private.                                             |
| A `Port` outside 1–65535                        | Not a port.                                                                                               |
| A `LivePath` or `ReadyPath` that is not rooted  | Matches no request, so the listener answers its own probe the uniform `404`.                              |
| `LivePath` and `ReadyPath` naming the same path | One of the two answers would be unreachable, and the one silently lost is readiness.                      |
| A blank `BindAddress`                           | Names no address. Leave it unset for the loopback default.                                                |

The Aspire builder refuses an unusable port where the app host is built, so the mistake surfaces against the line of code that made it rather than at deployment.

***

## Kubernetes

[Section titled “Kubernetes”](#kubernetes)

```yaml
livenessProbe:
  httpGet:
    path: /health/live
    port: 9110
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health/ready
    port: 9110
  periodSeconds: 5
```

The probe port must be declared as a container port for the kubelet to reach it, and it should **not** be exposed through a Service.

***

## Replacing an existing probe

[Section titled “Replacing an existing probe”](#replacing-an-existing-probe)

If you followed the guidance in [Unauthenticated Responses](/authproxy/configuration/unauthenticated-responses/) and pointed a probe at a declared anonymous path or downgraded it to TCP, this is the better answer for the proxy itself. Keep an application-path probe if you have one — it tests the proxy *and* the application end to end, which is a question worth asking — but point the *proxy’s own* liveness and readiness here, where they mean what their names say.

On a deployment in [`CapabilityOnly`](/authproxy/configuration/admission/) admission mode this listener is the **only** probe available: every path on the public listener answers `404` until a capability has been presented, including one a service declared anonymous.

# Public Application Surfaces

Some parts of an application are served to someone who has no account and never will: a magic-link landing page, a report reached by a signed URL, a public status page. The visitor is not anonymous to the *application* — the token in their link identifies them — but they are anonymous to the **proxy**, which has no session to check.

Declaring those paths is what [`AnonymousPaths`](/authproxy/configuration/services/#anonymous-paths) is for.

> **Not on a closed deployment.** Everything on this page describes a deployment in the default `Public` admission mode. Under [`CapabilityOnly`](/authproxy/configuration/admission/) a declared anonymous path answers the uniform `404` like everything else, because admission runs before authentication and decides whether there is anything here to reach at all. A deployment that needs both a genuinely public surface and a closed one needs two deployments.

***

## Declaring the surface

[Section titled “Declaring the surface”](#declaring-the-surface)

Name the specific paths the application serves without a session — the landing route that exchanges the token, and the API routes it calls:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Services": {
        "core": {
          "Frontend": { "BaseUrl": "http://core-web:3000/" },
          "Backend": { "BaseUrl": "http://core:8080/" },
          "AnonymousPaths": [
            "/customer-portal",
            "/api/customer-portal"
          ]
        }
      }
    }
  }
}
```

`/customer-portal` is served by the frontend, `/api/customer-portal` by the backend — the split follows the same `/api` rule the authenticated routes use.

### Declare the narrowest prefix that works

[Section titled “Declare the narrowest prefix that works”](#declare-the-narrowest-prefix-that-works)

Entries are prefixes and cover everything beneath them. `/api/customer-portal` opens every route under it, including ones added later by someone who does not know the prefix is public. If only some of those routes are public, name them individually instead.

***

## What still protects the surface

[Section titled “What still protects the surface”](#what-still-protects-the-surface)

The token in the link. AuthProxy does not check it — it cannot, because only the application knows how it was minted. The application validates it on every request, exactly as it would if the proxy were not there.

What the proxy still does:

* Strips inbound `x-ms-client-principal`, `x-ms-client-principal-id`, `x-ms-client-principal-name` and `Tenant-ID` headers, so a caller cannot assert an identity on the way in.
* Injects no principal headers, because there is no session.
* Leaves an authenticated visitor authenticated. A declared path is identity-*optional*, not identity-free: someone who happens to be signed in still arrives with their identity headers, though **without** a `Tenant-ID` if they have not selected a tenant. Handle a declared path as tenant-optional.

***

## Why declare it in the proxy rather than route around it

[Section titled “Why declare it in the proxy rather than route around it”](#why-declare-it-in-the-proxy-rather-than-route-around-it)

The alternative is an ingress rule above AuthProxy sending those paths straight to the service. It works, and it costs two things worth understanding before choosing it.

**It moves the identity-trust boundary.** Bypassing the proxy makes the service directly reachable, so the ingress rule must strip inbound `x-ms-client-principal*` and `Tenant-ID` headers itself. Stripping and re-injecting those headers is precisely AuthProxy’s job; a carve-out that forwards them unfiltered is an authentication bypass. The rule now has to be as correct as the proxy, and it is maintained somewhere else, by someone else.

**It weakens what you can say about the deployment.** “Public traffic reaches AuthProxy only” becomes “public traffic reaches AuthProxy except for this list”, and the list has to be re-audited whenever it changes.

Declaring the paths inside the proxy has neither cost. Traffic still flows through AuthProxy, so the header boundary holds and the invariant stays whole.

***

## Checking it works

[Section titled “Checking it works”](#checking-it-works)

An unauthenticated request to a declared path should reach the application. If it comes back as the sign-in chooser, the declaration was not accepted — an entry that is not a rooted path of literal segments is discarded silently, so check its spelling first. See [Anonymous paths](/authproxy/configuration/services/#anonymous-paths) for the exact rule.

If it comes back as a bare `404 Not Found` and so does every other path — including `/.cratis/providers` — the deployment is in [`CapabilityOnly`](/authproxy/configuration/admission/) admission mode, and no declaration will open it.

If the request comes back as `401` rather than the application’s response, the caller was not treated as a browser navigating to a page. That is expected for a `fetch()` or a command-line client against an *undeclared* path — see [Unauthenticated responses](/authproxy/configuration/unauthenticated-responses/).

For the sibling case, an inbound request from a system rather than a person, see [Receiving webhooks](/authproxy/configuration/webhooks/).

# Services

AuthProxy routes requests to one or more **services** using [YARP](https://microsoft.github.io/reverse-proxy/). Each service may expose a **backend** (API), a **frontend** (SPA / static assets), or both.

***

## Configuration

[Section titled “Configuration”](#configuration)

Services are configured under `Cratis:AuthProxy:Services`, keyed by a friendly name:

```json
{
  "Cratis": {
    "Services": {
      "portal": {
        "Backend": { "BaseUrl": "http://portal-api:8080/" },
        "Frontend": { "BaseUrl": "http://portal-web:3000/" },
        "ResolveIdentityDetails": true,
        "AnonymousPaths": [ "/welcome", "/api/webhooks/payments" ],
        "ClientCredentials": {
          "RoutePrefix": "/api",
          "VerificationPath": "/.cratis/client-credentials/verify"
        }
      },
      "catalog": {
        "Backend": { "BaseUrl": "http://catalog-api:8080/" }
      }
    }
  }
}
```

### ServiceConfig properties

[Section titled “ServiceConfig properties”](#serviceconfig-properties)

| Property                      | Type                             | Default                                                   | Description                                                                                                                                  |
| ----------------------------- | -------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `Backend`                     | `ServiceEndpointConfig`          | `null`                                                    | API backend endpoint.                                                                                                                        |
| `Frontend`                    | `ServiceEndpointConfig`          | `null`                                                    | SPA / static-asset frontend endpoint.                                                                                                        |
| `ResolveIdentityDetails`      | `bool?`                          | `true` when Backend is set                                | Whether to call `/.cratis/me` on this service **at all**. See [Identity enrichment](#identity-enrichment).                                   |
| `IdentityVerification`        | `BestEffort` \| `Required`       | `BestEffort`                                              | What that call’s answer **means**. See [Identity enrichment](#identity-enrichment).                                                          |
| `IdentityVerificationTimeout` | `TimeSpan`                       | `00:00:10` under `Required`, unbounded under `BestEffort` | How long to wait for the answer. Zero or negative leaves the wait unbounded. See [Two settings, two questions](#two-settings-two-questions). |
| `AnonymousPaths`              | `string[]`                       | `[]`                                                      | Path prefixes on this service served to unauthenticated callers. See [Anonymous paths](#anonymous-paths).                                    |
| `ClientCredentials`           | `ServiceClientCredentialsConfig` | `null`                                                    | Enables back-channel client-credentials verification and token minting for this service.                                                     |

### ServiceEndpointConfig properties

[Section titled “ServiceEndpointConfig properties”](#serviceendpointconfig-properties)

| Property  | Type     | Description                                                |
| --------- | -------- | ---------------------------------------------------------- |
| `BaseUrl` | `string` | Base URL of the endpoint (e.g. `http://my-service:8080/`). |

### ServiceClientCredentialsConfig properties

[Section titled “ServiceClientCredentialsConfig properties”](#serviceclientcredentialsconfig-properties)

| Property           | Type     | Description                                                                                                             |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `RoutePrefix`      | `string` | Route prefix that AuthProxy-issued bearer tokens are allowed to access (for example `/api`).                            |
| `VerificationPath` | `string` | Internal verification endpoint. Relative values are resolved against `Backend.BaseUrl`; absolute values are used as-is. |

***

## Routing

[Section titled “Routing”](#routing)

### Single service

[Section titled “Single service”](#single-service)

When only one service is configured, AuthProxy adds a plain catch-all route so the service is reachable without any special routing header or query parameter.

* `/{**path}` → frontend
* `/api/{**path}` → backend

### Multiple services

[Section titled “Multiple services”](#multiple-services)

With more than one service, clients must indicate the target using one of:

| Mechanism                   | Example              |
| --------------------------- | -------------------- |
| `Service-ID` request header | `Service-ID: portal` |
| `service` query parameter   | `?service=portal`    |

Routes are matched case-insensitively.

***

## Anonymous paths

[Section titled “Anonymous paths”](#anonymous-paths)

By default every path behind AuthProxy requires a session. An unauthenticated request is answered by the provider-selection page if it is a browser navigation, or [refused with a status code](/authproxy/configuration/unauthenticated-responses/) if it is not — and anything that does reach the reverse proxy is refused by the default authorization policy.

`AnonymousPaths` declares the paths a service genuinely serves without a session: a magic-link landing page, a signed-token report, a public webhook receiver.

A declared path is reachable by anyone who knows the URL — AuthProxy stops demanding a login, it does not authenticate the caller. The application remains responsible for deciding whether to trust the request.

Two how-to guides cover the cases in detail: [Public application surfaces](/authproxy/configuration/public-surfaces/) for a page or API a person reaches without an account, and [Receiving webhooks](/authproxy/configuration/webhooks/) for a request from another system.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Services": {
        "portal": {
          "Frontend": { "BaseUrl": "http://portal-web:3000/" },
          "Backend": { "BaseUrl": "http://portal-api:8080/" },
          "AnonymousPaths": [ "/welcome", "/api/webhooks/payments" ]
        }
      }
    }
  }
}
```

From Aspire:

```csharp
authProxy.WithAnonymousPaths("portal", "/welcome", "/api/webhooks/payments");
```

### Matching

[Section titled “Matching”](#matching)

Each entry is a **path prefix**, matched case-insensitively on segment boundaries — the same semantics as the built-in invite, registration and authentication-UI paths.

| Declared                 | Matches                                                 | Does not match                            |
| ------------------------ | ------------------------------------------------------- | ----------------------------------------- |
| `/welcome`               | `/welcome`, `/welcome/`, `/WELCOME`, `/welcome/abc/def` | `/welcomex`, `/app/welcome`               |
| `/api/webhooks/payments` | `/api/webhooks/payments/...`                            | `/api/webhooks`, `/api/webhooks/invoices` |

Because an entry covers everything below it, name the specific leaf path whenever a sibling under the same parent is not public.

### What a valid entry looks like

[Section titled “What a valid entry looks like”](#what-a-valid-entry-looks-like)

An entry must be a rooted path whose segments are made only of the characters `A–Z`, `a–z`, `0–9`, `-`, `.`, `_` and `~`. Anything else is **refused**, leaving that path authenticated.

Refusing rather than interpreting is deliberate, and every rule below is a case where a declared prefix would otherwise have meant one thing to the reader and another to the proxy:

| Refused                                 | Example                                                                              | Why                                                                                                                                                                                     |
| --------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Blank, whitespace, or the bare `/`      | `""`, `"/"`, `"///"`                                                                 | An empty prefix matches *every* request and would turn the whole service anonymous — the worst outcome this feature can produce.                                                        |
| Unrooted                                | `welcome`                                                                            | Not a path prefix.                                                                                                                                                                      |
| An empty segment                        | `/a//b`                                                                              | Not a legal route template.                                                                                                                                                             |
| A `.` or `..` segment                   | `/public/../admin`                                                                   | Reads as scoped to `/public` while naming `/admin`. Refused rather than resolved, so a prefix always means what it spells.                                                              |
| Any character outside the permitted set | `/a{x}`, `/a*`, `/a?b`, `/a;b`, `/a:b`, `/a@b`, `/a\b`                               | `{`, `}` and `*` would make the router match `/aANYTHING/…` where the middlewares match only the literal. The rest are separators or delimiters to some parsers and literals to others. |
| Percent-encoding                        | `/public%2fadmin`, `/public/%2e%2e/admin`                                            | A prefix whose meaning depends on encoding cannot be reasoned about — and these are the classic separator-smuggling and traversal forms.                                                |
| Control characters or whitespace        | `/a b`, `/a\tb`                                                                      | Invisible differences between two entries that read identically, and the raw material of log and header injection.                                                                      |
| Non-ASCII characters                    | `/públic`                                                                            | The same path has more than one Unicode spelling (`NFC` vs `NFD`), so which one is anonymous would depend on how the configuration file was saved.                                      |
| A path AuthProxy answers itself         | `/.cratis`, `/.cratis/token`, `/_pages`, `/invite`, `/register`, `/signin-microsoft` | These do not become “more public” — they take the endpoint *away* from AuthProxy and hand it to a backend.                                                                              |

A dot *inside* a segment is fine, so `/.well-known/acme-challenge` and `/public/health.json` are both valid. Only a segment that is exactly `.` or `..` is refused.

A refused entry is reported at startup as a warning naming the entry and the reason, so a declared path that still returns the selection page can be diagnosed from the log rather than by inspection.

`/api` chooses the endpoint the same way the authenticated routes do: a prefix under `/api` is served by the service’s `Backend`, anything else by its `Frontend`, falling back to whichever endpoint the service actually declares.

### What it does and does not change

[Section titled “What it does and does not change”](#what-it-does-and-does-not-change)

* The request still travels through AuthProxy. Inbound `x-ms-client-principal`, `x-ms-client-principal-id`, `x-ms-client-principal-name` and `Tenant-ID` headers are stripped as they are for every other request, so a caller cannot assert an identity on an anonymous path.
* No principal headers are injected for a caller with no session. A caller that *does* present a valid session is still authenticated normally and still gets its identity headers — the path is identity-*optional*, not identity-free.
* A signed-in caller reaches a declared path **without a `Tenant-ID` header** when they have not chosen a tenant, because tenant selection is skipped along with everything else. Handle a declared path as tenant-optional: it already has to work for a caller with no identity at all, so identity without a tenant is a strictly better-informed case of the same thing.
* The application remains responsible for authorizing these paths. This only stops the proxy from demanding a login before the application is ever reached.
* A declared prefix is claimed for the whole proxy. An anonymous caller cannot send a `Service-ID` header, so the path itself identifies the service — in a multi-service deployment no other service can serve anything under a declared prefix. If two services declare the same prefix, the first one in configuration order serves it; the path stays anonymous, which is what both asked for.
* A declared path is reachable for *every* caller, not only signed-out ones. Provider selection, the unresolved-tenant refusal and the tenant-selection page are all skipped for it, so a user who happens to be signed in — without having chosen a tenant — still gets the application’s response rather than a chooser page.

***

## Identity enrichment

[Section titled “Identity enrichment”](#identity-enrichment)

For each service with a `Backend` endpoint (and `ResolveIdentityDetails` not explicitly set to `false`), AuthProxy calls `GET {Backend.BaseUrl}/.cratis/me` after authentication. The response is stored in a short-lived cookie (`.cratis-identity`) and injected as the `x-ms-client-principal` header on every proxied request so that backend services can read identity details without re-calling the identity endpoint themselves.

What exactly your service receives — the four identity headers, the guarantee that every value is US-ASCII, the `x-ms-client-principal-name*` sibling for names that are not, and why `x-ms-client-principal` stays the canonical value — is described in [Forwarded identity headers](/authproxy/configuration/authentication/#forwarded-identity-headers).

### Two settings, two questions

[Section titled “Two settings, two questions”](#two-settings-two-questions)

`ResolveIdentityDetails` decides whether the endpoint is **called**. `IdentityVerification` decides what its answer is **worth**. They are separate because they are separate questions, and they have opposite failure directions.

Asking a service “what else do you know about this user” is enrichment: if the service is down, the right answer is to carry on without the extra details. Asking it “is this user allowed in at all” is verification: if the service is down, the only safe answer is no. A single flag cannot express both, so the mode is per service.

| Mode                   | Meaning                                                 | Use for                                                                           |
| ---------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `BestEffort` (default) | The endpoint enriches. Only an explicit `403` denies.   | A service that contributes display details — profile, preferences, feature flags. |
| `Required`             | The endpoint decides. Only an explicit positive admits. | The one service that genuinely answers with an authorization verdict.             |

`BestEffort` is the released behavior and stays the default, so an existing deployment is unaffected. That is meant exactly: the released proxy read no verdict out of a successful response body at all, it took `details` and forwarded the caller. So under `BestEffort` a body saying `"isAuthorized": false` is **not** a refusal — the caller is admitted and those details are merged, the same as before. Plenty of services answer that for reasons that are not about access at all: an account mid-onboarding, a lapsed trial, a profile the frontend renders a banner for. If your service means it as a decision, say so with `Required`.

`Required` also decides how long the call may take. See [What each outcome does](#what-each-outcome-does) for the timeout that follows from it.

### What each outcome does

[Section titled “What each outcome does”](#what-each-outcome-does)

| The service…                                                | `BestEffort`           | `Required`             |
| ----------------------------------------------------------- | ---------------------- | ---------------------- |
| answers `200` with an unambiguous positive verdict          | forward, merge details | forward, merge details |
| answers `403`                                               | **deny**               | **deny**               |
| answers `200` with a verdict of “not authorized”            | forward, merge details | **deny**               |
| cannot be reached (DNS, connection refused, TLS)            | forward                | **deny**               |
| does not answer within `IdentityVerificationTimeout`        | forward                | **deny**               |
| is still answering when the caller goes away                | forward                | **deny**               |
| answers any other non-`2xx` (400, 401, 404, 500, 502, 503…) | forward                | **deny**               |
| answers `204`, or `200` with an empty or blank body         | forward                | **deny**               |
| answers a body that will not parse as JSON                  | forward                | **deny**               |
| answers well-formed JSON carrying no verdict                | forward, merge details | **deny**               |
| answers `200` with contradicting verdicts                   | forward, merge details | **deny**               |

An **unambiguous positive** is a body carrying `isAuthorized: true` as a JSON boolean, and not contradicting it with `isAuthenticated: false`. A response that carries only details states no verdict — which is exactly right for a service being asked only to enrich, and never enough for one being asked to decide. Property names are matched without regard to casing; a quoted `"true"` is not a verdict.

Read the `BestEffort` column as one sentence: **`403` denies, everything else is forwarded and whatever details arrived are merged.** That is the released behavior, unchanged, and it is what makes the mode safe to leave alone.

### How long the call may take

[Section titled “How long the call may take”](#how-long-the-call-may-take)

`IdentityVerificationTimeout` states the wait. Leave it unset and the mode decides, because a bound on the wait is a property of a decision, not of enrichment:

| Mode         | Unset timeout means                                                                                                                                                                                                                             |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BestEffort` | Unbounded — the ambient 100-second HTTP client default, exactly as released. A slow enrichment service still gets to answer, because cutting it off would not refuse anybody, it would admit them with that service’s details silently missing. |
| `Required`   | Ten seconds. A service standing between a caller and a decision has to fail in bounded time — otherwise a service that accepts connections and then stops answering holds every authenticated request open for a minute and a half each.        |

A timeout you **do** state is honored in both modes. The wait is also bound to the caller’s own request lifetime either way, so a client that disconnects stops occupying the proxy.

Where several services take part, **every** service in `Required` mode must answer with a positive. Requirements add together and are never widened, the same way [service claim requirements](/authproxy/configuration/authorization/) compose. A `BestEffort` service failing alongside them costs the caller nothing but the details it would have supplied.

### On every denial

[Section titled “On every denial”](#on-every-denial)

AuthProxy serves the [forbidden page](/authproxy/configuration/well-known-pages/) at `403` and erases everything an earlier success left behind: the sealed `.cratis-identity-authorization` record is cleared, the readable `.cratis-identity` cookie is expired, and the in-memory result is evicted. Without that, the next request would present one of them and skip the question that was just answered no.

Set `Cratis:AuthProxy:Session:TerminateOnIdentityDenial` to `true` when a denial should also end the local AuthProxy session. AuthProxy signs out of its authentication cookie and clears the identity, authorization, tenant, invitation, registration, provider-selection, transient authentication, and configured additional logout cookies before serving the same `403`. It retains capability-entry and in-progress logout state, and does not initiate logout at the external identity provider. The default is `false`, which preserves the authenticated session exactly as earlier releases did.

Note

Two of those three erasures are *requests to the browser*, not guarantees. Clearing a cookie means sending a `Set-Cookie` that expires it, and a non-browser caller is free to ignore it and keep presenting the sealed record it was issued. So what `Required` bounds is **revocation latency**, not reuse: a positive can be replayed for at most `IdentityRevalidationInterval` (the sealed record) or `IdentityResultCacheDuration` (the proxy’s own cache), whichever applies, and no longer. Shorten them to shorten that window — or set `IdentityRevalidationInterval` to zero, which under `Required` means no record is sealed at all and every request is verified.

The denial is logged with a bounded reason code (`TransportFailure`, `TimedOut`, `UnsuccessfulStatusCode`, `NoVerdict`, …) and never with the response body, which is content from a system that knows who the caller is.

### Turning the memory off

[Section titled “Turning the memory off”](#turning-the-memory-off)

Two settings under [`Session`](/authproxy/configuration/authentication/#session) bound how long an answer is reused:

* `IdentityResultCacheDuration` (default 30 seconds) — the proxy’s own in-memory cache, which collapses a page load’s burst of requests into one round-trip per user and tenant. Set it to zero to resolve on every request.
* `IdentityRevalidationInterval` (default 10 minutes) — how long the sealed authorization record is honored. Set it to zero for no bound. Under `Required`, “no bound” means **no record is written at all**, so every request is verified.

Both are the window in which a user whose access has just been revoked still gets through, so shorten them deliberately: the cost is one identity-endpoint call per request per user.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Session": {
        "IdentityResultCacheDuration": "00:00:05",
        "IdentityRevalidationInterval": "00:01:00"
      },
      "Services": {
        "portal": {
          "Backend": { "BaseUrl": "http://portal-api:8080/" },
          "IdentityVerification": "Required",
          "IdentityVerificationTimeout": "00:00:10"
        },
        "reporting": {
          "Backend": { "BaseUrl": "http://reporting-api:8080/" }
        }
      }
    }
  }
}
```

From Aspire:

```csharp
authProxy.WithIdentityVerification("portal", IdentityVerificationMode.Required);
authProxy.WithSessionTerminationOnIdentityDenial();
```

> **Requiring verification makes that service a single point of failure, on purpose.** While it is down, nothing behind the proxy is served, because nobody can confirm who is allowed in. That is the trade the mode exists to make — take it only for a service that really does answer `/.cratis/me` with a verdict.

### `Required` needs a tenant resolution

[Section titled “Required needs a tenant resolution”](#required-needs-a-tenant-resolution)

Identity is resolved per **user and tenant**, so a verdict is always a verdict about somebody in some tenant. A deployment with no [tenant resolution](/authproxy/configuration/tenancy/) configured resolves no tenant for anybody — so there is nothing to verify against, on every request, for everyone.

AuthProxy therefore **refuses to start** when a service declares `Required` and `TenantResolutions` is empty, and the message names the key. Nothing about the alternative looks broken from the outside: the proxy starts, people sign in, requests are forwarded, and the only thing that does not happen is the check you asked for. A single-tenant deployment satisfies this with the `Specified` strategy:

```json
{
  "Cratis": {
    "AuthProxy": {
      "TenantResolutions": [
        { "Strategy": "Specified", "Options": { "TenantId": "00000000-0000-0000-0000-000000000000" } }
      ]
    }
  }
}
```

At request time the same principle applies: an authenticated caller whose tenant does not resolve is **refused**, not waved through. There is one deliberate exemption — a path listed in [`AnonymousPaths`](#anonymous-paths) is declared to be served without a session at all, so no verdict is demanded for it and the application stays responsible for authorizing it, exactly as that setting already says. AuthProxy’s own sign-in, invite and registration surfaces are also exempt, because they are answered by the proxy and never forwarded to a service; a signed-in caller with no organization has to be able to reach the provider-selection page.

***

## Client credentials

[Section titled “Client credentials”](#client-credentials)

When `ClientCredentials` is configured for a service, AuthProxy exposes `POST /.cratis/token`. That endpoint forwards the supplied client credentials to the service’s verification endpoint and, on success, issues a bearer token scoped to the configured `RoutePrefix`, along with a refresh token that can later be exchanged for a new access token without resupplying the client credentials.

This creates a one-to-one relationship between:

* the proxied service
* the route prefix the token may access
* the downstream endpoint that verifies the client credentials

The verification endpoint’s response can optionally include a `tenant` property, which AuthProxy then carries on the issued tokens and can resolve into the `Tenant-ID` header on proxied requests. See [Back-channel client credentials](/authproxy/configuration/authentication/#back-channel-client-credentials) for the full token, tenant-resolution, and refresh-token flow.

# Sign-in Notifications

AuthProxy can notify the application every time a user **actually signs in** — that is, when a signed-out user completes an interactive identity-provider login and a fresh session is established. The application can then record the sign-in, for example to alert the user of a new sign-in from an unfamiliar location or device.

The notification is a service-to-service back-channel, mirroring the [invite exchange](/authproxy/configuration/lobby/invitation-to-organization/) and the [credential link callback](/authproxy/configuration/link/): AuthProxy `POST`s a small JSON payload to a configured application endpoint.

***

## When it fires

[Section titled “When it fires”](#when-it-fires)

The notification fires **only on a genuine logged-out → signed-in transition**:

* ✅ A signed-out user is redirected to an identity provider, authenticates, and returns with a fresh ticket.
* ❌ An already-authenticated user making ordinary proxied requests — the existing session cookie is reused, no provider round-trip happens, and no notification is sent.
* ❌ The [credential-linking](/authproxy/configuration/link/) flow — that authenticates a *second* provider without establishing a new primary session, so it is never reported as a sign-in.

Technically, AuthProxy hooks the provider **callback** (`OnTicketReceived`), which the framework raises only when a new authentication ticket is delivered from a provider — not when an existing session is validated. That is what scopes the event to real sign-ins rather than every request. A notification failure never breaks the sign-in: the call is best-effort and any error is logged and swallowed.

***

## The payload

[Section titled “The payload”](#the-payload)

AuthProxy posts one of two JSON bodies to the configured [`NotifyUrl`](#configuration). A provider without [canonical federated identity](/authproxy/configuration/authentication/#canonical-federated-identity) keeps the legacy body:

```json
{
  "subject": "<provider subject>",
  "identityProvider": "<issuer / provider>",
  "ipAddress": "<resolved client IP>",
  "location": "<approximate location, may be empty>",
  "browser": "<parsed browser, e.g. Chrome>",
  "operatingSystem": "<parsed OS, e.g. Windows>",
  "userAgent": "<raw User-Agent header>"
}
```

An opted-in canonical provider adds `providerKey` and `issuer`; `subject` is the exact configured canonical subject and `identityProvider` becomes the same compatibility value as `providerKey`:

```json
{
  "subject": "<configured canonical subject>",
  "providerKey": "<configured stable provider key>",
  "issuer": "<normalized validated or configured issuer>",
  "identityProvider": "<same value as providerKey>",
  "ipAddress": "<resolved client IP>",
  "location": "<approximate location, may be empty>",
  "browser": "<parsed browser, e.g. Chrome>",
  "operatingSystem": "<parsed OS, e.g. Windows>",
  "userAgent": "<raw User-Agent header>"
}
```

* **Identity fields** — legacy providers select `subject` and `identityProvider` from the freshly authenticated principal. Canonical providers send the complete `(providerKey, issuer, subject)` tuple. Consumers must bind all three tuple components; neither `subject` alone nor `identityProvider` is a stable cross-provider account key.
* **`ipAddress`** — the client IP, taken from the left-most `X-Forwarded-For` entry (falling back to the connection’s remote address).
* **`location`** — a best-effort, coarse location. See [Approximate location](#approximate-location) below.
* **`browser`** / **`operatingSystem`** — parsed from the `User-Agent` header with a lightweight built-in heuristic (no third-party user-agent database). Unrecognized values are sent as empty strings rather than guessed.
* **`userAgent`** — the raw header, so the application can do its own richer parsing if it wants to.

By default the notification carries **no credential** and relies on the endpoint being network-isolated (see [Security](#security)). Configure [the signed envelope](#the-signed-envelope) to authenticate it instead.

Canonical identity is opt-in per provider, so an application migrating provider registrations must accept both body shapes. A notification says that a provider authenticated the tuple; it does not grant application membership, roles, scopes, or authorization.

***

## Approximate location

[Section titled “Approximate location”](#approximate-location)

AuthProxy deliberately does **not** bundle a geo-IP database — that would be a heavy dependency and a data pipeline of its own. The `location` is instead derived from what is already on the request:

* the resolved client IP (always sent); and
* coarse geo headers that a fronting CDN or reverse proxy may add — Cloudflare’s `CF-IPCountry`, and the conventional `X-Geo-City` / `X-Geo-Region` / `X-Geo-Country` and `X-AppEngine-City` / `-Region` / `-Country` headers.

When those headers are present, `location` is assembled as `City, Region, Country`. When they are **not** present, `location` is empty and only the IP travels — the application can resolve a fuller location from the IP itself if it needs one. This keeps AuthProxy dependency-light while still recording a genuine approximate location wherever the infrastructure provides one.

> **Note.** The client IP and any derived location are personal data. Handle and retain them in the application accordingly.

***

## Configuration

[Section titled “Configuration”](#configuration)

Set the application endpoint that records a completed sign-in under `Cratis:AuthProxy:SignIn:NotifyUrl`.

```json
{
  "Cratis": {
    "AuthProxy": {
      "SignIn": {
        "NotifyUrl": "https://studio.example.com/api/internal/sign-ins"
      }
    }
  }
}
```

Equivalent environment variable:

```plaintext
Cratis__AuthProxy__SignIn__NotifyUrl=https://studio.example.com/api/internal/sign-ins
```

When `NotifyUrl` is empty or the `SignIn` section is absent, sign-in notifications are disabled (nothing is posted).

***

## The signed envelope

[Section titled “The signed envelope”](#the-signed-envelope)

Without further configuration the notification body is the *only* evidence the application has, so anything that can reach the endpoint chooses which user gets recorded as signed in — including the `subject`, `providerKey` and `issuer`. Set `Cratis:AuthProxy:SignIn:Attestation` and AuthProxy signs a short-lived RS256 JWS over each notification and sends it as `Authorization: Bearer`.

**The body is unchanged.** The envelope travels in a header, so an application already consuming notifications keeps parsing exactly the same JSON.

### What the envelope binds

[Section titled “What the envelope binds”](#what-the-envelope-binds)

The envelope is a profile of [RFC 9449 (DPoP)](https://www.rfc-editor.org/rfc/rfc9449) rather than a scheme of its own. Six facts are bound:

| Fact       | Carried by                   | Meaning                                                   |
| ---------- | ---------------------------- | --------------------------------------------------------- |
| Provenance | `iss` + the `kid` JWS header | which AuthProxy deployment signed it, and under which key |
| Audience   | `aud`                        | the single application entitled to consume it             |
| Route      | `htm`, `htu`                 | the method and target URI of the request it accompanies   |
| Body       | `body_hash`                  | base64url SHA-256 of the exact bytes posted               |
| Time       | `iat`, `nbf`, `exp`          | the window it is valid in                                 |
| Replay     | `jti`                        | a random 256-bit identifier, unique per notification      |

A `purpose` claim of `sign-in-notification` separates the envelope from every other assertion AuthProxy signs, so an invitation attestation can never be presented in its place.

Two details a verifier must implement exactly:

* **`htu` follows RFC 9449** — the target URI *without* query and fragment. Compare it against the query-stripped request URI, not the raw target. Because the query is deliberately outside the binding, a `NotifyUrl` that carries one would be signed without it — so AuthProxy refuses to start with a query on `NotifyUrl` once `Attestation` is configured. Put anything the application needs in the body instead.
* **`body_hash` is an AuthProxy extension** — RFC 9449 defines no body digest. It uses the identical construction to that specification’s `ath` claim: unpadded base64url of the SHA-256 of the raw request body.

### Verifying a notification

[Section titled “Verifying a notification”](#verifying-a-notification)

1. Reject the request outright if the `Authorization: Bearer` header is missing.
2. Select the public key by the JWS `kid` header from your pinned key set, and require RS256.
3. Validate `iss`, `aud`, `exp` and `nbf` with no clock skew allowance beyond your own tolerance.
4. Require `purpose` to be `sign-in-notification`.
5. Compare `htm` to the request method and `htu` to the request URI with query and fragment removed.
6. Read the raw request body **before** deserializing it, and compare `body_hash` to its SHA-256 digest.
7. Reject a `jti` already seen inside the envelope lifetime.

> **AuthProxy publishes no JWKS document.** The verifying application pins the public keys by its own configuration and selects one by `kid` — the same way the invitation authority consumes invitation attestations. Key rotation is therefore a coordinated configuration change on both sides.

### Configuring it

[Section titled “Configuring it”](#configuring-it)

```json
{
  "Cratis": {
    "AuthProxy": {
      "SignIn": {
        "NotifyUrl": "https://studio.example.com/api/internal/sign-ins",
        "Attestation": {
          "Issuer": "https://auth.example.com",
          "Audience": "studio",
          "ActiveKeyId": "sign-in-2026-08",
          "Lifetime": "00:00:60",
          "SigningKeys": [
            {
              "KeyId": "sign-in-2026-08",
              "PrivateKeyPem": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
            }
          ]
        }
      }
    }
  }
}
```

| Setting                                           | Meaning                                                                                                                      |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Cratis:AuthProxy:SignIn:Attestation:Issuer`      | written to `iss`; required, and required to match at the verifier                                                            |
| `Cratis:AuthProxy:SignIn:Attestation:Audience`    | written to `aud`; names the one application entitled to the notification                                                     |
| `Cratis:AuthProxy:SignIn:Attestation:ActiveKeyId` | the key new envelopes are signed with; must name exactly one configured key                                                  |
| `Cratis:AuthProxy:SignIn:Attestation:SigningKeys` | the available keys, each a `KeyId` and a PEM-encoded RSA `PrivateKeyPem` of at least 2048 bits; every `KeyId` must be unique |
| `Cratis:AuthProxy:SignIn:Attestation:Lifetime`    | the envelope lifetime; between 10 and 60 seconds, defaulting to 60                                                           |

Supply `PrivateKeyPem` through a secret provider. AuthProxy never returns or logs it — publish only the matching public key to the application.

**Key rotation.** Add the new key to `SigningKeys`, publish its public half to the application, then move `ActiveKeyId` to it. Keep the previous key configured until every envelope it signed has expired.

### Compatibility and failure behavior

[Section titled “Compatibility and failure behavior”](#compatibility-and-failure-behavior)

* **Leaving the section unset changes nothing.** No `Authorization` header is added and the body is byte-for-byte what it has always been.
* **Once configured, AuthProxy never downgrades.** If an envelope cannot be signed — unusable key material, an `ActiveKeyId` naming no key — the notification is *not posted at all* and the failure is logged. A sign-in is never recorded on unauthenticated evidence.
* **Configuration is validated at startup**, so an unusable key fails the process rather than silently suppressing every sign-in notification. When attestation is configured, `NotifyUrl` must also be an absolute HTTPS URL (HTTP is accepted only for loopback development).

***

## Security

[Section titled “Security”](#security)

**Unsigned by default.** With no [`Attestation`](#the-signed-envelope) section the notification JSON is not signed and carries no credential. Point `NotifyUrl` at an internal application address that is **network-isolated** from public traffic, or authenticate AuthProxy separately at the application endpoint.

**Signed when configured.** The envelope establishes that AuthProxy produced this exact notification, for this application, over this exact body, recently, and only once. Network isolation and an authenticated envelope are complementary — enabling one is not a reason to relax the other.

Either way, treat the identity tuple as authenticated provider metadata, then apply the application’s own authorization policy before changing any access or membership. A verified envelope proves the notification’s origin and integrity; it grants no membership, role, or scope.

# Tenancy

AuthProxy resolves a **tenant ID** string from each incoming request and stores it in the request context. Downstream services receive the resolved tenant ID via the `Tenant-ID` header.

***

## Tenant resolution strategies

[Section titled “Tenant resolution strategies”](#tenant-resolution-strategies)

Resolution strategies run **in order** until one strategy resolves a tenant. Configure them under `Cratis:AuthProxy:TenantResolutions`:

```json
{
  "Cratis": {
    "AuthProxy": {
      "TenantResolutions": [
        { "Strategy": "Host" },
        { "Strategy": "Claim", "Options": { "ClaimType": "tid" } }
      ]
    }
  }
}
```

### Available strategies

[Section titled “Available strategies”](#available-strategies)

| Strategy    | Description                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Host`      | Uses the request host and matches it against configured tenant `Domains` / `SourceIdentifiers`.                           |
| `Claim`     | Reads a claim value from the authenticated user and matches it against configured tenant `SourceIdentifiers`.             |
| `Route`     | Extracts a source identifier from the request path by regex and matches it against configured tenant `SourceIdentifiers`. |
| `Specified` | Resolves directly to a fixed tenant ID string from configuration.                                                         |
| `Default`   | Resolves directly to a fallback tenant ID string from configuration.                                                      |
| `SubHost`   | Resolves directly from subhost convention, for example `acme.example.com` -> `acme`.                                      |
| `Selection` | Resolves from the selected-tenant cookie set by the tenant-selection page flow.                                           |

***

## Claim strategy options

[Section titled “Claim strategy options”](#claim-strategy-options)

```json
{
  "Strategy": "Claim",
  "Options": {
    "ClaimType": "tid"
  }
}
```

If `ClaimType` is omitted, AuthProxy falls back to reading `X-MS-CLIENT-PRINCIPAL`.

This is also how you resolve a tenant carried on an AuthProxy-issued client-credentials bearer token — point `ClaimType` at `cratis/tenant`. See [Resolving a tenant from the verification response](/authproxy/configuration/authentication/#resolving-a-tenant-from-the-verification-response).

***

## Route strategy options

[Section titled “Route strategy options”](#route-strategy-options)

```json
{
  "Strategy": "Route",
  "Options": {
    "Pattern": "^/tenant/(?<sourceIdentifier>[^/]+)"
  }
}
```

The regex must expose a named group called `sourceIdentifier`.

***

## Specified strategy options

[Section titled “Specified strategy options”](#specified-strategy-options)

```json
{
  "Strategy": "Specified",
  "Options": {
    "TenantId": "acme"
  }
}
```

***

## Default strategy options

[Section titled “Default strategy options”](#default-strategy-options)

```json
{
  "Strategy": "Default",
  "Options": {
    "TenantId": "lobby"
  }
}
```

***

## SubHost strategy options

[Section titled “SubHost strategy options”](#subhost-strategy-options)

```json
{
  "Strategy": "SubHost",
  "Options": {
    "ParentHost": "example.com",
    "VerificationUrlTemplate": "https://platform.example.com/internal/tenants/{tenantId}"
  }
}
```

| Property                  | Type     | Description                                                                                                                    |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `ParentHost`              | `string` | Parent host suffix used to extract the tenant ID from the request host.                                                        |
| `VerificationUrlTemplate` | `string` | Optional strategy-specific verification URL template. Overrides the global `TenantVerification.UrlTemplate` for this strategy. |

### How SubHost resolution works

[Section titled “How SubHost resolution works”](#how-subhost-resolution-works)

The strategy strips the configured `ParentHost` suffix from the incoming request host to derive the tenant ID.

Given `ParentHost: "example.com"`:

| Request host          | Resolved tenant ID | Notes                                                 |
| --------------------- | ------------------ | ----------------------------------------------------- |
| `acme.example.com`    | `acme`             | Single-segment subhost — resolved successfully.       |
| `contoso.example.com` | `contoso`          | Single-segment subhost — resolved successfully.       |
| `foo.bar.example.com` | —                  | Multi-segment subhost rejected — not resolved.        |
| `example.com`         | —                  | No subhost present — not resolved.                    |
| `other.com`           | —                  | Host does not end with `.example.com` — not resolved. |

The resolved subhost string becomes the tenant ID directly. **No `Tenants` dictionary lookup is performed** — unlike `Host`, `Claim`, and `Route` strategies, SubHost does not match a source identifier against a pre-configured list. This is intentional: SubHost is designed for environments where tenants are provisioned dynamically (for example SaaS platforms where each customer gets their own subdomain).

### SubHost and authentication callbacks

[Section titled “SubHost and authentication callbacks”](#subhost-and-authentication-callbacks)

For interactive authentication flows, AuthProxy stores SubHost strategy metadata in protected authentication `state` when it issues the provider challenge. On callback, AuthProxy restores this metadata and redirects to the tenant subhost.

This enables a shared callback endpoint (for example `auth.cratis.studio`) while returning the user to the original tenant host (for example `nova.cratis.studio`).

Because there is no registry lookup to prove the tenant exists, you should configure `VerificationUrlTemplate` to have AuthProxy call your back-end to confirm the tenant is valid before forwarding the request:

```json
{
  "Strategy": "SubHost",
  "Options": {
    "ParentHost": "example.com",
    "VerificationUrlTemplate": "https://internal-api.example.com/tenants/{tenantId}"
  }
}
```

AuthProxy replaces `{tenantId}` with the resolved subhost value and expects a `200` response. Any other response causes the request to be rejected with `tenant-not-found.html`. See [Tenant verification](#tenant-verification) for full response handling details.

***

## Selection strategy options

[Section titled “Selection strategy options”](#selection-strategy-options)

```json
{
  "Strategy": "Selection",
  "Options": {
    "TenantsEndpoint": "https://platform.example.com/api/tenants/selectable"
  }
}
```

| Property          | Type     | Description                                                                                                                                                                        |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TenantsEndpoint` | `string` | Absolute URL for the endpoint that returns selectable tenants for the current authenticated user. Expected response shape is an array of `{ "id": "...", "name": "..." }` objects. |

When this strategy is configured and no `.cratis-tenant` cookie exists yet, AuthProxy calls `TenantsEndpoint`, sets the `.cratis-tenants` cookie, and serves `select-tenant.html`. The page links back to `/.cratis/select-tenant?tenantId=<id>&returnUrl=<path>`, and AuthProxy validates the selected tenant against the endpoint response before writing the `.cratis-tenant` cookie.

***

## Tenant registry

[Section titled “Tenant registry”](#tenant-registry)

For `Host`, `Claim`, and `Route`, AuthProxy resolves a source identifier and then looks up the tenant ID in `Cratis:AuthProxy:Tenants`.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Tenants": {
        "acme": {
          "Domains": ["acme.example.com"],
          "SourceIdentifiers": ["acme", "tenant-acme"]
        },
        "contoso": {
          "Domains": ["contoso.example.com"],
          "SourceIdentifiers": ["contoso", "tenant-contoso"]
        }
      }
    }
  }
}
```

***

## Lobby fallback

[Section titled “Lobby fallback”](#lobby-fallback)

When no tenant can be resolved and the [lobby](/authproxy/configuration/lobby/) is configured, AuthProxy redirects the user to the lobby frontend instead of returning `401 Unauthorized`.

If no lobby is configured and `TenantResolutions` is non-empty, AuthProxy returns `401 Unauthorized`. When `TenantResolutions` is empty, the request proceeds without a tenant.

***

## Tenant verification

[Section titled “Tenant verification”](#tenant-verification)

After tenant resolution, AuthProxy can verify that the tenant exists before forwarding the request. This is optional.

### Global verification configuration

[Section titled “Global verification configuration”](#global-verification-configuration)

```json
{
  "Cratis": {
    "AuthProxy": {
      "TenantVerification": {
        "UrlTemplate": "https://platform.example.com/api/tenants/{tenantId}"
      }
    }
  }
}
```

| Property      | Type     | Description                                                         |
| ------------- | -------- | ------------------------------------------------------------------- |
| `UrlTemplate` | `string` | URL template for tenant verification. Use `{tenantId}` placeholder. |

### Response handling

[Section titled “Response handling”](#response-handling)

* `200`: tenant exists, request proceeds.
* `404`: tenant does not exist; AuthProxy serves `tenant-not-found.html` with `404`.
* Any other status or network error: treated as tenant verification failure, and `tenant-not-found.html` is served.

If a strategy provides a strategy-specific verification URL template (for example `SubHost.Options.VerificationUrlTemplate`), that template is used instead of the global `TenantVerification.UrlTemplate`.

### Tenant not found page

[Section titled “Tenant not found page”](#tenant-not-found-page)

When verification fails, AuthProxy serves `tenant-not-found.html`. See [Error pages](/authproxy/configuration/error-pages/) to override this page.

# Tenant Selection Page

When tenant selection is configured, AuthProxy serves a tenant-selection page after login until the user chooses a tenant.

The page receives tenant data through a cookie, not by calling your tenant endpoint directly.

***

## Flow

[Section titled “Flow”](#flow)

1. Authenticated request arrives without a `.cratis-tenant` cookie.
2. AuthProxy calls the configured `Selection.Options.TenantsEndpoint`.
3. If exactly one tenant is returned, AuthProxy sets `.cratis-tenant` immediately, removes any `.cratis-tenants` cookie, and redirects to the original URL (no selection page shown).
4. If more than one tenant is returned, AuthProxy writes `.cratis-tenants` (URL-encoded JSON array) as a session cookie and serves `select-tenant.html` — but only to a browser navigating to a page. Every other caller is refused with `403` instead, because a chooser page delivered as `200` reads as the data they asked for. See [Unauthenticated responses](/authproxy/configuration/unauthenticated-responses/).
5. User clicks a tenant option.
6. Browser navigates to `/.cratis/select-tenant?tenantId=<id>&returnUrl=<path>`.
7. AuthProxy validates the selected `tenantId` against `TenantsEndpoint` and sets `.cratis-tenant`.
8. AuthProxy redirects back to `returnUrl`. The `.cratis-tenants` cookie is **retained** so the application can offer an in-app tenant switcher.

***

## Switching tenants after selection

[Section titled “Switching tenants after selection”](#switching-tenants-after-selection)

For a user with **more than one** tenant, `.cratis-tenants` is written as a **session cookie** and is **not** deleted when a tenant is selected. It therefore remains available for the rest of the browser session, which lets the application’s toolbar decide whether to show a “switch tenant” control (show it only when the cookie lists more than one tenant).

To switch, the toolbar navigates to the same selection endpoint used by the selection page:

```plaintext
/.cratis/select-tenant?tenantId=<id>&returnUrl=<current path>
```

Every switch re-validates the requested `tenantId` against `TenantsEndpoint`, so a stale cookie can never grant access to a tenant the user is no longer a member of — an unknown `tenantId` is rejected with `400 Bad Request`.

***

## Periodic re-validation of the selected tenant

[Section titled “Periodic re-validation of the selected tenant”](#periodic-re-validation-of-the-selected-tenant)

`.cratis-tenant` is a session cookie, but it is also **not trusted indefinitely within a session**: AuthProxy re-validates the selected tenant against `TenantsEndpoint` when the configured `Cratis:AuthProxy:Session:TenantRevalidationInterval` (default 10 minutes) has lapsed. A successful re-validation is cached in memory, so the endpoint is **not** called on every request.

When the endpoint answers authoritatively that the tenant is no longer available to the user, the `.cratis-tenant` and `.cratis-tenants` cookies are deleted and the request is replayed without them — the user lands back in the regular selection flow (or the no-tenant handling when nothing remains). Revoked tenant access therefore takes effect within the interval, without waiting for the browser session to end. Transport failures fail open so a transient backend outage cannot lock users out; the next lapse of the window retries.

A user with exactly **one** tenant never receives `.cratis-tenants` (it is removed when the single tenant is auto-selected), so no switcher is shown for single-tenant users.

***

## Endpoint response shape

[Section titled “Endpoint response shape”](#endpoint-response-shape)

`TenantsEndpoint` must return JSON with one object per selectable tenant:

```json
[
  {
    "id": "some string",
    "name": "some string"
  }
]
```

***

## Cookie shape used by the page

[Section titled “Cookie shape used by the page”](#cookie-shape-used-by-the-page)

AuthProxy writes `.cratis-tenants` with the same shape:

```json
[
  {
    "id": "studio",
    "name": "Cratis Studio"
  },
  {
    "id": "sales",
    "name": "Sales Portal"
  }
]
```

***

## Building a custom `select-tenant.html`

[Section titled “Building a custom select-tenant.html”](#building-a-custom-select-tenanthtml)

`select-tenant.html` is a normal overridable page in `PagesPath`, exactly like the other built-in pages.

Minimum requirements:

1. Read `.cratis-tenants` from `document.cookie`.
2. Parse JSON and render `name`.
3. Link each item to `/.cratis/select-tenant?tenantId=<id>&returnUrl=<current path>`.

Example:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Select tenant</title>
</head>
<body>
  <h1>Select tenant</h1>
  <ul id="tenants"></ul>
  <p id="error" hidden>Unable to load tenant options.</p>

var json = getCookie('.cratis-tenants');
      var tenants;
      try { tenants = JSON.parse(json); } catch (_) { tenants = null; }

if (!tenants || tenants.length === 0) {
        document.getElementById('error').hidden = false;
        return;
      }

var returnUrl = window.location.pathname + window.location.search;
      var list = document.getElementById('tenants');

tenants.forEach(function (tenant) {
        var li = document.createElement('li');
        var a  = document.createElement('a');
        a.href = '/.cratis/select-tenant?tenantId=' +
          encodeURIComponent(tenant.id) +
          '&returnUrl=' + encodeURIComponent(returnUrl);
        a.textContent = tenant.name;
        li.appendChild(a);
        list.appendChild(li);
      });
    }());
  </script>
</body>
</html>
```

# Trusted Proxies

AuthProxy almost never sees a browser. It sees an ingress controller, a load balancer, a service-mesh sidecar, or a CDN edge — and everything it knows about the person on the other side comes from what that thing wrote into `X-Forwarded-For` and `X-Forwarded-Proto`.

Those are ordinary request headers. Nothing about them is signed, and nothing about them is special: any caller that can open a connection to AuthProxy can send whatever it likes in them. The question a reverse proxy has to answer, before it believes a single one, is **which callers are allowed to speak for someone else** — and that is a fact about your network that only your deployment knows.

This page is how you tell it.

***

## What is at stake

[Section titled “What is at stake”](#what-is-at-stake)

It is tempting to file forwarded headers under “logging detail”. They are not. Two values decide a surprising amount of AuthProxy’s behavior:

| Value              | What it decides                                                                                                                                                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The client address | The `ipAddress` in every [sign-in notification](/authproxy/configuration/sign-in/) — the record your application shows a user as “a new sign-in from 203.0.113.7” and acts on when it looks unfamiliar.                     |
| The request scheme | Whether every AuthProxy session cookie carries `Secure`; what the OIDC `post_logout_redirect_uri` claims your public origin to be; and which origins the [post-logout allow-list](/authproxy/configuration/logout/) admits. |

A caller who can set the first one writes its own audit trail. A caller who can set the second one changes whether a browser is willing to send your session cookies at all — and, in the other direction, whether a genuinely encrypted session is protected as one.

***

## Declaring the boundary

[Section titled “Declaring the boundary”](#declaring-the-boundary)

Name the peers directly in front of AuthProxy:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Ingress": {
        "TrustedProxies": [ "10.0.0.0/8", "203.0.113.7" ],
        "ForwardLimit": 1
      }
    }
  }
}
```

Or, as environment variables in a container:

```bash
Cratis__AuthProxy__Ingress__TrustedProxies__0=10.0.0.0/8
Cratis__AuthProxy__Ingress__TrustedProxies__1=203.0.113.7
Cratis__AuthProxy__Ingress__ForwardLimit=1
```

Each entry is an IP address (`10.0.0.7`, `2001:db8::1`) or a CIDR range (`10.0.0.0/8`, `2001:db8::/32`). A range written against a host address inside it — `10.0.0.1/8` — means the range, the same as everywhere else. An entry AuthProxy cannot parse **fails startup and names the offending value**; it is never quietly dropped, because a trusted proxy that is silently not trusted is a boundary silently in the wrong place.

The addresses to declare are the ones **AuthProxy sees as the peer**, not the addresses of your users. In Kubernetes that is the ingress controller’s pod CIDR; behind a cloud load balancer it is the balancer’s subnet; behind a CDN it is the CDN’s published egress ranges.

***

## `ForwardLimit` decides which address is reported as the client

[Section titled “ForwardLimit decides which address is reported as the client”](#forwardlimit-decides-which-address-is-reported-as-the-client)

This is the part worth reading twice, because it is the setting most often left at whatever the sample had.

`X-Forwarded-For` grows left to right: the outermost proxy appends the address it accepted the connection from, then the next one appends, and so on. AuthProxy therefore reads it **from the right**, consuming one entry per hop, and `ForwardLimit` is how many hops it consumes. Whatever it lands on becomes the client address — the one recorded against a sign-in.

Consider a request that reaches AuthProxy carrying `X-Forwarded-For: 198.51.100.9, 203.0.113.30` from a peer at `203.0.113.10`:

| `ForwardLimit`    | Reported client address | What that means                                                                                                                                                                    |
| ----------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `1` (the default) | `203.0.113.30`          | One hop consumed. Correct when a single ingress sits in front — but if there are really two, you are recording **your own inner proxy** as the client, identically for every user. |
| `2`               | `198.51.100.9`          | Two hops consumed. Correct when a CDN sits in front of a load balancer.                                                                                                            |
| `3`               | `198.51.100.9`          | The chain ran out first. The surplus can never be reached, which is exactly the protection.                                                                                        |

So set it to the number of hops your deployment actually has:

* **Too low** and the reported address is your own infrastructure — the audit trail is real but useless.
* **Too high** and the reported address is whatever the outermost caller chose to write — the audit trail is attacker-controlled, which is worse than useless.

Every hop counted must itself be a trusted peer. AuthProxy re-checks at each step, so raising `ForwardLimit` without also declaring the intermediate addresses in `TrustedProxies` changes nothing.

Note

**If you have more than one hop and have never set `ForwardLimit`, the address recorded against a sign-in changes with this release.** Read this even if you are not planning to configure anything.

AuthProxy used to record the **left-most** entry of `X-Forwarded-For` for the sign-in notification, while everything else in the proxy used the address the forwarded-headers middleware had settled on. Those are two different answers to one question, and the left-most one is the entry furthest from you — the one the outermost caller wrote, which nothing verified. Both now come from the same place, the address the middleware settled on after consuming `ForwardLimit` hops.

With `X-Forwarded-For: 198.51.100.7, 203.0.113.9` and the default `ForwardLimit` of `1`:

|        | Recorded `ipAddress` | What it is                                       |
| ------ | -------------------- | ------------------------------------------------ |
| Before | `198.51.100.7`       | the browser — but taken on trust from the header |
| Now    | `203.0.113.9`        | your own inner load balancer — one hop consumed  |

Nothing is broken and nothing is less safe; the new value is the honest one for a `ForwardLimit` of `1`. But every sign-in notification and audit record silently changes meaning, and if two hops really do sit in front of you the recorded address becomes identical for every user, which is useless as an audit trail.

**To restore the browser’s address, count the hops you actually have.** For the chain above that is `ForwardLimit: 2`, with the inner balancer’s address declared in `TrustedProxies` so the second hop is allowed to be consumed:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Ingress": {
        "TrustedProxies": [ "203.0.113.9", "10.0.0.0/8" ],
        "ForwardLimit": 2
      }
    }
  }
}
```

Verify it the way [Checking your work](#checking-your-work) describes: sign in and look at the `ipAddress` your `SignIn:NotifyUrl` endpoint received.

***

## Modes

[Section titled “Modes”](#modes)

`Mode` decides how the trusted set is arrived at. `Configured` is the default and is what almost every deployment wants.

```json
{
  "Cratis": {
    "AuthProxy": {
      "Ingress": {
        "Mode": "LoopbackOnly"
      }
    }
  }
}
```

| Mode           | Trusts                                  | Use it when                                                                                                                                                |
| -------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Configured`   | Exactly the peers in `TrustedProxies`   | Normal deployments. This is the default.                                                                                                                   |
| `LoopbackOnly` | Only a caller on the loopback interface | A sidecar, or local development. A deployment behind an ingress never sees loopback as the peer, so this refuses every forwarded header it receives.       |
| `TrustAny`     | Every caller                            | Nothing but your own ingress can reach AuthProxy at all — a private network with no other route in, or a listener with no peer address at all (see below). |

Caution

**Do not set `ASPNETCORE_FORWARDEDHEADERS_ENABLED`.** It is standard advice for containerized ASP.NET images, and it is the wrong thing here: it makes the host insert a forwarded-headers middleware of its own, ahead of every AuthProxy middleware, and clear the known-proxy lists while doing it. The peer AuthProxy records as the caller is then the one the header has already replaced, so the boundary you declared is applied to a request that was rewritten before AuthProxy saw it. AuthProxy consumes forwarded headers itself, from the configuration on this page — leave the variable unset. It logs a warning at startup if it finds it set.

### A listener with no peer address

[Section titled “A listener with no peer address”](#a-listener-with-no-peer-address)

`Configured` and `LoopbackOnly` both decide by looking at the peer’s IP address. A Unix domain socket does not have one — `RemoteIpAddress` is null — so every request over such a listener is treated as coming from an untrusted peer. Sessions keep working, which is what makes this quiet: the visible symptom is that `X-Forwarded-Proto` stops being honored, so cookies lose `Secure` and the public origin reverts to the transport scheme.

If AuthProxy listens on a Unix socket, and the only thing that can write to that socket is your own ingress, say `TrustAny`. That is what “the peer is trustworthy and cannot be identified by address” looks like when it is stated rather than stumbled into.

***

## The compatibility fallback, and the warning

[Section titled “The compatibility fallback, and the warning”](#the-compatibility-fallback-and-the-warning)

`Configured` with an **empty** `TrustedProxies` keeps the behavior AuthProxy has always had: every caller’s forwarded headers are believed. Upgrading breaks nothing.

It is not, however, silent. At startup AuthProxy logs a warning naming the mode it is running in and the configuration key that leaves it:

```text
warn: AuthProxy is running in Configured trusted-proxy mode with no trusted proxies configured, so it
      believes the X-Forwarded-For and X-Forwarded-Proto headers of every caller. Set
      Cratis:AuthProxy:Ingress:TrustedProxies to the addresses or CIDR ranges of the ingress in front of
      it, or set Cratis:AuthProxy:Ingress:Mode to LoopbackOnly or TrustAny to state the choice explicitly.
      A future major release will refuse to start in this state.
```

Note

Treat the warning as a task, not as noise. A future major release turns this condition into a refusal to start. Declaring `TrustedProxies` — or stating `TrustAny` deliberately, if that genuinely describes your network — is what clears it.

If you truly do run somewhere nothing else can reach AuthProxy, say `TrustAny` rather than leaving the list empty. The behavior is identical; the difference is that one of them is a decision somebody made and the other is an omission nobody noticed.

***

## What a declared boundary changes

[Section titled “What a declared boundary changes”](#what-a-declared-boundary-changes)

Once `TrustedProxies` is set, a request from a peer outside it is treated as what it is — a caller talking directly to AuthProxy:

* `X-Forwarded-For` is ignored; the connection’s real address is the client address.
* `X-Forwarded-Proto` is ignored; the real transport scheme decides cookie `Secure` and the public origin.
* The geo headers a fronting CDN adds — `CF-IPCountry`, `CF-Region`, `CF-IPCity`, and the conventional `X-Geo-*` / `X-AppEngine-*` city, region and country headers — resolve to an empty `location` in the sign-in notification, because from an untrusted caller they are values it chose rather than facts about where it is.

A request from a peer **inside** the boundary is honored exactly as before, for as many hops as `ForwardLimit` allows.

Two headers are never honored, from any peer: `X-Forwarded-Host` and `X-Forwarded-Prefix`. AuthProxy consumes only the address and the scheme, so neither the request host nor the path base can be moved by a header. The RFC 7239 `Forwarded` header is likewise not consumed.

***

## Configuring it from Aspire

[Section titled “Configuring it from Aspire”](#configuring-it-from-aspire)

The [Aspire hosting integration](/authproxy/aspire/) writes the same configuration keys:

```csharp
var authProxy = builder.AddAuthProxy("authproxy")
    .WithTrustedProxies("10.0.0.0/8", "203.0.113.7")
    .WithForwardLimit(2);
```

`WithTrustedProxies` appends, so the peers can be declared wherever each one is known. An entry that is neither an address nor a CIDR range is refused when the app host builds, rather than being carried to the proxy and refused there.

***

## Checking your work

[Section titled “Checking your work”](#checking-your-work)

The address AuthProxy settled on is the one it reports in the sign-in notification, so the quickest end-to-end check is to sign in and look at what your `SignIn:NotifyUrl` endpoint received:

* `ipAddress` should be the address of the machine you signed in from — not an address inside your cluster.
* `location` should be populated if, and only if, a fronting CDN is adding geo headers.

If `ipAddress` is one of your own proxies, raise `ForwardLimit` by one and add that proxy’s address to `TrustedProxies`. If it is an address you can influence from outside, `ForwardLimit` is too high.

# Unauthenticated Responses

AuthProxy answers a caller that cannot proceed in one of two ways: it serves a page, or it returns a status code. Which one it picks depends on the caller, not on the path.

> **Not on a closed deployment.** Everything on this page describes a deployment in the default `Public` admission mode. Under [`CapabilityOnly`](/authproxy/configuration/admission/) none of it applies to a caller who has not been admitted: there is no page, no `401`, no `403` and no redirect — every route and every method answers one byte-identical `404`, and the rules below start applying only once a capability has been presented.

***

## Why the caller decides

[Section titled “Why the caller decides”](#why-the-caller-decides)

The provider-selection and tenant-selection pages are HTML, and HTML has to be delivered with a success status to render. That is the right answer to a person in a browser, and the wrong answer to everything else:

* A webhook, an e-signing callback or any server-to-server integration reads **HTTP 200** as *delivered*. It does not retry, nothing is queued for redelivery, and nothing errors — so a refused request looks exactly like a successful one.
* A frontend’s `fetch()` passes the conventional `response.ok` check and only fails later, when parsing HTML as JSON. Arc’s own identity bootstrap calls `/.cratis/me` on boot and hits precisely this.

So AuthProxy serves a page only to a caller that is navigating to one, and refuses everyone else with a status code they can act on.

***

## The rule

[Section titled “The rule”](#the-rule)

| Caller                             | Response                                                                        |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| A browser navigating to a document | The page — provider selection at `200`, or a redirect to the identity provider  |
| Anything else                      | `401 Unauthorized`, or `403 Forbidden` when the caller is already authenticated |

A caller is treated as navigating when either:

1. It sends `Sec-Fetch-Dest: document` (or `iframe` / `frame`). Every current browser sends this header on every request, and it is the only signal that separates a navigation from a `fetch()` issued by the *same* browser on the *same* connection.
2. It sends no `Sec-Fetch-Dest` at all — a client predating fetch metadata — **and** names `text/html` explicitly in `Accept`.

A wildcard `Accept: */*` does not count. That is what `fetch()`, `curl` and most webhook senders send, and reading it as “HTML will do” is what produced the `200` in the first place. A caller that states nothing at all is treated as an API caller, because it almost always is.

***

## What returns what

[Section titled “What returns what”](#what-returns-what)

| Situation                                      | Browser navigation                 | Other callers                                 |
| ---------------------------------------------- | ---------------------------------- | --------------------------------------------- |
| Unauthenticated, multiple providers configured | `200` + `select-provider.html`     | `401`, no page, no `.cratis-providers` cookie |
| Unauthenticated, one provider configured       | `302` to the provider              | `401`                                         |
| Unauthenticated, no providers configured       | Forwarded                          | Forwarded                                     |
| Authenticated, tenant selection required       | `200` + `select-tenant.html`       | `403`, no page, no `.cratis-tenants` cookie   |
| Lobby mode, no invitation                      | `401` + `invitation-required.html` | `401` + `invitation-required.html`            |

Two rows are worth reading twice.

**No providers configured** is forwarded either way. With nothing to authenticate against there is no refusal to convert, and refusing here would turn a proxy that challenges nobody into one that refuses everybody.

**Tenant selection returns `403`, not `401`.** The caller is authenticated; answering `401` would send a frontend back through a login it has already completed. This matches the `403` AuthProxy already returns when an authenticated user belongs to no organization.

***

## Upgrading

[Section titled “Upgrading”](#upgrading)

This changes the status code an existing deployment returns to non-browser callers, and one case is worth checking before rolling out: **an HTTP liveness or readiness probe pointed at AuthProxy**.

A probe sends `Accept: */*` and no fetch metadata, so it is not a navigation. Pointed at `/` it used to get `200` (the selection page) or `302` (the provider redirect) — both of which a probe reads as healthy — and now gets `401`, which it reads as unhealthy. The pod then fails to become ready.

That probe was never testing much: it asserted that the login chooser renders, not that anything behind the proxy works. Replace it with one of:

* The [management listener](/authproxy/configuration/management-listener/) — an opt-in private port carrying AuthProxy’s own `/health/live` and `/health/ready`. This is the probe for the *proxy*: liveness answers while every dependency is down, and readiness verifies that the instance could actually serve an authenticated request.
* A path the application serves and the deployment declares in [`AnonymousPaths`](/authproxy/configuration/services/#anonymous-paths) — this actually exercises the proxy *and* the application, which is what a readiness probe is for.
* A TCP socket probe, if all you need is “the container is listening”. Note that this proves only that a process accepted a connection — not that AuthProxy could serve anybody.

On a deployment in [`CapabilityOnly`](/authproxy/configuration/admission/) admission mode the middle option is not available either — a declared anonymous path answers `404` to an unadmitted probe. Use the management listener.

Note that the bare `/` cannot be declared anonymous — it would match every request and turn the whole service anonymous, so it is rejected. Name a real path.

***

## Consequences for clients

[Section titled “Consequences for clients”](#consequences-for-clients)

* `!response.ok` is now a correct check against AuthProxy for any non-navigating caller. It was not before.
* A client that deliberately wants the selection page — a custom login shell rendering it in a frame, for instance — should send `Sec-Fetch-Dest: document`, or navigate to `/.cratis/select-provider` directly. That path is in the authentication UI skip list and is never intercepted.
* Paths a service declares in [`AnonymousPaths`](/authproxy/configuration/services/#anonymous-paths) never reach any of this. They are forwarded to the application, which answers them itself.

# Receiving Webhooks

An inbound webhook is a request from a system that has no user session and never will. AuthProxy has two mechanisms for it, and which one applies depends on a single question: **do you control the sender?**

***

## Choosing the mechanism

[Section titled “Choosing the mechanism”](#choosing-the-mechanism)

| The sender is                                             | Use                                                                                            | Why                                                                                                                                                                                  |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| A service or application you control                      | [Client credentials](/authproxy/configuration/authentication/#back-channel-client-credentials) | The sender can exchange credentials at `/.cratis/token` for a bearer token scoped to a route prefix. The proxy authenticates it, and the application receives a caller it can trust. |
| A third party — Stripe, GitHub, Slack, an e-sign provider | [`AnonymousPaths`](/authproxy/configuration/services/#anonymous-paths)                         | They will not perform a token exchange. They sign the request their own way, and only the application knows how to check it.                                                         |

If you control the sender, prefer client credentials. It keeps authentication in the proxy, which is what the proxy is for. Reach for `AnonymousPaths` when the sender’s scheme is not yours to choose.

***

## Third-party webhooks

[Section titled “Third-party webhooks”](#third-party-webhooks)

Declare the specific path the provider posts to:

```json
{
  "Cratis": {
    "AuthProxy": {
      "Services": {
        "core": {
          "Backend": { "BaseUrl": "http://core:8080/" },
          "AnonymousPaths": [ "/api/webhooks/payments" ]
        }
      }
    }
  }
}
```

### What AuthProxy does

[Section titled “What AuthProxy does”](#what-authproxy-does)

* Forwards the request to the service instead of answering it with a sign-in page.
* Strips inbound `x-ms-client-principal`, `x-ms-client-principal-id`, `x-ms-client-principal-name` and `Tenant-ID` headers, exactly as it does for every other request. A caller cannot assert an identity.
* Injects no principal headers, because there is no session.

### What AuthProxy does not do

[Section titled “What AuthProxy does not do”](#what-authproxy-does-not-do)

**It does not authenticate the request.** A declared path is reachable by anyone who knows the URL. The signature check is the application’s, and it is not optional — without it the endpoint accepts anything that anyone posts to it.

A typical provider signs a request with an HMAC over the raw body plus a timestamp. Verifying it means:

1. Reading the **raw body bytes**, before any deserialization.
2. Recomputing the signature with the shared secret, following that provider’s exact canonical form.
3. Comparing in **constant time**.
4. Rejecting timestamps outside a short window, so a captured request cannot be replayed.

### Why the proxy does not do this for you

[Section titled “Why the proxy does not do this for you”](#why-the-proxy-does-not-do-this-for-you)

Not an omission — a deliberate boundary:

* **Every provider canonicalizes differently.** Stripe signs `timestamp.body`, GitHub signs the body alone, Slack signs `v0:timestamp:body`, and they disagree on hex versus base64 and on tolerance windows. Configuring that generically is harder to get right than implementing it once in the application.
* **It requires buffering the body.** AuthProxy streams request bodies. Buffering them to compute a signature changes the memory profile of the path and risks altering exactly the bytes being verified.
* **The application needs the raw body regardless**, for idempotency and for storing the event, so it is already holding the thing that has to be checked.

***

## Keeping the opening small

[Section titled “Keeping the opening small”](#keeping-the-opening-small)

* **Name the exact path.** Entries are prefixes and cover everything beneath them, so `/api/webhooks` opens every current and future webhook route, including ones added later by someone who did not know the prefix was public. `/api/webhooks/payments` opens one.
* **Reject the methods you do not serve.** A webhook receiver is almost always `POST` only.
* **Treat the payload as untrusted until verified**, including any identifiers used to look up records.
* **Re-read the declared paths when reviewing the deployment.** They are the surface reachable without a session, and they are the shortest list worth auditing.

For the sibling case — a page or API a *person* reaches without an account, such as a magic-link landing page — see [Public application surfaces](/authproxy/configuration/public-surfaces/).

# Well-Known Pages

AuthProxy serves built-in HTML pages for a range of conditions — provider selection, invitation errors, tenant errors, and generic HTTP errors. Every page can be **overridden** by mounting a directory of custom pages into the container.

***

## Built-in pages

[Section titled “Built-in pages”](#built-in-pages)

The following pages are included with AuthProxy and are served automatically when the corresponding condition is detected:

| File name                                | Condition                                                                                                                                                                                                                                                                                                                                        | HTTP status |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `404.html`                               | The requested resource was not found.                                                                                                                                                                                                                                                                                                            | 404         |
| `403.html`                               | The identity resolver denied access.                                                                                                                                                                                                                                                                                                             | 403         |
| `not-authorized.html`                    | The caller is signed in but does not satisfy the claim requirements declared in [`Cratis:AuthProxy:Authorization`](/authproxy/configuration/authorization/).                                                                                                                                                                                     | 403         |
| `tenant-not-found.html`                  | The resolved tenant does not exist in the platform (see [Tenant verification](/authproxy/configuration/tenancy/#tenant-verification)).                                                                                                                                                                                                           | 404         |
| `select-provider.html`                   | A protected resource was requested and multiple identity providers are configured, or a sign-in failed (see [Failed Sign-ins](/authproxy/configuration/failed-sign-ins/)). The page reads the `.cratis-providers` cookie to render a sign-in button for each available provider, and shows a message when a `reason` query parameter is present. | 200         |
| `select-tenant.html`                     | Tenant selection is enabled and the authenticated user has not selected a tenant yet. The page reads the `.cratis-tenants` cookie to render selectable tenants.                                                                                                                                                                                  | 200         |
| `invitation-expired.html`                | The JWT token on an invite link has passed its expiry time. Served in either phase — when the link is followed (Phase 1) and when the token is re-validated at the exchange (Phase 2).                                                                                                                                                           | 401         |
| `invitation-invalid.html`                | The JWT token on an invite link is malformed or has an invalid signature. Served in either phase — when the link is followed (Phase 1) and when the token is re-validated at the exchange (Phase 2).                                                                                                                                             | 401         |
| `invitation-select-provider.html`        | A valid invite link was followed and multiple identity providers are configured. The page reads the `.cratis-providers` cookie to render a sign-in button for each available provider.                                                                                                                                                           | 200         |
| `invitation-subject-already-exists.html` | The authenticated user’s subject is already associated with an existing account during invite exchange (Phase 2).                                                                                                                                                                                                                                | 409         |
| `invitation-email-unavailable.html`      | Gateway email binding is enabled (`Invite.EmailClaim`), but the identity provider supplied no authenticated-session email address (Phase 2).                                                                                                                                                                                                     | 403         |
| `invitation-email-mismatch.html`         | Gateway email binding is enabled (`Invite.EmailClaim`), and the identity provider supplied another address or explicitly reported `email_verified=false` (Phase 2).                                                                                                                                                                              | 403         |
| `link-select-provider.html`              | The embeddable provider-selection page of the [credential-link flow](/authproxy/configuration/link/), served at `/.cratis/link`. Lists providers, opens the chosen provider’s link challenge in a top-level window, and reports the outcome to its embedding parent.                                                                             | 200         |
| `link-complete.html`                     | A credential link completed, at `/.cratis/link/complete`. Broadcasts the completion on the link flow’s `BroadcastChannel` and closes its window.                                                                                                                                                                                                 | 200         |
| `link-failed.html`                       | A credential link did not complete — the provider round-trip failed or the exchange was refused (see [Credential Linking](/authproxy/configuration/link/)). Broadcasts the failure so an embedding selection page can offer a retry.                                                                                                             | 403         |

***

## Overriding pages

[Section titled “Overriding pages”](#overriding-pages)

```json
{
  "Cratis": {
    "AuthProxy": {
      "PagesPath": "/mnt/pages"
    }
  }
}
```

Equivalent environment variable:

```plaintext
Cratis__AuthProxy__PagesPath=/mnt/pages
```

### Container mount example (Docker Compose)

[Section titled “Container mount example (Docker Compose)”](#container-mount-example-docker-compose)

```yaml
services:
  authproxy:
    image: cratis/authproxy:latest
    volumes:
      - ./my-pages:/mnt/pages
    environment:
      Cratis__AuthProxy__PagesPath: /mnt/pages
```

### Page assets

[Section titled “Page assets”](#page-assets)

Pages can reference stylesheets, images, and other assets.\
Place asset files in the same pages directory — they are served at the `/_pages/` URL prefix.

```html

<link rel="stylesheet" href="/_pages/styles.css" />
<img src="/_pages/logo.svg" alt="Logo" />
```

***

## Provider selection pages

[Section titled “Provider selection pages”](#provider-selection-pages)

`select-provider.html` and `invitation-select-provider.html` both serve the same purpose — letting the user choose an identity provider when multiple are configured — but they are triggered by different flows:

Both pages receive provider data via the `.cratis-providers` cookie and work identically from a customization standpoint. See [Provider Selection Pages](/authproxy/configuration/invitation-provider-selection/) for the full cookie schema, JavaScript examples, and guidance on building a custom branded page.

***

## Invitation error pages

[Section titled “Invitation error pages”](#invitation-error-pages)

Invitation error pages use **full descriptive names** rather than numeric HTTP status codes because they represent application-level conditions, not generic HTTP errors.

### `invitation-expired.html`

[Section titled “invitation-expired.html”](#invitation-expiredhtml)

Served when an invite token has a valid signature but has passed its `exp` claim. AuthProxy validates the token both when the `/invite/<token>` link is followed (Phase 1) and again at the post-login exchange (Phase 2), so this page is served whenever an expired token is detected in either phase. The user should request a fresh invitation.

### `invitation-invalid.html`

[Section titled “invitation-invalid.html”](#invitation-invalidhtml)

Served when an invite token is malformed, carries an invalid signature, or cannot be parsed at all. Because AuthProxy re-validates the token at the Phase-2 exchange — not only when the link is first followed — this page is also served if a tampered or forged token is presented at the exchange.

### `invitation-subject-already-exists.html`

[Section titled “invitation-subject-already-exists.html”](#invitation-subject-already-existshtml)

### `invitation-email-mismatch.html`

[Section titled “invitation-email-mismatch.html”](#invitation-email-mismatchhtml)

Served during Phase 2 (post-login invite exchange) when gateway email binding is enabled — the `Invite.EmailClaim` claim is configured — the invite token was issued for a specific email address — and the provider supplied another address or explicitly reported `email_verified=false`. This is distinct from a provider that supplied no address at all.

### `invitation-email-unavailable.html`

[Section titled “invitation-email-unavailable.html”](#invitation-email-unavailablehtml)

Served during Phase 2 when gateway email binding is enabled and the identity provider supplied no authenticated-session email address. The invite may still target the correct person, but AuthProxy has no address evidence to compare. Use this page to ask the invitee to choose an account or provider that exposes an address, rather than telling them their address mismatched.

Email binding is off by default. See [Invitation to Organization](/authproxy/configuration/lobby/invitation-to-organization/) for configuration and the limits of provider-supplied `email_verified` evidence.

***

## Tenant not found

[Section titled “Tenant not found”](#tenant-not-found)

***

## Not authorized

[Section titled “Not authorized”](#not-authorized)

`not-authorized.html` is served when [first-gate authorization](/authproxy/configuration/authorization/) is configured and an authenticated caller does not satisfy a required claim — a GitHub organization they do not belong to, a role they do not hold. It is distinct from `403.html`, which answers the *application* refusing a caller it does recognize; this one is the proxy refusing before the application is reached at all.

If you override it, **keep a way to sign out**. It is the only refusal whose remedy is to come back as somebody else, and someone who signed in with the wrong account is otherwise stuck looking at a page that will not change. The built-in page links to `/.cratis/logout?redirect=/`:

```html
<a href="/cratis/logout/?redirect=/">Sign out</a>
```

This is a good page to brand and to make specific — “ask #it-support for access to the planner” is far more useful to the person reading it than “not authorized”.

# Build a full-stack feature

> Put Chronicle, Arc, and Components together — go from a domain event to a working React screen in one vertical slice, with full-stack type safety.

This is where the three products meet. You’ll build one **vertical slice** of a library app — registering an author and listing authors — end to end: a command and event on the backend ([Arc](/arc/) + [Chronicle](/chronicle/)), a read model built by a projection, and a React screen ([Components](/components/)) that consumes the **generated, type-safe proxies**. No hand-written API client, no DTO duplication.

Everything for the feature lives in **one folder** — that’s the vertical-slice idea: you navigate by feature, not by technical layer.

Here’s the slice as an **[event model](/event-modeling/)** — read left to right, the user acts on a screen, a command records a fact, that fact is projected into a read model, and the next screen reads it:

```
UI/A: AuthorsUI/A: AuthorsC/RM: AuthorsC/RM: AuthorsStream: Authors
AddAuthor
RegisterAuthor

id: uuid, name: string
AuthorRegistered

name: string
Author
Authors
```

The blocks are the slice, one per product: the `ui` screens are [Components](/components/), the `cmd` and the `rmo`’s query are [Arc](/arc/), the `evt` is [Chronicle](/chronicle/), and the build generates the typed proxies that connect them. Frames 01–03 are the **command pattern** (intent → fact); 03–05 are the **view pattern** (fact → read model → screen).

## Before you start

[Section titled “Before you start”](#before-you-start)

Scaffold a full-stack app and have it running — `dotnet new cratis -o Library` from the [Chronicle getting started](/chronicle/get-started/). You’ll add the slice below into a `Features/Authors/` folder.

## The host

[Section titled “The host”](#the-host)

`dotnet new cratis` generates the host for you — the whole stack in two calls. `AddCratis` brings up Arc and Chronicle together; `UseCratis` activates both:

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.AddCratis(
    configureArcBuilder: arc => arc.WithMongoDB(),
    configureChronicleOptions: chronicle => chronicle.EventStore = "Library",
    configureChronicleBuilder: chronicle => chronicle.WithCamelCaseNamingPolicy());

var app = builder.Build();

app.UseCratis();
app.Run();
```

You won’t touch this again for the slice below — it’s here so you can see where the command, event, read model, and query you’re about to write get wired in. The [Cratis package](/arc/backend/chronicle/cratis-package/) reference covers what `AddCratis` configures and how to adjust it.

## 1. Model the slice (backend)

[Section titled “1. Model the slice (backend)”](#1-model-the-slice-backend)

1. **A strongly-typed id.** Never pass a raw `Guid` around — wrap it:

```csharp
   public record AuthorId(Guid Value) : ConceptAs<Guid>(Value)
   {
       public static AuthorId New() => new(Guid.NewGuid());
       public static implicit operator EventSourceId(AuthorId id) => new(id.Value.ToString());
   }
   ```

2. **The command and the event, together in one file.** The command is a record with `Handle()` on it — no separate handler class. `Handle()` returns the event that happened:

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

[EventType]
   public record AuthorRegistered(string Name);
   ```

3. **The read model and its projection.** Declare the shape you want to query and which event feeds it — AutoMap matches `AuthorRegistered.Name` to `Name`. A static method exposes the query as an observable so the UI updates live:

```csharp
   [ReadModel]
   [FromEvent<AuthorRegistered>]
   public record Author([property: Key] AuthorId Id, string Name)
   {
       public static ISubject<IEnumerable<Author>> AllAuthors(IMongoCollection<Author> collection) =>
           collection.Observe();
   }
   ```

That’s the whole backend for the feature — one file, three records. Run `dotnet build`.

What the build did

Building the backend **generates TypeScript proxies** for `RegisterAuthor` and `AllAuthors`. The frontend now has typed clients that match your C# exactly — change a property here and the frontend won’t compile until you fix it.

## 2. Build the screen (frontend)

[Section titled “2. Build the screen (frontend)”](#2-build-the-screen-frontend)

1. **A dialog that executes the command.** `CommandDialog` instantiates and runs the generated command and renders the OK/Cancel footer for you — you just supply the fields:

```tsx
   import { CommandDialog } from '@cratis/components/CommandDialog';
   import { InputTextField } from '@cratis/components/CommandForm';
   import { DialogProps } from '@cratis/arc.react/dialogs';
   import { RegisterAuthor } from './RegisterAuthor';
   import { Guid } from '@cratis/fundamentals';

export const AddAuthor = ({ closeDialog }: DialogProps) => (
       <CommandDialog<RegisterAuthor>
           command={RegisterAuthor}
           title="Add author"
           okLabel="Add"
           onBeforeExecute={(values) => { values.id = Guid.create(); return values; }}>
           <InputTextField<RegisterAuthor> value={i => i.name} title="Name" />
       </CommandDialog>
   );
   ```

2. **A table that reads the observable query.** The generated `AllAuthors` proxy is observable — `.use()` re-renders when the projection changes:

```tsx
   import { AllAuthors } from './Author';

## What you built

[Section titled “What you built”](#what-you-built)

* One **vertical slice**: command, event, read model, projection, and UI — all for a single behavior, in one place.
* **Full-stack type safety**: the React code calls proxies generated from your C# types. There is no second source of truth to drift.
* The **CQRS loop**: the command appends a fact, a projection builds the read model, and the observable query streams it to the UI live.

## Go deeper

[Section titled “Go deeper”](#go-deeper)

* Backend: [Commands](/arc/backend/commands/) and [Queries](/arc/backend/queries/) in Arc, [Projections](/chronicle/projections/) in Chronicle.
* Frontend: [Dialogs](/components/) and data tables in Components.
* The reasoning: [Why developers choose Cratis](/why-cratis/) and [Why Arc](/arc/why-arc/).

# Chronicle

> Kernel, protocol, storage, subscription, and local inspection boundaries for Chronicle.

Chronicle

## Event sourcing, the productive way

For information systems, this is the default architecture we recommend: store **every meaningful change as an immutable event** — the complete history of what happened — and turn those events into exactly the read models, reactions, and projections your application needs. Chronicle gives that event log a gRPC boundary, database-agnostic storage — MongoDB, PostgreSQL, Microsoft SQL Server, or SQLite — and tools you can actually operate. [Get started →](/chronicle/get-started/) · [Architecture →](/chronicle/architecture/)

## Start here

[Section titled “Start here”](#start-here)

[ Run Chronicle locally](#run-chronicle-locally)

[Start the development image, wait for readiness, and clean it up.](#run-chronicle-locally)

[ Understand the architecture](/chronicle/architecture/)

[Locate the protocol surfaces, kernel, runtime scopes, and persistent subscriptions.](/chronicle/architecture/)

[ Inspect with Workbench](/chronicle/workbench/)

[Use the bundled local browser inspection and projection-preview boundary.](/chronicle/workbench/)

## Run Chronicle locally

[Section titled “Run Chronicle locally”](#run-chronicle-locally)

For the shortest local path, use `latest-development`. It bundles Chronicle and MongoDB and tracks the newest published development image. When repeatability matters, pin a released version in your application or deployment configuration rather than copying an image digest into a getting-started command.

1. Pull and start the current development image with Chronicle available only on this machine. MongoDB remains internal to the container.

```bash
   docker run --pull=always --rm -d --name chronicle \
     -p 127.0.0.1:35000:35000 \
     cratis/chronicle:latest-development
   ```

2. Wait for the local health endpoint to report readiness. The development image uses a self-signed certificate, so this command disables certificate verification only for this local check.

```bash
   curl --insecure --fail --retry 30 --retry-all-errors --retry-delay 1 \
     https://localhost:35000/health
   ```

A successful response prints `Healthy`. At that point the kernel is ready for the next local evaluation step.

3. Stop and remove it when the evaluation is complete.

```bash
   docker rm -f chronicle
   ```

What this local start proves

A `Healthy` response proves that this local development container started. It does not establish production suitability, support, scale, security, durability, compatibility, a managed service, client/provider parity, or support for every topology.

## Independent-use boundary

[Section titled “Independent-use boundary”](#independent-use-boundary)

The self-hosted Chronicle kernel and bundled Workbench can be started without Arc or Components. Applications and clients still need compatible packages, protocols, and configuration for the Chronicle server they connect to.

## Inspection surfaces

[Section titled “Inspection surfaces”](#inspection-surfaces)

Chronicle Workbench provides a bundled local browser surface for authorized inspection of Chronicle runtime state and preview of supported projection behavior.

The Cratis CLI provides terminal workflows for inspecting and diagnosing Chronicle.

Inspection capability does not imply complete administration, production-ready mutation, client parity, federation, managed service, support, or an SLA.

## Continue

[Section titled “Continue”](#continue)

[ Architecture](/chronicle/architecture/)

[Understand the kernel, protocol, store, namespace, and subscription boundaries.](/chronicle/architecture/)

[ Workbench](/chronicle/workbench/)

[Inspect Chronicle from the bundled local browser application.](/chronicle/workbench/)

[ Cratis CLI](/cli/)

[Terminal inspection and diagnosis for Chronicle.](/cli/)

[ Chronicle source](https://github.com/Cratis/Chronicle/tree/main/Source)

[Owning kernel, client, Workbench, and package source.](https://github.com/Cratis/Chronicle/tree/main/Source)

# Chronicle in your language

> Event sourcing for .NET, TypeScript, Kotlin, Java, and Elixir: Chronicle is an open-source (MIT) event-sourcing database with idiomatic clients on NuGet, npm, Maven Central, and Hex — and a Python client coming soon.

Chronicle in your language

## One event-sourcing database, idiomatic clients

Chronicle is an event-sourcing database and processing runtime with a language-agnostic gRPC/protobuf boundary. That means the event store is not tied to one runtime: the first-class .NET SDK and the TypeScript, Kotlin/Java, and Elixir clients all work against the same store, the same events, and the same projections — and a Python client is coming soon. Everything is open source and MIT licensed. [Client SDK docs →](/chronicle/clients/)

## Event sourcing for .NET

[Section titled “Event sourcing for .NET”](#event-sourcing-for-net)

The .NET SDK is the first-class Chronicle client: typed access to event stores, event logs, read models, projections, reducers, reactors, constraints, migrations, namespaces, and hosting integration — including a one-line [.NET Aspire resource](/chronicle/hosting/aspire/).

```bash
dotnet add package Cratis.Chronicle
```

* [Event sourcing in .NET](/event-sourcing/dotnet/) — the dedicated landing page
* [.NET client docs](/chronicle/clients/dotnet/) · [Get started](/chronicle/get-started/)
* [`Cratis.Chronicle` on NuGet](https://www.nuget.org/packages/Cratis.Chronicle)
* [Chronicle on GitHub](https://github.com/Cratis/Chronicle)

## Event sourcing for TypeScript and Node.js

[Section titled “Event sourcing for TypeScript and Node.js”](#event-sourcing-for-typescript-and-nodejs)

`@cratis/chronicle` is the idiomatic TypeScript client for Chronicle, with support for transactions, jobs, webhooks, compliance/PII, and OpenTelemetry. It builds on the `@cratis/chronicle.contracts` gRPC contracts package.

```bash
npm install @cratis/chronicle
```

* [Event sourcing in TypeScript and Node.js](/event-sourcing/typescript/) — the dedicated landing page
* [TypeScript client docs](/chronicle/clients/typescript/)
* [`@cratis/chronicle` on npm](https://www.npmjs.com/package/@cratis/chronicle)
* [Chronicle.TypeScript on GitHub](https://github.com/Cratis/Chronicle.TypeScript)

## Event sourcing for Kotlin and Java

[Section titled “Event sourcing for Kotlin and Java”](#event-sourcing-for-kotlin-and-java)

`io.cratis:chronicle` is the idiomatic JVM client for Chronicle, usable from Kotlin and Java alike. It ships with a Spring Boot starter and a testing library.

build.gradle.kts

```kotlin
dependencies {
    implementation("io.cratis:chronicle:<version>")
    // Or, in a Spring Boot application:
    implementation("io.cratis:chronicle-spring-boot-starter:<version>")
}
```

* [Event sourcing in Kotlin and Java](/event-sourcing/kotlin/) — the dedicated landing page
* [Kotlin/Java client docs](/chronicle/clients/kotlin/)
* [`io.cratis:chronicle` on Maven Central](https://central.sonatype.com/artifact/io.cratis/chronicle)
* [Chronicle.Kotlin on GitHub](https://github.com/Cratis/Chronicle.Kotlin)

## Event sourcing for Elixir

[Section titled “Event sourcing for Elixir”](#event-sourcing-for-elixir)

`cratis_chronicle` is the idiomatic Elixir client for Chronicle, with transactions, optimistic concurrency, webhooks, and resilient reconnection.

mix.exs

```elixir
defp deps do
  [
    {:cratis_chronicle, "~> 0.0"}
  ]
end
```

* [Event sourcing in Elixir](/event-sourcing/elixir/) — the dedicated landing page
* [Elixir client docs](/chronicle/clients/elixir/)
* [`cratis_chronicle` on Hex](https://hex.pm/packages/cratis_chronicle)
* [Chronicle.Elixir on GitHub](https://github.com/Cratis/Chronicle.Elixir)

## Event sourcing for Python — coming soon

[Section titled “Event sourcing for Python — coming soon”](#event-sourcing-for-python--coming-soon)

A Python client for Chronicle is in development. It is pre-release and not yet published to PyPI, so there is nothing to install yet — follow the repository for progress.

* [Event sourcing in Python](/event-sourcing/python/) — the coming-soon landing page
* [Chronicle.Python on GitHub](https://github.com/Cratis/Chronicle.Python)

Pre-release

The Python client is pre-alpha. APIs will change, and no package has been published. Watch the repository or ask in [the community](/community/) if it matters to your project.

## Any language, one contract

[Section titled “Any language, one contract”](#any-language-one-contract)

Every client speaks the same gRPC/protobuf contracts, so any language with a gRPC implementation can talk to Chronicle. If your runtime is not listed above, you can implement the contracts directly.

[Building a client ](/chronicle/building-a-client/)Implement the Chronicle gRPC contracts for a new language or runtime.

[Chronicle architecture ](/chronicle/architecture/)How the kernel, the gRPC boundary, and the storage providers fit together.

[Chronicle MCP server ](/chronicle-mcp/)Connect an AI agent to a running Chronicle — it works regardless of which client language your app uses.

[Storage choice ](/chronicle/hosting/configuration/storage/)Run Chronicle over MongoDB (default), PostgreSQL, Microsoft SQL Server, or SQLite.

# Chronicle MCP Server

The Chronicle MCP server connects an AI agent to a running [Cratis Chronicle](https://github.com/Cratis/Chronicle) event store over the [Model Context Protocol](https://modelcontextprotocol.io). Point your agent at a Chronicle server and it can explore the domain, operate observers and jobs, and turn plain-language requests into Chronicle artifacts — always grounded in the store’s real schema.

The server offers two complementary sets of capabilities:

| Mode             | What it does                                                                                                                                      | Start here                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **Operate-side** | Inspect and operate a live system — browse events, watch observers, replay partitions, manage jobs.                                               | [Operating a store](/chronicle-mcp/operate-side/)       |
| **Design-time**  | Turn natural language into Chronicle artifacts — read models, projections, audits, catalogs — grounded in the actual event schema, never guessed. | [Design-time capabilities](/chronicle-mcp/design-time/) |

## Get started

[Section titled “Get started”](#get-started)

By the end of [Getting started](/chronicle-mcp/getting-started/) you will have the server wired into your agent and answering questions about a running Chronicle store.

1. [Getting started](/chronicle-mcp/getting-started/) — wire the server into your agent and ask your first question.
2. [Configuration](/chronicle-mcp/configuration/) — connection string, CLI config sharing, and authentication.
3. [How it works](/chronicle-mcp/concepts/) — the design-time vs. operate-side split and the grounding principle.

## Why this exists

[Section titled “Why this exists”](#why-this-exists)

Chronicle already exposes a rich gRPC management API, and the [Cratis CLI](https://github.com/Cratis/cli) puts it at your fingertips. This server puts the same store in reach of an AI agent — so instead of you translating a question into a sequence of API calls, the agent does it, and instead of hand-writing read-model boilerplate, the agent proposes a grounded starting point you review like any other change.

The design-time capabilities never invent field names or event shapes. Every suggestion is introspected from what the store actually has registered — see [How it works](/chronicle-mcp/concepts/#grounding-over-fluency).

# How it works

The Chronicle MCP server exposes two kinds of capability over one connection. Understanding the split is the fastest way to know which tool an agent will reach for — and why the design-time tools can be trusted not to make things up.

```
Server

inspect & operate

introspect schema

propose code

MCP over stdio

gRPC

AI agent

Chronicle store

Operate-side tools

Design-time tools

Reviewable proposal
```

## Two modes

[Section titled “Two modes”](#two-modes)

**Operate-side** is about *inspecting and operating a live system*. These tools read events, list observers, report failed partitions, and manage jobs. They are the natural-language equivalent of running the [Cratis CLI](https://github.com/Cratis/cli) against a store. See [Operating a store](/chronicle-mcp/operate-side/).

**Design-time** is about *turning intent into Chronicle artifacts*. Given a plain request, these tools introspect the store’s registered schema and produce read models, projections, audits, and catalogs. They are deliberately generative and advisory rather than operational. See [Design-time capabilities](/chronicle-mcp/design-time/).

The two are complementary: an agent might use operate-side tools to discover what event types exist, then a design-time tool to scaffold a read model from them.

## Grounding over fluency

[Section titled “Grounding over fluency”](#grounding-over-fluency)

Every design-time capability rests on one principle: **introspect the store before generating anything.** Field names, types, and event names come from Chronicle’s schema — never from a guess.

* Event fields are read from the JSON schema registered with each event type, exposed through [describe an event type](/chronicle-mcp/design-time/describe-event-type/).
* Consumers (projections, reducers, reactors) are read from the store’s projection and observer definitions.
* When the store does not have enough information to answer confidently — for example a requested event type is not registered — the tool says so and returns no fabricated shape, rather than inventing one.

This is worth over-engineering relative to the natural-language parsing itself: a plausible-sounding but wrong field name is worse than a tool that asks a clarifying question.

## Read-only against the store, generative against your codebase

[Section titled “Read-only against the store, generative against your codebase”](#read-only-against-the-store-generative-against-your-codebase)

No design-time capability mutates the store. They need only read access to the event type registry, projection and observer definitions, and namespaces. Generated code is returned as a proposal — the agent shows it to you, and you review it like any other change and apply it to your own project. Projections are cheap to regenerate but should never appear unreviewed in a codebase.

## Multi-tenancy awareness

[Section titled “Multi-tenancy awareness”](#multi-tenancy-awareness)

Chronicle isolates tenants by namespace. Every tool is scoped to an event store and namespace — defaulting to your configured defaults, overridable per call — so one tenant’s event shapes never leak into another’s suggestions by accident.

# Configuration

Configuration is optional. The server works out of the box with defaults suited to local development:

* **Connection string:** `chronicle://localhost:35000`
* **Credentials:** the development client id (`chronicle-dev-client`) and secret (`chronicle-dev-secret`)
* **Event store / namespace:** `default` / `Default`

You only set values when you need to point at a different server or authenticate against a secured one.

## Resolution order

[Section titled “Resolution order”](#resolution-order)

For every value the server has not been given explicitly, it resolves in this order, first match wins:

1. Explicit MCP options — environment variables or `appsettings.json`.
2. The `CHRONICLE_CONNECTION_STRING` environment variable.
3. The active context in the Cratis CLI configuration at `~/.cratis/config.json`.
4. Built-in development defaults.

Because step 3 reads the same file the [Cratis CLI](https://github.com/Cratis/cli) writes, a store you have already set up with `cratis context create` is picked up automatically — no separate configuration.

## Options

[Section titled “Options”](#options)

All options live under the `Cratis:Chronicle:Mcp` configuration section. As environment variables they take the `Cratis__Chronicle__Mcp__` prefix:

| Option                      | Environment variable                                     | Description                                                                          |
| --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `ConnectionString`          | `Cratis__Chronicle__Mcp__ConnectionString`               | The Chronicle connection string. Defaults to `chronicle://localhost:35000`.          |
| `Context`                   | `Cratis__Chronicle__Mcp__Context`                        | The CLI context to read connection details from. Defaults to the active context.     |
| `UseCliConfiguration`       | `Cratis__Chronicle__Mcp__UseCliConfiguration`            | Set to `false` to ignore `~/.cratis/config.json` entirely.                           |
| `ClientId` / `ClientSecret` | `Cratis__Chronicle__Mcp__ClientId` / `...__ClientSecret` | Client credentials for authentication. Defaults to development credentials.          |
| `ApiKey`                    | `Cratis__Chronicle__Mcp__ApiKey`                         | An API key to authenticate with, as an alternative to client credentials.            |
| `EventStore`                | `Cratis__Chronicle__Mcp__EventStore`                     | The default event store used by tools when none is specified. Defaults to `default`. |
| `Namespace`                 | `Cratis__Chronicle__Mcp__Namespace`                      | The default namespace used by tools when none is specified. Defaults to `Default`.   |

Every tool defaults the event store and namespace to these configured values, so you can ask high-level questions and only name a store or namespace when you need a specific one.

## Authentication

[Section titled “Authentication”](#authentication)

The server authenticates the same way the CLI does, and shares its token cache:

* **Client credentials (OAuth):** when the connection string carries a client id and secret (or you set `ClientId`/`ClientSecret`), the server obtains an OAuth token from the server’s token endpoint, derived from the connection’s own address. Tokens are cached on disk under `~/.cratis/tokens`, the same location the CLI uses, so the two share credentials.
* **API key:** set `ApiKey` (or embed `apiKey=` in the connection string) to authenticate with a static key instead.

> The token endpoint is taken from the connected server’s address; there is no separate management-port setting. If you are upgrading from an older release that had a `ManagementPort` option, you can remove it — it no longer has any effect.

## Connect timeout

[Section titled “Connect timeout”](#connect-timeout)

Set `CHRONICLE_CONNECT_TIMEOUT_SECONDS` to override the default 5-second connect timeout when reaching a slow or remote server.

# Design-time capabilities

The design-time tools turn a plain-language request into Chronicle artifacts — read models, projections, audits, and catalogs — grounded in the store’s real schema. They are read-only against the store and generative against your codebase: nothing is written to the store, and generated code comes back as a proposal you review. See [How it works](/chronicle-mcp/concepts/) for the principle behind them.

## Capabilities

[Section titled “Capabilities”](#capabilities)

| Capability                                                                           | Tool                           | Use it to                                                                                                     |
| ------------------------------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| [Describe the system](/chronicle-mcp/design-time/describe-system/)                   | `describe_system`              | Deduce what the system is and is for — entities, lifecycles, read surfaces, automations — and tell its story. |
| [Suggest the next event types](/chronicle-mcp/design-time/suggest-next-event-types/) | `suggest_next_event_types`     | Find lifecycle gaps and get grounded suggestions for the event types to introduce next.                       |
| [Ad-hoc projection](/chronicle-mcp/design-time/ad-hoc-projection/)                   | `run_ad_hoc_projection`        | Answer “show all X with all details” by folding events into current state on demand — nothing registered.     |
| [Describe an event type](/chronicle-mcp/design-time/describe-event-type/)            | `describe_event_type`          | Read an event type’s real fields and types — the grounding primitive the others build on.                     |
| [Read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/)         | `scaffold_read_model`          | Turn a set of event types into a reviewable read model + projection, grounded in their schema.                |
| [Unconsumed-event audit](/chronicle-mcp/design-time/unconsumed-event-audit/)         | `audit_unconsumed_event_types` | Find events nothing reads, and consumers pointing at event types that no longer exist.                        |
| [Event catalog](/chronicle-mcp/design-time/event-catalog/)                           | `generate_event_catalog`       | Produce a living data dictionary — every event, its fields, and its consumers.                                |
| [Causal trace](/chronicle-mcp/design-time/causal-trace/)                             | `explain_causal_trace`         | Turn an event source’s raw log into a “what happened and why” narrative.                                      |

## Prompts

[Section titled “Prompts”](#prompts)

Beyond tools, the server exposes MCP prompts that package whole workflows — clients that surface prompts (for example as slash commands) can offer them directly:

| Prompt                     | What it does                                                                                          |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| `describe_system`          | Describe what the system is and is for, and tell its story.                                           |
| `suggest_next_event_types` | Propose the next event types, refined with domain knowledge.                                          |
| `query_system`             | Answer a natural-language question (“show all employees with all details”) with an ad-hoc projection. |

## How an agent combines them

[Section titled “How an agent combines them”](#how-an-agent-combines-them)

A typical flow chains a few tools. To answer *“Show all employees with all details”* an agent might:

1. Understand the system with [describe the system](/chronicle-mcp/design-time/describe-system/) — which entities exist and which event types carry which facts.
2. Fold the relevant event types into current state with an [ad-hoc projection](/chronicle-mcp/design-time/ad-hoc-projection/) and present the result.
3. If the question keeps coming back, propose a permanent read model with [read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/).

Because the tools return structured data rather than prose, the agent does the natural-language reasoning while the store supplies the facts.

## Roadmap

[Section titled “Roadmap”](#roadmap)

The [capability hand-off](https://github.com/Cratis/Chronicle.Mcp) sketches ten design-time capabilities. The tools above cover the grounding-and-generation core plus system understanding, evolution suggestions, and ad-hoc querying. The remaining ideas — projection-vs-reducer advice, consistency-boundary (DCB) advice, schema-evolution assistance, spec scaffolding, and constraint suggestions — build on the same introspection pipeline and are candidates for future releases.

# Ad-hoc projection

*“Show all employees with all details.”* In an event-sourced system, answering that means folding events into current state — and if no projection happens to exist for exactly that question, the answer traditionally requires writing one, deploying it, and waiting for it to catch up. `run_ad_hoc_projection` removes that loop: it materializes the answer on demand, straight from the store, without registering or persisting anything.

Given the event types involved, the tool reads the matching events from the event sequence and folds them into per-event-source instances with the same semantics as an AutoMap projection: properties merge by name, later events overwrite earlier values, and removal events drop the instance. The result is the current state of every instance — computed in the moment, discarded after.

## The natural-language flow

[Section titled “The natural-language flow”](#the-natural-language-flow)

The assistant resolves the question to event types; the tool does the folding:

1. **Understand the system** — [describe the system](/chronicle-mcp/design-time/describe-system/) or the [event catalog](/chronicle-mcp/design-time/event-catalog/) reveals the entities and which event types carry which facts.
2. **Pick the event types** — for *“all employees with all details”* that is every event contributing employee state: `EmployeeHired,EmployeeMoved,EmployeePromoted`, with `EmployeeTerminated` as a removal so former employees drop out.
3. **Run the projection** — the tool folds the events and returns the instances.
4. **Present the answer** — instances share a shape, so a table usually reads best.

The `query_system` prompt packages exactly this flow: give it the natural-language question and it walks the assistant through resolving the event types and materializing the answer.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter         | Required | Description                                               |
| ----------------- | -------- | --------------------------------------------------------- |
| `eventTypes`      | yes      | Comma-separated event type ids to fold.                   |
| `removedWith`     | no       | Comma-separated event type ids that remove an instance.   |
| `eventStore`      | no       | The event store. Defaults to the configured event store.  |
| `namespace`       | no       | The namespace. Defaults to the configured namespace.      |
| `eventSequenceId` | no       | The event sequence to read from. Defaults to `event-log`. |
| `eventSourceId`   | no       | Scope to a single instance.                               |
| `limit`           | no       | Maximum instances returned. Defaults to 100.              |

## What it returns

[Section titled “What it returns”](#what-it-returns)

* **Instances** — one per event source, each with its folded properties, the sequence number of the last event applied, and when it occurred.
* **Counts** — how many events were folded and how many instances materialized (before the limit).
* **Guidance** — how to present and refine the result.

## From ad-hoc to permanent

[Section titled “From ad-hoc to permanent”](#from-ad-hoc-to-permanent)

An ad-hoc projection is a probe. When the same question keeps coming back, that is the signal it deserves a real read model — hand the same event types to [read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/) and turn the probe into a reviewable projection in your codebase.

## Honest limits

[Section titled “Honest limits”](#honest-limits)

* The folding is AutoMap-shaped: top-level properties merge by name, last write wins. Joins, children collections, and computed values are projection-engine territory — reach for a real projection when you need them.
* Every matching event is read from the sequence on each call. That is exactly right for design-time exploration and operational spot checks; it is not a serving layer for production queries.

## Related

[Section titled “Related”](#related)

* [Describe the system](/chronicle-mcp/design-time/describe-system/) — find out which event types exist before folding them.
* [Event catalog](/chronicle-mcp/design-time/event-catalog/) — the field-level detail per event type.
* [Read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/) — make a recurring ad-hoc projection permanent.

# Causal trace

`explain_causal_trace` reads the ordered event history of one event source together with each event’s correlation id and causation chain, so an agent can narrate *what happened and why* instead of a support engineer reading raw JSON logs. It is the natural-language equivalent of `git blame` for state.

## When to use it

[Section titled “When to use it”](#when-to-use-it)

* To answer a question like *“Why does this order show as cancelled?”* for support or operations staff.
* To reconstruct the sequence of facts that produced an entity’s current state.
* To relate an event to the wider flow that produced it, by following its correlation id.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter         | Required | Description                                               |
| ----------------- | -------- | --------------------------------------------------------- |
| `eventSourceId`   | yes      | The event source id to trace (for example the order id).  |
| `eventSequenceId` | no       | The event sequence to read from. Defaults to `event-log`. |
| `eventType`       | no       | A comma-separated event type filter.                      |
| `eventStore`      | no       | The event store. Defaults to the configured event store.  |
| `namespace`       | no       | The namespace. Defaults to the configured namespace.      |

## What it returns

[Section titled “What it returns”](#what-it-returns)

The event source’s events in sequence order. Each event carries:

* Its sequence number, event type, generation, and when it occurred.
* Its **correlation id** — the key that groups it with the wider flow it belongs to.
* The identity that **caused** it, when known.
* Its **causation** chain — the recorded causes, each with a type and details.
* The event payload as JSON.

## Example

[Section titled “Example”](#example)

**Prompt:** *“Why does order 8a3f… show as cancelled?”*

The agent calls `explain_causal_trace` with the order’s id and walks the returned timeline: `OrderPlaced`, then `PaymentFailed` sharing a correlation id with a payment retry flow, then `OrderCancelled` caused by that failure. From the ordered facts and their causation, the agent produces a plain-language narrative — “the order was cancelled because payment failed twice” — without anyone reading the raw log.

To widen the picture beyond a single entity, follow the correlation ids: events that share a correlation id belong to the same business flow, even across event sources.

## Related

[Section titled “Related”](#related)

* [Get events](/chronicle-mcp/operate-side/events/) — read raw events from a sequence with filtering.

# Describe an event type

`describe_event_type` reads an event type’s real schema from the store — every property with its JSON type and a suggested C# type. It is the grounding primitive the other design-time tools build on: any generated projection, read model, or spec starts from the fields the event actually carries, not a guess.

## When to use it

[Section titled “When to use it”](#when-to-use-it)

* Before generating anything from an event type, to confirm its shape.
* To answer “what fields does `UserRegistered` have?” without opening source code.
* As the first step when an agent maps a natural-language request onto concrete events.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter    | Required | Description                                                         |
| ------------ | -------- | ------------------------------------------------------------------- |
| `eventType`  | yes      | The event type id/name to describe (for example `UserRegistered`).  |
| `generation` | no       | A specific generation to describe. The latest is used when omitted. |
| `eventStore` | no       | The event store. Defaults to the configured event store.            |

## What it returns

[Section titled “What it returns”](#what-it-returns)

The event type’s identity (id, generation, owner, source, whether it is a tombstone, and the originating store when it is a foreign type received through the inbox), plus a list of properties. Each property carries its name, JSON schema type, a suggested C# type, any schema `format`, whether it is required, and its description.

Returns `null` when no matching event type is registered — a signal that the name is wrong or the type has not been registered yet.

## Example

[Section titled “Example”](#example)

**Prompt:** *“What does the UserRegistered event look like?”*

The agent calls `describe_event_type` with `eventType: "UserRegistered"` and gets back the grounded shape:

| Property       | JSON type          | C# type          | Required |
| -------------- | ------------------ | ---------------- | -------- |
| `Email`        | string             | `string`         | yes      |
| `Name`         | string             | `string`         | no       |
| `RegisteredAt` | string (date-time) | `DateTimeOffset` | no       |

The C# type suggestions map JSON schema types and formats to idiomatic C# — `guid`/`uuid` to `Guid`, `date-time` to `DateTimeOffset`, `integer` to `int`, arrays to `IEnumerable<T>`, and so on.

## Related

[Section titled “Related”](#related)

* [Read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/) uses these fields to build a read model.
* [Event catalog](/chronicle-mcp/design-time/event-catalog/) returns the same field detail for every event type at once.

# Describe the system

You inherit an event store — or return to one after six months — and the first question is always the same: *what is this system, and what is it for?* The answer is already in the store. Event names are past-tense facts about subjects, so the names themselves carry which entities exist and what can happen to them. `describe_system` reads that language back out.

Ask *“describe the system in Sales”* and the tool deduces a structural model from the registered metadata: it clusters event types into the entities they describe, places every event in its entity’s lifecycle, and maps the read models and automations around them. The assistant then turns that model into prose — what the system is, and the story of how it behaves.

## How the deduction works

[Section titled “How the deduction works”](#how-the-deduction-works)

Everything is deduced from what the store actually contains — nothing is guessed from code or documentation:

* **Entities** come from event type names. `AuthorRegistered`, `AuthorNameChanged`, and `AuthorRemoved` all name the same subject, so they cluster as the entity **Author**. Property-scoped clusters fold into their parent: with both `CustomerRegistered` and `CustomerAddressUpdated` present, “CustomerAddress” folds into **Customer** so the whole lifecycle sits together.
* **Lifecycle stages** come from the verb: *Registered/Created/Hired* mark **Creation**, *Changed/Renamed/Assigned* mark **Mutation**, *Received/Shipped/LoggedIn* mark **Activity**, *Corrected/Redacted* mark **Correction**, and *Removed/Closed/Cancelled* mark **Termination**.
* **Properties** come from each event type’s registered JSON schema — the same field detail as [describe an event type](/chronicle-mcp/design-time/describe-event-type/).
* **Read surfaces** are the projections and reducers with the read models they build — what the business watches.
* **Automations** are the reactors and external observers — what the system does on its own.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter    | Required | Description                                                                  |
| ------------ | -------- | ---------------------------------------------------------------------------- |
| `eventStore` | no       | The event store to describe. Defaults to the configured event store.         |
| `namespace`  | no       | The namespace to resolve observers in. Defaults to the configured namespace. |

## What it returns

[Section titled “What it returns”](#what-it-returns)

* **Entities** — each with its events ordered by lifecycle stage, and every event’s properties.
* **Read surfaces** — each read model with how it is built (projection or reducer) and the event types it derives from.
* **Automations** — each observer with the event types that trigger it.
* **Unconsumed event types** — facts the system records but nothing acts on yet.
* **Statistics** — headline counts, and the namespaces present in the store.
* **Narrative guidance** — instructions the assistant follows to turn the model into a description and a story.

## Example

[Section titled “Example”](#example)

**Prompt:** *“Describe the system in HR — and tell me its story.”*

From a store holding `EmployeeHired`, `EmployeeMoved`, `EmployeePromoted`, and `EmployeeTerminated`, plus an `AllEmployees` projection and an `OnboardingNotifier` reactor, the assistant deduces an HR system centered on the **Employee** entity and narrates it: an employee’s story begins when they are hired with a name and title; along the way they can move (the events carry the address vocabulary) and be promoted; the business watches all employees through `AllEmployees`; and when someone is hired, the system acts on its own to start onboarding. Termination ends the story.

The `describe_system` prompt packages this workflow, so clients that surface MCP prompts can offer it directly.

## Related

[Section titled “Related”](#related)

* [Suggest the next event types](/chronicle-mcp/design-time/suggest-next-event-types/) — the same deduced model, used to find the gaps.
* [Event catalog](/chronicle-mcp/design-time/event-catalog/) — the flat data dictionary underneath the narrative.
* [Ad-hoc projection](/chronicle-mcp/design-time/ad-hoc-projection/) — query the described system’s actual data.

# Event catalog

`generate_event_catalog` produces a living data dictionary from the event store: every event type, its fields, and every projection, reducer, and reactor that consumes it. Event names are the ubiquitous language of an event-sourced system, and this keeps that language documented and current straight from the store — useful onboarding material for new developers and grounding for any modeling question.

## When to use it

[Section titled “When to use it”](#when-to-use-it)

* To onboard someone to a domain without hand-maintained documentation.
* As grounding before a modeling conversation — the agent reads the catalog to know what already exists.
* To regenerate a data dictionary on demand instead of maintaining one by hand.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter    | Required | Description                                                                  |
| ------------ | -------- | ---------------------------------------------------------------------------- |
| `eventStore` | no       | The event store. Defaults to the configured event store.                     |
| `namespace`  | no       | The namespace to resolve observers in. Defaults to the configured namespace. |
| `eventType`  | no       | A single event type id to scope the catalog to. Omit for the whole store.    |

## What it returns

[Section titled “What it returns”](#what-it-returns)

One entry per event type, each with:

* **Identity** — id, generation, owner, source, whether it is a tombstone, and the originating store for foreign types.
* **Fields** — every property with its JSON and suggested C# type, the same detail as [describe an event type](/chronicle-mcp/design-time/describe-event-type/).
* **Consumers** — the projections, reducers, and reactors that read the event, each with its type, identifier, and the read model it builds (when it builds one).

An event type with an empty consumer list is an orphan — the same signal the [unconsumed-event audit](/chronicle-mcp/design-time/unconsumed-event-audit/) isolates.

## Example

[Section titled “Example”](#example)

**Prompt:** *“Give me a catalog of our order events and who reads them.”*

Scoped with `eventType` or filtered by the agent, the catalog shows, for each order event, its fields and its consumers — for example that `OrderPlaced` is read by the `OrderSummary` projection and the `ShippingNotifier` reactor, while `OrderCancelled` is read only by `OrderSummary`. From there the agent can explain the read side of the domain, or spot a gap.

## Related

[Section titled “Related”](#related)

* [Describe an event type](/chronicle-mcp/design-time/describe-event-type/) — the same field detail for a single type.
* [Unconsumed-event audit](/chronicle-mcp/design-time/unconsumed-event-audit/) — a focused view of the orphans in the catalog.

# Read-model scaffolding

`scaffold_read_model` is the flagship design-time capability. It turns a set of event types into a reviewable read model and its model-bound projection — with field names and types taken from the events’ real schema, never invented. The output is always a proposal to review, never a silent write into your codebase.

## When to use it

[Section titled “When to use it”](#when-to-use-it)

* To answer a request like *“Show me all the users registered”* with a working starting point in seconds instead of hand-written boilerplate.
* When product or analytics folks describe a read model in plain English and an engineer needs something to approve in a pull request.

The agent resolves the natural-language request to a concrete list of event types first — with [list event types](/chronicle-mcp/operate-side/exploring-the-store/), [describe an event type](/chronicle-mcp/design-time/describe-event-type/), or the [event catalog](/chronicle-mcp/design-time/event-catalog/) — then passes them to this tool.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter       | Required | Description                                                                                                |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `readModelName` | yes      | The name of the read model to generate (for example `Users`).                                              |
| `eventTypes`    | yes      | A comma-separated list of event type ids to project from (for example `UserRegistered,UserEmailVerified`). |
| `codeNamespace` | no       | The C# namespace to generate into. Defaults to `ReadModels`.                                               |
| `eventStore`    | no       | The event store. Defaults to the configured event store.                                                   |

## What it returns

[Section titled “What it returns”](#what-it-returns)

* **Generated C# code** for a model-bound read model and projection.
* **Chosen fields**, each traced back to the event it came from, so you can see why every property is there.
* **Existing projections** that already read these events or target this read model — surfaced so you do not create a duplicate.
* **Resolved and unresolved event types** — the requested types that were found, and any that are not registered.
* **Notes** on caveats, such as a property that appears with two different types across events, or an identity that should become a strongly-typed concept.

If none of the requested event types are registered, it returns no code and says so, rather than fabricating a shape.

## Example

[Section titled “Example”](#example)

**Prompt:** *“Show me all the users registered.”*

The agent resolves the request to the `UserRegistered` event, then calls `scaffold_read_model` with `readModelName: "Users"` and `eventTypes: "UserRegistered"`. The generated code is grounded in `UserRegistered`’s real fields:

```csharp
// Copyright (c) Cratis. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

using MongoDB.Driver;

namespace ReadModels;

/// <summary>
/// Users read model, scaffolded from UserRegistered.
/// Review the field selection and replace the Guid identity with a strongly-typed EventSourceId concept before use.
/// </summary>
[ReadModel]
[FromEvent<UserRegistered>]
public record Users(
    Guid Id,
    string Email,
    string Name)
{
    /// <summary>
    /// Queries all Users instances.
    /// </summary>
    /// <param name="collection">The read model collection.</param>
    /// <returns>All Users instances.</returns>
    public static IQueryable<Users> AllUsers(IMongoCollection<Users> collection) =>
        collection.AsQueryable();
}
```

## Reviewing the proposal

[Section titled “Reviewing the proposal”](#reviewing-the-proposal)

The scaffold is a starting point, not a finished slice. When you review it:

* **Identity.** The key is generated as `Guid Id`. Replace it with a strongly-typed identity concept derived from `EventSourceId<Guid>` — the note on the result reminds you.
* **AutoMap.** Field names match the event’s property names so Chronicle’s AutoMap wires them; keep names aligned or add explicit mapping where they diverge.
* **`using` directives.** `[ReadModel]` and `[FromEvent<T>]` come from Chronicle; most Cratis projects surface them through global usings. Adjust the usings to match your project.
* **Existing projections.** If the result lists an existing projection that already answers the question, prefer surfacing that over adding a duplicate.

## Related

[Section titled “Related”](#related)

* [Describe an event type](/chronicle-mcp/design-time/describe-event-type/) — inspect the fields before scaffolding.
* [Unconsumed-event audit](/chronicle-mcp/design-time/unconsumed-event-audit/) — find events that still lack a read model.

# Suggest the next event types

A growing event model develops blind spots: an entity that can be created but never removed, a value set once at registration that the business later needs to change, a lifecycle whose beginning is implicit. You usually discover these gaps the hard way — when a feature needs an event that does not exist. `suggest_next_event_types` finds them first.

Ask *“what event types should I introduce next for the system in Sales?”* and the tool deduces the system’s entities and lifecycles from the registered event types (the same deduction as [describe the system](/chronicle-mcp/design-time/describe-system/)), then runs deterministic gap analysis over them. Every suggestion names the concrete gap it closes — these are grounded findings, not brainstorming.

## The gaps it finds

[Section titled “The gaps it finds”](#the-gaps-it-finds)

* **No explicit creation** — an entity’s first recorded fact is a mutation or termination, so its lifecycle starts implicitly. Suggests an explicit creation event that gives projections a reliable initialization point.
* **A life without an end** — the entity has a beginning but nothing ever removes, closes, or archives it. Suggests a termination event so read models can clear state (`[RemovedWith]`) and compliance and cleanup have a fact to act on.
* **Facts frozen at creation** — a property is set when the entity comes to life and no later event ever touches it. If the business allows it to change, that change needs its own event. Identifier properties are excluded — those genuinely never change.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter    | Required | Description                                                                               |
| ------------ | -------- | ----------------------------------------------------------------------------------------- |
| `eventStore` | no       | The event store to analyze. Defaults to the configured event store.                       |
| `entity`     | no       | An entity name to scope the suggestions to (case-insensitive). Omit for the whole system. |

## What it returns

[Section titled “What it returns”](#what-it-returns)

* **Suggestions** — each with a suggested name (past tense, one purpose), the entity and lifecycle stage it completes, the rationale naming the gap, and candidate properties drawn from the existing schema.
* **The entities analyzed** — so the assistant can reason about the suggestions in context.
* **Guidance** — instructions for refining the seeds with domain knowledge.

## The suggestions are seeds

[Section titled “The suggestions are seeds”](#the-suggestions-are-seeds)

The analysis is deliberately mechanical so it never invents facts — which means the names need the domain’s own language. The guidance tells the assistant to refine them: a Book is *Withdrawn*, not *Removed*; an Order is *Cancelled*, not *Deleted*; and some facts really are immutable, in which case the right answer is to discard the suggestion and say why.

## Example

[Section titled “Example”](#example)

**Prompt:** *“What event types should I introduce next for the system in CRM?”*

From a store holding `CustomerRegistered` (with `Email`, `FullName`, `PhoneNumber`) and `CustomerAddressUpdated`, the analysis finds that nothing ever ends a customer’s life, and that email, name, and phone number are frozen at registration. The assistant proposes `CustomerRemoved` (or, refined, `CustomerOffboarded`), plus `CustomerEmailChanged`, `CustomerFullNameChanged`, and `CustomerPhoneNumberChanged` — each carrying its property from the existing schema — and notes which ones the business may not need.

The `suggest_next_event_types` prompt packages this workflow for clients that surface MCP prompts.

## Related

[Section titled “Related”](#related)

* [Describe the system](/chronicle-mcp/design-time/describe-system/) — the deduced model the analysis runs over.
* [Unconsumed-event audit](/chronicle-mcp/design-time/unconsumed-event-audit/) — the complementary gap: events that exist but nothing reads.
* [Read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/) — once the new events exist, project them.

# Unconsumed-event audit

`audit_unconsumed_event_types` cross-references every registered event type against everything that consumes it — projections, reducers, and reactors — and reports two kinds of silent data debt:

* **Unconsumed event types** — data being written that no read model or reactor reads.
* **Dangling references** — the inverse: a consumer that references an event type id which no longer exists in the registry, typically a dead projection left behind after a refactor.

It needs no natural-language parsing and is cheap to run, which makes it a good periodic health check rather than only an ad-hoc query.

## When to use it

[Section titled “When to use it”](#when-to-use-it)

* As a recurring audit to catch events recorded “just in case” that never became a read model.
* After a refactor, to find projections or reducers still pointing at event types that have been removed.

## Parameters

[Section titled “Parameters”](#parameters)

| Parameter    | Required | Description                                                                  |
| ------------ | -------- | ---------------------------------------------------------------------------- |
| `eventStore` | no       | The event store. Defaults to the configured event store.                     |
| `namespace`  | no       | The namespace to resolve observers in. Defaults to the configured namespace. |

## What it returns

[Section titled “What it returns”](#what-it-returns)

* The number of event types considered.
* **Unconsumed** event types, each with its id, generation, owner, and whether it is a tombstone. The owner tells you whether it is a `Client` type a developer usually cares about or a framework-internal `Chronicle` type.
* **Dangling references**, each naming the missing event type id and the consumer (its type and id) that still points at it.

## How consumption is determined

[Section titled “How consumption is determined”](#how-consumption-is-determined)

The audit is grounded entirely in the store’s registered definitions:

* **Projections** contribute the event types they read from — the keys of their `From`, `Join`, and removal definitions, walked into nested and child projections.
* **Observers** (reactors, reducers, and projections) contribute the event types each observes.

An event type is *unconsumed* when nothing in either set references it. A reference is *dangling* when it names an event type id that is not in the registry.

## Example

[Section titled “Example”](#example)

**Prompt:** *“What events are we writing that nothing reads?”*

The agent calls `audit_unconsumed_event_types` and reports back, for example, that `CartAbandoned` is written but read by no projection or reactor — a candidate for either a new read model or removal — and that a `LegacyOrderView` projection still references a `PriceQuoted` event type that no longer exists.

## Related

[Section titled “Related”](#related)

* [Event catalog](/chronicle-mcp/design-time/event-catalog/) — the full picture of every event and its consumers, including the orphans this audit isolates.
* [Read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/) — turn an unconsumed event into a read model.

# Getting started

By the end of this page you will have the Chronicle MCP server running inside your agent and answering questions about a live Chronicle store.

## Prerequisites

[Section titled “Prerequisites”](#prerequisites)

* A running Chronicle server. If you do not have one, the [`docker-compose.yml` in the repository](https://github.com/Cratis/Chronicle.Mcp/blob/main/Source/docker-compose.yml) brings one up with `docker compose up -d`.
* An MCP-capable agent (for example VS Code with an agent extension, or any client that speaks the Model Context Protocol over stdio).
* Docker, to run the pre-built `cratis/chronicle-mcp` image.

## Wire it into your agent

[Section titled “Wire it into your agent”](#wire-it-into-your-agent)

The server speaks MCP over stdio and ships as a container. Configure your agent to launch it. In VS Code, add it to your user settings or to a `.vscode/mcp.json` in your project:

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

On macOS and Windows the host machine is reachable from the container at `host.docker.internal`. The connection string is the only value most setups need to change — everything else has a working local-development default. See [Configuration](/chronicle-mcp/configuration/) for the full resolution order and authentication.

## Ask your first questions

[Section titled “Ask your first questions”](#ask-your-first-questions)

Once the server is connected, your agent can reach the store. Start with the operate-side capabilities to confirm connectivity:

* “List all event stores.”
* “What event types are registered?”
* “Are there any failed partitions?”

Then try the design-time capabilities, which turn a plain request into a grounded artifact:

* “Describe the system in this event store” → the agent deduces entities and lifecycles with [describe the system](/chronicle-mcp/design-time/describe-system/) and tells the system’s story.
* “Show all employees with all details” → an [ad-hoc projection](/chronicle-mcp/design-time/ad-hoc-projection/) folds the events into current state on demand.
* “What event types should I introduce next?” → grounded gap findings from [suggest the next event types](/chronicle-mcp/design-time/suggest-next-event-types/).
* “Show me all the users registered” → the agent resolves the event types, then proposes a read model with [read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/).
* “What events are we writing that nothing reads?” → an [unconsumed-event audit](/chronicle-mcp/design-time/unconsumed-event-audit/).
* “Why does this order show as cancelled?” → a [causal trace](/chronicle-mcp/design-time/causal-trace/) of the order’s history.

## Where to go next

[Section titled “Where to go next”](#where-to-go-next)

* [Configuration](/chronicle-mcp/configuration/) — connect to a secured server, share the CLI’s context, or run without Docker.
* [How it works](/chronicle-mcp/concepts/) — the two modes and why every design-time suggestion is grounded in real schema.
* [Design-time capabilities](/chronicle-mcp/design-time/) — the full set of generative and advisory tools.

# Operating a store

The operate-side tools inspect and operate a live Chronicle system. They are the natural-language equivalent of running the [Cratis CLI](https://github.com/Cratis/cli) against a store: browse the domain, watch observers, read events, and manage jobs. Every tool defaults the event store and namespace to your [configured defaults](/chronicle-mcp/configuration/), so you only name a store or namespace when you want a specific one.

## Capabilities

[Section titled “Capabilities”](#capabilities)

| Area                | Tools                                                                                                                                                | Page                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Exploring the store | `list_event_stores`, `list_namespaces`, `list_event_types`, `list_projections`, `list_read_models`, `get_read_model_instances`, `get_server_version` | [Exploring the store](/chronicle-mcp/operate-side/exploring-the-store/) |
| Events              | `get_events`, `get_tail_sequence_number`                                                                                                             | [Events](/chronicle-mcp/operate-side/events/)                           |
| Observer health     | `list_observers`, `get_observer`, `list_failed_partitions`, `list_recommendations`                                                                   | [Observer health](/chronicle-mcp/operate-side/observer-health/)         |
| Jobs                | `list_jobs`, `get_job`, `get_job_steps`, `stop_job`, `resume_job`, `delete_job`                                                                      | [Jobs](/chronicle-mcp/operate-side/jobs/)                               |

## Things to ask

[Section titled “Things to ask”](#things-to-ask)

* List all event stores.
* List all event types in the `orders` event store.
* Show me the events for order `8a3f…`.
* Are there any failed partitions?
* What observers use the event type `OrderPlaced`?
* List all jobs, and show me the steps of job `…`.

## Operate-side and design-time together

[Section titled “Operate-side and design-time together”](#operate-side-and-design-time-together)

Operate-side tools discover *what is there*; design-time tools turn that into *artifacts*. A common pattern is to explore event types here, then hand them to [read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/). See [How it works](/chronicle-mcp/concepts/) for the full split.

# Events

These tools read from event sequences — the append-only logs at the heart of Chronicle.

## Tools

[Section titled “Tools”](#tools)

| Tool                       | Description                                                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_events`               | Retrieve events from an event sequence, with optional filtering by sequence range, event source id, and event type. Returns event headers and JSON content. |
| `get_tail_sequence_number` | Return the highest used sequence number (the tail) in an event sequence.                                                                                    |

## `get_events`

[Section titled “get\_events”](#get_events)

| Parameter                  | Description                                                                                         |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| `eventSequenceId`          | The sequence to read from. Defaults to `event-log`.                                                 |
| `from` / `to`              | The sequence-number range. `from` defaults to `0`; `to` is optional.                                |
| `eventSourceId`            | An optional event source id to filter by.                                                           |
| `eventType`                | An optional comma-separated event type filter (for example `UserRegistered` or `UserRegistered+1`). |
| `eventStore` / `namespace` | Default to the configured values.                                                                   |

Use it to read what actually happened — for a whole sequence, a range, or a single event source.

## `get_tail_sequence_number`

[Section titled “get\_tail\_sequence\_number”](#get_tail_sequence_number)

The tail is the highest used sequence number, not a total count of events — gaps can exist. Use it to gauge how far a sequence has progressed, for example when checking whether an observer has caught up.

## Narrating history

[Section titled “Narrating history”](#narrating-history)

`get_events` returns raw events. To turn one event source’s history into a “what happened and why” narrative — following correlation and causation — use the design-time [causal trace](/chronicle-mcp/design-time/causal-trace/) tool instead.

# Exploring the store

These tools let an agent walk a Chronicle store’s structure — its stores, namespaces, event types, projections, read models, and current instances — to build up a picture of the domain before doing anything else.

## Tools

[Section titled “Tools”](#tools)

| Tool                       | Description                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `get_server_version`       | Get version info from the server. Doubles as a connectivity check.                               |
| `list_event_stores`        | List all event stores on the server.                                                             |
| `list_namespaces`          | List namespaces within an event store.                                                           |
| `list_event_types`         | List registered event types, with id, generation, owner, and source.                             |
| `list_projections`         | List projection definitions, including the read model each projects into and its activity state. |
| `list_read_models`         | List read model definitions.                                                                     |
| `get_read_model_instances` | List the current instances of a read model, paged.                                               |

## Typical flow

[Section titled “Typical flow”](#typical-flow)

Start broad and narrow down:

1. `get_server_version` — confirm the server is reachable.
2. `list_event_stores` then `list_namespaces` — find the store and tenant you care about.
3. `list_event_types` — see the domain’s vocabulary.
4. `list_projections` and `list_read_models` — see what is already derived from those events.
5. `get_read_model_instances` — read the current state a projection has produced.

## Going deeper on an event type

[Section titled “Going deeper on an event type”](#going-deeper-on-an-event-type)

`list_event_types` gives you the inventory. To see an event type’s actual fields and types, use the design-time [describe an event type](/chronicle-mcp/design-time/describe-event-type/) tool, or [generate an event catalog](/chronicle-mcp/design-time/event-catalog/) for the whole store at once.

# Jobs

Chronicle runs long-lived work — replays, projections rebuilds, and other maintenance — as jobs. These tools let an agent list jobs, inspect their progress and steps, and control their lifecycle.

## Tools

[Section titled “Tools”](#tools)

| Tool            | Description                                                          |
| --------------- | -------------------------------------------------------------------- |
| `list_jobs`     | List all jobs in a namespace, optionally filtered by job status.     |
| `get_job`       | Get a specific job by id, including full details and status changes. |
| `get_job_steps` | Get the steps of a specific job, optionally filtered by step status. |
| `stop_job`      | Stop a specific job. It transitions to a stopped status.             |
| `resume_job`    | Resume a specific stopped job.                                       |
| `delete_job`    | Delete a specific job. It transitions to a removing status.          |

## Typical flow

[Section titled “Typical flow”](#typical-flow)

1. `list_jobs` — see what is running or has run, filtered by status when you only care about, say, failed jobs.
2. `get_job` — inspect one job’s details and the history of its status changes.
3. `get_job_steps` — drill into the individual steps to see where a job is or where it stopped.
4. `stop_job` / `resume_job` / `delete_job` — control the job once you understand its state.

## A note on control operations

[Section titled “A note on control operations”](#a-note-on-control-operations)

`stop_job`, `resume_job`, and `delete_job` change a running system. Have the agent confirm the job id and its current state — with `get_job` — before invoking them, the same care you would take from the CLI.

# Observer health

Observers — projections, reducers, and reactors — consume event sequences to build read models and trigger side effects. These tools let an agent check their health, find failures, and surface maintenance the store recommends.

## Tools

[Section titled “Tools”](#tools)

| Tool                     | Description                                                                                                                               |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `list_observers`         | List observers in a namespace, with health and replay status. Optionally filter by type (reactor, reducer, projection, or all).           |
| `get_observer`           | Show detailed information about a specific observer — its type, running state, owner, handled sequence numbers, and observed event types. |
| `list_failed_partitions` | List observer partitions that have failed and are paused.                                                                                 |
| `list_recommendations`   | List active maintenance recommendations the store has raised.                                                                             |

## A troubleshooting flow

[Section titled “A troubleshooting flow”](#a-troubleshooting-flow)

When an observer is stuck or a read model looks stale:

1. `list_observers` — check the observer’s running state and how far its sequence numbers have progressed.
2. `get_observer` — inspect the observer in detail, including which event types it observes.
3. `list_failed_partitions` — see whether a partition has failed and paused the observer.
4. `list_recommendations` — see whether the store already recommends a fix.

A **quarantined** observer does not auto-resume; an operator has to clear the quarantine. Use the [Cratis CLI](https://github.com/Cratis/cli) or the management API to replay, retry, or clear quarantine once you have diagnosed the cause here.

## Finding the consumers of an event type

[Section titled “Finding the consumers of an event type”](#finding-the-consumers-of-an-event-type)

`get_observer` shows the event types a single observer consumes. For the reverse — every consumer of a given event type across the store, plus its fields — use the design-time [event catalog](/chronicle-mcp/design-time/event-catalog/).

# Chronicle architecture

> Chronicle's kernel, protocol, event-store, namespace, and persistent-subscription boundaries.

Chronicle

## Kernel and protocol boundaries

Chronicle uses a .NET/Orleans actor-based kernel behind gRPC/HTTP surfaces and supports multiple event stores, namespaces, and persistent event-store subscriptions with outbox/inbox sequences.

🎯Use this page to locate

* the gRPC and HTTP protocol surfaces;
* the .NET/Orleans kernel;
* event-store and namespace runtime scopes; and
* persistent-subscription outbox/inbox sequences.

## Runtime shape

[Section titled “Runtime shape”](#runtime-shape)

```
gRPC surface

.NET / Orleans kernel

HTTP surface

Event stores

Namespaces

Persistent event-store subscriptions

Outbox / inbox sequences
```

| Boundary                    | Owns in this diagram                                       | Does not imply                                                 |
| --------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------- |
| Protocol surfaces           | gRPC and HTTP entry boundaries around the kernel           | Every client or tool uses both transports                      |
| Kernel                      | .NET/Orleans runtime                                       | Horizontal scale, throughput, recovery, or topology guarantees |
| Event stores and namespaces | Separate runtime scopes                                    | Client/provider parity or compatibility breadth                |
| Persistent subscriptions    | Event-store subscription state with outbox/inbox sequences | Guaranteed or exactly-once delivery                            |

## Related inspection surfaces

[Section titled “Related inspection surfaces”](#related-inspection-surfaces)

Chronicle Workbench provides a bundled local browser surface for authorized inspection of Chronicle runtime state and preview of supported projection behavior.

The Cratis CLI provides terminal workflows for inspecting and diagnosing Chronicle. These statements do not assign either tool to a specific transport in the diagram above.

Architecture is not an operational guarantee

This page does not claim horizontal scale, throughput, guaranteed delivery, exactly-once behavior, client/provider parity, durability tier, compliance, or support for every topology.

## Continue

[Section titled “Continue”](#continue)

[ Chronicle overview](/chronicle/)

[Start Chronicle locally and understand what the runtime owns.](/chronicle/)

[ Workbench](/chronicle/workbench/)

[Inspect the running Chronicle instance from a local browser.](/chronicle/workbench/)

[ Cratis CLI](/cli/)

[Use terminal inspection and diagnostic workflows.](/cli/)

# Building a Chronicle Client

Chronicle speaks gRPC. In theory that means any language with a gRPC implementation can talk to it. In practice, hand-rolling a client means solving the same handful of hard problems every client has to solve before it can do anything useful: generating strongly-typed bindings from the wire contract, exchanging credentials for a token and keeping that token fresh, discovering and load-balancing across a cluster of servers, reconnecting when a connection drops, and rejecting a server whose contract has drifted instead of silently sending it garbage.

None of that is domain logic. It’s the same plumbing whether the client ends up written in Go, Python, Rust, or Java — and it’s exactly the plumbing Chronicle’s own team has already built more than once, for TypeScript, Elixir, and Kotlin. This section is that experience written down as a checklist, so a new client doesn’t have to rediscover it one gap at a time.

**Start with [The checklist](/chronicle/building-a-client/checklist/).** It’s the whole section distilled into one page — work through it while you build, and come back to it whenever you’re not sure what’s left. The rest of the pages exist to explain the *why* behind each item.

## The shape of every Chronicle client so far

[Section titled “The shape of every Chronicle client so far”](#the-shape-of-every-chronicle-client-so-far)

Every client Chronicle has shipped follows the same layering, whether or not that was the plan going in:

```
Kernel .proto files

(Source/Kernel/Protobuf)

Generated contracts package

(published, one per language)

Idiomatic client

(the thing developers import)

Convenience / hosting packages

(optional — ASP.NET Core, Spring Boot, …)
```

* **[The checklist](/chronicle/building-a-client/checklist/)** — every item below, pulled into one page to work through.
* **[Two ways to start](/chronicle/building-a-client/starting-points/)** — use the `.proto` files directly, or ask the Cratis team to generate and publish a contracts package for your language. Most clients so far took the second path.
* **[Layering an idiomatic client](/chronicle/building-a-client/layering-an-idiomatic-client/)** — why the generated contracts are deliberately not the client developers use, and how a raw client and optional convenience packages sit on top of them.
* **[Authentication and bearer tokens](/chronicle/building-a-client/authentication-and-bearer-tokens/)** — how a client turns connection-string credentials into a bearer token on every call, and keeps it fresh.
* **[Clustering and the connection lifecycle](/chronicle/building-a-client/clustering-and-connection-lifecycle/)** — what a client has to implement to be a good citizen of a multi-server Chronicle cluster.
* **[Connection string elements](/chronicle/building-a-client/connection-string-elements/)** — the object model a client SDK typically wraps around the connection string grammar.
* **[Documentation and snippets](/chronicle/building-a-client/documentation-and-snippets/)** — how a new client repo’s `Documentation/` folder plugs into the shared Chronicle docs site.

## Talk to us first

[Section titled “Talk to us first”](#talk-to-us-first)

Before generating anything yourself, get in touch with the Cratis team. Every contracts package Chronicle has shipped so far — TypeScript, Elixir, Kotlin, and Python — was generated from the kernel’s own `.proto` files and published to the right registry (npm, Hex, Maven Central, PyPI) from Chronicle’s own release pipeline, version-locked to the kernel release it matches. That pipeline already exists; turning it on for a new language is normally a matter of days, not the weeks it takes to build a `protoc` toolchain from scratch and get the packaging right. See [Two ways to start](/chronicle/building-a-client/starting-points/) for what that conversation looks like and what you get out of it.

Note

This section is written for whoever builds and maintains a **new** Chronicle client — Cratis team members and community contributors alike. If you’re building an *application on* Chronicle rather than a new client SDK, you want the [get started](/chronicle/get-started/) guide instead.

# Authentication and bearer tokens

Every call a Chronicle client makes to the Kernel over gRPC needs a bearer token attached to it. This page describes the exchange a new client has to implement to get one, keep it fresh, and attach it correctly — reverse-engineered from the .NET client’s reference implementation, since that’s where the behavior is defined today.

Note

This page is about how a **client authenticates to the Kernel**. Chronicle also has `BearerTokenAuthorization`, `BasicAuthorization`, and `OAuthAuthorization` types in its .NET client — those configure *outbound* authorization for **Webhooks** and **External Services** targets the Kernel calls out to. They’re unrelated to how a client authenticates itself, and naming a new client’s own types the same way as those would be a confusing coincidence, not a pattern to follow.

## The three authentication modes

[Section titled “The three authentication modes”](#the-three-authentication-modes)

Which mode a connection uses is decided entirely by what’s present in the connection string — there’s no separate flag:

| Mode               | Connection string carries                    | What happens                                                                                 |
| ------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Client credentials | `username:password@host` (or nothing at all) | Exchanged for a bearer token via OAuth’s `client_credentials` grant                          |
| API key            | `?apiKey=...` query parameter                | Sent as-is (no exchange)                                                                     |
| None               | `?auth=none` query parameter                 | No credentials presented at all — only works against a server with authentication turned off |

Supplying both client credentials and an API key in the same connection string is an error (`AmbiguousAuthenticationMode`); supplying neither and not asking for `auth=none` is also an error (`MissingAuthentication`) — except that an *empty* connection string is treated as client credentials rather than an error, because of the development default below. See [Connection string elements](/chronicle/building-a-client/connection-string-elements/) for the full grammar.

## Client credentials really means OAuth client-credentials

[Section titled “Client credentials really means OAuth client-credentials”](#client-credentials-really-means-oauth-client-credentials)

It’s easy to assume `username:password@host` is HTTP Basic auth. It isn’t. The username and password in the connection string map directly onto an OAuth `client_credentials` grant: username becomes `client_id`, password becomes `client_secret`, and the client exchanges them for an access token by calling the Kernel’s own token endpoint before making any other RPC:

```text
POST https://{host}:{port}/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={username}&client_secret={password}
```

The response is parsed for `access_token` and `expires_in` (a missing `expires_in` defaults to 3600 seconds). The client secret is never sent as a Basic-auth header, and it’s never sent on every call — only once, to get a token, which is what then goes on every call.

### Development defaults

[Section titled “Development defaults”](#development-defaults)

A connection string with no credentials at all still resolves to client-credentials mode — it substitutes two well-known development values rather than connecting anonymously:

```text
client_id     = chronicle-dev-client
client_secret = chronicle-dev-secret
```

`chronicle://localhost:35000` and `chronicle://chronicle-dev-client:chronicle-dev-secret@localhost:35000` are exactly equivalent. This is what makes local development work with no setup, and it’s also why those two values are not a secret worth protecting — they’re baked into every Chronicle client and meaningless outside a server explicitly configured to accept them.

## Attaching the token to a call

[Section titled “Attaching the token to a call”](#attaching-the-token-to-a-call)

Once a token exists, it goes on every outgoing gRPC call as a metadata header:

```text
authorization: Bearer {access_token}
```

A gRPC client interceptor is the natural place to do this — it needs to run for unary calls and every streaming variant (client-streaming, server-streaming, duplex), and it needs one more piece of behavior beyond just attaching the header: if a call comes back `Unauthenticated`, force a token refresh and retry the call exactly once before giving up. That single retry is what makes a token that expires mid-session invisible to the caller instead of surfacing as a hard failure.

## Keeping the token fresh

[Section titled “Keeping the token fresh”](#keeping-the-token-fresh)

A well-behaved client refreshes proactively rather than waiting to be rejected:

* Track when the token was issued and how long it’s valid for (`expires_in`).
* Treat it as needing renewal a margin *before* actual expiry — a 60-second margin is a reasonable default — so a call that starts just before expiry doesn’t race the clock.
* If a refresh attempt fails (the token endpoint is briefly unreachable, say), keep serving the still-technically-valid cached token rather than failing every call until the endpoint recovers. Throttle repeated failed-refresh attempts (a few seconds between retries) so a down token endpoint doesn’t turn into a tight retry loop on every call.
* Treat an *explicit* refresh request (triggered by the 401-retry above) differently from routine proactive renewal: it should bypass the failure throttle, since it’s evidence-driven rather than a guess that the token might be stale.

### Optional: caching a token to disk

[Section titled “Optional: caching a token to disk”](#optional-caching-a-token-to-disk)

Short-lived processes — a CLI invoked once per command, a script run from cron — pay the full token-exchange cost on every single invocation if the token only ever lives in memory. A client worth using from tooling like that benefits from an optional decorator that persists the token to a local file (client ID, token, and expiry — nothing else) and reuses it across process invocations until it’s genuinely close to expiring, deleting the cache file and fetching fresh on an explicit refresh. Treat a missing or corrupt cache file as “no token” and fetch normally rather than failing — a cache is an optimization, never a dependency.

## What a new client needs to implement

[Section titled “What a new client needs to implement”](#what-a-new-client-needs-to-implement)

* Determine the auth mode from the connection string (client credentials / API key / none), with the same “empty means development defaults” and “both present is an error” rules.
* For client credentials, perform the OAuth `client_credentials` exchange against `/connect/token` on the configured host.
* Attach `authorization: Bearer {token}` to every call, across every streaming shape your gRPC library exposes.
* Cache the token, refresh it proactively ahead of expiry, and retry once on a 401.
* Never log a raw connection string or a raw token — see [Connection string elements](/chronicle/building-a-client/connection-string-elements/#never-log-the-unredacted-form) for why and how the .NET client avoids it.

Next: [Clustering and the connection lifecycle](/chronicle/building-a-client/clustering-and-connection-lifecycle/) covers what happens before and after that first authenticated call — picking a server and staying connected to it.

# The checklist

Everything below is pulled from the detailed pages in this section — this page exists so you can work through it top to bottom while you build, and come back to it when you’re not sure what’s left. Each item links to the page that explains the *why*.

## Before you write any code

[Section titled “Before you write any code”](#before-you-write-any-code)

* [ ] Talk to the Cratis team about generating and publishing a contracts package for your language, rather than hand-rolling a `protoc` toolchain yourself. See [Two ways to start](/chronicle/building-a-client/starting-points/).

## Contracts (generated layer)

[Section titled “Contracts (generated layer)”](#contracts-generated-layer)

* [ ] Treat the generated contracts package as read-only — never hand-edit it, never hand-maintain a fork of it. It’s regenerated by Chronicle’s own pipeline on every kernel release.
* [ ] Depend on the *published* contracts package as an ordinary dependency in your idiomatic client. Don’t vendor it, and don’t build your idiomatic client in the same package. See [Layering an idiomatic client](/chronicle/building-a-client/layering-an-idiomatic-client/).

## The idiomatic client

[Section titled “The idiomatic client”](#the-idiomatic-client)

* [ ] Build it as a separate, hand-maintained package with its own release cadence — not inside the generated contracts package, and not by hiding hand-written code inside generated files.
* [ ] Name and export it so nobody consuming it ever needs to import the contracts package directly.
* [ ] Make it a complete, general-purpose client on its own: usable from a console tool, a script, or a background worker with no hosting framework required. A convenience/hosting package (an ASP.NET-Core- or Spring-Boot-style integration) is optional and comes later, once the idiomatic client is stable — see [Layering an idiomatic client](/chronicle/building-a-client/layering-an-idiomatic-client/#convenience-packages-sit-above-that-and-are-optional).

## Authentication

[Section titled “Authentication”](#authentication)

* [ ] Parse all three authentication modes from the connection string: client credentials, API key, and none (`auth=none`).
* [ ] For client credentials, implement the OAuth `client_credentials` exchange against `/connect/token` — the username and password in the connection string map to `client_id` and `client_secret`, not to HTTP Basic auth.
* [ ] Fall back to the `chronicle-dev-client` / `chronicle-dev-secret` development defaults when the connection string carries no credentials at all.
* [ ] Attach `authorization: Bearer {token}` to every outgoing call, across every streaming shape your gRPC library exposes.
* [ ] Cache the token, refresh it proactively ahead of expiry, and retry exactly once on an `Unauthenticated` response.
* [ ] Never log a raw connection string or a raw token — always log through a redacted rendering. See [Authentication and bearer tokens](/chronicle/building-a-client/authentication-and-bearer-tokens/).

## Clustering and the connection lifecycle

[Section titled “Clustering and the connection lifecycle”](#clustering-and-the-connection-lifecycle)

* [ ] Support both connection-string forms: an explicit, comma-separated host list and `chronicle+srv://` DNS-based discovery.
* [ ] Re-resolve the server list on *every* connect and reconnect, not just once at startup.
* [ ] Ship at least `least-connections` (matching the real probe/reserve protocol against `/connections/count` and `/connections/reserve`) and `round-robin` (with a random start offset per instance).
* [ ] Embed your contracts package’s compiled descriptor set, and run the wire-compatibility check before treating a new connection as usable. Fail hard on a real incompatibility — don’t degrade silently.
* [ ] Run a keep-alive watchdog with capped exponential backoff, and reuse the same connect path for reconnects that the initial connect uses. See [Clustering and the connection lifecycle](/chronicle/building-a-client/clustering-and-connection-lifecycle/).

## The connection string object model

[Section titled “The connection string object model”](#the-connection-string-object-model)

* [ ] Parse the connection string into a typed value once. Don’t re-parse or grep the raw string wherever a setting is needed.
* [ ] Compute the authentication mode from the parsed fields rather than storing it separately, so the two can’t drift apart.
* [ ] Offer a fluent builder that validates as it assembles (reject “credentials and API key both present” at construction time, not at first connect).
* [ ] Offer a redacted rendering of the connection string, and use it everywhere the client itself logs. See [Connection string elements](/chronicle/building-a-client/connection-string-elements/).

## Publishing

[Section titled “Publishing”](#publishing)

* [ ] Publish the contracts package from Chronicle’s own release pipeline, version-locked to the kernel release it was generated from.
* [ ] Publish the idiomatic client as its own artifact, on its own release cadence, once it’s stable enough to ship.
* [ ] **The moment you add a second publishable module — a testing package, a convenience/hosting package — add it to your CI’s actual publish job in the same change that adds its build config.** This is not a hypothetical: `io.cratis:chronicle-testing` and `io.cratis:chronicle-spring-boot-starter` both had correct Maven coordinates and a working `mavenPublishing` block for weeks before anyone noticed the release workflow only ever ran `:Source:publishAndReleaseToMavenCentral`. Valid build config for a module that CI never tells to publish is indistinguishable, from the outside, from a module that doesn’t exist.

## Documentation

[Section titled “Documentation”](#documentation)

* [ ] Create a `Documentation/` folder with a `toc.yml`, an `index.md`, and a `client-snippets/**` tree from day one.
* [ ] Add a snippet validator and a CI workflow that runs it before your first snippet ships.
* [ ] Don’t write your own “Events” or “Projections” pages — those concepts live in the shared Chronicle docs. Your repo only owns pages that are genuinely different per client: installation, connection setup, framework integration, troubleshooting.
* [ ] If your artifact serves two languages the way Kotlin serves Java, plan for two parallel snippet trees (`client-snippets/`, `client-snippets-<other-language>/`) from the start. See [Documentation and snippets](/chronicle/building-a-client/documentation-and-snippets/).

Next: [Two ways to start](/chronicle/building-a-client/starting-points/) walks through the first decision in more depth.

# Clustering and the connection lifecycle

[Connection Strings → Server support](/chronicle/connection-strings/server/) is the canonical reference for the connection string format, the load-balancer strategies, and DNS SRV lookup, written for someone configuring an existing client. This page covers the same ground from the other side: what a **new client** actually has to implement to participate correctly in a multi-server Chronicle cluster, and the parts of the picture that page doesn’t cover — the wire-compatibility handshake and the reconnect loop.

## Discovering the server list

[Section titled “Discovering the server list”](#discovering-the-server-list)

A connection string names either an explicit, comma-separated list of hosts (`chronicle://a,b,c`) or, with the `chronicle+srv://` scheme, a single DNS name to resolve via SRV records — the same mechanism `mongodb+srv://` uses. For SRV, the client queries `_chronicle._tcp.<host>` and treats the returned targets, ordered by SRV priority then weight, as the candidate list. **This resolution happens fresh on every connect and every reconnect**, not once at startup — a server added to or removed from DNS is picked up automatically the next time the client needs to pick one, with no client-side configuration change and no restart.

## Picking a server: load balancer strategies

[Section titled “Picking a server: load balancer strategies”](#picking-a-server-load-balancer-strategies)

A load balancer strategy is a single operation: given the current candidate list, return the one server to connect to next. It’s invoked on every connect, including every reconnect after a dropped session — a client doesn’t fail over to a fixed backup, it re-runs the same selection.

Implement at least these three; `least-connections` is the sensible default:

* **`least-connections`** — the real default, and the most involved. Every Chronicle server exposes two *anonymous* endpoints (anonymous because a client needs to ask before it has authenticated): `GET /connections/count` reports how many clients are connected to that specific server, and `POST /connections/reserve` reserves a slot ahead of actually connecting. Probe every candidate in parallel, pick the lowest count (breaking ties randomly, not by list order), then reserve a slot on the winner before starting the real connect handshake. A server that doesn’t answer within a short timeout (2 seconds is what the .NET client uses) is treated as maximally loaded rather than failing selection outright, so a restarting or briefly unreachable server just gets routed around. Add a small random jitter (up to 250ms) before every probe, not only the first, so that a fleet of clients starting or reconnecting together doesn’t send synchronized probe bursts. The reservation itself expires on its own after a short window (30 seconds) if it never converts into a real connection, so an abandoned attempt doesn’t permanently inflate a server’s reported count.
* **`round-robin`** — cycle through the candidate list in order, but start each client instance at a random offset. Without the random start, a fleet of identical client instances all begin at index zero and stay in lockstep on the same server.
* **`random`** — pick uniformly at random on every connect. The simplest strategy, and a reasonable first one to ship while `least-connections` is still being built.

The full mechanics of the probe/reserve dance — including why the reservation exists at all — are written out in detail in [Connection Strings → Server support: How least-connections picks a server](/chronicle/connection-strings/server/#how-least-connections-picks-a-server). A new client’s `least-connections` implementation should match that behavior, not just the name.

## The wire-compatibility handshake

[Section titled “The wire-compatibility handshake”](#the-wire-compatibility-handshake)

Before a connection is usable, the client and server need to agree they’re speaking the same contract — not just the same protocol version, but the same set of services, messages, and fields. Chronicle does this with an actual structural diff, not a version-number check:

Every contracts package — .NET’s included — carries a compiled `FileDescriptorSet` (`chronicle.desc` in the non-.NET packages) generated from the exact same `.proto` files the server was built from. On connect, before treating the connection as usable, the client sends its descriptor set to the server, which parses it and compares it structurally against its own: removed services or methods, changed method signatures or streaming shape, removed messages, and fields or enum values that were removed, retyped, relabeled, or renamed (fields are matched by their protobuf field *number*, not name, so a rename is detected even though the wire format itself wouldn’t break). **Pure additions are never reported as incompatible** — a client is only broken by things it can no longer find, not by things the server has grown since the client shipped.

If the server reports any incompatibility, the client should raise a hard error and refuse to proceed — better a clear “your client’s contract doesn’t match this server” failure at connect time than a stream of confusing per-call errors later. Against an older server that doesn’t support the compatibility check at all, fall back to fetching its descriptor set and comparing on the client side instead — don’t skip the check entirely just because the newer RPC isn’t there.

This is precisely why the contracts package matters so much: your client’s copy of `chronicle.desc` *is* the thing being checked. A hand-generated or stale set of bindings doesn’t just risk subtly wrong types — it risks a hard rejection at connect time, which is the system working as intended.

## Staying connected

[Section titled “Staying connected”](#staying-connected)

A gRPC channel doesn’t tell you when the server it’s pointed at goes away — TCP can stay technically open on a server that’s stopped responding. Chronicle handles this with a server-pushed keep-alive stream and a client-side watchdog:

* The server pushes a keep-alive on an open stream at a steady interval. The client just needs to notice one arriving.
* The watchdog checks, on a short fixed interval (roughly once a second is enough), whether a keep-alive has arrived recently (a threshold of a few seconds — five is a reasonable default). If not, treat the session as dropped immediately rather than waiting for an RPC to fail.
* On a dropped session, reconnect with **exponential backoff, capped** — doubling the wait each attempt starting from around a second, up to a ceiling around 30 seconds — rather than hammering a server that’s still coming back up. A cancellation should stop the loop outright rather than be treated as a failed attempt to back off from.
* The reconnect path is the *same* connect path described above: re-resolve addresses (DNS may have changed), re-run load-balancer selection (the server that dropped isn’t guaranteed to be the one to reconnect to), and re-run the compatibility check.

## What a new client needs to implement

[Section titled “What a new client needs to implement”](#what-a-new-client-needs-to-implement)

* Parse both connection-string forms (explicit host list, `+srv`) and re-resolve on every connect.
* Ship at least `least-connections` (matching the probe/reserve protocol) and `round-robin`.
* Embed the compiled descriptor set from your contracts package and run the compatibility check before treating a connection as usable; fail hard, don’t degrade silently, on a real mismatch.
* Run a keep-alive watchdog with capped exponential backoff, reusing the same connect path for reconnects that the initial connect uses.

Next: [Connection string elements](/chronicle/building-a-client/connection-string-elements/) covers the object model most clients wrap around the string itself.

# Connection string elements

[Connection Strings → Server support](/chronicle/connection-strings/server/) is the grammar reference — the scheme, every query parameter, and what each one means. Don’t re-derive that grammar from scratch or from this page; treat it as the spec. This page is narrower: the object model a client SDK typically wraps around that grammar, using the .NET client’s `ChronicleConnectionString` and `ChronicleConnectionStringBuilder` as the reference shape, since that’s the most complete implementation that exists today.

## Parse into a value, don’t pass strings around

[Section titled “Parse into a value, don’t pass strings around”](#parse-into-a-value-dont-pass-strings-around)

Every client so far parses the connection string once, into a typed value, rather than re-parsing or grep-ing the raw string wherever a setting is needed. The .NET client’s parsed shape exposes:

| Property                                  | Comes from                                                            |
| ----------------------------------------- | --------------------------------------------------------------------- |
| `ServerAddress` / `ServerAddresses`       | the host list (single value / full list)                              |
| `IsSrv`                                   | whether the `+srv` scheme was used                                    |
| `LoadBalancer`                            | the `loadBalancer` parameter, defaulting to `least-connections`       |
| `SrvNameServer`                           | the `srvNameServer` parameter, for `+srv` lookups                     |
| `Username` / `Password`                   | the credentials in the authority section                              |
| `AuthenticationMode`                      | **computed**, not stored — derived from which credentials are present |
| `ApiKey`                                  | the `apiKey` parameter                                                |
| `SkipTlsValidation`                       | the `skipTlsValidation` parameter                                     |
| `CertificatePath` / `CertificatePassword` | client certificate options                                            |

`AuthenticationMode` being computed rather than stored is worth copying deliberately: it means there’s exactly one place that can get the “both credentials and API key present” or “neither present” cases wrong, and it can never drift out of sync with the fields it’s derived from.

## Offer a builder, not string concatenation

[Section titled “Offer a builder, not string concatenation”](#offer-a-builder-not-string-concatenation)

Constructing a connection string by hand — string-formatting a host, a port, and a pile of query parameters — is exactly the kind of thing that quietly produces an invalid or ambiguous string (wrong separator, double `?`, an unescaped credential). A fluent builder that knows the grammar is worth offering alongside the parser. The shape worth matching — the .NET client’s own builder, used to construct a connection string from discrete settings:

* C#

```csharp
  using Cratis.Chronicle.Connections;

public static class ConnectionStringsFluentBuilder
  {
      public static ChronicleClient Create()
      {
          var connectionString = new ChronicleConnectionStringBuilder()
              .WithHost("server.example.com")
              .WithPort(35000)
              .WithCredentials("clientId", "clientSecret")
              .Build();

var options = ChronicleOptions.FromConnectionString(connectionString);
          return new ChronicleClient(options);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.ChronicleOptions
  import io.cratis.chronicle.connection.ChronicleConnectionString
  import io.cratis.chronicle.connection.ChronicleServerAddress

// Kotlin has no separate connection string builder type — a data class with named constructor
  // arguments already gives every property a name, so ChronicleConnectionString is constructed
  // directly rather than through a fluent builder.
  fun createClientWithExplicitConnectionString(): ChronicleClient {
      val connectionString = ChronicleConnectionString(
          addresses = listOf(ChronicleServerAddress("server.example.com", 35000)),
          username = "clientId",
          password = "clientSecret"
      )
      return ChronicleClient(ChronicleOptions(connectionString))
  }
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.connection.ChronicleConnectionString;
  import io.cratis.chronicle.connection.ChronicleServerAddress;
  import io.cratis.chronicle.java.BlockingChronicleClient;

import java.util.List;

// Java has no separate connection string builder type either — ChronicleConnectionString is a
  // Kotlin data class, so its full constructor (with every property named) is called directly.
  class ConnectionStringsFluentBuilder {
      BlockingChronicleClient create() {
          ChronicleConnectionString connectionString = new ChronicleConnectionString(
              List.of(new ChronicleServerAddress("server.example.com", 35000)),
              "clientId",
              "clientSecret",
              false,
              true,
              null,
              io.cratis.chronicle.connection.LoadBalancer.LEAST_CONNECTIONS,
              null,
              false);

return BlockingChronicleClient.connect(new ChronicleOptions(connectionString));
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

with equivalents for `WithServerAddresses(...)` (multiple hosts), `WithDevelopmentCredentials()`, `WithApiKey(...)`, `WithoutAuthentication()` (`auth=none`), `WithTlsValidationSkipped()`, and `WithCertificate(path, password)`. `Build()` should validate as it assembles — the same “credentials and API key together is an error” rule the parser enforces should be enforced here too, at construction time rather than at first-connect time.

## Never log the unredacted form

[Section titled “Never log the unredacted form”](#never-log-the-unredacted-form)

A connection string carries the client secret, and possibly an API key or a certificate password — in full. `ToString()` (or whatever renders it back to a string) should render everything, because something in the client genuinely needs the real value to connect with. But that real value should never end up in a log line or an error message as-is.

Offer a second rendering — the .NET client calls it `Redacted` — that keeps everything a log entry needs to be useful (scheme, host, port, non-sensitive options) and replaces every credential with a fixed placeholder. Use that form, specifically, everywhere the client itself logs the connection string — connecting, reconnecting, reporting a connection failure. This is not a theoretical concern: the .NET client’s own log messages used to write the unredacted string on every connect, and the fix was exactly to route those call sites through `Redacted` instead. A new client should get this right from its first log statement rather than patch it in later.

## Building blocks worth keeping separate

[Section titled “Building blocks worth keeping separate”](#building-blocks-worth-keeping-separate)

Two things are easy to conflate but should stay as distinct concepts in the object model:

* **The load-balancer strategy name** (`loadBalancer=round-robin`) selects *which* built-in strategy runs. It should also be overridable programmatically with a custom strategy implementation for callers who need one the built-ins don’t cover — don’t make the string parameter the only way in.
* **TLS validation** (`skipTlsValidation`) is a connection-string concern, but certificate configuration for a client presenting its *own* certificate (`certificatePath`, `certificatePassword`) is a related but separate concern from validating the *server’s* certificate. Keep them as separate settings even though they both live under “TLS” in the query string.

See the full parameter table in [Connection Strings → Server support](/chronicle/connection-strings/server/#query-parameters) for every name, type, and example.

Next: [Documentation and snippets](/chronicle/building-a-client/documentation-and-snippets/) covers the last thing a new client needs before it’s ready for other people to use.

# Documentation and snippets

Chronicle’s docs are published as one site, aggregated at build time from a `Documentation/` folder in each product repo — including every client repo. A new client needs to shape its `Documentation/` folder the same way from day one, because the shared Chronicle pages actively rely on every participating client having one.

This page is an orientation, not the full mechanics — those are already written down in [Contributing to Clients](/chronicle/contributing/clients/#shared-documentation-snippets). Read that page for the complete rules on snippet IDs, CI validation, and adding a client to the shared tab system. What follows is the shape to start from.

## The standard shape

[Section titled “The standard shape”](#the-standard-shape)

```text
Documentation/
├── toc.yml
├── index.md                    landing page for this client's docs
├── getting-started.md
├── client-snippets/**          source-only — never becomes a public page
└── <client-specific-pages>     install, connection setup, framework integration, troubleshooting
```

`Documentation/client-snippets/**` is the important one to get right early: it’s not a docs page at all, it’s the source for the language-specific code shown in the *shared* Chronicle docs. A shared page says:

```mdx
<ChronicleClientTabs snippet="events/appending/example" />
```

and the site looks for a matching snippet ID under every registered client’s snippet root — your client shows up in that tab group the moment `Documentation/client-snippets/events/appending/example.md` exists, with a single fenced code block in your language. No other wiring makes a client opt-in; the file’s presence is the whole mechanism.

## Why concepts live in the shared docs, not in your repo

[Section titled “Why concepts live in the shared docs, not in your repo”](#why-concepts-live-in-the-shared-docs-not-in-your-repo)

Resist the pull to write your own “Events” or “Projections” page inside your client’s docs. Those concepts are the same across every client — what differs is only the code that expresses them. A client-specific page is for things that are genuinely different per client: installation, how a connection gets configured in your language’s idioms, framework/hosting integration, decorators or annotations, and troubleshooting. Everything else belongs in the shared Chronicle pages, with your code shown through a snippet.

If your client doesn’t support a workflow yet, that fact belongs *in the snippet*, not as prose on the shared page — an explicit “this client doesn’t support this yet” snippet keeps the claim next to the code, where whoever adds the capability is already looking, instead of rotting silently in a shared page nobody remembers to update.

## Keep a validator in CI

[Section titled “Keep a validator in CI”](#keep-a-validator-in-ci)

Every existing client repo runs a snippet validator (`Documentation/validate-client-snippets.py` in today’s clients) that compiles every snippet against the real client source, wired into a CI workflow that triggers on changes to either `Documentation/client-snippets/**` or `Source/**`. This is what stops a client API change from silently leaving the shared docs’ code examples broken — without it, a snippet is just a string nobody checks. Build the equivalent for your language before your first snippet ships, not after the first drift is reported.

## Two parallel trees, if your artifact serves two languages

[Section titled “Two parallel trees, if your artifact serves two languages”](#two-parallel-trees-if-your-artifact-serves-two-languages)

Chronicle.Kotlin serves both Kotlin and Java from a single published artifact, and its `Documentation/` folder reflects that directly: `client-snippets/` for Kotlin and a fully parallel `client-snippets-java/` for Java, with every subfolder mirrored between the two. If your client does the same — one package, two idiomatic surfaces — plan for two snippet trees from the start rather than retrofitting a second one later.

## Getting a new client wired into the published site

[Section titled “Getting a new client wired into the published site”](#getting-a-new-client-wired-into-the-published-site)

Once your `Documentation/` folder exists, getting it into the published site alongside the other four clients is a short, concrete checklist — see [Contributing to Clients → Add another Chronicle client](/chronicle/contributing/clients/#add-another-chronicle-client) for the exact steps (registering the repo, adding it to the client-docs config, wiring the sync workflow). That’s also the point to talk to the Cratis team again if you haven’t already — getting a new client’s docs live on the site is a one-time setup they can do quickly.

# Layering an idiomatic client

A generated contracts package is not something you’d want to hand a developer and call it a day. It’s a faithful mechanical translation of the wire format — service interfaces, message types, `int64` fields as `bigint`, `Guid` as whatever protobuf-net’s BCL extensions say a `Guid` is. It has no decorators, no fluent builder, no idea what a “read model” or a “reactor” is. That’s by design: it’s generated on every kernel release, so nothing generated can carry hand-written idiomatic API surface without it being overwritten the next time.

The idiomatic client is a second, separate thing built *on top of* the contracts package, hand written and hand maintained, with its own release cadence. This split — raw contracts underneath, idiomatic API on top — is the one structural decision every Chronicle client has made so far, independent of language.

```
Hand-maintained, its own release cadence

Generated — tracks the kernel's release cadence

Contracts package

@cratis/chronicle.contracts · io.cratis:chronicle-contracts · cratis_chronicle_contracts

Idiomatic client

@cratis/chronicle · io.cratis:chronicle · cratis_chronicle

Optional: in-process testing module

io.cratis:chronicle-testing

Optional: convenience / hosting package

Cratis.Chronicle.AspNetCore · io.cratis:chronicle-spring-boot-starter
```

## Why the split exists

[Section titled “Why the split exists”](#why-the-split-exists)

* **The generated layer can’t carry taste.** Attribute-based artifact discovery, fluent builders, a `ChronicleClient` → `EventStore` → `EventLog` API shape — none of that survives regeneration. It has to live somewhere the generator never touches.
* **The two layers version independently.** The contracts package tracks the kernel’s release number; the idiomatic client tracks its own API stability. Chronicle.Kotlin, for example, is presently at `2.1.1` while the `io.cratis:chronicle-contracts` package it depends on tracks the kernel’s `16.x` version — two numbers, two meanings, on purpose.
* **The value contract, not the whole API, is what has to agree across languages.** Only what crosses the wire — how a `Guid`, a date, a duration, a concept, a derived type is serialized — has to be identical everywhere. Everything above that (dependency injection, task scheduling, how a language discovers its own artifacts) is free to be idiomatic. See [The Value Contract](/chronicle/contributing/clients/value-contract/) for the exact, short list of things that must agree, and [Client Types](/chronicle/contributing/clients/client-types/) for how the .NET client’s own project dependency graph reflects this layering internally.

## How C# does it differently — and why that’s not the model to copy

[Section titled “How C# does it differently — and why that’s not the model to copy”](#how-c-does-it-differently--and-why-thats-not-the-model-to-copy)

C#‘s idiomatic client, `Cratis.Chronicle`, does not depend on a separately published contracts NuGet package the way the other three languages do. Instead, `Contracts.csproj` is referenced directly and packaged as a **runtime-only** dependency: it ships inside the `Cratis.Chronicle` NuGet package under `runtimes/`, invisible to IntelliSense and uncompilable against directly, while the SDK’s own types occupy `lib/`. A build-time step (`GrpcClients`, using `System.Reflection.Emit`) even pre-generates the gRPC client implementations that would otherwise need a compile-time reference to the internalized contracts types. The mechanics are in [Internalization](/chronicle/contributing/clients/internalization/).

That’s possible because C# is Chronicle’s own implementation language and NuGet’s `ref`/`lib` split gives it a tool the other ecosystems don’t have as cleanly. It is not a pattern to reach for in a new client. The other three languages hide the seam a simpler way: publish the contracts package on its own, and let the idiomatic client’s package name and its exports be the only thing a developer ever consumes directly. Nobody imports `@cratis/chronicle.contracts` in application code; they import `@cratis/chronicle`, which happens to depend on it.

## The raw client is usable on its own

[Section titled “The raw client is usable on its own”](#the-raw-client-is-usable-on-its-own)

The idiomatic client — on its own, with no convenience package — is a complete, general-purpose client. It’s what you reach for in a console tool, a script, a background worker, or a test project. Every one of the four existing clients treats this as the default entry point — create the client, get an event store, append an event:

* C#

Program.cs

```csharp
  using var client = new ChronicleClient();
  var eventStore = await client.GetEventStore("ChronicleConsole");

await eventStore.EventLog.Append("some-event-source", new TestEvent("Hello world!"));
  ```

* Kotlin

Main.kt

```kotlin
  val client = ChronicleClient(ChronicleOptions.development())
  val eventStore = client.getEventStore("ChronicleConsole")

eventStore.eventLog.append("some-event-source", TestEvent("Hello world!"))
  ```

* Java

Main.java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.java.BlockingChronicleClient;

class Main {
      void run() {
          var client = BlockingChronicleClient.connect(ChronicleOptions.development());
          var eventStore = client.getEventStore("ChronicleConsole");

eventStore.getEventLog().append("some-event-source", new TestEvent("Hello world!"));
      }
  }
  ```

* Elixir

application.ex

```elixir
  children = [
    {Chronicle.Client,
     connection_string: "chronicle://localhost:35000",
     event_store: "chronicle-console",
     otp_app: :my_app}
  ]

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

Append the event

```elixir
  :ok =
    Chronicle.append("some-event-source", %MyApp.Events.TestEvent{
      message: "Hello world!"
    })
  ```

* TypeScript

index.ts

```typescript
  import 'reflect-metadata';
  import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';

const client = new ChronicleClient(ChronicleOptions.development());
  const eventStore = await client.getEventStore('ChronicleConsole');

await eventStore.eventLog.append('some-event-source', new TestEvent('Hello world!'));
  ```

## Convenience packages sit above that, and are optional

[Section titled “Convenience packages sit above that, and are optional”](#convenience-packages-sit-above-that-and-are-optional)

Once the raw client is stable, it’s common — not mandatory — to build a thin package on top that wires the client into a specific hosting environment: registering it in a DI container, resolving configuration from the host’s standard config system, binding request-scoped concerns like tenant or identity to the current HTTP request. C# has done this since early on with `Cratis.Chronicle.AspNetCore`. Kotlin followed the same shape much later, once its idiomatic client’s artifact-discovery machinery existed to build on: `io.cratis:chronicle-spring-boot-starter` provides Spring auto-configuration, `ChronicleProperties`, and per-request namespace resolution (fixed, HTTP-header, subdomain, or authentication-claim based) — the direct JVM analogue of the ASP.NET Core package.

TypeScript and Elixir don’t have an equivalent yet (no Express/Fastify/NestJS package for TypeScript, no Phoenix package for Elixir). That’s a genuine gap in those ecosystems today, not a sign the pattern doesn’t apply — build a convenience package when your idiomatic client is stable enough to build one on top of, and there’s an obvious dominant hosting framework in your language to target.

A fourth, optional layer is worth knowing about too: an **in-process testing module** (`io.cratis:chronicle-testing` in Kotlin, `Cratis.Chronicle.Testing`/`Cratis.Chronicle.XUnit` in .NET) that depends on the idiomatic client and lets application code exercise slices without a live kernel. It’s the same “build it once the layer beneath is stable” story as the convenience package, just aimed at test authors instead of host authors.

Next: [Authentication and bearer tokens](/chronicle/building-a-client/authentication-and-bearer-tokens/) covers the first thing the idiomatic client actually has to do once it opens a connection.

# Two ways to start

Before writing a line of idiomatic code, a new client needs typed bindings for Chronicle’s gRPC services. There are two ways to get them, and they’re not equally good uses of your time.

## Option A: generate from the `.proto` files yourself

[Section titled “Option A: generate from the .proto files yourself”](#option-a-generate-from-the-proto-files-yourself)

Chronicle’s gRPC service and message definitions are code-first: they’re written in C# using [protobuf-net.Grpc](https://github.com/protobuf-net/protobuf-net.Grpc) attributes (`[Service]`, `[Operation]`), and standard `.proto` files are extracted from the compiled contracts assembly by a tool called `ProtoGenerator`. Those extracted files live in `Source/Kernel/Protobuf/*.proto` in the Chronicle repository and are regenerated on every kernel build — see [Protobuf Extraction](/chronicle/contributing/clients/protobuf-extraction/) for exactly how that works.

Because they’re standard proto3, any language with a gRPC/protobuf toolchain can generate client bindings from them directly:

```bash
protoc \
  -I Source/Kernel/Protobuf \
  --go_out=. \
  --go-grpc_out=. \
  Source/Kernel/Protobuf/*.proto
```

This is the fully self-service path. Nobody has to grant you anything — the files are in the repository. It’s also the slower path: you own getting the `protoc` invocation right for your language’s plugin ecosystem, you own re-running it every time the kernel’s contract changes, and you own publishing and versioning the result yourself.

## Option B: ask the Cratis team for a generated package (recommended)

[Section titled “Option B: ask the Cratis team for a generated package (recommended)”](#option-b-ask-the-cratis-team-for-a-generated-package-recommended)

The alternative is to ask the Cratis team to turn on the same pipeline that already produces TypeScript, Elixir, and Kotlin’s contracts packages, for your language. Concretely, that pipeline:

1. Extracts `.proto` files from the kernel’s contracts assembly (the step Option A does by hand).
2. Runs your language’s code generator against them.
3. Publishes the result to the registry your ecosystem actually uses — npm, Hex, Maven Central, NuGet, wherever idiomatic packages for that language live.
4. Version-locks the published package to the kernel release it was generated from, and gates the whole release on a wire-compatibility check, so a contracts package can never ship out of step with the server it talks to.

This is precisely how it happened for every contracts package that exists today:

| Language    | Contracts package               | Registry      |
| ----------- | ------------------------------- | ------------- |
| TypeScript  | `@cratis/chronicle.contracts`   | npm           |
| Kotlin/Java | `io.cratis:chronicle-contracts` | Maven Central |
| Elixir      | `cratis_chronicle_contracts`    | Hex           |
| Python      | `cratis-chronicle-contracts`    | PyPI          |

Python is the newest addition, and it’s worth noticing what stage it’s at: the contracts package exists and publishes on its own, but there’s no idiomatic `Chronicle.Python` repo built on top of it yet. That’s expected — [layering an idiomatic client](/chronicle/building-a-client/layering-an-idiomatic-client/) on top of the contracts package is a separate, later step, not something that has to land in the same change as the contracts package itself.

None of these client repos generate or own their own contracts — the packages are built and published from parallel jobs in Chronicle’s own `publish.yml`, all consuming the same `.proto` artifact, all gated behind the same `wire-compatibility` check. It happens fast, too: Elixir’s idiomatic client already depended on a published, versioned contracts package (`{:cratis_chronicle_contracts, ">= 0.1.0"}`) in its very first commit.

### Why this is worth asking for

[Section titled “Why this is worth asking for”](#why-this-is-worth-asking-for)

* **It’s fast.** The generator, the packaging conventions, and the publish pipeline already exist and already work for three ecosystems. Adding a fourth is mostly configuration, not invention.
* **It stays correct without your attention.** The package versions in lockstep with the kernel and is protected by the wire-compatibility gate — you’re not responsible for noticing that the kernel added a field or renamed a service.
* **It’s published where your ecosystem expects it.** A hand-generated set of files sitting in a `vendor/` folder is not something other people in your language’s community can `npm install` or `mix deps.get`. A registry package is.
* **It’s the internal team’s day-to-day workflow too.** Asking isn’t a special-case request that routes around some other, more official process — it *is* the process the Cratis team already uses for every language it supports.

Reach out to the Cratis team to start that conversation. Once the contracts package exists and is publishing on its own release cadence, move on to [layering an idiomatic client on top of it](/chronicle/building-a-client/layering-an-idiomatic-client/).

# Captures

Captures let you describe Change Data Capture (CDC) pipelines that turn external data changes into Chronicle events.

## Overview

[Section titled “Overview”](#overview)

A capture definition describes:

* **Source**: where data comes from (`api`, `webhook`, `message`)
* **Identity key**: the property used to detect changes per entity
* **Mapping**: optional transformations before append logic
* **Append rules**: which event to append and when to append it
* **Scopes**: root, nested objects, and child collections

Chronicle supports three authoring approaches. Only the first is language-neutral — the other two are .NET client features, documented alongside the rest of the .NET client:

* **Capture Declaration Language (CDL)** for text-based definitions
* **Declarative API** (.NET) for fluent definitions in code
* **Model-bound API** (.NET) for attribute-based definitions

## Topics

[Section titled “Topics”](#topics)

| Topic                                                                             | Description                                              |
| --------------------------------------------------------------------------------- | -------------------------------------------------------- |
| [Capture Declaration Language](/chronicle/captures/capture-declaration-language/) | CDL syntax, semantics, and formal language specification |
| [Declarative Captures](/chronicle/clients/dotnet/captures/declarative/)           | .NET client fluent API (`ICapturer` + `ICaptureBuilder`) |
| [Model-Bound Captures](/chronicle/clients/dotnet/captures/model-bound/)           | .NET client attribute-based capture declarations         |

# Capture Declaration Language

The Capture Declaration Language (CDL) is an indentation-based DSL for defining captures that transform external data changes into Chronicle events.

## Overview

[Section titled “Overview”](#overview)

CDL definitions compile to `CaptureDefinition` and support:

* Source declarations (`api`, `webhook`, `message`)
* Key declaration for identity and diffing
* Optional map operations (`translate`, `split`, field rename, template assignment)
* Event append rules with `when` conditions
* Nested object scopes
* Child collection scopes

## Example

[Section titled “Example”](#example)

```cdl
capture InvoiceCapture
  source api
    api InvoicingApi
    route /invoices
    poll 10m
  key id
  map
    status = status translate
      "utkast" => draft
      "betalt" => paid
  append InvoiceStatusChanged
    when status
    status = $.status
    changedAt = $context.occurred
  nested billingAddress
    append InvoiceBillingAddressChanged
      when street or city
      street = $.billingAddress.street
  children lineItems identified by lineNumber
    append InvoiceLineItemAdded
      when added
      lineNumber = $.lineNumber
    append InvoiceLineItemRemoved
      when removed
      lineNumber = $.lineNumber
```

## Language elements

[Section titled “Language elements”](#language-elements)

### Header

[Section titled “Header”](#header)

* `capture <Name>` defines one capture.

### Source block

[Section titled “Source block”](#source-block)

```cdl
source api|webhook|message
  ...
```

Source properties:

* API: `api`, `route`, `poll`
* Webhook: `path`
* Message: `topic`

For API sources, `api` identifies a configured **[External Service](/chronicle/external-services/)** by name. The External Service holds the base URL and the authentication for the connection. `route` is optional and is appended to that base URL; if omitted, the base URL is used as-is.

Note

Authentication is **not** part of the CDL. For API sources it is configured on the referenced External Service; for webhook sources it is configured in code on the source builder. Either way, secrets and tokens never live in capture text. See [Configuring authentication](#configuring-authentication) below.

### Configuring authentication

[Section titled “Configuring authentication”](#configuring-authentication)

**API sources** connect through a configured [External Service](/chronicle/external-services/). Configure the base URL and authentication once on the External Service; the capture simply references it by name — see the [Declarative Captures](/chronicle/clients/dotnet/captures/declarative/) example for what that reference looks like in the .NET client’s builder API.

**Webhook sources** are inbound and configure their authentication in code on the source builder:

* `WithBasicAuth(username, password)` — basic authentication
* `WithBearerToken(token)` — bearer token authentication
* `WithOAuth(authority, clientId, clientSecret)` — OAuth authentication

When no authentication is configured, the source is treated as unauthenticated.

### Key directive

[Section titled “Key directive”](#key-directive)

* `key <propertyPath>`

### Map block

[Section titled “Map block”](#map-block)

`map` supports:

* field rename: `target = source`

* template assignment: “target = \`template ${expr}\`\`\`

* translate: `target = source translate` + value entries

* split:

```cdl
  split source by ","
    first
    second
  ```

### Append block

[Section titled “Append block”](#append-block)

```cdl
append <EventType>
  when ...
  <targetField> = <sourceExpression>
```

Supported `when` forms:

* `when property`
* `when p1 or p2`
* `when p1 and p2`
* `when property from old to new`
* `when added`
* `when removed`
* `when \`expr“

### Nested block

[Section titled “Nested block”](#nested-block)

```cdl
nested <objectPath>
  [map ...]
  append ...
```

### Children block

[Section titled “Children block”](#children-block)

```cdl
children <collectionPath> identified by <childKey>
  [map ...]
  append ...
```

## Expressions

[Section titled “Expressions”](#expressions)

Typical source expressions:

* `$.path` (current payload)
* `$previous.path` (previous payload)
* `$context.occurred` (capture context)
* `$env.VARIABLE` (environment lookup)

## Formal language specification

[Section titled “Formal language specification”](#formal-language-specification)

See [Grammar (EBNF)](/chronicle/captures/capture-declaration-language/grammar/) for the full formal syntax.

# Grammar (EBNF)

This document defines the formal grammar for the Capture Declaration Language (CDL).

## EBNF notation

[Section titled “EBNF notation”](#ebnf-notation)

| Notation  | Meaning       |
| --------- | ------------- |
| `=`       | Definition    |
| `;`       | End of rule   |
| `{ ... }` | Zero or more  |
| `[ ... ]` | Optional      |
| `(...)`   | Grouping      |
| `\|`      | Alternative   |
| `"..."`   | Literal token |

## Complete grammar

[Section titled “Complete grammar”](#complete-grammar)

```ebnf
Document         = { Capture } ;

Capture          = "capture", Path, NL,
                   [ INDENT,
                     { Directive },
                   DEDENT ] ;

SourceBlock      = "source", SourceType, NL,
                   INDENT,
                     { SourceProperty },
                   DEDENT ;

SourceType       = "api" | "webhook" | "message" ;

SourceProperty   = ("api" | "route" | "poll" | "path" | "topic"), LineValue, NL ;

KeyDirective     = "key", LineValue, NL ;

MapBlock         = "map", NL,
                   INDENT,
                     { MapOperation },
                   DEDENT ;

MapOperation     = SplitOperation
                 | RenameOrTemplateOrTranslate ;

RenameOrTemplateOrTranslate
                 = Identifier, "=", LineValue, [ "translate", NL,
                     INDENT,
                       { TranslateEntry },
                     DEDENT
                   ], NL ;

TranslateEntry   = SimpleValue, "=>", SimpleValue, NL ;

SplitOperation   = "split", Path, "by", StringLiteral, NL,
                   INDENT,
                     { Path, NL },
                   DEDENT ;

AppendBlock      = "append", Path, NL,
                   INDENT,
                     "when", WhenExpression, NL,
                     { Assignment },
                   DEDENT ;

WhenExpression   = "added"
                 | "removed"
                 | TemplateLiteral
                 | Path, [ "from", SimpleValue, "to", SimpleValue
                         | { "or", Path }
                         | { "and", Path } ] ;

Assignment       = Identifier, "=", LineValue, NL ;

NestedBlock      = "nested", Path, NL,
                   INDENT,
                     [ MapBlock ],
                     { AppendBlock },
                   DEDENT ;

ChildrenBlock    = "children", Path, "identified", "by", Path, NL,
                   INDENT,
                     [ MapBlock ],
                     { AppendBlock },
                   DEDENT ;

Path             = Identifier, { ".", Identifier } ;
LineValue        = { TokenExceptNewline } ;
SimpleValue      = StringLiteral | NumberLiteral | "true" | "false" | "null" | Identifier ;
Identifier       = Letter, { Letter | Digit | "_" } ;
```

## Semantic constraints

[Section titled “Semantic constraints”](#semantic-constraints)

The parser grammar is complemented by compiler validation rules:

* Exactly one `source` block is required
* Exactly one `key` directive is required
* At most one root `map` block is allowed
* Every `append` block must contain one `when` clause

# Client SDKs

Chronicle concepts, guides, and feature workflows live in the shared Chronicle docs and use language tabs when the client APIs differ. Use the client SDK sections for installation, connection setup, runtime integration, language idioms, and API reference details.

## Shared Chronicle topics

[Section titled “Shared Chronicle topics”](#shared-chronicle-topics)

* [Get started](/chronicle/get-started/)
* [Events and event logs](/chronicle/events/)
* [Event appending](/chronicle/events/appending/)
* [Read models](/chronicle/read-models/)
* [Projections](/chronicle/projections/)
* [Reactors](/chronicle/reactors/)
* [Reducers](/chronicle/reducers/)
* [Constraints](/chronicle/constraints/)
* [Event seeding](/chronicle/event-seeding/)
* [Compliance](/chronicle/compliance/)
* [Transactions and unit of work](/chronicle/events/transactions/)
* [Event evolution](/chronicle/understanding-event-evolution/)

## Client SDK details

[Section titled “Client SDK details”](#client-sdk-details)

* [.NET client](/chronicle/clients/dotnet/)
* [Kotlin client](/chronicle/clients/kotlin/)
* [Elixir client](/chronicle/clients/elixir/)
* [TypeScript client](/chronicle/clients/typescript/)

# .NET client

> Use the .NET client when your Chronicle application runs on C# or another .NET language.

The .NET client is the C#/.NET SDK for Chronicle. It gives .NET applications typed access to event stores, event logs, read models, projections, reducers, reactors, constraints, migrations, namespaces, and hosting integration.

Use this section for .NET-specific setup and APIs. The main Chronicle docs explain the event-sourcing concepts once and use language tabs for examples that apply across clients.

## When to use it

[Section titled “When to use it”](#when-to-use-it)

Use the .NET client when you are building:

* a console tool or script that talks directly to Chronicle
* an ASP.NET Core service that appends events from endpoints or Arc commands
* a Worker Service that runs projections, reducers, reactors, or background append logic
* a .NET test project that uses Chronicle’s in-process testing scenarios

## Install

[Section titled “Install”](#install)

Install the .NET packages that match the host style you are building. The templates do this for you, but explicit package references are useful when adding Chronicle to an existing application.

```bash
dotnet add package Cratis.Chronicle
dotnet add package Cratis.Chronicle.AspNetCore
```

## Shared Chronicle topics

[Section titled “Shared Chronicle topics”](#shared-chronicle-topics)

## .NET-specific pages

[Section titled “.NET-specific pages”](#net-specific-pages)

* [Console quickstart](/chronicle/get-started/console/)
* [ASP.NET Core hosting](/chronicle/get-started/aspnetcore/)
* [Worker Service hosting](/chronicle/get-started/worker/)
* [.NET connection strings](/chronicle/connection-strings/dotnet-client/)
* [.NET namespace resolution](/chronicle/namespaces/dotnet-client/)
* [.NET event type migrations](/chronicle/migrations/dotnet-client/)
* [Seeding events with C#](/chronicle/event-seeding/seeding-with-csharp/)

## Shared examples

[Section titled “Shared examples”](#shared-examples)

When a Chronicle concept applies to every client, keep the prose in the shared Chronicle page and put the C# code in `Chronicle/Documentation/client-snippets/**`. The site renders it beside Kotlin, Elixir, and TypeScript snippets in synchronized language tabs.

# Authoring captures in .NET

> The two .NET-only ways to author Chronicle captures in code — model-bound attributes and the declarative fluent builder — alongside the language-neutral Capture Declaration Language.

[Captures](/chronicle/captures/) turn external data changes into Chronicle events. Chronicle supports three ways to author a capture, and only one of them is language-neutral:

| Approach                           | Language               | Where it’s documented                                                             |
| ---------------------------------- | ---------------------- | --------------------------------------------------------------------------------- |
| Capture Declaration Language (CDL) | Text-based, any client | [Capture Declaration Language](/chronicle/captures/capture-declaration-language/) |
| Declarative API                    | C# fluent builder      | [Declarative Captures](/chronicle/clients/dotnet/captures/declarative/)           |
| Model-bound API                    | C# attributes          | [Model-Bound Captures](/chronicle/clients/dotnet/captures/model-bound/)           |

The declarative and model-bound APIs are .NET client features — they compile to the same `CaptureDefinition` a CDL text file would, but the authoring surface itself is C#-specific.

# Declarative captures

> Fluent C# builder API for defining CDC captures in code — ICapturer, ICaptureBuilder, source configuration, mapping, and append rules.

Declarative captures use fluent C# builder APIs to define CDC behavior in code.

## Entry points

[Section titled “Entry points”](#entry-points)

* Implement `ICapturer`
* Configure the capture in `Define(ICaptureBuilder builder)`

```csharp
public class InvoiceCapture : ICapturer
{
    public void Define(ICaptureBuilder builder) => builder
        .FromApi("InvoicingApi", _ => _
            .OnRoute("/invoices")
            .PollEvery("10m"))
        .Key("id")
        .Append<InvoiceStatusChanged>(_ => _
            .WhenPropertyChanges("status")
            .Set(e => e.Status, "$.status")
            .Set(e => e.ChangedAt, "$context.occurred"));
}
```

## Source configuration

[Section titled “Source configuration”](#source-configuration)

* `FromApi(api, configure?)`
* `FromWebhook(path, configure?)`
* `FromMessageTopic(topic)`

API source options:

* `OnRoute(route)`
* `PollEvery(interval)`

`FromApi(api, ...)` references a configured [External Service](/chronicle/external-services/) by name. The External Service holds the base URL and authentication, so no authentication is configured on the API source. If no route is configured, the External Service base URL is used directly.

Webhook source options (webhook sources are inbound and configure their own authentication):

* `WithBasicAuth(username, password)`
* `WithBearerToken(token)`
* `WithOAuth(authority, clientId, clientSecret)`

Authentication is never part of the capture declaration text, so that secrets and tokens do not live in capture definitions.

## Defining identity

[Section titled “Defining identity”](#defining-identity)

Use `Key(propertyPath)` to define the identity property used when comparing current vs. previous payload.

## Mapping operations

[Section titled “Mapping operations”](#mapping-operations)

Use `Map(...)` on root, nested, or children scopes:

* `Rename(source, target)`
* `Template(target, template)`
* `Translate(target, source, entries => ...)`
* `Split(source, separator, targets...)`

## Append rules

[Section titled “Append rules”](#append-rules)

Use `Append<TEvent>(...)` with one condition and one or more field assignments:

Condition methods:

* `WhenPropertyChanges(property)`
* `WhenAnyOf(properties...)`
* `WhenAllOf(properties...)`
* `WhenTransition(property, from, to)`
* `WhenAdded()`
* `WhenRemoved()`
* `WhenExpression(expression)`

Assignment method:

* `Set(targetPropertyExpression, sourceExpression)`

## Scoped capture sections

[Section titled “Scoped capture sections”](#scoped-capture-sections)

* `Nested(objectPath, configure)` for nested object rules
* `Children(collectionPath, identifiedBy, configure)` for child collection rules

Both support local `Map(...)` and `Append<TEvent>(...)` blocks.

## Optional capture metadata

[Section titled “Optional capture metadata”](#optional-capture-metadata)

You can set an explicit capture ID using `[Capture("guid")]` on the `ICapturer` type.

# Model-bound captures

> Attribute-based capture declarations in the .NET client — source, key, append conditions, and field mappings declared with attributes.

Model-bound captures use attributes to declare source, key, append conditions, and field mappings.

## Capture source and key

[Section titled “Capture source and key”](#capture-source-and-key)

Apply one source attribute and one key attribute on the capture type:

* `[ApiCapture(api, Poll = ..., Route = ...)]`
* `[WebhookCapture(path)]`
* `[MessageCapture(topic)]`
* `[CaptureKey(property)]`

```csharp
[ApiCapture("InvoicingApi", Poll = "10m", Route = "/invoices")]
[CaptureKey("id")]
public class InvoiceCapture;
```

`ApiCapture` references a named API configuration. If `Route` is not set, the configured API base URL is used directly.

Note

Authentication is not declared on the capture attribute. It is configured in code where the source is configured, so that secrets never live in the capture declaration. See [Configuring authentication](/chronicle/captures/capture-declaration-language/#configuring-authentication).

## Append conditions on event types

[Section titled “Append conditions on event types”](#append-conditions-on-event-types)

Use one condition attribute on each event type:

* `[WhenPropertyChanged(property)]`
* `[WhenAnyOf(properties...)]`
* `[WhenAllOf(properties...)]`
* `[WhenTransition(property, from, to)]`
* `[WhenAdded]`
* `[WhenRemoved]`

```csharp
[WhenPropertyChanged("status")]
public record InvoiceStatusChanged(
    [MapFrom("$.status")] string Status,
    [MapFromContext("occurred")] DateTimeOffset ChangedAt);
```

## Field mapping attributes

[Section titled “Field mapping attributes”](#field-mapping-attributes)

Use on event properties (or primary-constructor parameters):

* `[MapFrom(sourcePath)]` maps from capture payload values
* `[MapFromContext(contextProperty)]` maps from capture runtime context

## When to use model-bound captures

[Section titled “When to use model-bound captures”](#when-to-use-model-bound-captures)

Use this approach when:

* Capture intent should live close to event contracts
* Mapping is mostly direct and attribute-friendly
* You want concise definitions with minimal fluent code

# Registering External Services from code

> Register External Services programmatically from the .NET client, as an alternative to configuring them in the Workbench.

[External Services](/chronicle/external-services/) are usually configured in the Workbench, but the .NET client also exposes a programmatic API on `IEventStore`:

```csharp
// An HTTP service with bearer token authentication and a header
await eventStore.ExternalServices.Register("CustomersApi", _ => _
    .Http("https://api.example.com")
    .WithBearerToken(token)
    .WithHeader("X-Tenant", "acme"));

// A PostgreSQL database service
await eventStore.ExternalServices.Register("CustomersDb", _ => _
    .PostgreSql("db.example.com", "customers", "postgres", password, port: 5432));
```

The builder also exposes `WithBasicAuth`, `WithOAuth`, `MsSql`, and `WithOption`.

# Get started with the .NET client

> Connect a .NET application to Chronicle and append an event.

Use the .NET client when you want direct typed access to Chronicle from a C# application. The smallest useful loop is:

1. create a `ChronicleClient`
2. open an event store
3. append a fact to an event log
4. let projections, reducers, and reactors observe that fact

## Connect

[Section titled “Connect”](#connect)

For local development, start the Chronicle kernel and connect with the development connection string.

```csharp
using Cratis.Chronicle;

using var client = new ChronicleClient(ChronicleConnectionString.Development);
var eventStore = await client.GetEventStore("Quickstart");
```

`ChronicleConnectionString.Development` points at the default local Chronicle kernel with development credentials. Use `ChronicleConnectionString.Default` or an explicit `new ChronicleConnectionString("chronicle://...")` when connecting to another environment.

## Define an event

[Section titled “Define an event”](#define-an-event)

Events are immutable facts. In .NET, mark event records with `[EventType]` so Chronicle can discover and register their schema.

```csharp
using Cratis.Chronicle.Events;

[EventType]
public record BookAdded(string Title, string Isbn);
```

## Append the event

[Section titled “Append the event”](#append-the-event)

Append the event against the event source it belongs to. The event source id is not part of the event payload; Chronicle stores it in the event context.

```csharp
var bookId = "book-123";

var result = await eventStore.EventLog.Append(
    bookId,
    new BookAdded("The Pragmatic Programmer", "978-0135957059"));

if (!result.IsSuccess)
{
    // Decide whether to retry or surface the append failure to the caller.
}
```

After the append succeeds, Chronicle persists the event and forwards it to the projections, reducers, reactors, and subscriptions that observe the event sequence.

## Use a host integration

[Section titled “Use a host integration”](#use-a-host-integration)

For ASP.NET Core and Worker Service applications, prefer the host integration instead of creating the client manually:

```csharp
builder.Services.AddCratisChronicle(options => options.EventStore = "Quickstart");
```

The host integration registers the event store, event log, read models, projections, reducers, reactors, constraints, and related services in dependency injection.

## Next

[Section titled “Next”](#next)

# Querying behavior patterns

> Ask what a user usually does in a given context, from the .NET client, backed by the patterns Chronicle mined from event history.

[Behavior patterns](/chronicle/patterns/) are recurring combinations of context that Chronicle mined from an event store’s history. The .NET client exposes them on `IEventStore.Patterns`.

## Asking what somebody usually does right now

[Section titled “Asking what somebody usually does right now”](#asking-what-somebody-usually-does-right-now)

Most applications have one question: *what does this person normally do at this point in the week?* Every Chronicle client offers that as a single call — see [asking about a moment](/chronicle/patterns/) for the shared contract. In .NET it is `GetPatternsAt`, and it takes the scope and nothing else:

```csharp
foreach (var pattern in await eventStore.Patterns.GetPatternsAt(userId))
{
    var command = pattern.Facets.ValueOf(FacetName.CommandType);
    Console.WriteLine($"{command} — {pattern.Confidence.Value:P0} of the time");
}
```

Each answer names a **command**, and its `Confidence` is the chance of that command given the context it was established in. You get at most one answer per command, so a habit mined at several context sizes at once comes back once rather than three times.

The day and the part of the day are read off the moment for you, using the same rule the engine bucketed events with when it mined them — so the answer is about the slot the behavior was actually learned in. Pass a moment to ask about a different one:

```csharp
var patterns = await eventStore.Patterns.GetPatternsAt(userId, tomorrowMorning);
```

Add further facets when the question is narrower than a moment — *what does this person usually do with an invoice on a Monday morning?*

```csharp
var patterns = await eventStore.Patterns.GetPatternsAt(
    userId,
    alsoConstraining: FacetSet.Empty.With(FacetName.AggregateType, "Invoice"));
```

Note

Derive the time bucket yourself and you own a copy of a rule the engine also owns. When they drift, nothing fails — the query simply asks about a slot the mining never used and returns nothing. `GetPatternsAt` exists so that copy does not have to exist. If you do need the bucket for something else, `ToTimeBucket()` on `DateTimeOffset` is the same rule the engine mines with.

## Asking about a context that is not a moment

[Section titled “Asking about a context that is not a moment”](#asking-about-a-context-that-is-not-a-moment)

`GetUsualActions` is the call underneath. Build a context from the facets you know and ask within a scope — normally the user whose behavior you are asking about:

```csharp
using Cratis.Chronicle.Concepts.Patterns;

var patterns = await eventStore.Patterns.GetUsualActions(
    groupingKey: userId,
    context: FacetSet.Empty
        .With(FacetName.Day, DayOfWeek.Monday.ToString())
        .With(FacetName.AggregateType, "Invoice"));

foreach (var pattern in patterns)
{
    Console.WriteLine($"{pattern.Facets.ValueOf(FacetName.CommandType)} — {pattern.Confidence.Value:P0} confident, seen {pattern.Occurrences.Value} times");
}
```

The context may constrain **any subset** of the facets. Facets the store does not mine are discarded rather than narrowing the lookup to nothing, so a caller can describe its situation in whatever terms it has.

Results are ranked **most likely first**. Constraining `CommandType` here does nothing — it names the answer rather than the situation, and the answer is what you are asking for.

## Checking whether an action is normal

[Section titled “Checking whether an action is normal”](#checking-whether-an-action-is-normal)

`GetPatterns` asks the opposite question: given a situation you can describe *completely*, including the command, which established patterns cover it? That is the check you make before flagging something as unusual, rather than the prediction above.

```csharp
var covering = await eventStore.Patterns.GetPatterns(
    groupingKey: userId,
    context: FacetSet.Empty
        .With(FacetName.CommandType, "DeleteSupplier")
        .With(FacetName.Day, DayOfWeek.Sunday.ToString())
        .With(FacetName.TimeBucket, TimeBucket.Night.ToString()));

if (!covering.Any(pattern => pattern.Facets.Constrains(FacetName.CommandType)))
{
    // Nothing established covers this person doing this, here.
}
```

A pattern is returned when **its facets are a subset of the context you asked with**, so every result describes something you named. Results are ranked **most specific first**, then most confident: a pattern constraining everything you asked about describes your situation; a broader, more confident one describes a situation you did not ask about.

### An empty result is an answer

[Section titled “An empty result is an answer”](#an-empty-result-is-an-answer)

Both calls return nothing when no pattern clears the confidence bar. That is a true statement — this scope has no established behavior for this context — and it is deliberately not padded with the best of a bad set. Treat “no patterns” as “do not claim to know”:

```csharp
var patterns = await eventStore.Patterns.GetUsualActions(userId, context);
if (!patterns.Any())
{
    return "I don't have enough history to say what usually happens here.";
}
```

### Thresholds and limits

[Section titled “Thresholds and limits”](#thresholds-and-limits)

```csharp
var patterns = await eventStore.Patterns.GetUsualActions(
    groupingKey: userId,
    context: context,
    minimumConfidence: new PatternConfidence(0.8d),
    maximumResults: 3,
    cancellationToken: cancellationToken);
```

Leave `minimumConfidence` and `maximumResults` unset to use whatever the **server** is configured for. The client deliberately does not carry its own copy of the thresholds — a default duplicated here would silently disagree with the configured one the moment either changed.

## Browsing everything a scope established

[Section titled “Browsing everything a scope established”](#browsing-everything-a-scope-established)

`GetPatternsForScope` is the listing call — everything held for a scope, unfiltered, including patterns below the confidence threshold. It is what a browsing view binds to, as opposed to the two calls above, which each answer a question about one situation.

```csharp
var everything = await eventStore.Patterns.GetPatternsForScope(userId);
```

Which leaves the question of what to pass. A browsing view rarely knows a scope up front — it has to offer the ones that exist — and patterns are per scope, so there is nothing to show until one is chosen. `GetScopes` is that list:

```csharp
foreach (var scope in await eventStore.Patterns.GetScopes())
{
    var patterns = await eventStore.Patterns.GetPatternsForScope(scope);
}
```

The scopes returned are the ones that actually hold patterns, not every identity that ever appeared in the store. A scope missing from the list has established no behavior yet — which is the same answer an empty `GetUsualActions` gives, one level up.

## What you get back

[Section titled “What you get back”](#what-you-get-back)

Each result is a `BehaviorPattern`:

| Member                   | Type                 | Meaning                                                        |
| ------------------------ | -------------------- | -------------------------------------------------------------- |
| `GroupingKey`            | `PatternGroupingKey` | The scope the pattern belongs to                               |
| `Facets`                 | `FacetSet`           | The facets the pattern constrains                              |
| `Occurrences`            | `PatternOccurrences` | How many times it has been observed                            |
| `Confidence`             | `PatternConfidence`  | How often it holds when its context is present, 0 to 1         |
| `Support`                | `PatternSupport`     | The share of all observed events it was seen in, 0 to 1        |
| `Weight`                 | `PatternWeight`      | Recency-weighted strength — decays as the behavior goes unseen |
| `FirstSeen` / `LastSeen` | `DateTimeOffset`     | When it was first and last observed                            |

`Occurrences` counts everything that ever happened; `Weight` is how much of that is still recent. Order by `Weight` when recency matters more than history.

Read a single facet off a pattern with `ValueOf`, and check whether it constrains one at all with `Constrains`:

```csharp
var pattern = patterns.First();
var command = pattern.Facets.ValueOf(FacetName.CommandType);

if (pattern.Facets.Constrains(FacetName.TimeBucket))
{
    // The pattern is specific to a part of the day.
}
```

## Building a context

[Section titled “Building a context”](#building-a-context)

`FacetSet` is canonical and immutable: facets are ordered by name, at most one value per facet survives, and facets with no value are dropped. `With` returns a new set and **replaces** a facet that is already constrained, so a context built up in steps never depends on the order it was written in.

```csharp
var context = FacetSet.Empty
    .With(FacetName.CommandType, "ApproveExpenseReport")
    .With(FacetName.Day, DayOfWeek.Monday.ToString())
    .With(FacetName.Day, DayOfWeek.Tuesday.ToString());   // replaces Monday
```

The facet names are the well-known statics on `FacetName` — `CommandType`, `InitiatorType`, `InitiatorId`, `OnBehalfOf`, `CausedByCommand`, `CorrelationRootId`, `AggregateType`, `Year`, `Month`, `Day` and `TimeBucket`. See [Behavior Patterns](/chronicle/patterns/) for what each one means and which of them are mined by default.

## Making the command visible to mining

[Section titled “Making the command visible to mining”](#making-the-command-visible-to-mining)

`CommandType` and `CausedByCommand` are only as good as what named the command. If you append through [Cratis Arc](/arc/), its command pipeline records a `Command` causation naming the executing command and nothing else is needed.

Appending directly, add the same property to the causation you scope around the work:

```csharp
using Cratis.Chronicle.Auditing;
using Cratis.Chronicle.Concepts.Patterns;

using (causationManager.BeginScope(
    "Command",
    new Dictionary<string, string> { { WellKnownCausationProperties.CommandType, nameof(ApproveExpenseReport) } }))
{
    await eventStore.EventLog.Append(expenseReportId, new ExpenseReportApproved(approvedBy));
}
```

Use `BeginScope` rather than `Add` for work with a beginning and an end. `Add` is append-only, which is right for a link describing how the work arrived — an HTTP request — but wrong for one describing a bounded piece of work: two such pieces done one after the other both stay on the chain, and the second then reads as caused by the first. That ordering never happened, and pattern mining would learn it as a fact.

# Observing artifact registration

> Ask an event store whether its declared artifacts registered, instead of re-driving discovery and registration to find out.

Chronicle registers your artifacts for you. `RegisterAll` is wired to the connection lifecycle and runs whenever the connection comes up, which is the right default and stays the default.

What `IEventStore.Registration` adds is a way to ask afterwards how it went.

## Why you might need it

[Section titled “Why you might need it”](#why-you-might-need-it)

A read model that cannot be built is isolated: it is logged and skipped, so one broken read model no longer costs the rest of your read side. That is a good trade, but it turns a loud failure into a quiet one. The broken read model is simply absent afterwards, and nothing throws.

Without an outcome to read, these three situations look identical from outside:

* every artifact registered
* some registered, and the rest were dropped
* registration has not run yet

`Registration` tells them apart.

## Reading the outcome

[Section titled “Reading the outcome”](#reading-the-outcome)

```csharp
var outcome = eventStore.Registration;

if (!outcome.HasRun)
{
    // Registration has not finished yet - or has not been triggered at all.
}

if (outcome.Failure is not null)
{
    // Registration ran and did not finish. Whatever registered before it stopped is still in Artifacts.
    Console.WriteLine($"Registration failed: {outcome.Failure.Message}");
}

foreach (var failed in outcome.Failures)
{
    Console.WriteLine($"{failed.ArtifactType.Name} did not register: {failed.Failure!.Message}");
}
```

| Member      | What it answers                                                                           |
| ----------- | ----------------------------------------------------------------------------------------- |
| `HasRun`    | Whether `RegisterAll` has finished at least once, successfully or not                     |
| `Artifacts` | Every declared projection artifact, with `IsRegistered` and the `Failure` that stopped it |
| `Failure`   | What stopped `RegisterAll` itself, or `null` when it finished                             |
| `IsSuccess` | Registration ran, finished, and every declared artifact registered                        |
| `Failures`  | Only the artifacts that did not register                                                  |

`RegistrationOutcome.NotRun` is the value before registration has finished.

There are two kinds of failure here and they are not the same. An artifact in `Failures` could not be built, so it was isolated and skipped and registration carried on without it — the rest of the read side is up. A `Failure` on the outcome itself ended the run, so registration stopped wherever it got to. A run that ends this way still reports itself rather than staying at `NotRun`, so waiting on it returns instead of timing out.

## Waiting for it

[Section titled “Waiting for it”](#waiting-for-it)

Registration runs on the connection lifecycle, so a consumer that has just constructed a client may simply be early. `WaitForRegistration` waits for it to have run, with the same timeout shape as the other Chronicle wait helpers:

```csharp
using Cratis.Chronicle.Registrations;

var outcome = await eventStore.WaitForRegistration(TimeSpan.FromSeconds(10));

if (!outcome.IsSuccess)
{
    throw new InvalidOperationException("The read side did not come up.");
}
```

It waits for registration to have *run*, not to have succeeded — ask the returned outcome about that. A run that failed returns here too, carrying its `Failure`; the timeout is for a registration that never finished, not for one that finished badly. If it has not finished within the timeout, the wait throws `TaskCanceledException`.

## What it covers

[Section titled “What it covers”](#what-it-covers)

`Registration` reports projection artifacts: the fluent `IProjectionFor<T>` implementations and the model-bound read models. Those are the artifacts whose registration round-trips to the kernel inside `RegisterAll`, so the outcome is observed rather than assumed.

Reactors and reducers are deliberately not reported. Their registration only opens a duplex stream and returns before the kernel has answered, so the client has nothing to report about them that would be a fact. To know a reactor or reducer is live, wait on its observer state instead — `WaitTillSubscribed` or `WaitTillActive` — which the kernel answers.

The outcome is read-only and decides nothing. Whether a failed artifact should abort start-up, fail a spec, or be tolerated is yours to decide.

Caution

Do not use `IConnectionLifecycle.IsConnected` as a stand-in. It is set to `true` *before* the connected handlers run — registration is one of them — and only rolled back afterwards if one of them failed. Polling it races: it reads `true` while registration is still in flight, and while a registration about to be reported as failed is still running. It answers “connected”, which is necessary and not sufficient.

# Chronicle Elixir Client

`chronicle` is the Elixir SDK for Chronicle. Use this section for Mix setup, supervision, connection behavior, Elixir modules/macros, process-scoped context, and other runtime-specific details.

Shared Chronicle concepts and workflows live in the main Chronicle docs and use language tabs when code differs by client.

## Shared Chronicle topics

[Section titled “Shared Chronicle topics”](#shared-chronicle-topics)

* [Get started](/chronicle/get-started/)
* [Events and event logs](/chronicle/events/)
* [Appending events](/chronicle/events/appending/)
* [Read models](/chronicle/read-models/)
* [Projections](/chronicle/projections/)
* [Reactors](/chronicle/reactors/)
* [Reducers](/chronicle/reducers/)
* [Constraints](/chronicle/constraints/)
* [Event seeding](/chronicle/event-seeding/)
* [Compliance](/chronicle/compliance/)
* [Transactions and unit of work](/chronicle/events/transactions/)
* [Event evolution](/chronicle/understanding-event-evolution/)

## Elixir-specific pages

[Section titled “Elixir-specific pages”](#elixir-specific-pages)

* [Get Started](/chronicle/clients/elixir/get-started/) — install the client, start `Chronicle.Client`, and append an event
* [Connections](/chronicle/clients/elixir/connections/) — connection strings, authentication, resilience, and re-registration
* [Context Management](/chronicle/clients/elixir/context/) — process-scoped correlation IDs, identities, and causation chains
* [Event Store Discovery](/chronicle/clients/elixir/event-stores/) — discovering event stores and namespaces
* [Event Store Subscriptions](/chronicle/clients/elixir/event-store-subscriptions/) — importing events between event stores
* [Jobs](/chronicle/clients/elixir/jobs/) — inspecting and controlling Chronicle jobs
* [WebHooks](/chronicle/clients/elixir/webhooks/) — registering webhooks from Elixir
* [External Services](/chronicle/clients/elixir/external-services/) — registering HTTP and database external services from Elixir
* [Failed Partitions](/chronicle/clients/elixir/failed-partitions/) — inspecting observers whose partitions have failed

# Compliance

Compliance and PII handling are shared Chronicle topics. The shared docs own the concepts, storage behavior, and client-tabbed examples.

* [Compliance](/chronicle/compliance/)
* [PII](/chronicle/compliance/pii/)
* [Compliance in read models](/chronicle/compliance/read-models/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

# Concepts

A `String.t()` is a `String.t()` is a `String.t()`. Nothing stops an employee id being passed where a customer id was expected, or a plain email address sitting in an event field with no signal at all that it needs to be encrypted. Both compile. Both look fine in code review. The bug — or the compliance gap — surfaces later, in production.

`Chronicle.Concept` gives a domain value a type of its own: a small wrapper struct that declares what the value *is*, and, when it matters, that it is personally identifiable information Chronicle should protect.

## Declaring one

[Section titled “Declaring one”](#declaring-one)

Use `Chronicle.Concept` in a module and declare the primitive type it wraps:

```elixir
defmodule MyApp.PersonName do
  use Chronicle.Concept, type: :string
end

defmodule MyApp.Age do
  use Chronicle.Concept, type: :integer
end
```

Supported types are `:string`, `:integer`, `:float`, `:boolean`, and `:uuid`. Anything else raises `ArgumentError` at compile time, with the list of valid types in the message.

A concept is a plain struct with a single field:

```elixir
%MyApp.PersonName{value: "Ada Lovelace"}
```

Use it wherever a raw value used to sit, as the **default value** of a `defstruct` field on an event type or read model:

```elixir
defmodule MyApp.Events.EmployeeRegistered do
  use Chronicle.Events.EventType, id: "employee-registered"

defstruct name: %MyApp.PersonName{}, department: ""
end
```

The default matters, not just as a starting value: `Chronicle.Schemas.JsonSchemaGenerator` reads struct field defaults to build the JSON schema Chronicle registers, so a field’s default is also how the generator learns the field’s type. A field that should be recognized as a `MyApp.PersonName` needs `%MyApp.PersonName{}` as its default — `nil` carries no type information to infer from.

## What goes on the wire

[Section titled “What goes on the wire”](#what-goes-on-the-wire)

A concept serializes as the value it wraps, not as an object wrapping one:

```elixir
iex> Jason.encode!(%MyApp.PersonName{value: "Ada Lovelace"})
"\"Ada Lovelace\""
```

That is what makes a concept something you can adopt for a property that is already in production. The JSON does not change, the schema Chronicle validates against does not change, and every event stored before the concept existed still reads back. This mirrors the intent of Kotlin’s `ConceptAs<T>` and its `ConceptTypeAdapterFactory`, and C#‘s `ConceptAs<T>`.

## Concepts and compliance (PII)

[Section titled “Concepts and compliance (PII)”](#concepts-and-compliance-pii)

The most useful thing a concept does is carry its compliance classification with it. Declare `pii/0,1` once, on the concept, and every event or read model field that uses it is encrypted automatically — no need to remember `Chronicle.Compliance.pii/1,2` on every event that happens to carry the value:

```elixir
defmodule MyApp.PersonName do
  use Chronicle.Concept, type: :string
  pii("Legal name of the data subject")
end
```

The optional `details` argument documents *why* the value is classified as PII — the legal basis or retention period, for example. It is stored in the generated schema for compliance tooling to read; it plays no part in encryption.

`Chronicle.Schemas.JsonSchemaGenerator` resolves PII from two places, and applies both consistently across event type registration and read model registration:

* **Property-level** — `pii(:field, details)` declared on the event type or read model module itself, exactly as before.
* **Type-level** — a field whose default value is an instance of a `Chronicle.Concept` module that declared `pii/0,1` on itself.

The generator also **descends into nested structs**, so a concept does not have to sit directly on an event or read model field — it is still found several levels down, inside a plain value object:

```elixir
defmodule MyApp.Address do
  defstruct street: %MyApp.PersonName{}, postal_code: ""
end
```

and inside a **list**, where the first element’s schema (including its compliance metadata) becomes the schema for every item:

```elixir
defmodule MyApp.Events.EmployeeRegistered do
  use Chronicle.Events.EventType, id: "employee-registered-with-aliases"

defstruct name: %MyApp.PersonName{}, aliases: [%MyApp.PersonName{}]
end
```

Compliance metadata always ends up on a schema **leaf** — never on a container node describing a whole object — with one deliberate exception: compliance declared on the array *field itself* (rather than resolved from its element type) stays on the array, because Chronicle blob-encrypts that collection as a whole. A leaf reached through more than one path (a concept’s own PII plus a redundant property-level `pii/1,2` on the same field) is only ever recorded once.

## Event source ids are never PII

[Section titled “Event source ids are never PII”](#event-source-ids-are-never-pii)

A concept can also stand in for a Chronicle event source identifier:

```elixir
defmodule MyApp.EmployeeId do
  use Chronicle.Concept, type: :uuid, event_source_id: true
end
```

Chronicle uses the event source id to look up the encryption key for a subject’s PII values, so it cannot itself be one of the encrypted values — you cannot use the key to find the key. Combining `event_source_id: true` with `pii/0,1` on the same concept raises `ArgumentError` at compile time, mirroring the C# client’s `PIINotSupportedOnEventSourceId`:

```elixir
defmodule MyApp.EmployeeId do
  use Chronicle.Concept, type: :uuid, event_source_id: true
  # Raises ArgumentError at compile time.
  pii()
end
```

If the identifier itself is sensitive, use a non-sensitive surrogate (a random `:uuid` concept with `event_source_id: true` and no `pii`) as the event source id, and store the sensitive value in a separate PII-marked concept.

## Introspection

[Section titled “Introspection”](#introspection)

`__chronicle_concept__/1` exposes a concept’s metadata, accepting `:type`, `:event_source_id?`, or `:pii` as the key:

```elixir
MyApp.PersonName.__chronicle_concept__(:type)
#=> :string

MyApp.PersonName.__chronicle_concept__(:event_source_id?)
#=> false
```

See [Compliance](/chronicle/clients/elixir/compliance/) for the full PII picture, including right-to-erasure key deletion.

# Concurrency

Optimistic concurrency is shared Chronicle behavior. Use the shared docs for concurrency scopes, expected sequence numbers, and client-tabbed examples.

* [Optimistic concurrency](/chronicle/events/concurrency/)
* [Appending events](/chronicle/events/appending/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

# Connections

A Chronicle client maintains a long-lived gRPC connection to a Chronicle kernel. Everything the client does — appending events, projecting read models, running reactors and reducers, seeding — flows over that one connection. Because it is long-lived, it *will* be interrupted: kernels restart, networks blip, load balancers recycle. The client is built to treat those interruptions as normal and recover from them without losing observers or dropping into a broken state.

These guides explain how the connection is established, how it is described, and how the client stays resilient when it drops.

## Guides

[Section titled “Guides”](#guides)

* [Resilience and the Connection Lifecycle](/chronicle/clients/elixir/connections/resilience/) — How the client connects, detects a dead connection, reconnects, and re-registers every observer in the correct order.
* [Connection Strings](/chronicle/clients/elixir/connections/connection-strings/) — The `chronicle://` URL format, authentication modes, and the available options.

## At a glance

[Section titled “At a glance”](#at-a-glance)

Start a client by pointing it at a kernel with a connection string:

```elixir
{Chronicle.Client,
  connection_string: "chronicle://localhost:35000",
  event_store: "store",
  otp_app: :my_app}
```

The client connects in the background. Calls such as `Chronicle.append/3` work as soon as the connection is ready; you never manage the socket yourself.

# Connection Strings

A connection string tells the client which kernel to connect to and how to authenticate. It is a URL with the `chronicle://` scheme, so it carries the host, port, credentials and options in one value you can keep in config or an environment variable.

```plaintext
chronicle://host:port?option=value&option=value
```

The default, when you pass no connection string, is `chronicle://localhost:35000` — the local development kernel.

## Authentication

[Section titled “Authentication”](#authentication)

Two modes are supported.

**Client credentials** — supply a client id and secret in the URL userinfo:

```plaintext
chronicle://client-id:client-secret@host:35000
```

**API key** — supply an `apiKey` query parameter:

```plaintext
chronicle://host:35000?apiKey=my-api-key
```

When neither is present the client connects without authentication, which is the normal case for local development.

## Options

[Section titled “Options”](#options)

| Option                | Purpose                                                                                                                                                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`              | API key used for authentication.                                                                                                                                                                                                             |
| `disableTls`          | Set to `true` to connect over plain HTTP/2 instead of TLS. The Chronicle kernel requires TLS on its single port, so only set this when connecting through something else that terminates TLS for you, such as a plaintext-terminating proxy. |
| `certificatePath`     | Path to a client certificate file for mutual TLS.                                                                                                                                                                                            |
| `certificatePassword` | Password for the client certificate.                                                                                                                                                                                                         |

## Examples

[Section titled “Examples”](#examples)

Local development:

```elixir
{Chronicle.Client, connection_string: "chronicle://localhost:35000"}
```

TLS is mandatory even for local development — the kernel auto-generates a self-signed certificate for `localhost` when none is configured, and the client trusts it automatically, no setup required.

Production with an API key over TLS:

```elixir
{Chronicle.Client, connection_string: "chronicle://chronicle.internal:35000?apiKey=#{api_key}"}
```

Client credentials:

```elixir
{Chronicle.Client, connection_string: "chronicle://my-client:#{secret}@chronicle.internal:35000"}
```

## Why a URL

[Section titled “Why a URL”](#why-a-url)

Putting everything in one URL keeps connection configuration in a single place — one environment variable per environment — rather than spreading host, port, credentials and flags across several settings that can drift out of sync.

# Resilience and the Connection Lifecycle

A Chronicle client is a small supervision tree of processes that all depend on one thing: a live connection to the kernel. Reactors, reducers, projections, seeders, webhooks and subscriptions all need that connection, and they all need it to come *back* after it drops. Rather than have each of them poll and retry on its own — which races, reconnects in the wrong order, and registers observers before the kernel knows about them — the client funnels every part through a single connection lifecycle.

This mirrors the behavior of the .NET Chronicle client, so the two clients recover identically.

## The three phases

[Section titled “The three phases”](#the-three-phases)

The lifecycle moves through three ordered phases:

| Phase           | Meaning                                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `:disconnected` | No live session with the kernel.                                                                                                                                 |
| `:connected`    | The session handshake completed — the kernel has acknowledged the client’s connection id. The channel can carry calls.                                           |
| `:registered`   | The base artifacts (event store, namespace, event types, read models, constraints, projections) are registered with the kernel. Observers may now safely attach. |

Splitting `:connected` from `:registered` is the important part. A reducer’s observation stream cannot be registered until the kernel already knows about the reducer’s read model. If observers attached the moment the connection came up, they would race ahead of those definitions and the kernel would reject them. Waiting for `:registered` removes that race entirely.

## What happens on connect

[Section titled “What happens on connect”](#what-happens-on-connect)

When the connection is established, the client always runs the same ordered registration, on first connect and on every reconnect:

1. Ensure the event store and namespace exist.
2. Register event types and read models.
3. Register constraints and projections (including reducer read-model definitions).
4. Advance to `:registered`.
5. Reactors and reducers open their observation streams; webhook and subscription registrars register; seeders run.

Steps 1–3 must complete before step 5 — that ordering is what keeps observers from registering against definitions that do not exist yet.

## What happens on disconnect

[Section titled “What happens on disconnect”](#what-happens-on-disconnect)

The client keeps a keepalive stream open to the kernel. When keepalives stop arriving, the connection is considered dead:

1. The lifecycle moves to `:disconnected`.
2. Reactors and reducers tear down their observation streams and wait.
3. The connection id is rotated, so the next session uses a fresh identity — exactly as the .NET client does.
4. The client reconnects with exponential backoff, and the connect sequence above runs again from the top.

Because reactors register as replayable and projections and reducers are rewindable, any events that arrive while an observer is briefly detached are picked up by replay once it re-attaches — nothing is missed.

## Seeding is connection-aware

[Section titled “Seeding is connection-aware”](#seeding-is-connection-aware)

Seeders no longer run on a fixed delay at startup. They run when the lifecycle reaches `:registered`, so they never fail with `:not_connected`. Seeding is idempotent — it skips event sources that already have events — so re-running it after a reconnect is a cheap no-op.

## Failure isolation

[Section titled “Failure isolation”](#failure-isolation)

Each observer manages its own stream-level retry: if a single reactor or reducer stream fails while the connection is otherwise healthy, only that stream re-registers, after a short delay. A failing observer never takes down the connection or its siblings.

## You don’t manage any of this

[Section titled “You don’t manage any of this”](#you-dont-manage-any-of-this)

All of the above is automatic. You start a `Chronicle.Client`, and appends, queries, reactors and reducers keep working across kernel restarts and network interruptions without any reconnect code of your own.

# Constraints

Constraints are shared Chronicle behavior. The shared docs cover constraint concepts, model-bound constraints, declarative constraints, and client-tabbed examples.

* [Constraints](/chronicle/constraints/)
* [Understanding constraints](/chronicle/understanding-constraints/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

## Scoping uniqueness checks

[Section titled “Scoping uniqueness checks”](#scoping-uniqueness-checks)

`unique/2` accepts a `:scope` option that narrows a uniqueness check to values observed at append time along one or more dimensions, instead of checking globally across the whole event store. Mirrors the C# client’s `IConstraintBuilder.PerEventSourceType()` / `PerEventStreamType()` / `PerEventStreamId()`.

`:scope` takes an atom — `:per_event_source_type`, `:per_event_stream_type`, or `:per_event_stream_id` — or a list of them to scope along more than one dimension at once:

```elixir
defmodule MyApp.Events.EmailChanged do
  use Chronicle.Events.EventType, id: "email-changed"

defstruct [:email]

# Unique only among events from the same event source type — the same email value
  # may repeat across different event source types (e.g. an employee and a customer
  # can share an email without tripping this constraint).
  unique(:email, scope: :per_event_source_type)
end
```

Without `:scope`, uniqueness is checked globally, as before.

# Context Management: Correlation, Identity, and Causation

Chronicle Elixir provides process-scoped context management for tracking correlation, identity, and causation information as you append events. See [Correlation, identity, and causation](/chronicle/concepts/correlation-identity-causation/) for what these three mean and why Chronicle tracks them. This page covers the Elixir-specific API in depth.

All three are process-scoped: set them once at the start of a request or operation and every subsequent `append` call in the same process will include them automatically. You can always override on a per-call basis.

## Correlation IDs

[Section titled “Correlation IDs”](#correlation-ids)

Correlation IDs group related operations together, making it easy to trace a user action through multiple services.

### Creating Correlation IDs

[Section titled “Creating Correlation IDs”](#creating-correlation-ids)

```elixir
alias Chronicle.CorrelationId

# Generate a new random UUID-based correlation ID
correlation_id = CorrelationId.create()

# Parse a string or UUID as a correlation ID
correlation_id = CorrelationId.parse("92a130f7-16e2-44f7-a8e3-79e76f5df3e1")
```

### Process-Scoped Correlation

[Section titled “Process-Scoped Correlation”](#process-scoped-correlation)

Set a correlation ID for your process, and all subsequent `append` calls will include it:

```elixir
alias Chronicle.CorrelationId

# Set for the current process
correlation_id = CorrelationId.create()
Chronicle.set_correlation_id(correlation_id)

# All appends now use this correlation ID
:ok = Chronicle.append("account-42", %MyApp.Events.AccountOpened{...})
:ok = Chronicle.append("account-42", %MyApp.Events.FundsDeposited{...})

# Get the current correlation ID
current = Chronicle.current_correlation_id()

# Clear it when done
Chronicle.clear_correlation_id()
```

### One-Off Correlation Override

[Section titled “One-Off Correlation Override”](#one-off-correlation-override)

For a single append, override the process-scoped correlation ID:

```elixir
:ok = Chronicle.append("account-42", event,
  correlation_id: "92a130f7-16e2-44f7-a8e3-79e76f5df3e1"
)
```

## Identity

[Section titled “Identity”](#identity)

Identity answers the question: *who caused this state change?* It is stored with every event appended to the Chronicle event log, giving you a permanent, queryable record of authorship. This is essential for compliance, debugging, and building audit UIs that show “last changed by”.

An identity has three fields:

| Field       | Description                                                             |
| ----------- | ----------------------------------------------------------------------- |
| `subject`   | Stable unique identifier (e.g. a user UUID from your identity provider) |
| `name`      | Human-readable display name                                             |
| `user_name` | Login / username                                                        |

### Creating Identity

[Section titled “Creating Identity”](#creating-identity)

```elixir
alias Chronicle.Identity

# Create with subject, display name, and username
identity = Identity.new("user-42", "Alice Cooper", "alice")
```

Chronicle also provides three sentinel identities for well-known cases:

```elixir
Identity.system()    # automated processes or background workers
Identity.not_set()   # identity was not provided (default when none is set)
Identity.unknown()   # identity information could not be determined
```

### Process-Scoped Identity

[Section titled “Process-Scoped Identity”](#process-scoped-identity)

Set identity for your process, and all subsequent appends will include it automatically:

```elixir
alias Chronicle.Identity

identity = Identity.new("user-42", "Alice Cooper", "alice")
Chronicle.set_identity(identity)

# All appends now record Alice as the causer
:ok = Chronicle.append("account-42", %MyApp.Events.AccountOpened{...})
:ok = Chronicle.append("account-42", %MyApp.Events.FundsDeposited{...})

# Get the current identity
current = Chronicle.current_identity()

# Clear it when done
Chronicle.clear_identity()
```

### One-Off Identity Override

[Section titled “One-Off Identity Override”](#one-off-identity-override)

For a single append, override the process-scoped identity:

```elixir
identity = Identity.new("system", "Batch Processor", "batch")

:ok = Chronicle.append("account-42", event,
  identity: identity
)
```

### Switching Identity

[Section titled “Switching Identity”](#switching-identity)

In applications where a single process serves multiple users (e.g. a CLI tool, a test harness, or an admin console), you can switch the process-scoped identity between operations. Chronicle records the identity at the moment of each `append`, so different events in the same process can record different causers:

```elixir
alice = Identity.new("u-alice", "Alice Smith", "alice.smith")
bob   = Identity.new("u-bob",   "Bob Jones",   "bob.jones")

# Alice approves a leave request
Chronicle.set_identity(alice)
:ok = Chronicle.append(request_id, %LeaveApproved{approved_by: "u-alice"})

# Bob then archives it
Chronicle.set_identity(bob)
:ok = Chronicle.append(request_id, %RequestArchived{})
```

The event log now shows Alice caused the approval and Bob caused the archival, even though both happened in the same process.

### On-Behalf-Of / Delegation Chains

[Section titled “On-Behalf-Of / Delegation Chains”](#on-behalf-of--delegation-chains)

When a system actor performs an action on behalf of a human user, you can express this as a delegation chain. The `on_behalf_of` field links the acting identity to the originating identity:

```elixir
alias Chronicle.Identity

# The human who initiated the request
human = Identity.new("u-alice", "Alice Smith", "alice.smith")

# The system process acting on her behalf
system_acting = Identity.new(
  "s-workflow",
  "Workflow Engine",
  "workflow-engine",
  human  # on_behalf_of
)

Chronicle.set_identity(system_acting)
:ok = Chronicle.append("order-99", %OrderFulfilled{})
```

Chronicle records the full chain: “Workflow Engine (on behalf of Alice Smith)”. Use `Identity.without_duplicates/1` if you need to deduplicate subjects in a long chain.

## Causation Chains

[Section titled “Causation Chains”](#causation-chains)

Causation tracks the sequence of operations that led to an event. Each entry in the chain represents one step — a root action (e.g. an incoming HTTP request), followed by the commands or messages that triggered subsequent state changes. This chain is stored with every event, giving you a navigable audit trail you can replay forward from any point.

### Building Causation Chains

[Section titled “Building Causation Chains”](#building-causation-chains)

```elixir
alias Chronicle.Auditing.CausationManager

# Define the root cause (the initial action that started the chain)
CausationManager.define_root(%{application: "banking-api", version: "1.0"})

# Add the command that this request is executing
CausationManager.add("Banking.Commands.OpenAccount", %{account_id: "account-42"})

# Append events — each one is stored with the full causation chain
:ok = Chronicle.append("account-42", %MyApp.Events.AccountOpened{...})
:ok = Chronicle.append("account-42", %MyApp.Events.FundsDeposited{...})

# Clear for the next operation
CausationManager.clear()
```

### Causation Entries

[Section titled “Causation Entries”](#causation-entries)

Each entry in the chain is a `Chronicle.Auditing.CausationEntry` with a type and a map of properties. The type can be any string that identifies the operation — typically a fully-qualified command or message name:

```elixir
alias Chronicle.Auditing.CausationManager

# Root entry with metadata about the originating context
CausationManager.define_root(%{request_id: "req-1", source: "my-api"})

# Command step
CausationManager.add("MyApp.Commands.PlaceOrder", %{order_id: "order-99"})

# A second command triggered by the first (translation / saga step)
CausationManager.add("MyApp.Commands.ReserveInventory", %{sku: "ABC123", qty: 2})
```

### One-Off Causation Override

[Section titled “One-Off Causation Override”](#one-off-causation-override)

For a single append, pass a causation list directly:

```elixir
alias Chronicle.Auditing.CausationEntry

causation = [
  CausationEntry.new("MyApp.Commands.InitialRequest", %{request_id: "req-1"}),
  CausationEntry.new("MyApp.Commands.ProcessRequest", %{item_id: "item-1"})
]

:ok = Chronicle.append("resource-42", event, causation: causation)
```

## Typical Usage Pattern

[Section titled “Typical Usage Pattern”](#typical-usage-pattern)

Set up correlation, identity, and causation at the boundary of each request or operation. All appends inside that boundary inherit the context automatically.

```elixir
defmodule MyApp.Web.AccountController do
  alias Chronicle.{CorrelationId, Identity, Auditing.CausationManager}

def open_account(conn, params) do
    # --- Set up request context ---
    Chronicle.set_correlation_id(CorrelationId.create())
    Chronicle.set_identity(Identity.new(
      conn.assigns[:user_id],
      conn.assigns[:user_display_name],
      conn.assigns[:user_name]
    ))

CausationManager.clear()
    CausationManager.define_root(%{request_id: conn.assigns[:request_id]})
    CausationManager.add("MyApp.Commands.OpenAccount", %{account_id: params["account_id"]})

# --- Execute the operation ---
    case Chronicle.append(params["account_id"], %MyApp.Events.AccountOpened{...}) do
      :ok ->
        # --- Clean up ---
        Chronicle.clear_correlation_id()
        Chronicle.clear_identity()
        CausationManager.clear()
        send_resp(conn, 201, "Account created")

{:error, reason} ->
        send_resp(conn, 400, inspect(reason))
    end
  end
end
```

## Async/Spawn Considerations

[Section titled “Async/Spawn Considerations”](#asyncspawn-considerations)

Context is process-scoped using Elixir’s process dictionary. Spawned processes do not inherit context from their parent — capture and pass it explicitly:

```elixir
# Capture before spawning
correlation_id = Chronicle.current_correlation_id()
identity = Chronicle.current_identity()

spawn(fn ->
  Chronicle.set_correlation_id(correlation_id)
  Chronicle.set_identity(identity)
  Chronicle.append(...)
end)
```

## See Also

[Section titled “See Also”](#see-also)

* `Chronicle.CorrelationId` — correlation ID value type and parsing
* `Chronicle.Correlation.CorrelationIdManager` — process-scoped correlation handling
* `Chronicle.Identity` — identity value type, sentinel values, and `on_behalf_of` chains
* `Chronicle.Identity.IdentityProvider` — process-scoped identity handling
* `Chronicle.Auditing.CausationManager` — process-scoped causation chain building
* `Chronicle.Auditing.CausationEntry` — individual causation chain steps
* `Chronicle.Auditing.CausationType` — built-in causation entry type constants

# Event Sequences

Event sequences are a shared Chronicle concept. Use the shared docs for the event log, custom sequences, filtering, and appending behavior.

* [Event sequence concept](/chronicle/concepts/event-sequence/)
* [Events and event logs](/chronicle/events/)
* [Appending events](/chronicle/events/appending/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

The sections below cover `Chronicle.EventSequences.EventLog` APIs that are new to the Elixir client and not yet covered by the shared docs above.

## Redacting events

[Section titled “Redacting events”](#redacting-events)

Redaction permanently erases an event’s content for compliance/GDPR erasure. Unlike compliance encryption (reversible via key rotation), this overwrites the event’s content in the log for good. Mirrors the C# and TypeScript clients’ `IEventSequence.Redact()`.

Redact a single event by its sequence number, with a reason:

```elixir
:ok = Chronicle.EventSequences.EventLog.redact(sequence_number, "Customer requested erasure")
```

Redact every event for an event source in one call — for example, to erase all data for a specific user:

```elixir
:ok =
  Chronicle.EventSequences.EventLog.redact_for_event_source(
    event_source_id,
    "Account closed under GDPR"
  )
```

Narrow a bulk redaction to specific event types by passing a list of event type modules as the third argument:

```elixir
:ok =
  Chronicle.EventSequences.EventLog.redact_for_event_source(
    event_source_id,
    "Email address was captured in error",
    [MyApp.Events.EmailChanged]
  )
```

Both functions accept the same options as `append/3` (`:client`, `:namespace`, `:event_sequence_id`).

## Reading forward from a sequence number

[Section titled “Reading forward from a sequence number”](#reading-forward-from-a-sequence-number)

`get_from_sequence_number/2` returns events from (and including) a given sequence number onward, optionally filtered by event source id and event types. Mirrors the C# and TypeScript clients’ `GetFromSequenceNumber()`.

```elixir
{:ok, events} =
  Chronicle.EventSequences.EventLog.get_from_sequence_number(sequence_number,
    event_source_id: event_source_id,
    event_types: [MyApp.Events.OrderPlaced]
  )
```

## Sequence numbers

[Section titled “Sequence numbers”](#sequence-numbers)

`get_tail_sequence_number/2` returns the sequence number of the last appended event. `get_next_sequence_number/2` mirrors it but returns the number that will be assigned to the **next** appended event — it distinguishes “the log is empty” (returns `0`) from “the tail is at sequence `0`” (returns `1`), which `get_tail_sequence_number/2` alone cannot do. Mirrors the C# and TypeScript clients’ `GetNextSequenceNumber()`.

```elixir
{:ok, tail} = Chronicle.EventSequences.EventLog.get_tail_sequence_number(event_source_id)
{:ok, next} = Chronicle.EventSequences.EventLog.get_next_sequence_number(event_source_id)
```

`get_tail_sequence_number_for_observer/2` scopes the tail lookup to only the event types a reactor or reducer module subscribes to (its `@handles` declarations), instead of every event type. Mirrors the C# client’s `GetTailSequenceNumberForObserver()`.

```elixir
{:ok, tail} =
  Chronicle.EventSequences.EventLog.get_tail_sequence_number_for_observer(
    MyApp.Reactors.OrderNotifier
  )
```

## Filtering by stream

[Section titled “Filtering by stream”](#filtering-by-stream)

`get_for_event_source/2` and `get_tail_sequence_number/2` also accept `:event_source_type`, `:event_stream_type`, and `:event_stream_id` options, narrowing either call to a specific non-default stream instead of silently ignoring these dimensions:

```elixir
{:ok, events} =
  Chronicle.EventSequences.EventLog.get_for_event_source(event_source_id,
    event_stream_type: "audit-trail",
    event_stream_id: "2024"
  )
```

## Completing a stream

[Section titled “Completing a stream”](#completing-a-stream)

`complete_stream/3` closes a named, non-default stream so that no further events can be appended to it. The default stream can never be completed.

```elixir
case Chronicle.EventSequences.EventLog.complete_stream("audit-trail", "2024") do
  {:ok, tail_sequence_number} -> :ok
  {:error, :default_stream_cannot_be_completed} -> :error
  {:error, :already_completed} -> :ok
end
```

## Appending and waiting for observer completion

[Section titled “Appending and waiting for observer completion”](#appending-and-waiting-for-observer-completion)

`append_and_wait_for_completion/3` appends a single event and then waits (default: 5 seconds) for every observer affected by the append — reactors, reducers, projections — to either reach the appended sequence number or fail, instead of returning as soon as the event is durably stored. Mirrors the C# client’s `AppendResult.WaitForCompletion()`.

```elixir
case Chronicle.EventSequences.EventLog.append_and_wait_for_completion(
       event_source_id,
       %MyApp.Events.OrderPlaced{customer_id: customer_id, total: total}
     ) do
  {:ok, %{success: true, failed_partitions: []}} ->
    :ok

{:ok, %{success: false, failed_partitions: failed_partitions}} ->
    # One or more observers failed or timed out — inspect failed_partitions
    # (a list of `Chronicle.FailedPartitions.FailedPartition`).
    :error

{:error, reason} ->
    :error
end
```

Pass `:timeout` (milliseconds) to override the default wait.

# Event Store Subscriptions

Chronicle.Elixir supports event store subscriptions for importing events from one event store into another event store.

This is useful when you want one Chronicle event store to consume selected events from another store’s outbox without writing a reactor or webhook. See [Explicit event store subscriptions](/chronicle/subscriptions/explicit-subscriptions/) and [Outbox/inbox](/chronicle/subscriptions/outbox-inbox/) for the underlying concepts and how they apply across every client. This page adds the Elixir-specific **discoverable subscription module** pattern (`use Chronicle.EventStoreSubscriptions.Subscription`), which isn’t covered there.

## Two ways to register subscriptions

[Section titled “Two ways to register subscriptions”](#two-ways-to-register-subscriptions)

You can register subscriptions:

1. **Discoverably** with `use Chronicle.EventStoreSubscriptions.Subscription`
2. **Imperatively** with `Chronicle.EventStoreSubscriptions.subscribe/4`

`Chronicle.Client` can auto-discover and register subscription modules during startup, just like it does for reactors, reducers, read models, migrations, and webhooks.

## Discoverable subscriptions

[Section titled “Discoverable subscriptions”](#discoverable-subscriptions)

Define a module like this:

```elixir
defmodule MyApp.EventStoreSubscriptions.DefaultAccountEvents do
  use Chronicle.EventStoreSubscriptions.Subscription,
    source_event_store: "default"

alias Chronicle.EventStoreSubscriptions.DefinitionBuilder

### Options for `use Chronicle.EventStoreSubscriptions.Subscription`

[Section titled “Options for use Chronicle.EventStoreSubscriptions.Subscription”](#options-for-use-chronicleeventstoresubscriptionssubscription)

* `:source_event_store` — **required** name of the source event store to subscribe to
* `:id` — optional stable identifier for the subscription. Defaults to the module name.

The `define/1` callback receives a `Chronicle.EventStoreSubscriptions.DefinitionBuilder`. Return the builder after selecting event types.

If you do not specify any event types, Chronicle.Elixir uses all registered event types available to the client.

## Auto-registration with `Chronicle.Client`

[Section titled “Auto-registration with Chronicle.Client”](#auto-registration-with-chronicleclient)

Start `Chronicle.Client` with discovery enabled:

```elixir
children = [
  {Chronicle.Client,
   connection_string: "chronicle://localhost:35000",
   event_store: "target-store",
   otp_app: :my_app}
]
```

If your OTP application includes modules that use `Chronicle.EventStoreSubscriptions.Subscription`, the client discovers them and registers them automatically on startup.

You can also register discoverable subscriptions manually:

```elixir
:ok = Chronicle.register_event_store_subscription(MyApp.EventStoreSubscriptions.DefaultAccountEvents, client: MyApp.Chronicle)

:ok = Chronicle.register_discovered_event_store_subscriptions(client: MyApp.Chronicle)
```

## Imperative registration

[Section titled “Imperative registration”](#imperative-registration)

For one-off or runtime-defined subscriptions, register them directly:

```elixir
:ok =
  Chronicle.subscribe_to_event_store(
    "default-account-events",
    "default",
    fn builder ->
      builder
      |> Chronicle.EventStoreSubscriptions.DefinitionBuilder.with_event_type(
        MyApp.Events.AccountOpened
      )
      |> Chronicle.EventStoreSubscriptions.DefinitionBuilder.with_event_type(
        MyApp.Events.FundsDeposited
      )
    end
  )
```

The arguments are:

* subscription id
* source event store
* a function that configures the definition builder
* optional keyword options such as `client: MyApp.Chronicle`

## Removing subscriptions

[Section titled “Removing subscriptions”](#removing-subscriptions)

Remove a subscription by identifier:

```elixir
:ok = Chronicle.unsubscribe_from_event_store("default-account-events")
```

## Listing subscriptions

[Section titled “Listing subscriptions”](#listing-subscriptions)

`Chronicle.EventStoreSubscriptions.get_all/1` returns every event store subscription currently registered with the target event store. Mirrors the C# and Kotlin clients’ `IEventStoreSubscriptions.GetAll()`.

```elixir
{:ok, subscriptions} = Chronicle.EventStoreSubscriptions.get_all()

Enum.each(subscriptions, fn subscription ->
  IO.puts("#{subscription.id} <- #{subscription.source_event_store}")
end)
```

Each subscription is returned as a `%Chronicle.EventStoreSubscriptions.Definition{}` with:

* `:id` — the subscription’s identifier
* `:source_event_store` — the event store it imports events from
* `:event_types` — the `%Chronicle.EventStoreSubscriptions.EventType{}` list it subscribes to

## Definition builder

[Section titled “Definition builder”](#definition-builder)

`Chronicle.EventStoreSubscriptions.DefinitionBuilder` currently supports:

* `new/1`
* `with_event_type/2`
* `build/3`

Example:

```elixir
alias Chronicle.EventStoreSubscriptions.DefinitionBuilder

builder =
  DefinitionBuilder.new([MyApp.Events.AccountOpened, MyApp.Events.FundsDeposited])
  |> DefinitionBuilder.with_event_type(MyApp.Events.AccountOpened)
```

If `with_event_type/2` is never called, `build/3` uses all registered event types passed to `new/1`.

## Client options

[Section titled “Client options”](#client-options)

`Chronicle.Client` accepts:

* `:event_store_subscriptions` — explicit list of discoverable subscription modules
* `:discover` — enables or disables auto-discovery
* `:otp_app` — limits discovery to modules that belong to one OTP app

Explicit subscriptions are merged with discovered ones.

## Notes

[Section titled “Notes”](#notes)

* Event store subscriptions are registered against the client’s target event store.
* The source event store is defined per subscription.
* `:namespace` is accepted in the API option list for consistency with other Chronicle APIs, but it is not currently used by the subscription registration request.
* The current Chronicle contracts expose add/remove operations, so Chronicle.Elixir focuses on registration and removal APIs.

# Event Store Discovery

Chronicle Elixir provides APIs to query information about available event stores and their namespaces from the Chronicle kernel. This is useful for administrative tasks, multi-tenant applications, and debugging. See [Event Store](/chronicle/concepts/event-store/) and [Namespaces](/chronicle/concepts/namespaces/) for what these concepts mean and how they relate to multi-tenancy — this page covers the Elixir-specific discovery APIs for listing and verifying them at runtime.

## Getting Event Stores

[Section titled “Getting Event Stores”](#getting-event-stores)

Query all event store names from the Chronicle kernel:

```elixir
{:ok, stores} = Chronicle.get_event_stores()
# => {:ok, ["my-app", "crm", "analytics"]}
```

This is useful in multi-tenant or multi-application scenarios where you need to discover which event stores are available:

```elixir
case Chronicle.get_event_stores() do
  {:ok, stores} ->
    IO.puts("Available event stores: #{inspect(stores)}")
  {:error, reason} ->
    IO.puts("Failed to get event stores: #{inspect(reason)}")
end
```

## Getting Namespaces

[Section titled “Getting Namespaces”](#getting-namespaces)

Query all namespaces within an event store:

```elixir
# Use the configured client's event store
{:ok, namespaces} = Chronicle.get_namespaces()
# => {:ok, ["tenant-1", "tenant-2", "tenant-3"]}

# Specify a different event store
{:ok, namespaces} = Chronicle.get_namespaces(event_store: "analytics")
```

This is especially useful in multi-tenant applications:

```elixir
defmodule MyApp.Tenants do
  def list_all_tenants() do
    case Chronicle.get_namespaces() do
      {:ok, tenant_ids} -> tenant_ids
      {:error, _} -> []
    end
  end

def migrate_all_tenants(migration_func) do
    Enum.each(list_all_tenants(), fn tenant_id ->
      IO.puts("Migrating tenant: #{tenant_id}")
      migration_func.(tenant_id)
    end)
  end
end
```

## Typical Usage

[Section titled “Typical Usage”](#typical-usage)

### Multi-Tenant Admin Interface

[Section titled “Multi-Tenant Admin Interface”](#multi-tenant-admin-interface)

```elixir
defmodule MyApp.Admin.Dashboard do
  alias MyApp.Tenants

def get_system_stats() do
    with {:ok, stores} <- Chronicle.get_event_stores(),
         {:ok, namespaces} <- Chronicle.get_namespaces() do
      %{
        event_stores: stores,
        current_store_namespaces: namespaces,
        total_tenants: Enum.count(namespaces)
      }
    else
      {:error, reason} -> {:error, reason}
    end
  end

def list_tenant_info() do
    with {:ok, tenant_ids} <- Chronicle.get_namespaces() do
      Enum.map(tenant_ids, fn tenant_id ->
        %{
          id: tenant_id,
          event_store: "my-app",
          namespace: tenant_id
        }
      end)
    else
      {:error, reason} -> {:error, reason}
    end
  end
end
```

### Verifying Environment Before Operations

[Section titled “Verifying Environment Before Operations”](#verifying-environment-before-operations)

```elixir
defmodule MyApp.Operations do
  def safe_append(tenant_id, event) do
    with {:ok, namespaces} <- Chronicle.get_namespaces() do
      if Enum.member?(namespaces, tenant_id) do
        Chronicle.append("entity-123", event, namespace: tenant_id)
      else
        {:error, :tenant_not_found}
      end
    end
  end

def safe_read(tenant_id, entity_id) do
    with {:ok, namespaces} <- Chronicle.get_namespaces() do
      if Enum.member?(namespaces, tenant_id) do
        Chronicle.read_model(MyApp.ReadModels.Entity, entity_id, namespace: tenant_id)
      else
        {:error, :tenant_not_found}
      end
    end
  end
end
```

### Multi-Store Operations

[Section titled “Multi-Store Operations”](#multi-store-operations)

```elixir
defmodule MyApp.MultiStore do
  def list_all_entities() do
    with {:ok, stores} <- Chronicle.get_event_stores() do
      Enum.flat_map(stores, fn store_name ->
        case Chronicle.all(MyApp.ReadModels.Entity, client: store_name) do
          {:ok, entities} -> entities
          {:error, _} -> []
        end
      end)
    else
      {:error, _} -> []
    end
  end

def get_global_stats() do
    with {:ok, stores} <- Chronicle.get_event_stores() do
      Enum.map(stores, fn store_name ->
        with {:ok, namespaces} <- Chronicle.get_namespaces(event_store: store_name) do
          %{
            store: store_name,
            namespace_count: Enum.count(namespaces),
            namespaces: namespaces
          }
        else
          {:error, reason} -> %{store: store_name, error: reason}
        end
      end)
    end
  end
end
```

## Options

[Section titled “Options”](#options)

Both `get_event_stores/1` and `get_namespaces/1` accept options:

* `:client` — the client name (default: `Chronicle.Client`)
* `:event_store` — for `get_namespaces/1`, the event store to query (defaults to the configured client’s event store)

```elixir
# Use a named client
Chronicle.get_event_stores(client: :my_app_client)

# Query a specific event store's namespaces
Chronicle.get_namespaces(event_store: "crm")

# Both
Chronicle.get_namespaces(client: :analytics, event_store: "analytics")
```

## Error Handling

[Section titled “Error Handling”](#error-handling)

Both functions return `{:ok, list}` on success or `{:error, reason}` on failure:

```elixir
case Chronicle.get_namespaces() do
  {:ok, namespaces} ->
    IO.puts("Namespaces: #{inspect(namespaces)}")
  {:error, reason} ->
    case reason do
      :no_client -> IO.puts("Chronicle.Client not started")
      _ -> IO.puts("Error: #{inspect(reason)}")
    end
end
```

## See Also

[Section titled “See Also”](#see-also)

* `Chronicle.EventStores` — low-level event store discovery
* `Chronicle` — high-level API
* `README.md` — quick start guide
* Configuration options in `Chronicle.Client`
* [Event Store](/chronicle/concepts/event-store/) and [Namespaces](/chronicle/concepts/namespaces/) — the shared concepts behind event stores and namespace-scoped tenancy

# Events

Events and event logs are shared Chronicle topics. Use the shared docs for event modeling, event types, appending, querying, and evolution.

* [Events and event logs](/chronicle/events/)
* [Event concept](/chronicle/concepts/event/)
* [Appending events](/chronicle/events/appending/)
* [Event evolution](/chronicle/understanding-event-evolution/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

# External Services

`Chronicle.ExternalServices` provides an idiomatic Elixir API for registering external service definitions with Chronicle.

External services let the Chronicle kernel talk to systems outside the event store — an HTTP API or a MsSql/PostgreSql database — under a name other kernel features (such as captures) can reference. They are usually configured in the Workbench, but the Elixir client also exposes a programmatic API.

## Registering an HTTP service

[Section titled “Registering an HTTP service”](#registering-an-http-service)

```elixir
:ok =
  Chronicle.ExternalServices.register("CustomersApi", fn builder ->
    builder
    |> Chronicle.ExternalServices.DefinitionBuilder.http("https://api.example.com")
    |> Chronicle.ExternalServices.DefinitionBuilder.with_bearer_token(token)
    |> Chronicle.ExternalServices.DefinitionBuilder.with_header("X-Tenant", "acme")
  end)
```

`configure` receives a `Chronicle.ExternalServices.DefinitionBuilder` and must return it (or a continuation of it) once the endpoint is configured.

## Registering a database service

[Section titled “Registering a database service”](#registering-a-database-service)

```elixir
:ok =
  Chronicle.ExternalServices.register("CustomersDb", fn builder ->
    Chronicle.ExternalServices.DefinitionBuilder.postgre_sql(
      builder,
      "db.example.com",
      "customers",
      "postgres",
      password,
      5432
    )
  end)
```

Use `Chronicle.ExternalServices.DefinitionBuilder.ms_sql/6` instead for a Microsoft SQL Server endpoint — it takes the same host, database, username, password, and port arguments.

## Builder API

[Section titled “Builder API”](#builder-api)

`Chronicle.ExternalServices.DefinitionBuilder` is immutable and pipeline-friendly.

```elixir
builder
|> DefinitionBuilder.http("https://api.example.com")
|> DefinitionBuilder.with_basic_auth("user", "password")
|> DefinitionBuilder.with_bearer_token("token")
|> DefinitionBuilder.with_oauth("https://login.example.com", "client-id", "client-secret")
|> DefinitionBuilder.with_header("x-tenant", "acme")
```

* `http/2` configures an HTTP endpoint.
* `ms_sql/6` and `postgre_sql/6` configure a database endpoint — mutually exclusive with `http/2` and each other; the last call wins.
* `with_basic_auth/3`, `with_bearer_token/2`, and `with_oauth/4` are mutually exclusive with each other and only meaningful for HTTP endpoints.
* `with_header/3` adds or replaces an HTTP header sent with every request.
* `with_option/3` adds a provider-specific option to a database endpoint’s connection configuration.

## Using a named client

[Section titled “Using a named client”](#using-a-named-client)

```elixir
:ok =
  Chronicle.ExternalServices.register(
    "CustomersApi",
    fn builder -> Chronicle.ExternalServices.DefinitionBuilder.http(builder, "https://api.example.com") end,
    client: :bank_chronicle
  )
```

# Failed Partitions

`Chronicle.FailedPartitions` provides an idiomatic Elixir API for inspecting Chronicle’s failed partitions.

A partition (an event source, within an observer’s subscription) is marked failed when a reactor, reducer, or other observer’s handling of an event raises or returns an error. Failed partitions stop advancing until they are retried or the observer is replayed. Mirrors the C# and Kotlin clients’ `IFailedPartitions`.

## Starting point

[Section titled “Starting point”](#starting-point)

Start `Chronicle.Client` first:

```elixir
children = [
  {Chronicle.Client,
    connection_string: "chronicle://localhost:35000",
    event_store: "banking",
    otp_app: :my_app}
]
```

## Getting all failed partitions

[Section titled “Getting all failed partitions”](#getting-all-failed-partitions)

Get every failed partition for any observer (reactor, reducer, and so on) on the current event store:

```elixir
{:ok, failed_partitions} = Chronicle.FailedPartitions.get_all()
```

## Getting failed partitions for a specific observer

[Section titled “Getting failed partitions for a specific observer”](#getting-failed-partitions-for-a-specific-observer)

Narrow the lookup to a single observer by its id:

```elixir
{:ok, failed_partitions} = Chronicle.FailedPartitions.get_for("MyApp.Reactors.OrderNotifier")
```

## The `FailedPartition` and `Attempt` structs

[Section titled “The FailedPartition and Attempt structs”](#the-failedpartition-and-attempt-structs)

Each failed partition is returned as `%Chronicle.FailedPartitions.FailedPartition{}` with:

* `:id`
* `:observer_id`
* `:partition` — the event source id that failed
* `:attempts` — the list of failed attempts, oldest first

Each attempt is a `%Chronicle.FailedPartitions.Attempt{}` with:

* `:occurred`
* `:sequence_number`
* `:messages`
* `:stack_trace`

```elixir
Enum.each(failed_partitions, fn failed_partition ->
  IO.puts("#{failed_partition.observer_id}: #{failed_partition.partition}")

Enum.each(failed_partition.attempts, fn attempt ->
    IO.puts("  ##{attempt.sequence_number}: #{Enum.join(attempt.messages, "; ")}")
  end)
end)
```

## Using a named client

[Section titled “Using a named client”](#using-a-named-client)

```elixir
{:ok, failed_partitions} = Chronicle.FailedPartitions.get_all(client: :bank_chronicle)
```

# Get Started

This guide takes you from an empty project to a running Chronicle client that appends and reads events.

## Install

[Section titled “Install”](#install)

Add the client to your `mix.exs` dependencies:

```elixir
defp deps do
  [
    {:cratis_chronicle, "~> 2.2"}
  ]
end
```

Then fetch it:

```shell
mix deps.get
```

You also need a running Chronicle kernel. For local development, the kernel listens on `localhost:35000` over TLS, serving an auto-generated self-signed certificate — the client trusts it out of the box, no configuration needed.

## Define an event

[Section titled “Define an event”](#define-an-event)

```elixir
defmodule MyApp.Events.AccountOpened do
  use Chronicle.Events.EventType, id: "account-opened-v1"
  defstruct [:account_id, :owner_name, :initial_balance]
end
```

See [Event Types](/chronicle/clients/elixir/events/) for the full guide.

## Start the client

[Section titled “Start the client”](#start-the-client)

Add `Chronicle.Client` to your application’s supervision tree. With `otp_app:`, it discovers your event types, reactors, reducers, read models and seeders automatically:

```elixir
defmodule MyApp.Application do
  use Application

@impl true
  def start(_type, _args) do
    children = [
      {Chronicle.Client,
        connection_string: "chronicle://localhost:35000",
        event_store: "my-store",
        otp_app: :my_app}
    ]

Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
  end
end
```

The client connects in the background and recovers automatically if the connection drops. See [Resilience and the Connection Lifecycle](/chronicle/clients/elixir/connections/resilience/).

## Append an event

[Section titled “Append an event”](#append-an-event)

```elixir
:ok =
  Chronicle.append("account-1", %MyApp.Events.AccountOpened{
    account_id: "account-1",
    owner_name: "Alice",
    initial_balance: 500
  })
```

## Read it back

[Section titled “Read it back”](#read-it-back)

```elixir
{:ok, events} =
  Chronicle.EventSequences.EventLog.get_for_event_source("account-1")
```

## Where to next

[Section titled “Where to next”](#where-to-next)

* [Reducers](/chronicle/clients/elixir/reducers/) and [Reactors](/chronicle/clients/elixir/reactors/) to build read models and side effects from your events.
* [Read Models](/chronicle/clients/elixir/read-models/) and [Projections](/chronicle/clients/elixir/projections/) to query and shape projected state.
* [Constraints](/chronicle/clients/elixir/constraints/) for uniqueness and append-time invariants.
* [Event Sequences](/chronicle/clients/elixir/event-sequences/) and [Concurrency](/chronicle/clients/elixir/concurrency/) for the event log and optimistic concurrency.
* [Transactions](/chronicle/clients/elixir/transactions/) for unit-of-work semantics across appends.
* [Migrations](/chronicle/clients/elixir/migrations/) for evolving event schemas over time.
* [Compliance](/chronicle/clients/elixir/compliance/) for PII handling and GDPR erasure.
* [Connections](/chronicle/clients/elixir/connections/) to understand connection strings and resilience.

# Jobs

`Chronicle.Jobs` provides an idiomatic Elixir API for inspecting and controlling Chronicle jobs.

Jobs represent long-running Chronicle operations such as replays, rebuilds, and other background work performed by the Chronicle Kernel.

## Starting point

[Section titled “Starting point”](#starting-point)

Start `Chronicle.Client` first:

```elixir
children = [
  {Chronicle.Client,
    connection_string: "chronicle://localhost:35000",
    event_store: "banking",
    otp_app: :my_app}
]
```

Once the client is running, use `Chronicle.Jobs`:

```elixir
{:ok, jobs} = Chronicle.Jobs.all()
{:ok, job} = Chronicle.Jobs.get("8a6f5a0c-0fbf-42bd-8db0-a60f9a449b11")
{:ok, steps} = Chronicle.Jobs.steps("8a6f5a0c-0fbf-42bd-8db0-a60f9a449b11")
```

## API

[Section titled “API”](#api)

### List all jobs

[Section titled “List all jobs”](#list-all-jobs)

```elixir
{:ok, jobs} = Chronicle.Jobs.all()
```

Each job is returned as `%Chronicle.Jobs.Job{}` with:

* `:id`
* `:details`
* `:type`
* `:status`
* `:created_at`
* `:status_changes`
* `:progress`

### Get one job

[Section titled “Get one job”](#get-one-job)

```elixir
{:ok, job} = Chronicle.Jobs.get(job_id)
```

Returns `{:ok, nil}` when the job does not exist.

### Get job steps

[Section titled “Get job steps”](#get-job-steps)

```elixir
{:ok, steps} = Chronicle.Jobs.steps(job_id)
```

Each step is returned as `%Chronicle.Jobs.JobStep{}`.

### Stop, resume, and delete

[Section titled “Stop, resume, and delete”](#stop-resume-and-delete)

```elixir
:ok = Chronicle.Jobs.stop(job_id)
:ok = Chronicle.Jobs.resume(job_id)
:ok = Chronicle.Jobs.delete(job_id)
```

## Status values

[Section titled “Status values”](#status-values)

Job statuses are normalized to atoms:

* `:none`
* `:preparing_job`
* `:preparing_steps`
* `:starting_steps`
* `:running`
* `:completed_successfully`
* `:completed_with_failures`
* `:stopped`
* `:failed`
* `:removing`

Job-step statuses are normalized to atoms:

* `:unknown`
* `:scheduled`
* `:running`
* `:completed_successfully`
* `:completed_with_failure`
* `:stopped`
* `:failed`
* `:removing`

## Using a named client

[Section titled “Using a named client”](#using-a-named-client)

```elixir
{:ok, jobs} = Chronicle.Jobs.all(client: :bank_chronicle)
```

## Top-level convenience helpers

[Section titled “Top-level convenience helpers”](#top-level-convenience-helpers)

`Chronicle` also delegates to the jobs API:

```elixir
{:ok, jobs} = Chronicle.get_jobs()
{:ok, job} = Chronicle.get_job(job_id)
{:ok, steps} = Chronicle.get_job_steps(job_id)
:ok = Chronicle.stop_job(job_id)
```

# Migrations

Event type migrations are shared Chronicle behavior. The shared docs own the migration model and client-tabbed examples.

* [Understanding event evolution](/chronicle/understanding-event-evolution/)
* [Event type migrations concept](/chronicle/concepts/event-type-migrations/)
* [Migrations](/chronicle/migrations/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

# Projections

Projections are shared Chronicle read-model behavior. Use the shared docs for projection styles, model-bound projections, declarative projections, and client-tabbed examples.

* [Projections](/chronicle/projections/)
* [Choosing a read model style](/chronicle/projections/choosing-a-read-model-style/)
* [Model-bound projections](/chronicle/projections/model-bound/)
* [Declarative projections](/chronicle/projections/declarative/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

# Reactors

Reactors are documented in the shared Chronicle docs with synchronized examples for C#, Kotlin, Java, Elixir, and TypeScript.

* [Getting started with reactors](/chronicle/reactors/getting-started/)
* [Reactor event processing](/chronicle/reactors/event-processing/)
* [Reactors overview](/chronicle/reactors/)

Use the [Elixir get started page](/chronicle/clients/elixir/get-started/) for client startup and supervision setup.

## Side-effect appending

[Section titled “Side-effect appending”](#side-effect-appending)

`handle/2` can return `{:ok, event_or_events}` in addition to `:ok`/`{:error, reason}`, and Chronicle.Elixir appends the returned event(s) as a side effect right after `handle/2` returns. Mirrors C#‘s `Reactors/SideEffects` and Kotlin’s `ReactorsService.appendSideEffects`.

Returning a single event struct appends it to the same event source that triggered the handler:

```elixir
defmodule MyApp.Reactors.OrderNotifier do
  use Chronicle.Reactors.Reactor

alias MyApp.Events.{OrderPlaced, OrderConfirmationQueued}

@handles OrderPlaced

@impl true
  def handle(%OrderPlaced{} = event, _context) do
    {:ok, %OrderConfirmationQueued{customer_id: event.customer_id}}
  end
end
```

Return a list of events to append them all atomically to that same event source. To target a **different** event source, wrap the event in a `Chronicle.EventSequences.EventForEventSourceId`; a list of these (optionally mixed with bare event structs, which are normalized to the triggering event source) is appended atomically across all their event source ids in one call.

If appending the side effect fails, `handle/2`’s overall result becomes `{:error, reason}` — reported the same way as a plain `{:error, reason}` return.

## Replay lifecycle hooks

[Section titled “Replay lifecycle hooks”](#replay-lifecycle-hooks)

Implement any of `on_replay_begin/0`, `on_replay_end/0`, `on_partition_replay_begin/1`, or `on_partition_replay_end/1` to be notified when Chronicle starts or finishes replaying this reactor — either as a whole, or for a single partition (event source). All four are optional. Mirrors C#‘s `ICanBeNotifiedWhenReplay` / `ICanBeNotifiedWhenPartitionReplayed`.

```elixir
defmodule MyApp.Reactors.ReplayAwareNotifier do
  use Chronicle.Reactors.Reactor

require Logger

alias MyApp.Events.OrderPlaced

@handles OrderPlaced

@impl true
  def handle(%OrderPlaced{}, _context), do: :ok

@impl true
  def on_replay_begin, do: Logger.info("Replay starting")

@impl true
  def on_replay_end, do: Logger.info("Replay finished")
end
```

These are notifications, not events to handle — they run outside normal `handle/2` dispatch, are not subject to failed-partition tracking, and a raised exception is logged and swallowed rather than reported to Chronicle.

# Read Models

Read models are shared Chronicle concepts. Querying, snapshots, watching, and consistency are documented in the shared Chronicle section.

* [Read models](/chronicle/read-models/)
* [Getting a single read model](/chronicle/read-models/getting-single-instance/)
* [Getting read model collections](/chronicle/read-models/getting-collection-instances/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

## Watching for live changes

[Section titled “Watching for live changes”](#watching-for-live-changes)

`Chronicle.ReadModels.watch/2` subscribes the calling process to live changesets for a read model over the kernel’s server-streaming `Watch` RPC. Elixir has no `IObservable`/ async-iterable equivalent to the C# and TypeScript clients’ `Watch<TReadModel>()`, so this follows the same message-based idiom as `Chronicle.Connections.Lifecycle.subscribe/1`.

```elixir
{:ok, watcher} = Chronicle.ReadModels.watch(MyApp.ReadModels.AccountInfo)

receive do
  {:chronicle_read_model_changed, MyApp.ReadModels.AccountInfo, changeset} ->
    # changeset is a %Chronicle.ReadModels.Changeset{} with :model_key, :read_model,
    # :change_type (:added | :modified | :removed), :event_sequence_number, and more.
    IO.inspect(changeset.read_model)

{:chronicle_read_model_watch_error, MyApp.ReadModels.AccountInfo, reason} ->
    # The stream failed and the watch has ended — call watch/2 again to resume.
    IO.inspect(reason)
end

Chronicle.ReadModels.unwatch(watcher)
```

## Dehydrating a session

[Section titled “Dehydrating a session”](#dehydrating-a-session)

A read-model session (created implicitly whenever you read with a `:session_id`) normally expires on its own. `dehydrate_session/4` explicitly cleans one up once the caller is done with it, releasing the resources Chronicle held for it right away.

```elixir
:ok =
  Chronicle.ReadModels.dehydrate_session(
    MyApp.ReadModels.AccountInfo,
    account_id,
    session_id
  )
```

# Reducers

Reducers are shared Chronicle read-model behavior. Use the shared reducer docs for the model, lifecycle, filtering, and client-tabbed examples.

* [Reducers](/chronicle/reducers/)
* [Getting started with reducers](/chronicle/reducers/getting-started/)
* [Reducer event processing](/chronicle/reducers/event-processing/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

## Passive reducers

[Section titled “Passive reducers”](#passive-reducers)

`use Chronicle.Reducers.Reducer` accepts an `:active` option, defaulting to `true`. Set it to `false` for a **passive** reducer: its read model is only computed on demand (e.g. via `Chronicle.ReadModels.get_instance_by_id/3`) instead of being kept warm in the background as events are appended — useful for a reducer whose read model backs a command-side decision that’s read rarely, where continuous observation would be wasted work. Mirrors C#‘s `ReducerAttribute.IsActive`.

```elixir
defmodule MyApp.Reducers.AccountReducer do
  use Chronicle.Reducers.Reducer, model: MyApp.ReadModels.AccountInfo, active: false

alias MyApp.Events.OrderPlaced

@handles OrderPlaced

@impl true
  def reduce(%OrderPlaced{}, model, _context), do: model
end
```

## Replay lifecycle hooks

[Section titled “Replay lifecycle hooks”](#replay-lifecycle-hooks)

Reducers support the same optional `on_replay_begin/0`, `on_replay_end/0`, `on_partition_replay_begin/1`, and `on_partition_replay_end/1` callbacks as reactors — see [Replay lifecycle hooks](/chronicle/clients/elixir/reactors/#replay-lifecycle-hooks) for details. They run outside normal `reduce/3` dispatch and are not events to reduce.

# Seeding

This page shows how to seed events using the Chronicle Elixir client. Seeding is sent to the Chronicle Server when the event store connects, and the server applies it once per namespace. See [Event Seeding](/chronicle/event-seeding/) for the concept this page assumes.

## Define events

[Section titled “Define events”](#define-events)

```elixir
defmodule MyApp.Events.AccountOpened do
  use Chronicle.Events.EventType, id: "account-opened"

defstruct [:account_id, :owner_name, :initial_balance]
end

defmodule MyApp.Events.FundsDeposited do
  use Chronicle.Events.EventType, id: "funds-deposited"

defstruct [:account_id, :amount]
end
```

## Implement a seeder

[Section titled “Implement a seeder”](#implement-a-seeder)

Use `Chronicle.Seeding.Seeder` and implement the `seed/1` callback:

```elixir
defmodule MyApp.Seeders.AccountSeeder do
  use Chronicle.Seeding.Seeder

alias MyApp.Events.{AccountOpened, FundsDeposited}

@impl true
  def seed(builder) do
    builder
    |> Chronicle.Seeding.for(AccountOpened, "account-1", [
      %AccountOpened{account_id: "account-1", owner_name: "Alice", initial_balance: 1000}
    ])
  end
end
```

```elixir
# Explicit
{Chronicle.Client,
  connection_string: "chronicle://localhost:35000",
  event_store: "banking",
  seeders: [MyApp.Seeders.AccountSeeder]}

# Auto-discovery (enabled by default when otp_app is set)
{Chronicle.Client,
  connection_string: "chronicle://localhost:35000",
  event_store: "banking",
  otp_app: :my_app}
```

## Seed multiple events of the same type

[Section titled “Seed multiple events of the same type”](#seed-multiple-events-of-the-same-type)

`Chronicle.Seeding.for/4` seeds one or more events of the same type for a single event source:

```elixir
def seed(builder) do
  builder
  |> Chronicle.Seeding.for(AccountOpened, "account-1", [
    %AccountOpened{account_id: "account-1", owner_name: "Alice", initial_balance: 1000}
  ])
  |> Chronicle.Seeding.for(AccountOpened, "account-2", [
    %AccountOpened{account_id: "account-2", owner_name: "Bob", initial_balance: 500}
  ])
end
```

## Seed mixed event types

[Section titled “Seed mixed event types”](#seed-mixed-event-types)

`Chronicle.Seeding.for_event_source/3` seeds several different event types for the same event source:

```elixir
def seed(builder) do
  builder
  |> Chronicle.Seeding.for_event_source("account-1", [
    %AccountOpened{account_id: "account-1", owner_name: "Alice", initial_balance: 1000},
    %FundsDeposited{account_id: "account-1", amount: 500}
  ])
end
```

## Namespace-scoped seed data

[Section titled “Namespace-scoped seed data”](#namespace-scoped-seed-data)

By default, seed data applies to all namespaces in the event store. To target a specific namespace, use `Chronicle.Seeding.for_namespace/3`:

```elixir
def seed(builder) do
  builder
  |> Chronicle.Seeding.for_namespace("production", fn scoped ->
    scoped
    |> Chronicle.Seeding.for(AccountOpened, "account-1", [
      %AccountOpened{account_id: "account-1", owner_name: "Alice", initial_balance: 1000}
    ])
  end)
end
```

The scoped builder supports the same `for/4` and `for_event_source/3` functions as the top-level builder. Each namespace receives only its own scoped events in addition to any global events.

## How it runs

[Section titled “How it runs”](#how-it-runs)

* Seeders are discovered and executed once during `Chronicle.Client` initialization.
* All seeders are invoked, accumulating their events, then all events are sent to Chronicle in a single batch.
* The server deduplicates seeded events and applies them once per namespace.
* Seeders should be idempotent — if your application restarts, seeders run again, and Chronicle’s event log handles duplicates based on your event constraints.
* Errors in a seeder are logged but don’t prevent other seeders from running or the client from starting.

## Best practices

[Section titled “Best practices”](#best-practices)

* Keep seed data minimal and deterministic.
* Use clear event source IDs to make debugging easier.
* Use `:id` on `use Chronicle.Seeding.Seeder` only if you need a stable identifier for tooling — it doesn’t affect seeding behavior, since seeders run once per startup rather than being tracked by the server.
* Use `for_namespace/3` when seed data is tenant-specific or environment-specific to avoid polluting other namespaces.

# Seeding

Event seeding is shared Chronicle behavior. The shared docs cover when to seed and how client APIs express seed data.

* [Event seeding](/chronicle/event-seeding/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

# Sinks

See [Sinks](/chronicle/sinks/) for what a sink is and the storage backends Chronicle ships with. This page covers Elixir-specific configuration: setting the default sink per client, running multiple clients with different sinks, and the `Chronicle.Sinks.WellKnownSinkTypes` reference.

## Default sink

[Section titled “Default sink”](#default-sink)

Unless configured otherwise, Chronicle writes read models into MongoDB. You do not need to set anything — the default is correct for most applications.

## Changing the default sink

[Section titled “Changing the default sink”](#changing-the-default-sink)

Pass `:default_sink_type_id` when starting `Chronicle.Client`:

```elixir
{Chronicle.Client,
  connection_string: "chronicle://localhost:35000",
  event_store: "my-store",
  default_sink_type_id: :sql,
  read_models: [MyApp.ReadModels.Account],
  reducers: [MyApp.Reducers.AccountReducer]}
```

The option accepts an atom from `Chronicle.Sinks.WellKnownSinkTypes` or a raw string identifier for custom sink types:

| Atom         | String       | Storage backend                       |
| ------------ | ------------ | ------------------------------------- |
| `:mongodb`   | `"MongoDB"`  | MongoDB (default)                     |
| `:sql`       | `"SQL"`      | SQL database                          |
| `:in_memory` | `"InMemory"` | In-process memory only                |
| `:not_set`   | `"NotSet"`   | No sink — read model is not persisted |

The configured sink applies to **all** projections and reducers registered by that client instance. There is no per-read-model sink override at this time.

## Multiple clients with different sinks

[Section titled “Multiple clients with different sinks”](#multiple-clients-with-different-sinks)

If your application needs some read models in MongoDB and others in SQL, start two separate `Chronicle.Client` instances with different names and assign the relevant read models to each:

```elixir
children = [
  {Chronicle.Client,
   name: :mongo_client,
   connection_string: "chronicle://localhost:35000",
   event_store: "store",
   default_sink_type_id: :mongodb,
   read_models: [MyApp.ReadModels.AccountSummary]},

{Chronicle.Client,
   name: :sql_client,
   connection_string: "chronicle://localhost:35000",
   event_store: "store",
   default_sink_type_id: :sql,
   read_models: [MyApp.ReadModels.AccountReport]}
]

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

Pass `:client` when querying to target the right instance:

```elixir
{:ok, summary} = Chronicle.ReadModels.get(MyApp.ReadModels.AccountSummary, id, client: :mongo_client)
{:ok, report} = Chronicle.ReadModels.get(MyApp.ReadModels.AccountReport, id, client: :sql_client)
```

## Reference — `Chronicle.Sinks.WellKnownSinkTypes`

[Section titled “Reference — Chronicle.Sinks.WellKnownSinkTypes”](#reference--chroniclesinkswellknownsinktypes)

| Function                         | Returns                                |
| -------------------------------- | -------------------------------------- |
| `WellKnownSinkTypes.mongodb/0`   | `"MongoDB"`                            |
| `WellKnownSinkTypes.sql/0`       | `"SQL"`                                |
| `WellKnownSinkTypes.in_memory/0` | `"InMemory"`                           |
| `WellKnownSinkTypes.not_set/0`   | `"NotSet"`                             |
| `WellKnownSinkTypes.resolve/1`   | Resolves an atom or passthrough string |

`resolve/1` is used internally by `Chronicle.Client` to normalise the `:default_sink_type_id` option. You rarely need to call it directly, but it is useful when building custom tooling or test helpers:

```elixir
alias Chronicle.Sinks.WellKnownSinkTypes

WellKnownSinkTypes.resolve(:mongodb)    # => "MongoDB"
WellKnownSinkTypes.resolve(:sql)        # => "SQL"
WellKnownSinkTypes.resolve("Custom")    # => "Custom"
```

# Transactions and Unit of Work

Unit-of-work transactions are now documented as a shared Chronicle workflow with synchronized client examples.

* [Transactions and unit of work](/chronicle/events/transactions/)
* [Appending many events](/chronicle/events/appending-many/)
* [Elixir client setup](/chronicle/clients/elixir/get-started/)

# WebHooks

`Chronicle.WebHooks` provides an idiomatic Elixir API for registering and inspecting Chronicle webhooks.

Webhooks let Chronicle push observed events to external HTTP endpoints.

## Discoverable webhooks

[Section titled “Discoverable webhooks”](#discoverable-webhooks)

Discoverable webhooks follow the same pattern as projections and constraints: define them as modules and Chronicle exposes metadata through `__chronicle_webhook__/1`.

```elixir
defmodule MyApp.WebHooks.AccountEvents do
  use Chronicle.WebHooks.Webhook,
    id: "account-events",
    target_url: "https://example.com/chronicle/webhooks",
    event_sequence_id: "event-log"

alias Chronicle.WebHooks.DefinitionBuilder

@impl true
  def define(builder) do
    builder
    |> DefinitionBuilder.with_event_type(MyApp.Events.AccountOpened)
    |> DefinitionBuilder.with_event_type(MyApp.Events.FundsDeposited)
    |> DefinitionBuilder.with_header("x-source", "my-app")
    |> DefinitionBuilder.with_bearer_token(System.fetch_env!("WEBHOOK_TOKEN"))
  end
end
```

When `Chronicle.Client` starts with `otp_app: :my_app`, discoverable webhooks are found automatically and registered on startup.

```elixir
{Chronicle.Client,
  connection_string: "chronicle://localhost:35000",
  event_store: "banking",
  otp_app: :my_app}
```

You can also register explicit modules:

```elixir
{Chronicle.Client,
  connection_string: "chronicle://localhost:35000",
  event_store: "banking",
  webhooks: [MyApp.WebHooks.AccountEvents]}
```

## Imperative registration

[Section titled “Imperative registration”](#imperative-registration)

```elixir
:ok =
  Chronicle.WebHooks.register(
    "account-events",
    "https://example.com/chronicle/webhooks",
    fn builder ->
      builder
      |> Chronicle.WebHooks.DefinitionBuilder.with_event_type(MyApp.Events.AccountOpened)
      |> Chronicle.WebHooks.DefinitionBuilder.with_basic_auth("chronicle", "secret")
      |> Chronicle.WebHooks.DefinitionBuilder.with_header("x-source", "my-app")
    end
  )
```

## Builder API

[Section titled “Builder API”](#builder-api)

`Chronicle.WebHooks.DefinitionBuilder` is immutable and pipeline-friendly.

```elixir
builder
|> DefinitionBuilder.on_event_sequence("audit-sequence")
|> DefinitionBuilder.with_event_type(MyApp.Events.AccountOpened)
|> DefinitionBuilder.with_basic_auth("user", "password")
|> DefinitionBuilder.with_bearer_token("token")
|> DefinitionBuilder.with_oauth("https://login.example.com", "client-id", "client-secret")
|> DefinitionBuilder.with_header("x-source", "my-app")
|> DefinitionBuilder.not_replayable()
|> DefinitionBuilder.not_active()
```

If no event types are configured explicitly, the builder uses all event types registered for the current client.

## Query and remove webhooks

[Section titled “Query and remove webhooks”](#query-and-remove-webhooks)

```elixir
{:ok, webhooks} = Chronicle.WebHooks.all()
:ok = Chronicle.WebHooks.remove("account-events")
```

Registered webhooks are returned as `%Chronicle.WebHooks.Definition{}` with:

* `:id`
* `:event_sequence_id`
* `:event_types`
* `:target`
* `:replayable?`
* `:active?`

The nested `%Chronicle.WebHooks.Target{}` contains:

* `:url`
* `:headers`
* `:authorization`

Authorization is normalized to one of:

* `{:basic, %{username: ..., password: ...}}`
* `{:bearer, %{token: ...}}`
* `{:oauth, %{authority: ..., client_id: ..., client_secret: ...}}`
* `nil`

## Manual discovery

[Section titled “Manual discovery”](#manual-discovery)

```elixir
webhooks = Chronicle.WebHooks.discover()
:ok = Chronicle.WebHooks.register_discovered()
```

## Top-level convenience helpers

[Section titled “Top-level convenience helpers”](#top-level-convenience-helpers)

`Chronicle` also delegates to the webhook API:

```elixir
{:ok, webhooks} = Chronicle.get_webhooks()
:ok = Chronicle.register_discovered_webhooks()
:ok = Chronicle.remove_webhook("account-events")
```

# Chronicle Kotlin Client

The Chronicle Kotlin client is the JVM SDK for Chronicle. It wraps the Chronicle gRPC contracts with Kotlin-native constructs such as coroutines, data classes, and annotations.

Use this section for Kotlin and Java setup, runtime integration, annotations, and API reference details. Shared Chronicle concepts and workflows live in the main Chronicle docs and use language tabs when code differs by client.

## Shared Chronicle topics

[Section titled “Shared Chronicle topics”](#shared-chronicle-topics)

## Kotlin and Java setup

[Section titled “Kotlin and Java setup”](#kotlin-and-java-setup)

You need a running Chronicle Kernel. The simplest way is Docker Compose. Chronicle serves gRPC, the API, and health checks on port `35000` over TLS with a self-signed development certificate:

```yaml
services:
  chronicle:
    image: cratis/chronicle:latest-development-slim
    depends_on:
      - mongodb
      - mongodb-init
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - Cratis__Chronicle__Storage__Type=MongoDB
      - Cratis__Chronicle__Storage__ConnectionDetails=mongodb://mongodb:27017/?directConnection=true
    ports:
      - "35000:35000"

mongodb:
    image: mongo:8.2
    command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
    ports:
      - "27017:27017"

# Chronicle's MongoDB storage needs a replica set — initiate it once.
  mongodb-init:
    image: mongo:8.2
    depends_on:
      - mongodb
    restart: "no"
    command:
      - /bin/bash
      - -lc
      - |
        until mongosh --host mongodb --quiet \
          --eval "db.adminCommand('ping')" >/dev/null 2>&1; do
          sleep 1
        done
        mongosh --host mongodb --quiet --eval "
        try {
          rs.status();
        } catch (e) {
          rs.initiate({
            _id: 'rs0',
            members: [{ _id: 0, host: 'mongodb:27017' }]
          });
        }"
```

Chronicle is ready once `curl -sk https://localhost:35000/health` reports `Healthy`. The `Samples/Kotlin/Console` and `Samples/Java/Console` folders in the repository contain this file along with PostgreSQL, SQL Server, and SQLite profiles.

Then add the client to your Gradle build:

```kotlin
dependencies {
    implementation("io.cratis:chronicle:2.1.2")
}
```

The same JVM client supports both Kotlin and Java. Shared pages include separate Kotlin and Java tabs when both examples exist.

Spring Boot applications add the starter instead — it brings the client with it and wires everything up:

```kotlin
dependencies {
    implementation("io.cratis:chronicle-spring-boot-starter:2.1.1")
}
```

## Client-specific pages

[Section titled “Client-specific pages”](#client-specific-pages)

* [Get Started](/chronicle/clients/kotlin/get-started/) — install the JVM client, connect, and run a small Kotlin flow
* [Artifact Registration](/chronicle/clients/kotlin/guides/artifact-registration/) — how artifacts are discovered and registered, and how to narrow or turn that off
* [Spring Boot](/chronicle/clients/kotlin/guides/spring-boot/) — the starter, multi-tenancy, and per-request identity, causation and units of work
* [Reference](/chronicle/clients/kotlin/reference/) — annotations, configuration, and service API details

# Concepts

Chronicle concepts are documented once in the shared Chronicle docs. The Kotlin client pages only cover Kotlin and Java setup, annotations, and API details.

Use these shared pages for the concepts:

* [Events](/chronicle/concepts/event/)
* [Event sources](/chronicle/concepts/event-source/)
* [Observers](/chronicle/concepts/observers/)
* [Read models](/chronicle/read-models/)
* [Projections](/chronicle/projections/)
* [Reactors](/chronicle/reactors/)
* [Reducers](/chronicle/reducers/)

Shared examples use synchronized C#, Kotlin, Java, Elixir, and TypeScript tabs when the client APIs differ.

For JVM-specific syntax, see the [annotation reference](/chronicle/clients/kotlin/reference/annotations/).

# Events

Events are documented in the shared Chronicle docs so the concepts stay the same across C#, Kotlin, Java, Elixir, and TypeScript.

* [Event concept](/chronicle/concepts/event/)
* [Event types](/chronicle/concepts/event-type/)
* [Event source identity](/chronicle/concepts/event-source/)
* [Appending events](/chronicle/events/appending/)
* [Event evolution](/chronicle/understanding-event-evolution/)

For JVM syntax, see the [annotation reference](/chronicle/clients/kotlin/reference/annotations/).

# Observers

Observers are documented in the shared Chronicle docs. Use those pages for the conceptual model and examples that apply across clients.

* [Observer concepts](/chronicle/concepts/observers/)
* [Reactors](/chronicle/reactors/)
* [Reducers](/chronicle/reducers/)
* [Projections](/chronicle/projections/)

For JVM syntax, see the [annotation reference](/chronicle/clients/kotlin/reference/annotations/) and [EventStore API reference](/chronicle/clients/kotlin/reference/event-store-api/).

# Read Models

Read models are documented in the shared Chronicle docs so the model stays consistent across clients.

* [Read models](/chronicle/read-models/)
* [Getting a single read model instance](/chronicle/read-models/getting-single-instance/)
* [Projections](/chronicle/projections/)
* [Reducers](/chronicle/reducers/)

For JVM syntax, see the [annotation reference](/chronicle/clients/kotlin/reference/annotations/) and [EventStore API reference](/chronicle/clients/kotlin/reference/event-store-api/).

## Kotlin client: `IReadModelsService`

[Section titled “Kotlin client: IReadModelsService”](#kotlin-client-ireadmodelsservice)

Beyond `getInstanceByKey`, the Kotlin client’s `store.readModels` exposes a richer surface for reading and managing read model instances:

| Member                  | Use it for                                             |
| ----------------------- | ------------------------------------------------------ |
| `getInstances`          | Every instance, replaying events in-process.           |
| `getSnapshotsById`      | Snapshots of a read model grouped by correlation id.   |
| `watch`                 | A `Flow` of changesets for a read model — a live view. |
| `dehydrateSession`      | Releasing session-scoped state for an instance.        |
| `release`/`releaseMany` | Decrypts `@Pii` properties, one or many.               |
| `materialized`          | Paginated, server-materialized reads — see below.      |

To react to changes without collecting a `Flow` yourself, write a convention-dispatched reactor instead — see [Read Model Reactors](/chronicle/clients/kotlin/guides/read-model-reactors/).

`getSnapshotsById` and `watch` both deserialize straight into the read model type you ask for — `getSnapshotsById(EmployeeProfile::class, key)` returns `List<ReadModelSnapshot<EmployeeProfile>>`, and `watch(EmployeeProfile::class)` returns `Flow<ReadModelChangeset<EmployeeProfile>>` — no manual JSON parsing either way.

```kotlin
val employees = store.readModels.getInstances(EmployeeProfile::class)
employees.forEach { employee ->
    println("${employee.firstName} ${employee.lastName}")
}
```

### Materialized (server-side) reads

[Section titled “Materialized (server-side) reads”](#materialized-server-side-reads)

`store.readModels.materialized` provides paginated access to instances a sink has already materialized server-side, instead of replaying events in-process:

```kotlin
val page = store.readModels.materialized.getInstances(
    EmployeeProfile::class,
    skip = 0,
    take = 50
)

store.readModels.materialized
    .observeInstances(EmployeeProfile::class, skip = 0, take = 50)
    .collect { updatedPage -> /* re-render whenever the page changes */ }
```

`getInstances` returns a single page; `observeInstances` returns a `Flow` that emits a fresh page every time the underlying data changes.

# Get Started

By the end of this guide you will have a Kotlin or Java application that appends events to Chronicle and reads a projected read model back. The entire example is a self-contained Gradle project.

## Prerequisites

[Section titled “Prerequisites”](#prerequisites)

* JDK 17 or later
* A running Chronicle Kernel (see the [Docker Compose snippet](/chronicle/clients/kotlin/./))
* Gradle 8+

## 1. Add the dependency

[Section titled “1. Add the dependency”](#1-add-the-dependency)

The client is published to Maven Central as `io.cratis:chronicle`.

### Kotlin Setup

[Section titled “Kotlin Setup”](#kotlin-setup)

build.gradle.kts

```kotlin
dependencies {
    implementation("io.cratis:chronicle:2.1.2")
}
```

### Java Setup

[Section titled “Java Setup”](#java-setup)

build.gradle

```groovy
dependencies {
    implementation 'io.cratis:chronicle:2.1.2'
}
```

## 2. Connect to the kernel

[Section titled “2. Connect to the kernel”](#2-connect-to-the-kernel)

`ChronicleClient` is the entry point, and it takes a `ChronicleOptions`. For local development use the `development()` factory, which points at `localhost:35000` over TLS with the standard development credentials:

### Kotlin Development Setup

[Section titled “Kotlin Development Setup”](#kotlin-development-setup)

```kotlin
import io.cratis.chronicle.ChronicleClient
import io.cratis.chronicle.ChronicleOptions

val client = ChronicleClient(ChronicleOptions.development())
val store = client.getEventStore("MyApp")
```

### Java Development Setup

[Section titled “Java Development Setup”](#java-development-setup)

Java goes through `BlockingChronicleClient`, which is the same client with the coroutines taken off — see [step 3](#3-suspend-functions-and-java-interop).

```java
import io.cratis.chronicle.ChronicleOptions;
import io.cratis.chronicle.java.BlockingChronicleClient;
import io.cratis.chronicle.java.BlockingEventStore;

var client = BlockingChronicleClient.connect(ChronicleOptions.development());
BlockingEventStore store = client.getEventStore("MyApp");
```

For anything other than local development, supply a connection string. The grammar is `chronicle://<user>:<password>@<host>[:<port>][,<host>...][?<options>]` — see [Configuration](/chronicle/clients/kotlin/reference/configuration/) for the full set of hosts, options, and the `chronicle+srv://` form.

### Kotlin Production Setup

[Section titled “Kotlin Production Setup”](#kotlin-production-setup)

```kotlin
val client = ChronicleClient(
    ChronicleOptions.fromConnectionString(
        "chronicle://my-client:my-secret@chronicle.internal:35000"
    )
)
```

### Java Production Setup

[Section titled “Java Production Setup”](#java-production-setup)

```java
var client = BlockingChronicleClient.connect(
    ChronicleOptions.fromConnectionString(
        "chronicle://my-client:my-secret@chronicle.internal:35000"
    )
);
```

## 3. Suspend functions and Java interop

[Section titled “3. Suspend functions and Java interop”](#3-suspend-functions-and-java-interop)

Every call that talks to the kernel — appending, registering, querying — is a Kotlin `suspend` function. In Kotlin, call them from a coroutine; `runBlocking` is fine for a console application:

```kotlin
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val client = ChronicleClient(ChronicleOptions.development())
    val store = client.getEventStore("MyApp")
    // everything below happens inside this coroutine
}
```

Java cannot call a `suspend` function at all — it carries a hidden continuation on the JVM. So Java uses `BlockingChronicleClient`, the same client with the waiting done for it:

```java
import io.cratis.chronicle.ChronicleOptions;
import io.cratis.chronicle.java.BlockingChronicleClient;

class JavaMain {
    void run() {
        var client = BlockingChronicleClient.connect(ChronicleOptions.development());
        var store = client.getEventStore("MyApp");
        // everything below is an ordinary blocking call
    }
}
```

Each call blocks until the kernel answers, which is what a `main`, a controller method or a scheduled job wants. `unwrap()` on any of these returns the suspending object underneath, and `io.cratis.chronicle.java` also holds lower-level static bridges for the corners the blocking client does not wrap — see [Java interop](/chronicle/clients/kotlin/reference/event-store-api/#java-interop).

## 4. Define an event type

[Section titled “4. Define an event type”](#4-define-an-event-type)

Annotate a data class or Java record with `@EventType`. The class name is used as the identifier, so no argument is needed.

### Kotlin Event Definition

[Section titled “Kotlin Event Definition”](#kotlin-event-definition)

```kotlin
import io.cratis.chronicle.events.EventType

@EventType
data class EmployeeHired(
    val employeeId: String = "",
    val firstName: String = "",
    val lastName: String = "",
    val department: String = ""
)
```

### Java Event Definition

[Section titled “Java Event Definition”](#java-event-definition)

```java
import io.cratis.chronicle.events.EventType;

@EventType
public record EmployeeHired(
    String employeeId,
    String firstName,
    String lastName,
    String department
) {}
```

## 5. Append an event

[Section titled “5. Append an event”](#5-append-an-event)

Nothing had to be registered first. Chronicle needs the schema for an event type before it will accept events of that type, and the same goes for every other artifact your application owns — but the client finds them all on the classpath and declares them to the kernel as it connects, and the first append waits for that to finish. There is no registration step to write and none to sequence.

Prefer to register by hand? Turn discovery off with `ChronicleOptions.development().withoutAutoRegistration()` and call the services yourself — `store.eventTypes.register(EmployeeHired::class)` and friends. See [Artifact Registration](/chronicle/clients/kotlin/guides/artifact-registration/) for both paths in full.

### Kotlin Append Event

[Section titled “Kotlin Append Event”](#kotlin-append-event)

```kotlin
val employeeId = "emp-001"
val result = store.eventLog.append(
    eventSourceId = employeeId,
    event = EmployeeHired(
        employeeId = employeeId,
        firstName = "Jane",
        lastName = "Smith",
        department = "Engineering"
    )
)

if (result.isSuccess) {
    println("Appended at sequence ${result.sequenceNumber.value}")
} else {
    println("Failed: ${result.constraintViolations.map { it.message }}")
}
```

### Java Append Event

[Section titled “Java Append Event”](#java-append-event)

```java
import java.util.stream.Collectors;

String employeeId = "emp-001";
var result = store.getEventLog().append(
    employeeId,
    new EmployeeHired(
        employeeId,
        "Jane",
        "Smith",
        "Engineering"
    )
);

if (result.isSuccess()) {
    System.out.println("Appended at sequence " +
        result.getSequenceNumberValue());
} else {
    String violations =
        result.getConstraintViolations().stream()
            .map(v -> v.getMessage())
            .collect(Collectors.joining(", "));
    System.out.println("Failed: " + violations);
}
```

`sequenceNumber` is an `EventSequenceNumber`, a Kotlin value class, whose getter has a mangled JVM signature Java cannot name — so `AppendResult` carries `getSequenceNumberValue()` for reading the position as a plain `long`. The same goes the other way: Java never has to construct a value class, because nothing Java-facing asks for one.

## 6. React to events

[Section titled “6. React to events”](#6-react-to-events)

A reactor observes events and performs side effects (see [Reactors](/chronicle/reactors/) for the full model). Annotate the class with `@Reactor` and write one method per event type you want to handle. The first parameter type is what selects the events a method receives — the method name is free.

### Kotlin Reactor

[Section titled “Kotlin Reactor”](#kotlin-reactor)

```kotlin
import io.cratis.chronicle.observation.Reactor

@Reactor
class HrNotifications {
    fun employeeHired(event: EmployeeHired) {
        println("Welcome ${event.firstName} ${event.lastName} " +
                "to ${event.department}!")
    }
}
```

The client finds it and starts the observation on connect. To register it by hand instead:

```kotlin
store.reactors.register(HrNotifications())
```

### Java Reactor

[Section titled “Java Reactor”](#java-reactor)

```java
import io.cratis.chronicle.observation.Reactor;

@Reactor
public class HrNotifications {
    public void employeeHired(EmployeeHired event) {
        System.out.println("Welcome " + event.firstName() +
                          " " + event.lastName() +
                          " to " + event.department() + "!");
    }
}
```

The client finds it and starts the observation on connect. To register it by hand instead:

```java
store.getReactors().register(new HrNotifications());
```

## 7. Build a read model

[Section titled “7. Build a read model”](#7-build-a-read-model)

A reducer folds a stream of events into a single object (see [Reducers](/chronicle/reducers/) for the full model). The `@ReadModel` marks the read model class, and `@Reducer` marks the reducer.

A reducer method takes the event, and optionally the current state. The state is `null` for the first event of an event source, so declare that parameter as nullable and fall back to a fresh instance.

A reducer registers its read model too, tagged with the reducer that produces it — so a read model only needs registering on its own when nothing projects into it. All of it happens automatically; the calls below are what you would write with discovery turned off.

### Kotlin Read Model

[Section titled “Kotlin Read Model”](#kotlin-read-model)

```kotlin
import io.cratis.chronicle.readModels.ReadModel
import io.cratis.chronicle.observation.Reducer

@ReadModel
data class EmployeeProfile(
    val id: String = "",
    val firstName: String = "",
    val lastName: String = "",
    val department: String = ""
)

@Reducer
class EmployeeProfileReducer {
    fun employeeHired(
        event: EmployeeHired,
        state: EmployeeProfile?
    ): EmployeeProfile =
        (state ?: EmployeeProfile()).copy(
            id = event.employeeId,
            firstName = event.firstName,
            lastName = event.lastName,
            department = event.department
        )
}
```

```kotlin
store.reducers.register(EmployeeProfileReducer())
```

### Java Read Model

[Section titled “Java Read Model”](#java-read-model)

Java needs one file per public type, so the read model and the reducer are two files.

```java
import io.cratis.chronicle.readModels.ReadModel;

@ReadModel
public class EmployeeProfile {
    private String id = "";
    private String firstName = "";
    private String lastName = "";
    private String department = "";

public EmployeeProfile() {}

// Getters and setters
    public String getId() { return id; }
    public void setId(String id) { this.id = id; }

public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

public String getLastName() { return lastName; }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

public String getDepartment() { return department; }
    public void setDepartment(String department) {
        this.department = department;
    }
}
```

```java
import io.cratis.chronicle.observation.Reducer;

@Reducer
public class EmployeeProfileReducer {
    public EmployeeProfile employeeHired(EmployeeHired event,
                                         EmployeeProfile state) {
        EmployeeProfile result =
            state != null ? state : new EmployeeProfile();
        result.setId(event.employeeId());
        result.setFirstName(event.firstName());
        result.setLastName(event.lastName());
        result.setDepartment(event.department());
        return result;
    }
}
```

```java
store.getReducers().register(new EmployeeProfileReducer());
```

## 8. Query a read model by key

[Section titled “8. Query a read model by key”](#8-query-a-read-model-by-key)

After events have been projected, query the read model by its event source identifier:

### Kotlin Query

[Section titled “Kotlin Query”](#kotlin-query)

```kotlin
val profile = store.readModels.getInstanceByKey(
    EmployeeProfile::class,
    employeeId
)
println(profile?.firstName) // Jane
```

### Java Query

[Section titled “Java Query”](#java-query)

```java
EmployeeProfile profile = store.getReadModels()
    .getInstanceByKey(EmployeeProfile.class, employeeId);
System.out.println(profile.getFirstName()); // Jane
```

## What’s next

[Section titled “What’s next”](#whats-next)

* [Guides](/chronicle/clients/kotlin/guides/) — deeper dives into reactors, projections, constraints, seeding, and compliance
* [Concepts](/chronicle/clients/kotlin/concepts/) — understand events, observers, and the read model pipeline
* [Reference](/chronicle/clients/kotlin/reference/) — full annotation and API reference

# Guides

Chronicle task guides are shared across clients. They live in the main Chronicle docs and use synchronized language tabs for Kotlin, Java, C#, Elixir, and TypeScript examples.

Start with:

* [Appending events](/chronicle/events/appending/)
* [Read models](/chronicle/read-models/)
* [Projections](/chronicle/projections/)
* [Reactors](/chronicle/reactors/)
* [Reducers](/chronicle/reducers/)
* [Constraints](/chronicle/constraints/)
* [Event evolution](/chronicle/understanding-event-evolution/)

Use the Kotlin client section for [setup](/chronicle/clients/kotlin/get-started/) and [API reference](/chronicle/clients/kotlin/reference/).

# Appending Events

Appending events is documented in the shared Chronicle docs with synchronized examples for C#, Kotlin, Java, Elixir, and TypeScript.

* [Appending events](/chronicle/events/appending/)
* [Appending many events](/chronicle/events/appending-many/)
* [Event source identity](/chronicle/events/event-source-id/)
* [Concurrency](/chronicle/events/concurrency/)

Use the [Kotlin get started page](/chronicle/clients/kotlin/get-started/) for JVM setup before running the shared examples.

## Kotlin client: `IEventSequence` and `IEventLog`

[Section titled “Kotlin client: IEventSequence and IEventLog”](#kotlin-client-ieventsequence-and-ieventlog)

Beyond `append`/`appendMany`, the Kotlin client’s `store.eventLog` (and any sequence from `store.getEventSequence`) exposes a richer surface for reading, redacting, and observing events:

| Member                             | Use it for                                        |
| ---------------------------------- | ------------------------------------------------- |
| `appendMany(events)`               | One atomic batch spanning several event sources.  |
| `getTailSequenceNumber`            | Current end of the sequence or one source.        |
| `getForEventSourceIdAndEventTypes` | Events for one source, by type.                   |
| `getFromSequenceNumber`            | Events forward from a position (a bookmark).      |
| `getNextSequenceNumber`            | Sequence number the next append will get.         |
| `completeStream`                   | Closes a stream so it can’t be appended to again. |
| `redact`/`redactForEventSource`    | Erases event content — see below.                 |
| `appendOperations`                 | Hot `Flow` of appends made through this instance. |

See the [EventStore API reference](/chronicle/clients/kotlin/reference/event-store-api/) for the full `IEventSequence` interface and `ConcurrencyScope` (optimistic concurrency via `AppendOptions.concurrencyScope`).

### Appending across event sources

[Section titled “Appending across event sources”](#appending-across-event-sources)

`appendMany(eventSourceId, events)` shapes the whole batch around one event source. When a single unit of work touches several — moving money between two accounts, say — pass `EventForEventSourceId` records instead. Each carries its own event source id and its own shaping, and the batch still commits as one atomic append:

```kotlin
import io.cratis.chronicle.events.EventType

@EventType
data class OrderLineAdded(val sku: String, val quantity: Int)

@EventType
data class StockReserved(val sku: String, val quantity: Int)
```

```kotlin
import io.cratis.chronicle.eventSequences.EventForEventSourceId

store.eventLog.appendMany(
    listOf(
        EventForEventSourceId("order-1", OrderLineAdded("sku-9", 2)),
        EventForEventSourceId("sku-9", StockReserved("sku-9", 2))
    )
)
```

Pass `concurrencyScopes` to check specific event sources optimistically — it is keyed by event source id, and any source left out is appended unchecked.

### Composing a batch across call sites

[Section titled “Composing a batch across call sites”](#composing-a-batch-across-call-sites)

Sometimes the events for one unit of work are not all decided in the same place. `forEventSourceId` starts a composed operation you can build up and inspect before anything is sent, then commit with a single `perform()`:

```kotlin
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.operations.forEventSourceId

val operations = store.eventLog.forEventSourceId("order-1") {
    withConcurrencyScope {
        withSequenceNumber(EventSequenceNumber(4)).withEventSourceId()
    }
    append(OrderLineAdded("sku-9", 2))
}

operations.forEventSourceId("sku-9") {
    append(StockReserved("sku-9", 2), tags = listOf("inventory"))
}

// Nothing has reached the kernel yet - this is exactly what perform() will send.
println(operations.getEventsToAppend())

val results = operations.perform()
```

Concurrency lives on the event source rather than on an individual event, because that is where the kernel checks it. A source that never asks for a scope is appended unchecked, and a scope already set is never cleared by a later call that expresses no expectation.

### Redacting events

[Section titled “Redacting events”](#redacting-events)

`redact` and `redactForEventSource` permanently rewrite event content — a destructive, irreversible operation, not a soft delete or a field mask. Once either call returns, the original content is gone from the event store for good. Use them only for a confirmed compliance/erasure request:

```kotlin
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.RedactionReason

val reason = RedactionReason("GDPR erasure request")
store.eventLog.redact(EventSequenceNumber(42), reason)
store.eventLog.redactForEventSource("customer-1", reason)
```

# Artifact Registration

Chronicle’s kernel has to know what your application is made of before it can do anything useful with it. Event types need schemas registered so events can be validated and migrated. Reducers and projections need to be declared so the kernel knows what to feed them. Constraints need to exist before the append they are meant to stop.

The client does all of that for you. Every class carrying `@EventType`, `@ReadModel`, `@Reactor`, `@Reducer`, `@Constraint`, `@FromEvent`, or implementing `IProjectionFor`, `ICanSeedEvents` or `IWebhookDefiner` is found on the classpath and registered the moment the client connects — in the order the kernel needs them.

## The short version

[Section titled “The short version”](#the-short-version)

Write your artifacts. Connect. That is the whole setup:

```kotlin
val client = ChronicleClient(ChronicleOptions.development())
val store = client.getEventStore("MyApp")
store.awaitRegistration()

store.eventLog.append("employee-1", EmployeeHired("Ada", "Lovelace", "Engineer"))
```

From Java:

```java
var client = new ChronicleClient(ChronicleOptions.Companion.development());
EventStore store = client.getEventStore("MyApp", "Default");
EventStoreJavaBridge.awaitRegistration(store);

EventLogJavaBridge.append(store.getEventLog(), "employee-1",
    new EmployeeHired("Ada", "Lovelace", "Engineer"), null);
```

`awaitRegistration()` returns as soon as the first registration pass is through. It is not required — appending before it completes simply races the kernel — but calling it once at startup makes the first append deterministic.

In a Spring Boot application even that is unnecessary: the starter holds the application back until registration is done. See [Spring Boot](/chronicle/clients/kotlin/guides/spring-boot/).

## What gets discovered

[Section titled “What gets discovered”](#what-gets-discovered)

| Artifact                  | Recognized by                               |
| ------------------------- | ------------------------------------------- |
| Event type                | `@EventType`                                |
| Event type migration      | Implements `IEventTypeMigration`            |
| Read model                | `@ReadModel`                                |
| Projection                | Implements `IProjectionFor`                 |
| Model-bound projection    | Read model carrying `@FromEvent`            |
| Reactor                   | `@Reactor`                                  |
| Reducer                   | `@Reducer`                                  |
| Constraint                | Implements `IConstraint`                    |
| Event seeder              | Implements `ICanSeedEvents`                 |
| Webhook                   | Implements `IWebhookDefiner`                |
| Capture                   | Implements `ICapture`                       |
| Reactor middleware        | Implements `IReactorMiddleware`             |
| Reactor argument resolver | Implements `IReactorMethodArgumentResolver` |

Only concrete classes qualify — interfaces and abstract classes are skipped, so your own base types never get registered by accident.

The two reactor entries are client-side: they are never declared to the kernel, they take part in how a reactor handler is invoked. They are discovered here because they answer the same question — what is this application made of? See [Reactor middlewares](#reactor-middlewares) below.

External services and event store subscriptions are configuration rather than artifacts: they describe systems outside your application, so they are still set up explicitly through `store.externalServices` and `store.eventStoreSubscriptions`.

## The order things are registered in

[Section titled “The order things are registered in”](#the-order-things-are-registered-in)

Order matters, and the client gets it right so you do not have to think about it:

1. **Event types and their migrations**, together in one call, because everything else is expressed in terms of event type ids and because the kernel merges an event type’s generations from a single registration.
2. **Read models that no observer produces.** A read model built by a reducer or a projection is registered by that observer instead, which is the only place the observer’s type and identity are known.
3. **Constraints, projections and webhooks.**
4. **Reactors and reducers**, which start observing.
5. **Captures**, which start appending the moment they run, so like seeding they go behind every observer that should see what they bring in.
6. **Seeders**, last of all — the kernel appends seeded events immediately, so every observer that should see them has to be watching first.

Registration runs again on every reconnect, because a kernel that restarted has forgotten what it was told. Reactors and reducers are started only once: each one re-establishes its own observation when the connection comes back.

## Narrowing the scan

[Section titled “Narrowing the scan”](#narrowing-the-scan)

Scanning the whole classpath is fine for most applications and takes a fraction of a second. In a large one, or where third-party libraries ship Chronicle artifacts of their own, point discovery at the packages you own:

```kotlin
val options = ChronicleOptions.development()
    .withArtifactsFrom("com.acme.ordering", "com.acme.shipping")
```

Sub-packages are included, so one entry per top-level package is usually enough.

## Listing artifacts explicitly

[Section titled “Listing artifacts explicitly”](#listing-artifacts-explicitly)

`KnownClientArtifacts` takes the list instead of finding it — useful where classpath scanning is unwanted, such as a locked-down runtime or a spec that must not see the rest of the classpath. Each class is sorted into every kind it qualifies for, so a `@ReadModel` carrying `@FromEvent` only has to be listed once:

```kotlin
import io.cratis.chronicle.artifacts.KnownClientArtifacts

val options = ChronicleOptions.development().copy(
    artifacts = KnownClientArtifacts(
        EmployeeHired::class,
        EmployeeState::class,
        EmployeeStateReducer::class,
        UniqueEmployeeEmail::class
    )
)
```

## Turning it off

[Section titled “Turning it off”](#turning-it-off)

Manual registration is still fully supported. Turn discovery off and register whatever you like, whenever you like:

```kotlin
val client = ChronicleClient(ChronicleOptions.development().withoutAutoRegistration())
val store = client.getEventStore("MyApp")

store.eventTypes.register(EmployeeHired::class, EmployeePromoted::class)
store.reducers.register(EmployeeStateReducer())
store.constraints.register(UniqueEmployeeEmail())
```

From Java:

```java
var options = ChronicleOptions.Companion.development().withoutAutoRegistration();
var client = new ChronicleClient(options);
EventStore store = client.getEventStore("MyApp", "Default");

EventTypesServiceJavaBridge.register(store.getEventTypes(),
    EmployeeHired.class, EmployeePromoted.class);
ReducersServiceJavaBridge.register(store.getReducers(), new EmployeeStateReducer());
```

With auto-registration off, `awaitRegistration()` returns immediately — there is nothing to wait for. `store.registerAll()` still works, and registers everything discovery found in one call, so you can keep discovery and merely control *when* it happens.

The console samples in `Samples/Kotlin/Console` and `Samples/Java/Console` deliberately opt out, so they double as a tour of the registration API.

## Artifacts with dependencies

[Section titled “Artifacts with dependencies”](#artifacts-with-dependencies)

By default an artifact is created by calling a constructor that takes no arguments — either a genuine no-arg constructor, or one where every parameter has a default. That covers reactors, reducers, constraints and seeders as they are normally written.

An artifact that needs collaborators should be created by a container. Supply an `IArtifactActivator` and the client will ask it instead:

```kotlin
import io.cratis.chronicle.artifacts.IArtifactActivator

val options = ChronicleOptions.development().copy(
    artifactActivator = IArtifactActivator { type -> myContainer.resolve(type) }
)
```

Spring Boot applications get this for free — see [Spring Boot](/chronicle/clients/kotlin/guides/spring-boot/).

If an artifact cannot be created, the client throws `ArtifactActivationFailed` naming the class and explaining the three ways out: give it a constructor that takes nothing, give its parameters defaults, or activate it through a container.

## Reactor middlewares

[Section titled “Reactor middlewares”](#reactor-middlewares)

Tracing, logging, metrics and correlation scoping want to happen around every reactor handler and belong to none of them. Put them in an `IReactorMiddleware` and every reactor stays a description of what happens when a fact arrives:

```kotlin
import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.observation.IReactorMiddleware

class HandlerTiming : IReactorMiddleware {
    private val started = ThreadLocal<Long>()

override suspend fun beforeInvoke(context: EventContext, event: Any) {
        started.set(System.nanoTime())
    }

override suspend fun afterInvoke(context: EventContext, event: Any) {
        println("${event::class.simpleName} took ${System.nanoTime() - started.get()}ns")
    }
}
```

Writing the class is all there is to it — discovery finds it and applies it to every reactor. `beforeInvoke` runs outermost-first and `afterInvoke` in reverse, so middlewares nest the way you would write them by hand, and `afterInvoke` runs whether the handler returned or threw.

Java cannot implement a suspending method, so a Java middleware implements `BlockingReactorMiddleware` — the same two methods without `suspend` — and the client adapts it onto the same chain.

## Handler parameters beyond the event

[Section titled “Handler parameters beyond the event”](#handler-parameters-beyond-the-event)

A reactor handler takes the event, and optionally its `EventContext`. Anything past that is resolved per invocation, which is how a handler asks for the current state of a read model without reaching for the event log:

```kotlin
@Reactor
class OverdraftAlerts(private val mail: Mailer) {
    suspend fun moneyWithdrawn(
        event: MoneyWithdrawn,
        account: AccountBalance?
    ) {
        if ((account?.balance ?: 0.0) < 0.0) mail.overdrawn(event.accountId)
    }
}
```

The instance is fetched for the event source the event arrived under, and is `null` when nothing has been projected for that key yet — so declare the parameter nullable.

Implement `IReactorMethodArgumentResolver` to supply anything else, a container-backed service for instance. Discovered resolvers are consulted before the built-in read model one, so an application can take over a parameter the client would otherwise claim. A parameter nothing can supply is rejected when the reactor registers, rather than failing on every event.

## Reference

[Section titled “Reference”](#reference)

| Option                    | Default                   | Description                     |
| ------------------------- | ------------------------- | ------------------------------- |
| `autoDiscoverAndRegister` | `true`                    | Register artifacts on connect   |
| `artifacts`               | `ClientArtifacts.default` | What the application is made of |
| `artifactActivator`       | `ArtifactActivator`       | How artifacts are created       |

| Method on `IEventStore` | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `registerAll()`         | Register everything now. Safe to call repeatedly |
| `awaitRegistration()`   | Wait for it. Returns at once when it is off      |

# Captures

Not everything that matters happens inside your application. An exchange rate moves, a partner posts a webhook, a supplier’s API changes a price. Those are facts too — and the usual answer is a scheduled job somewhere that polls, maps, and appends, which nobody owns and nobody notices when it stops.

A capture is that job, declared rather than written, and run by the kernel.

## Declaring one

[Section titled “Declaring one”](#declaring-one)

Implement `ICapture` and discovery saves it with the kernel on connect and starts it, so the source is live as soon as your application is:

```kotlin
import io.cratis.chronicle.captures.ICapture

class ExchangeRates : ICapture {
    override val id = "exchange-rates"

override val declaration = """
        capture ExchangeRates
            from api "https://api.example.com/rates" every 5 minutes
                append RateObserved
                    set currency to base
                    set rate to value
    """
}
```

The body is a Capture Declaration Language document. The language belongs to the kernel, which is what parses and runs it — see the [Chronicle documentation](https://github.com/Cratis/Chronicle) for its full shape.

Set `startOnRegistration` to `false` to have the capture saved but held — an environment where the source is not reachable, or one where starting it is an operator’s decision.

A declaration the kernel cannot parse is reported to standard error naming the capture, the line and the column. One bad capture does not take the rest of your application’s registration down with it.

## When the declaration is not known at build time

[Section titled “When the declaration is not known at build time”](#when-the-declaration-is-not-known-at-build-time)

`store.captures` is the whole surface, for declarations that come from somewhere else — an editor, configuration, an operator:

```kotlin
// Check as it is typed, without saving anything
val problems = store.captures.validate(declaration)

// Save, then start
when (val result = store.captures.save("exchange-rates", declaration)) {
    is CaptureDeclarationResult.Accepted -> store.captures.start(result.capture.id)
    is CaptureDeclarationResult.Rejected -> result.messages.forEach(::println)
}
```

| Member                  | Does                                          |
| ----------------------- | --------------------------------------------- |
| `getAll()`              | Every capture the store holds, running or not |
| `observeAll()`          | The same, re-emitted on every change          |
| `save(id, declaration)` | Saves under an id, replacing what was there   |
| `validate(declaration)` | Checks a declaration without saving anything  |
| `start(id)`             | Starts it appending                           |
| `stop(id)`              | Stops it. It stays saved                      |
| `delete(id)`            | Removes it entirely                           |

A declaration is a piece of text, so the first thing that can go wrong is that the kernel cannot make sense of it. That is an ordinary outcome of writing in a language rather than an exception, so `save` returns `Accepted` or `Rejected` and every message names a line and column.

Messages do not by themselves mean rejection — a declaration can be accepted with something worth telling you. `isSuccess`, or the shape of the result, is what says whether it took.

## What stopping does not undo

[Section titled “What stopping does not undo”](#what-stopping-does-not-undo)

Events a capture already appended are facts. Stopping or deleting the capture changes nothing about them — they stay exactly where they are, and everything projected from them stays as it was.

From Java, use `CapturesServiceJavaBridge`.

# PII Compliance

Compliance and PII handling are shared Chronicle topics. The shared docs own the concepts, storage behavior, and client-tabbed examples.

* [Compliance](/chronicle/compliance/)
* [PII](/chronicle/compliance/pii/)
* [Compliance in read models](/chronicle/compliance/read-models/)
* [Kotlin and Java client setup](/chronicle/clients/kotlin/get-started/)

# Strongly-typed identifiers

A `String` is a `String` is a `String`. Nothing stops a book’s identifier being passed where a member’s was expected — both compile, and the bug surfaces in production as a lookup that quietly finds nothing.

```kotlin
fun borrow(bookId: String, memberId: String) { }

// Compiles. Wrong.
borrow(memberId, bookId)
```

Give each value a type of its own and the compiler catches it while you are still typing.

## Declaring one

[Section titled “Declaring one”](#declaring-one)

A concept is any type implementing `ConceptAs<T>`:

```kotlin
import io.cratis.chronicle.concepts.ConceptAs

data class BookId(override val value: String) : ConceptAs<String>
data class MemberId(override val value: String) : ConceptAs<String>
data class CopyNumber(override val value: Int) : ConceptAs<Int>
```

Then use them wherever the value used to be:

```kotlin
@EventType
data class BookBorrowed(
    val book: BookId = BookId(""),
    val member: MemberId = MemberId("")
)

// Won't compile — which is the entire point.
BookBorrowed(memberId, bookId)
```

## What goes on the wire

[Section titled “What goes on the wire”](#what-goes-on-the-wire)

A concept serializes as the value it wraps, not as an object wrapping one:

```json
{ "book": "dune", "member": "ada" }
```

That is what makes concepts something you can adopt for a property that is already in production. The JSON does not change, the schema the kernel validates against does not change, and every event stored before the concept existed still reads back. The kernel never learns that the value has a type on your side, and does not need to.

The same holds for read models, reducer state, and constraint declarations — everything goes through one serializer, so a concept behaves identically wherever it appears.

## Event source ids

[Section titled “Event source ids”](#event-source-ids)

The event source id is a `String` on the wire and always will be. So that your side of the call can still be typed, every client method taking one has an overload taking a `ConceptAs<String>`:

```kotlin
import io.cratis.chronicle.concepts.append

store.eventLog.append(BookId("dune"), BookBorrowed(BookId("dune"), MemberId("ada")))
```

These are extension functions in `io.cratis.chronicle.concepts`, so import the one you need. They cover `append`, `appendMany`, `hasEventsFor`, `getTailSequenceNumber`, `getForEventSourceIdAndEventTypes`, `redactForEventSource`, and `getInstanceByKey`.

## From Java

[Section titled “From Java”](#from-java)

A concept is an ordinary type, so Java declares one as a record:

```java
public record BookId(String value) implements ConceptAs<String> {
    @Override public String getValue() { return value; }
}
```

The extra `getValue()` is the Kotlin property’s accessor — a Java record’s `value()` does not satisfy it on its own.

## Data class or value class

[Section titled “Data class or value class”](#data-class-or-value-class)

Kotlin’s `@JvmInline value class` also works and avoids the allocation, but its mangled JVM signatures are awkward from Java. Prefer a `data class` unless the allocation genuinely matters and Java never touches the type.

# Constraints

Constraints are shared Chronicle behavior. The shared docs cover constraint concepts, model-bound constraints, declarative constraints, and client-tabbed examples.

* [Constraints](/chronicle/constraints/)
* [Understanding constraints](/chronicle/understanding-constraints/)
* [Kotlin and Java client setup](/chronicle/clients/kotlin/get-started/)

## Kotlin client: constraint scoping

[Section titled “Kotlin client: constraint scoping”](#kotlin-client-constraint-scoping)

`IConstraintBuilder` (passed into `IConstraint.define`) can scope every constraint added through it to a narrower uniqueness dimension than the whole event store:

| Member               | Scopes uniqueness checking per… |
| -------------------- | ------------------------------- |
| `perEventSourceType` | Event source type               |
| `perEventStreamType` | Event stream type               |
| `perEventStreamId`   | Event stream id                 |

Combine any of the three; by default (none called) a constraint is checked globally across the whole event store:

```kotlin
import io.cratis.chronicle.constraints.Constraint
import io.cratis.chronicle.constraints.IConstraint
import io.cratis.chronicle.constraints.IConstraintBuilder
import io.cratis.chronicle.events.EventType

@EventType
data class ConstraintsBridgeUserRegistered(
    val userId: String = "",
    val email: String = ""
)

@Constraint
class ConstraintsBridgeUniqueEmail : IConstraint {
    override fun define(builder: IConstraintBuilder) {
        builder
            .perEventSourceType()
            .unique { unique ->
                unique
                    .on(
                        ConstraintsBridgeUserRegistered::class,
                        ConstraintsBridgeUserRegistered::email
                    )
                    .withMessage("Email must be unique per event source type.")
            }
    }
}
```

# Event Evolution

Event schema evolution and migrations are shared Chronicle behavior. The shared docs own the migration model and client-tabbed examples.

* [Understanding event evolution](/chronicle/understanding-event-evolution/)
* [Event type migrations concept](/chronicle/concepts/event-type-migrations/)
* [Migrations](/chronicle/migrations/)
* [Kotlin and Java client setup](/chronicle/clients/kotlin/get-started/)

# External Services

This page shows how to register external services using the Chronicle Kotlin client. An external service is a named endpoint — HTTP or database — that Chronicle-side integrations (such as webhooks or reactor-triggered calls) can address by name instead of embedding connection details throughout your code. See [External Services](/chronicle/external-services/) for the concept this page assumes.

## Registering an HTTP endpoint

[Section titled “Registering an HTTP endpoint”](#registering-an-http-endpoint)

`register` takes a name — also used as the service’s identifier — and a callback for configuring the endpoint:

```kotlin
store.externalServices.register("payroll-provider") { builder ->
    builder
        .http("https://payroll.example.com/api")
        .withBearerToken("payroll-integration-token")
}
```

## Authentication

[Section titled “Authentication”](#authentication)

`IExternalServiceBuilder` supports the same three authentication schemes as webhooks, plus arbitrary headers:

```kotlin
builder.withBasicAuth("username", "password")
builder.withBearerToken("token")
builder.withOAuth("https://auth.example.com", "client-id", "client-secret")
builder.withHeader("X-Custom-Header", "value")
```

## Registering a database endpoint

[Section titled “Registering a database endpoint”](#registering-a-database-endpoint)

Use `msSql` or `postgreSql` instead of `http` to describe a database endpoint. `port` defaults to the provider’s standard port when left at `0`:

```kotlin
store.externalServices.register("payroll-database") { builder ->
    builder.postgreSql(
        host = "payroll-db.internal",
        database = "payroll",
        username = "chronicle",
        password = "secret"
    )
}
```

Add provider-specific connection options with `withOption`:

```kotlin
builder
    .msSql(
        host = "payroll-db.internal",
        database = "payroll",
        username = "chronicle",
        password = "secret"
    )
    .withOption("Encrypt", "true")
```

## Best practices

[Section titled “Best practices”](#best-practices)

* Register external services once at startup, next to your event type and observer registrations, so the set of integrations Chronicle knows about is easy to find.
* Give services stable, descriptive names — they’re the identifier other Chronicle features (like webhooks) use to reference the service.
* Keep credentials out of source control; load them from configuration or a secret store before passing them to the builder.

# Projections

Projections are shared Chronicle read-model behavior. Use the shared docs for projection styles, model-bound projections, declarative projections, and client-tabbed examples.

* [Projections](/chronicle/projections/)
* [Choosing a read model style](/chronicle/projections/choosing-a-read-model-style/)
* [Model-bound projections](/chronicle/projections/model-bound/)
* [Declarative projections](/chronicle/projections/declarative/)
* [Kotlin and Java client setup](/chronicle/clients/kotlin/get-started/)

## Kotlin model-bound attributes

[Section titled “Kotlin model-bound attributes”](#kotlin-model-bound-attributes)

Beyond `@FromEvent` and `@SetFrom`, the Kotlin client has annotations for structural shapes (joins, children, nested objects), arithmetic (counters, running totals), catch-all mappings, and rewind behavior. Full parameter tables are in the [annotation reference](/chronicle/clients/kotlin/reference/annotations/).

| Attribute                    | Use it for                                                |
| ---------------------------- | --------------------------------------------------------- |
| `@Join`                      | Pulling in a property from another event type by id.      |
| `@ChildrenFrom`              | A collection built from child instances of an event type. |
| `@Nested`                    | A nullable sub-object built from its own `@FromEvent`.    |
| `@ClearWith`                 | Which event clears (nulls out) a `@Nested` property.      |
| `@Count`                     | An occurrence counter for a specific event type.          |
| `@Increment` / `@Decrement`  | Bumping a numeric property by one.                        |
| `@AddFrom` / `@SubtractFrom` | Adding/subtracting an event value in.                     |
| `@FromAll` / `@FromEvery`    | A property populated from every event type.               |
| `@NotRewindable`             | Marking a projection as forward-only.                     |
| `@RemovedWith`               | Which event removes an instance or a child.               |
| `@RemovedWithJoin`           | Like `@RemovedWith`, but resolving the id via a join.     |
| `@NoAutoMap`                 | Disabling AutoMap for a type or a single property.        |

`@NotRewindable` is worth considering for projections fed by events that can’t reliably be redelivered — e.g. from an [event store subscription](/chronicle/subscriptions/explicit-subscriptions/).

```kotlin
import io.cratis.chronicle.projections.Increment
import io.cratis.chronicle.projections.Join
import io.cratis.chronicle.readModels.ReadModel

@ReadModel
data class OrderOverview(
    val id: String = "",
    @Increment(OrderShipped::class) val shipmentCount: Int = 0,
    @Join(
        eventType = CustomerRegistered::class,
        on = "customerId",
        eventPropertyName = "email"
    )
    val customerEmail: String = ""
)
```

## Richer declarative projections

[Section titled “Richer declarative projections”](#richer-declarative-projections)

`IProjectionBuilderFor<T>` also supports `.join()`, `.fromEvery()`/`.fromAll()`, `.removedWith()`/`.removedWithJoin()`, `.children()`, `.nested()`, and `.notRewindable()` — the fluent equivalents of the attributes above, for projections defined with a separate `IProjectionFor<T>` class instead of model-bound annotations:

```kotlin
import io.cratis.chronicle.projections.IProjectionBuilderFor
import io.cratis.chronicle.projections.IProjectionFor

class OrderOverviewProjection : IProjectionFor<OrderOverview> {
    override fun define(builder: IProjectionBuilderFor<OrderOverview>) {
        builder
            .from(OrderPlaced::class)
            .join(CustomerRegistered::class) { join ->
                join.on(OrderOverview::customerEmail)
                    .set(OrderOverview::customerEmail)
                    .toProperty("email")
            }
            .notRewindable()
    }
}
```

# Reactors

Reactors are documented in the shared Chronicle docs with synchronized examples for C#, Kotlin, Java, Elixir, and TypeScript.

* [Getting started with reactors](/chronicle/reactors/getting-started/)
* [Reactor event processing](/chronicle/reactors/event-processing/)
* [Reactors overview](/chronicle/reactors/)

Use the [Kotlin annotation reference](/chronicle/clients/kotlin/reference/annotations/) for JVM annotation details.

# Read Model Reactors

`store.readModels.watch(...)` hands you a `Flow` of changesets — and with it the job of collecting it, branching on the change type, keeping the subscription alive, and doing it again for every read model you care about.

A read model reactor takes that plumbing away. You write one method per change, register the class, and Chronicle dispatches to it. Where a [reactor](/chronicle/clients/kotlin/guides/reactors/) reacts to events, a read model reactor reacts to the *state those events produced* — an instance being added, modified, or removed.

## Writing a reactor

[Section titled “Writing a reactor”](#writing-a-reactor)

Implement `IReadModelReactor` and name a method after the change it handles: `added`, `modified` or `removed`. The first parameter is the read model, and its type is what decides which read model the reactor watches — the same way a reactor’s first parameter selects its event type.

```kotlin
import io.cratis.chronicle.readModels.IReadModelReactor
import io.cratis.chronicle.readModels.ReadModelChangeset

class EmployeeProfileAlerts : IReadModelReactor {
    fun added(profile: EmployeeProfile) {
        println("${profile.firstName} joined ${profile.department}")
    }

fun modified(
        profile: EmployeeProfile,
        changeset: ReadModelChangeset<EmployeeProfile>
    ) {
        println("${changeset.modelKey} changed at " +
                "sequence ${changeset.eventSequenceNumber}")
    }
}
```

The optional second parameter is the `ReadModelChangeset` that caused the call. Take it when you need the instance’s `modelKey`, the `eventSequenceNumber` that produced the change, or its `correlationId`; leave it off when the instance itself is all you need.

Method names are matched case-insensitively, so `Added` works as well as `added`.

## Reacting to removals

[Section titled “Reacting to removals”](#reacting-to-removals)

A removal never carries an instance — there is nothing left to hand you — so a Kotlin `removed` handler must declare its read model parameter nullable. The key of the instance that went away is on the changeset:

```kotlin
class EmployeeProfileOffboarding : IReadModelReactor {
    fun removed(
        profile: EmployeeProfile?,
        changeset: ReadModelChangeset<EmployeeProfile>
    ) {
        println("${changeset.modelKey} is gone")
    }
}
```

Declaring it non-nullable fails at registration with `InvalidHandlerSignature` rather than throwing on every removal that arrives.

## Watching more than one read model

[Section titled “Watching more than one read model”](#watching-more-than-one-read-model)

Each handler’s first parameter stands on its own, so one reactor can cover several read models. Chronicle opens one watch per read model it finds:

```kotlin
class HrDashboardAlerts : IReadModelReactor {
    fun added(profile: EmployeeProfile) {
        println("profile added: ${profile.id}")
    }

fun added(overview: OrderOverview) {
        println("order added: ${overview.id}")
    }
}
```

A handler can also take a `List` of read models instead of a single instance; the element type is then what selects the read model.

## Returning events as side effects

[Section titled “Returning events as side effects”](#returning-events-as-side-effects)

Like a reactor, a handler may return an event instead of taking a dependency on the event log. It is appended for you, using the changed instance’s key as the event source id:

```kotlin
import io.cratis.chronicle.events.EventType

@EventType
data class EmployeeProfileArchived(val employeeId: String)

class EmployeeProfileArchiver : IReadModelReactor {
    fun removed(
        profile: EmployeeProfile?,
        changeset: ReadModelChangeset<EmployeeProfile>
    ) = EmployeeProfileArchived(changeset.modelKey)
}
```

Return a `List` to append several events, and wrap one in `EventForEventSourceId` to send it to an event source other than the changed instance’s key. Anything that is not an event type — including `Unit` — is ignored, so handlers that just do their work and return nothing are fine.

## Registering and stopping

[Section titled “Registering and stopping”](#registering-and-stopping)

`ReadModelReactors` needs the read models to watch through and the event log to append side effects to. Registration is not a suspending call: it starts the subscriptions and returns the `Job` backing them.

```kotlin
import io.cratis.chronicle.readModels.ReadModelReactors

val readModelReactors = ReadModelReactors(store.readModels, store.eventLog)
readModelReactors.register(EmployeeProfileAlerts())
readModelReactors.register(EmployeeProfileOffboarding())

// Later, when shutting down:
readModelReactors.stop()
```

`stop()` cancels every reactor registered through that instance. Cancel the returned `Job` instead when you want to stop a single reactor.

Handlers may be called more than once for the same change — a watch that ends is re-established — so keep them idempotent, exactly as you would a reactor.

## Java

[Section titled “Java”](#java)

`IReadModelReactor` is a plain marker interface and `register` is not a suspending function, so Java uses both directly with no bridge. Java parameters carry no nullability, so a Java `removed` handler declares the read model type as it is:

```java
import io.cratis.chronicle.readModels.IReadModelReactor;
import io.cratis.chronicle.readModels.ReadModelChangeset;

public class JavaEmployeeProfileAlerts implements IReadModelReactor {
    public void added(EmployeeProfile profile) {
        System.out.println(profile.getFirstName() + " joined");
    }

public void removed(
            EmployeeProfile profile,
            ReadModelChangeset<EmployeeProfile> changeset) {
        System.out.println(changeset.getModelKey() + " is gone");
    }
}
```

```java
import io.cratis.chronicle.readModels.ReadModelReactors;

ReadModelReactors readModelReactors =
        new ReadModelReactors(store.getReadModels(), store.getEventLog());
readModelReactors.register(new JavaEmployeeProfileAlerts());
```

See the [EventStore API reference](/chronicle/clients/kotlin/reference/event-store-api/) for the full `IReadModelReactors` surface, and [Read Models](/chronicle/clients/kotlin/concepts/read-models/) for the imperative `watch` this builds on.

# Reducers

Reducers are shared Chronicle read-model behavior. Use the shared reducer docs for the model, lifecycle, filtering, and client-tabbed examples.

* [Reducers](/chronicle/reducers/)
* [Getting started with reducers](/chronicle/reducers/getting-started/)
* [Reducer event processing](/chronicle/reducers/event-processing/)
* [Kotlin and Java client setup](/chronicle/clients/kotlin/get-started/)

# Seeding

This page shows how to seed events using the Chronicle Kotlin client. Seeding is sent to the Chronicle Server when the event store connects, and the server applies it once per namespace. See [Event Seeding](/chronicle/event-seeding/) for the concept this page assumes.

## Define events

[Section titled “Define events”](#define-events)

```kotlin
import io.cratis.chronicle.events.EventType

@EventType
data class AccountOpened(
    val accountId: String,
    val ownerName: String,
    val initialBalance: Double
)

@EventType
data class FundsDeposited(val accountId: String, val amount: Double)
```

## Implement a seeder

[Section titled “Implement a seeder”](#implement-a-seeder)

Annotate a class with `@Seeder`, implement `ICanSeedEvents`, and use `IEventSeedingBuilder.forEventSource` to accumulate events:

```kotlin
import io.cratis.chronicle.seeding.ICanSeedEvents
import io.cratis.chronicle.seeding.IEventSeedingBuilder
import io.cratis.chronicle.seeding.Seeder

@Seeder
class AccountSeeder : ICanSeedEvents {
    override fun seed(builder: IEventSeedingBuilder) {
        builder.forEventSource(
            "account-1",
            listOf(AccountOpened("account-1", "Alice", 1000.0))
        )
    }
}
```

## Seed mixed event types for one event source

[Section titled “Seed mixed event types for one event source”](#seed-mixed-event-types-for-one-event-source)

`forEventSource` takes a list of any event types, so mixing types for the same event source is the same call:

```kotlin
@Seeder
class MixedAccountSeeder : ICanSeedEvents {
    override fun seed(builder: IEventSeedingBuilder) {
        builder.forEventSource(
            "account-1",
            listOf(
                AccountOpened("account-1", "Alice", 1000.0),
                FundsDeposited("account-1", 500.0)
            )
        )
    }
}
```

Chain multiple calls to seed several event sources:

```kotlin
@Seeder
class MultiAccountSeeder : ICanSeedEvents {
    override fun seed(builder: IEventSeedingBuilder) {
        builder
            .forEventSource(
                "account-1",
                listOf(AccountOpened("account-1", "Alice", 1000.0))
            )
            .forEventSource(
                "account-2",
                listOf(AccountOpened("account-2", "Bob", 500.0))
            )
    }
}
```

## Seed a specific event type

[Section titled “Seed a specific event type”](#seed-a-specific-event-type)

`forEventType` is an alternative to `forEventSource` that also checks the event class is annotated with `@EventType` before accepting it — useful when a seeder should only ever seed one specific event type and you want that caught early rather than at the server:

```kotlin
@Seeder
class TypedAccountSeeder : ICanSeedEvents {
    override fun seed(builder: IEventSeedingBuilder) {
        builder.forEventType(
            AccountOpened::class,
            "account-1",
            listOf(AccountOpened("account-1", "Alice", 1000.0))
        )
    }
}
```

## Seed a specific namespace

[Section titled “Seed a specific namespace”](#seed-a-specific-namespace)

By default, seed data targets the event store’s own namespace. Call `forNamespace` to target a different one instead — it returns a scoped builder whose `forEventSource`/`forEventType` calls all seed into that namespace, leaving calls made directly on `builder` targeting the event store’s own namespace as before:

```kotlin
@Seeder
class MultiNamespaceAccountSeeder : ICanSeedEvents {
    override fun seed(builder: IEventSeedingBuilder) {
        builder
            .forEventSource(
                "account-1",
                listOf(AccountOpened("account-1", "Alice", 1000.0))
            )
            .forNamespace("staging")
            .forEventSource(
                "account-1",
                listOf(AccountOpened("account-1", "Staging Alice", 250.0))
            )
    }
}
```

## Running seeders

[Section titled “Running seeders”](#running-seeders)

Pass seeder instances to the event store’s `seeding` service:

```kotlin
import io.cratis.chronicle.IEventStore

suspend fun runSeeders(store: IEventStore) {
    store.seeding.seed(AccountSeeder())
}
```

## How it runs

[Section titled “How it runs”](#how-it-runs)

* Seed batches are sent to the Chronicle Server when the event store connects.
* The server deduplicates seeded events and applies them once per namespace.
* Events are appended in a single batch for efficient startup.

## Best practices

[Section titled “Best practices”](#best-practices)

* Keep seed data minimal and deterministic.
* Use clear event source IDs to make debugging easier.
* Group seeders by scenario so you can remove or adjust them easily.
* Only call `store.seeding.seed(...)` when you want seeding to run — for example, guard it behind a development-only build flag or configuration check.

# Spring Boot

The Chronicle Spring Boot starter turns “wire up an event-sourced backend” into “add a dependency”. Put it on the classpath and you get a connected client, every artifact in your application registered with the kernel before the first request is served, per-request tenancy, identity and units of work — and an `IEventStore` you can inject anywhere.

It works the same from Kotlin and from Java.

## Add the dependency

[Section titled “Add the dependency”](#add-the-dependency)

The starter is published to Maven Central as `io.cratis:chronicle-spring-boot-starter`, and brings the client with it.

build.gradle.kts

```kotlin
dependencies {
    implementation("io.cratis:chronicle-spring-boot-starter:2.1.1")
}
```

build.gradle

```groovy
dependencies {
    implementation 'io.cratis:chronicle-spring-boot-starter:2.1.1'
}
```

## Configure it

[Section titled “Configure it”](#configure-it)

Everything has a default that works on a developer’s machine, so the only setting most applications need is the name of their event store:

```yaml
cratis:
  chronicle:
    event-store: Ordering
```

That gives you the local development kernel on `localhost:35000`, the `Default` namespace, and automatic discovery and registration of every artifact in your application’s packages.

## Write artifacts, not wiring

[Section titled “Write artifacts, not wiring”](#write-artifacts-not-wiring)

There is no registration code. Write the event, the read model, and the reducer, and they are found and registered on startup:

```kotlin
@EventType
data class EmployeeHired(
    val firstName: String = "",
    val lastName: String = "",
    val title: String = ""
)

@ReadModel
data class EmployeeState(
    val id: String = "",
    val firstName: String = "",
    val title: String = ""
)

@Reducer
class EmployeeStateReducer {
    fun employeeHired(event: EmployeeHired): EmployeeState =
        EmployeeState(firstName = event.firstName, title = event.title)
}
```

Discovery is scoped to the packages Spring Boot already scans for components — the package of your `@SpringBootApplication` class and everything beneath it. Override it with `cratis.chronicle.artifact-packages` when your artifacts live somewhere else.

## Artifacts are Spring components

[Section titled “Artifacts are Spring components”](#artifacts-are-spring-components)

An artifact is activated through the container, so it takes its dependencies through its constructor exactly like a `@Service` would:

```kotlin
@Reactor
class WelcomePackageReactor(private val mailer: Mailer) {
    fun employeeHired(
        event: EmployeeHired,
        context: EventContext
    ): WelcomePackageRequested {
        mailer.send(event.email, "Welcome to the team!")
        return WelcomePackageRequested(context.eventSourceId)
    }
}
```

```java
@Reactor
public class WelcomePackageReactor {
    private final Mailer mailer;

public WelcomePackageReactor(Mailer mailer) {
        this.mailer = mailer;
    }

public WelcomePackageRequested employeeHired(
            EmployeeHired event, EventContext context) {
        mailer.send(event.email(), "Welcome to the team!");
        return new WelcomePackageRequested(context.getEventSourceId());
    }
}
```

Declaring an artifact as a `@Component` is optional. If you do, that bean is the one used, with its own scope and lifecycle. If you do not, it is still constructed with everything it needs injected.

## Using it from Kotlin

[Section titled “Using it from Kotlin”](#using-it-from-kotlin)

Inject `IEventStore` and use the full coroutine API. Spring MVC handlers are blocking, so bridge with `runBlocking` — on WebFlux, mark the handler `suspend` and drop the bridge:

```kotlin
@RestController
@RequestMapping("/api/employees")
class Employees(private val eventStore: IEventStore) {
    @PostMapping("/{id}/hire")
    fun hire(@PathVariable id: String, @RequestBody hire: Hire) = runBlocking {
        eventStore.eventLog.append(
            id, EmployeeHired(hire.firstName, hire.lastName, hire.title))
        ResponseEntity.accepted().build<Any>()
    }

@GetMapping("/{id}")
    fun get(@PathVariable id: String) = runBlocking {
        eventStore.readModels.getInstanceByKey(EmployeeState::class, id)
    }
}
```

## Using it from Java

[Section titled “Using it from Java”](#using-it-from-java)

Java has no coroutines, so inject `Chronicle` instead. It is the same event store, with the everyday operations exposed as ordinary blocking methods:

```java
@RestController
@RequestMapping("/api/employees")
public class Employees {
    private final Chronicle chronicle;

public Employees(Chronicle chronicle) {
        this.chronicle = chronicle;
    }

@PostMapping("/{id}/hire")
    public ResponseEntity<Object> hire(
            @PathVariable String id, @RequestBody Hire hire) {
        chronicle.append(id,
            new EmployeeHired(hire.firstName(), hire.lastName(), hire.title()));
        return ResponseEntity.accepted().build();
    }

@GetMapping("/{id}")
    public EmployeeState get(@PathVariable String id) {
        return chronicle.readModel(EmployeeState.class, id);
    }
}
```

Anything beyond the everyday is one hop away through `chronicle.getEventStore()`, which is the full API.

| Method on `Chronicle`               | Description                              |
| ----------------------------------- | ---------------------------------------- |
| `append(eventSourceId, event)`      | Append one event                         |
| `appendMany(eventSourceId, events)` | Append several to one event source       |
| `readModel(type, key)`              | One read model instance by key           |
| `readModels(type)`                  | Every instance of a read model           |
| `readModelHistory(type, key)`       | Every state an instance has been through |
| `inUnitOfWork(work)`                | Run work atomically outside a request    |
| `getEventStore()`                   | The full `IEventStore`                   |

## What you get per request

[Section titled “What you get per request”](#what-you-get-per-request)

In a servlet application the starter adds three filters. Each can be turned off on its own.

### Identity

[Section titled “Identity”](#identity)

The authenticated principal becomes the identity recorded on every event appended while handling the request, so the audit trail comes out right without any code passing a user around. Subject, name and username are read from the `sub`, `name` and `preferred_username` claims, falling back to the principal’s name.

Requires Spring Security on the classpath. Disable with `cratis.chronicle.identity.enabled: false`.

### Causation

[Section titled “Causation”](#causation)

The route, method, host, scheme and query of the request are recorded on the causation chain of every event it produces. “Why does this record say what it says?” is then answered by the event’s own metadata rather than by correlating log files.

Disable with `cratis.chronicle.causation.enabled: false`.

### Unit of work

[Section titled “Unit of work”](#unit-of-work)

Each request runs inside a unit of work that is committed when the request completes and rolled back if it throws. A handler can append several events across several event sources and have them land together or not at all:

```kotlin
@PostMapping("/{id}/hire")
fun hire(@PathVariable id: String, @RequestBody hire: Hire) = runBlocking {
    // Both events commit together when the request completes. If the email is
    // already taken, the constraint stops both.
    eventStore.eventLog.append(
        id, EmployeeHired(hire.firstName, hire.lastName, hire.title))
    eventStore.eventLog.append(id, EmployeeEmailSet(hire.email))
    ResponseEntity.accepted().build<Any>()
}
```

A handler that commits or rolls back itself is left alone. Disable with `cratis.chronicle.unit-of-work.enabled: false`.

## Multi-tenancy

[Section titled “Multi-tenancy”](#multi-tenancy)

A namespace is Chronicle’s tenancy boundary: the same event store, the same artifacts, entirely separate streams of events. The injected `IEventStore` routes to the namespace the current piece of work belongs to on every call, so application code never mentions a tenant.

Pick how the tenant is decided:

```yaml
cratis:
  chronicle:
    namespace-resolution:
      strategy: http-header    # fixed | http-header | subdomain | authentication
      http-header: x-cratis-tenant-id
      claim: tenant_id
```

| Strategy         | Where the namespace comes from                             |
| ---------------- | ---------------------------------------------------------- |
| `fixed`          | `cratis.chronicle.namespace`. The single-tenant default    |
| `http-header`    | A header on the current request                            |
| `subdomain`      | The first label of the host — `acme` in `acme.example.com` |
| `authentication` | A claim on the authenticated principal                     |

`authentication` is the strongest of the four, because the tenant comes from the token rather than from anything a caller can set. Work outside a request — a scheduled job, a reactor — falls back to the `Default` namespace.

Declare your own `IEventStoreNamespaceResolver` bean to decide it any other way:

```kotlin
@Bean
fun namespaceResolver(tenants: TenantDirectory) =
    IEventStoreNamespaceResolver { tenants.currentTenant().namespace }
```

## Startup

[Section titled “Startup”](#startup)

The starter connects on startup and holds the application back until every artifact is registered, so the first request never reaches a kernel that has not been told about the event types it is about to be handed.

The wait is bounded by `cratis.chronicle.registration-timeout` (30 seconds by default). If the kernel cannot be reached in time the application starts anyway, logs why, and keeps trying in the background — a temporarily unavailable kernel degrades rather than blocks.

## Configuration reference

[Section titled “Configuration reference”](#configuration-reference)

| Property                           | Default                   | Description                          |
| ---------------------------------- | ------------------------- | ------------------------------------ |
| `connection-string`                | development kernel        | Where the kernel is                  |
| `event-store`                      | `Default`                 | The event store to work against      |
| `namespace`                        | `Default`                 | Namespace for the `fixed` strategy   |
| `auto-discover-and-register`       | `true`                    | Register artifacts on connect        |
| `artifact-packages`                | application packages      | Packages to scan                     |
| `default-sink-type-id`             | `MongoDB`                 | Where read models are persisted      |
| `program-identifier`               | `spring.application.name` | Name in diagnostics                  |
| `registration-timeout`             | `30s`                     | How long startup waits for it        |
| `namespace-resolution.strategy`    | `fixed`                   | How the namespace is decided         |
| `namespace-resolution.http-header` | `x-cratis-tenant-id`      | Header to read                       |
| `namespace-resolution.claim`       | `tenant_id`               | Claim to read                        |
| `unit-of-work.enabled`             | `true`                    | Unit of work per request             |
| `causation.enabled`                | `true`                    | Request causation on events          |
| `identity.enabled`                 | `true`                    | Authenticated user as event identity |

## Replacing what the starter provides

[Section titled “Replacing what the starter provides”](#replacing-what-the-starter-provides)

Every bean the starter contributes backs off the moment your application declares its own, so nothing has to be turned off before it can be replaced — declare a `ChronicleOptions`, `IChronicleClient`, `IEventStore`, `IArtifactActivator` or `IEventStoreNamespaceResolver` bean and yours wins.

## Samples

[Section titled “Samples”](#samples)

* `Samples/Kotlin/SpringBoot` — the Kotlin version of everything above
* `Samples/Java/SpringBoot` — the same application in Java

Both need a running kernel:

```bash
docker run -p 35000:35000 cratis/chronicle:latest-development
gradle :Samples:Kotlin:SpringBoot:bootRun
```

## See also

[Section titled “See also”](#see-also)

* [Artifact Registration](/chronicle/clients/kotlin/guides/artifact-registration/) — what gets discovered, and how to narrow, replace or turn off discovery

# Testing

Specifying a Chronicle-backed slice used to mean driving the real client against a running event store: a kernel, a sink, Docker, and a test that takes seconds instead of milliseconds. That is an integration test, and it has its place — but it is a poor place to specify “given these three events, the state should be this”.

`io.cratis:chronicle-testing` runs the same code with nothing behind it.

## Adding it

[Section titled “Adding it”](#adding-it)

```kotlin
dependencies {
    testImplementation("io.cratis:chronicle-testing:<version>")
}
```

## Specifying what gets appended

[Section titled “Specifying what gets appended”](#specifying-what-gets-appended)

`EventScenario` hands your code an `IEventSequence` that keeps events in a list, then lets you ask what landed in it:

```kotlin
import io.cratis.chronicle.testing.EventScenario
import io.cratis.chronicle.testing.shouldHaveAppended
import io.cratis.chronicle.testing.shouldHaveAppendedExactly

@Test
fun `registering an employee records that they were hired`() = runBlocking {
    val scenario = EventScenario()

Registrations(scenario.eventLog)
        .register("employee-1", "Ada", "Lovelace")

scenario.shouldHaveAppended<EmployeeHired>("employee-1") {
        it.firstName == "Ada"
    }
    scenario.shouldHaveAppendedExactly(1)
}
```

`given` appends preconditions — what was already true before the code under test ran — so an assertion about what it appended does not have to count them:

```kotlin
scenario.given(
    "employee-1",
    EmployeeHired("Ada", "Lovelace", "Engineer")
)

Registrations(scenario.eventLog).promote("employee-1", "Principal")

scenario.shouldHaveAppended<EmployeePromoted>("employee-1")
```

| Assertion                             | Fails unless                           |
| ------------------------------------- | -------------------------------------- |
| `shouldHaveAppended<T>(source) { }`   | One `T` matching the condition landed  |
| `shouldHaveAppendedExactly(count)`    | Exactly `count` events landed in total |
| `shouldHaveAppendedExactly<T>(count)` | Exactly `count` events of `T` landed   |
| `shouldNotHaveAppended<T>()`          | No `T` was appended                    |
| `shouldHaveAppendedNothing()`         | Nothing at all was appended            |

The assertions exist for their failure messages rather than for the check — a failure prints every event that *was* appended, with its event source and its JSON, which is usually enough to see the problem without a debugger.

## Specifying what a reducer folds

[Section titled “Specifying what a reducer folds”](#specifying-what-a-reducer-folds)

A reducer is a fold: events in, read model out. `ReadModelScenario` runs it the way the client runs it against a real kernel — handlers discovered the same way, chosen by event type the same way, invoked with the same shapes, awaited if they suspend:

```kotlin
import io.cratis.chronicle.testing.ReadModelScenario

@Test
fun `promotion changes the title and keeps the name`() = runBlocking {
    val scenario = ReadModelScenario<EmployeeState>(EmployeeStateReducer())

val state = scenario.fold(
        "employee-1",
        EmployeeHired("Ada", "Lovelace", "Engineer"),
        EmployeePromoted("Principal Engineer")
    )

assertEquals("Ada", state!!.firstName)
    assertEquals("Principal Engineer", state.title)
}
```

Chronicle folds each event source independently, and so does this — state does not leak between event sources, which is exactly the mistake a reducer spec should be able to catch. `stateFor(eventSourceId)` reads back what each one folded to, and folding the same event source again continues from where it left off, so a history can be built in stages.

## What is real and what is not

[Section titled “What is real and what is not”](#what-is-real-and-what-is-not)

Real:

* The client’s own serializer. Every event round-trips through it on the way in, so an event that could not survive a trip to the kernel fails here too — and so does a reducer that only works on an instance it was handed directly.
* Event contexts. Sequence numbers, event source ids, stream type and id, tags and the time it occurred are filled in the way the kernel fills them.
* Handler dispatch. The same discovery, the same shapes, the same `suspend` support.

Not real, and deliberately so:

* **Constraints.** Nothing is enforced, so every append succeeds. A constraint is the kernel’s job and belongs in an integration test.
* **Projections.** Only reducers fold in-process. A projection is a declaration the kernel executes.
* **Concurrency scopes.** Accepted and ignored.
* **Observation.** Nothing observes, so reactors do not run and there is no replay.

When a spec needs any of those, it needs a kernel — and at that point it is an integration test, which is a different and more expensive thing on purpose.

# Tracing

A request comes in, a command appends an event, a reactor picks it up and calls something else. When that takes eight seconds, the question is which part of it did — and without Chronicle in the trace, the answer is a gap.

The client reports spans through the OpenTelemetry API, so Chronicle work nests under whatever span your application was already in.

## Turning it on

[Section titled “Turning it on”](#turning-it-on)

Nothing, if your application already runs the OpenTelemetry SDK. The client depends on the API alone, which no-ops until an SDK is registered, so:

* an application that never instruments pays a virtual call and nothing else
* an application that does gets Chronicle spans without configuring the client

If your application holds its own `OpenTelemetry` rather than registering it globally, hand it over:

```kotlin
val options = ChronicleOptions.development().copy(openTelemetry = myOpenTelemetry)
```

## What you get

[Section titled “What you get”](#what-you-get)

| Span                            | Produced when              |
| ------------------------------- | -------------------------- |
| `Chronicle append <EventType>`  | An event is appended       |
| `Chronicle appendMany`          | A batch is appended        |
| `Chronicle observe <EventType>` | A reactor handles an event |
| `Chronicle reduce <EventType>`  | A reducer folds an event   |

Every span is reported under the `io.cratis.chronicle` instrumentation scope, and carries the identifiers you would otherwise correlate by hand:

| Attribute                     | On                       |
| ----------------------------- | ------------------------ |
| `chronicle.event_type`        | Appends and observations |
| `chronicle.event_source_id`   | Appends and observations |
| `chronicle.event_sequence_id` | All                      |
| `chronicle.event_store`       | Appends                  |
| `chronicle.namespace`         | Appends                  |
| `chronicle.observer_id`       | Observations             |
| `chronicle.sequence_number`   | Observations             |
| `chronicle.event_count`       | Batch appends            |
| `chronicle.is_replay`         | Observations             |

An append the kernel refuses, or a handler that throws, ends its span with an error status and the exception recorded on it — which is usually the span you came looking for.

## Reading a trace

[Section titled “Reading a trace”](#reading-a-trace)

An observation span is not a child of the append that produced the event. They are separate pieces of work, often in separate processes, connected by the correlation id rather than by span parentage. Query on `chronicle.event_source_id` to see everything that happened to one event source.

Inside a reactor, anything else instrumented — an outgoing HTTP call, a database query — nests under the observation span, because the span is made current for the duration of the handler.

## Adding your own

[Section titled “Adding your own”](#adding-your-own)

`IReactorMiddleware` wraps every reactor handler invocation, which is where application-specific instrumentation belongs rather than inside the reactors. See [Artifact Registration](/chronicle/clients/kotlin/guides/artifact-registration/#reactor-middlewares).

# Transactions

Unit-of-work transactions are now documented as a shared Chronicle workflow with synchronized Kotlin and Java examples.

* [Transactions and unit of work](/chronicle/events/transactions/)
* [Appending many events](/chronicle/events/appending-many/)
* [Kotlin and Java client setup](/chronicle/clients/kotlin/get-started/)

## Kotlin client: `IUnitOfWork`

[Section titled “Kotlin client: IUnitOfWork”](#kotlin-client-iunitofwork)

Beyond `commit`/`rollback`, `IUnitOfWork` (from `store.unitOfWorkManager`) exposes the outcome of a commit:

| Member                                   | Use it for                                            |
| ---------------------------------------- | ----------------------------------------------------- |
| `isSuccess`                              | Whether every staged event committed cleanly.         |
| `getConstraintViolations`                | Constraint violations detected on commit.             |
| `getConcurrencyViolations`               | Concurrency violations detected on commit.            |
| `getAppendErrors`                        | Append errors detected on commit.                     |
| `tryGetLastCommittedEventSequenceNumber` | Highest sequence committed.                           |
| `onCompleted`                            | A callback invoked once commit or rollback completes. |

See the [EventStore API reference](/chronicle/clients/kotlin/reference/event-store-api/#unit-of-work) for the full `IUnitOfWork`/`IUnitOfWorkManager` interfaces.

```kotlin
val unitOfWork = store.unitOfWorkManager.begin()
unitOfWork.onCompleted { completed ->
    println("Unit of work ${completed.correlationId} completed")
}
```

# Reference

Complete API and annotation reference for the Chronicle Kotlin client.

* [Annotations](/chronicle/clients/kotlin/reference/annotations/) — all annotations and their parameters
* [EventStore API](/chronicle/clients/kotlin/reference/event-store-api/) — `IEventStore`, `IEventLog`, service interfaces
* [Geospatial types](/chronicle/clients/kotlin/reference/geospatial/) — `Point`, `LineString`, `Polygon` as GeoJSON
* [Configuration](/chronicle/clients/kotlin/reference/configuration/) — `ChronicleOptions` and connection settings

# Annotations

## @EventType

[Section titled “@EventType”](#eventtype)

Marks a data class as a Chronicle event type.

| Parameter    | Type      | Default | Description                                   |
| ------------ | --------- | ------- | --------------------------------------------- |
| `id`         | `String`  | `""`    | Stable identifier. Defaults to class name.    |
| `generation` | `Int`     | `1`     | Schema version. Increment when shape changes. |
| `tombstone`  | `Boolean` | `false` | Signals event source retirement.              |

```kotlin
import io.cratis.chronicle.events.EventType

@EventType
data class OrderPlaced(val orderId: String, val totalAmount: Double)
```

Omitting `id` is the common case — Chronicle uses `OrderPlaced` as the identifier automatically.

***

## @Reactor

[Section titled “@Reactor”](#reactor)

Marks a class as a Chronicle reactor. Each public method becomes a handler for the event type of its first parameter.

| Parameter       | Type     | Default   | Description                                                                    |
| --------------- | -------- | --------- | ------------------------------------------------------------------------------ |
| `id`            | `String` | `""`      | Stable identifier. Defaults to class name.                                     |
| `eventSequence` | `String` | event log | The event sequence to observe. Overridden by [@EventSequence](#eventsequence). |

A handler takes the event, and optionally an `EventContext` carrying the event’s metadata:

```kotlin
import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.observation.Reactor

@Reactor
class OrderNotifications {
    fun orderPlaced(event: OrderPlaced) {
        println("Order ${event.orderId} placed")
    }

fun orderShipped(event: OrderShipped, context: EventContext) {
        println("Order ${event.orderId} shipped at ${context.occurred}")
    }
}
```

Supply an explicit `id` only when you need the identifier to survive class renames.

***

## @OnceOnly

[Section titled “@OnceOnly”](#onceonly)

Excludes a reactor, or a single handler, from replay. Put it on the class and the whole reactor is registered as non-replayable, so redaction, revision, and observer rewind never replay it. Put it on one method and only that handler is skipped when an event arrives as part of a replay — the reactor’s other handlers still replay.

Use it for side effects where running again is worse than never running again.

```kotlin
import io.cratis.chronicle.observation.OnceOnly
import io.cratis.chronicle.observation.Reactor

@Reactor
class PaymentNotifications {
    @OnceOnly
    fun orderPlaced(event: OrderPlaced) {
        println("Charging for ${event.orderId} - never repeated on replay")
    }
}
```

***

## @Replay

[Section titled “@Replay”](#replay)

Marks a reactor handler as the one to run while events are being replayed. When an event type has a handler marked with this, it takes over for the duration of the replay and the everyday handler does not also run. Without one, the everyday handler keeps running during replay.

Use [@OnceOnly](#onceonly) instead when the side effect should simply not happen again on replay.

```kotlin
import io.cratis.chronicle.observation.Reactor
import io.cratis.chronicle.observation.Replay

@Reactor
class ShippingNotifications {
    fun orderPlaced(event: OrderPlaced) {
        println("Emailing the customer about ${event.orderId}")
    }

@Replay
    fun orderPlacedDuringReplay(event: OrderPlaced) {
        println("Rebuilding ${event.orderId} without emailing anyone")
    }
}
```

***

## @Reducer

[Section titled “@Reducer”](#reducer)

Marks a class as a reducer. Each public method folds one event type into the read model.

| Parameter       | Type      | Default   | Description                                                                    |
| --------------- | --------- | --------- | ------------------------------------------------------------------------------ |
| `id`            | `String`  | `""`      | Stable identifier. Defaults to class name.                                     |
| `eventSequence` | `String`  | event log | The event sequence to observe. Overridden by [@EventSequence](#eventsequence). |
| `isActive`      | `Boolean` | `true`    | Whether the kernel runs the reducer.                                           |

A handler takes the event, the state so far, and optionally an `EventContext`. The state is `null` until the first event for an event source has been folded in.

```kotlin
import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.observation.Reducer

@Reducer
class OrderSummaryReducer {
    fun orderPlaced(event: OrderPlaced, state: OrderSummary?): OrderSummary =
        (state ?: OrderSummary()).copy(orderId = event.orderId)

fun orderShipped(
        event: OrderShipped,
        state: OrderSummary?,
        context: EventContext
    ): OrderSummary = (state ?: OrderSummary()).copy(status = "shipped at ${context.occurred}")
}
```

***

## @ReadModel

[Section titled “@ReadModel”](#readmodel)

Marks a data class as a Chronicle read model.

| Parameter     | Type     | Default | Description                                |
| ------------- | -------- | ------- | ------------------------------------------ |
| `id`          | `String` | `""`    | Stable identifier. Defaults to class name. |
| `displayName` | `String` | `""`    | Human-readable label. Defaults to name.    |

```kotlin
import io.cratis.chronicle.readModels.ReadModel

@ReadModel
data class OrderSummary(val orderId: String = "", val status: String = "pending")
```

***

## @Passive

[Section titled “@Passive”](#passive)

Marks a model-bound read model’s projection as passive — registered with the kernel but not actively run. A passive projection’s read model is computed on demand rather than kept up to date as events arrive. Placed on the read model class.

No parameters.

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.readModels.Passive
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class SnapshotCreated(val data: String)

@Passive
@ReadModel
@FromEvent(SnapshotCreated::class)
data class HistoricalSnapshot(val data: String = "")
```

***

## @Projection

[Section titled “@Projection”](#projection)

Marks a class as a Chronicle projection, or overrides the projection identifier on a model-bound read model. It is optional — when omitted, the class simple name is used as the identifier.

For a declarative projection the read model type is inferred from the `IProjectionFor<T>` type parameter. For a model-bound projection the annotated class is itself the read model.

```kotlin
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.Projection
import io.cratis.chronicle.readModels.ReadModel

@ReadModel
@Projection(eventSequence = "outbox")
@FromEvent(OrderPlaced::class)
data class OutboxOrderTracking(val orderId: String = "")
```

***

## @EventSequence

[Section titled “@EventSequence”](#eventsequence)

Points an observer — a reactor, a reducer or a projection — at the event sequence it observes. This is the standalone alternative to the `eventSequence` parameter on [@Reactor](#reactor), [@Reducer](#reducer) and [@Projection](#projection); reach for it when the sequence is the only thing being configured, so the observer keeps its conventional identifier.

| Parameter | Type     | Default      | Description                    |
| --------- | -------- | ------------ | ------------------------------ |
| `value`   | `String` | *(required)* | The event sequence to observe. |

```kotlin
import io.cratis.chronicle.observation.EventSequence
import io.cratis.chronicle.observation.Reactor

@Reactor
@EventSequence("outbox")
class OutboxOrderNotifications {
    fun orderPlaced(event: OrderPlaced) {
        println("Order ${event.orderId} placed, observed from the outbox")
    }
}
```

When both this annotation and the `eventSequence` parameter are present, this annotation wins.

There is no `@EventLog` counterpart. In the .NET client it exists to override the inbox routing that `[EventStore]` on an event type turns on — and the Kotlin client has no `@EventStore`, so an observer without an explicit sequence already reads from the event log.

***

## @Constraint

[Section titled “@Constraint”](#constraint)

Marks a class as a Chronicle constraint definition. The class must implement `IConstraint`.

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `id`      | `String` | `""`    | Stable identifier. Defaults to class name. |

***

## @Unique

[Section titled “@Unique”](#unique)

Marks a property or an event type as needing to be unique - the model-bound alternative to a hand-written `IConstraint`. On a property, no two events of that type may carry the same value; applying it with the same `id` to properties on more than one event type groups them under one constraint, checked across all of them combined. On an event type, at most one instance of that type may exist per event source.

| Parameter | Type     | Default | Description                                        |
| --------- | -------- | ------- | -------------------------------------------------- |
| `id`      | `String` | `""`    | Constraint name, defaulting to the property/class. |
| `message` | `String` | `""`    | Message for a constraint violation.                |

```kotlin
import io.cratis.chronicle.constraints.Unique
import io.cratis.chronicle.events.EventType

@EventType
data class ProjectCreated(@Unique val name: String, val description: String)

@EventType
@Unique
data class WorkspaceClaimed(val slug: String)
```

Pair it with [@RemoveConstraint](#removeconstraint) on a removal event to release the value for reuse.

***

## @RemoveConstraint

[Section titled “@RemoveConstraint”](#removeconstraint)

Marks an event type as releasing a named [@Unique](#unique) constraint when it is appended - typically a deletion or lifecycle-ending event. Repeatable, so one event can release more than one constraint.

Only one event type may release a given constraint name with this client - if more than one declares the same name, registration keeps the first one it finds and reports the rest, rather than silently overwriting on every reconnect.

| Parameter | Type     | Default      | Description                        |
| --------- | -------- | ------------ | ---------------------------------- |
| `value`   | `String` | *(required)* | Name of the constraint to release. |

```kotlin
import io.cratis.chronicle.constraints.RemoveConstraint
import io.cratis.chronicle.events.EventType

@EventType
@RemoveConstraint("UniqueWorkspaceSlug")
data class WorkspaceArchived(val workspaceId: String)
```

***

## @Seeder

[Section titled “@Seeder”](#seeder)

Marks a class as a Chronicle event seeder. The class must implement `ICanSeedEvents`.

***

## @Pii

[Section titled “@Pii”](#pii)

Marks a property, constructor parameter, field, or type as personally identifiable information. Chronicle encrypts annotated values at rest using a per-subject key. See [PII Attribute](/chronicle/compliance/pii/) for the full compliance model this participates in.

Applying it directly to a property works, but the declare-once pattern is to put it on a `ConceptAs<T>` type instead: every event or read model property that reuses that concept is PII automatically, with nothing to repeat at each call site. It can also mark a composite value object type, in which case every value the type holds is treated as PII wherever that type appears.

`@Pii` cannot be applied to an `EventSourceId` concept — Chronicle uses the event source id to look up the encryption key for every other PII value belonging to that source, so encrypting the id itself would make its own key unfindable.

| Parameter     | Type     | Default | Description                      |
| ------------- | -------- | ------- | -------------------------------- |
| `description` | `String` | `""`    | Note about what the field holds. |

```kotlin
import io.cratis.chronicle.compliance.Pii
import io.cratis.chronicle.events.EventType

// Declared once on the concept, every event or read model property that
// reuses EmailAddress is PII automatically.
@Pii(description = "Customer email address")
data class EmailAddress(override val value: String) : io.cratis.chronicle.concepts.ConceptAs<String>

@EventType
data class CustomerRegistered(
    val customerId: String,
    val email: EmailAddress
)
```

***

## @JsonSchemaType

[Section titled “@JsonSchemaType”](#jsonschematype)

Overrides the type a class is represented as in the generated JSON schema. Apply it to a type that brings its own serializer and writes something other than its own shape on the wire — a value object collapsed into a single string, for instance. Without it the generated schema would describe the Kotlin shape, and the value would not round-trip through the kernel.

| Parameter | Type        | Default      | Description                       |
| --------- | ----------- | ------------ | --------------------------------- |
| `type`    | `KClass<*>` | *(required)* | Type the class is represented as. |

```kotlin
import io.cratis.chronicle.schemas.JsonSchemaType

// Money serializes as a single string ("42.50 USD") through its own
// serializer, so the schema needs to describe a string, not an object
// with amount/currency fields.
@JsonSchemaType(String::class)
data class Money(val amount: Double, val currency: String)
```

Pointing the annotation at the annotated type itself throws `SelfReferencingJsonSchemaType` — generating that schema would recurse forever.

***

## @Subject

[Section titled “@Subject”](#subject)

Marks a property as the compliance subject - the identity a release decrypts [@Pii](#pii) values against. `IReadModelsService.release` uses it to pick which property carries the subject; without it, release falls back to a property named `id` (case-insensitive), the convention every read model followed before this annotation existed.

Add it whenever a read model’s subject is not its `id` - for example a support ticket keyed by ticket id but holding a customer’s PII, where the customer, not the ticket, is who the encryption key belongs to.

No parameters.

```kotlin
import io.cratis.chronicle.Subject
import io.cratis.chronicle.readModels.ReadModel

@ReadModel
data class SupportTicketSummary(
    val id: String = "",
    @Subject val customerId: String = "",
    val topic: String = ""
)
```

***

## @FromEvent

[Section titled “@FromEvent”](#fromevent)

Applied to a read model class to declare that its fields are mapped from an event type. Part of the annotation-based projection style. It is repeatable — apply it once per event type the read model projects from.

| Parameter   | Type        | Default           | Description                     |
| ----------- | ----------- | ----------------- | ------------------------------- |
| `eventType` | `KClass<*>` | *(required)*      | The source event class.         |
| `key`       | `String`    | `"EventSourceId"` | Correlates events to instances. |

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class OrderShipped(val orderId: String, val carrier: String)

@ReadModel
@FromEvent(OrderPlaced::class)
@FromEvent(OrderShipped::class)
data class OrderTracking(
    val orderId: String = "",
    val status: String = ""
)
```

***

## @Key

[Section titled “@Key”](#key)

Marks a property on an event as the key a projection correlates that event to a read model instance by. [@FromEvent](#fromevent)’s `key` parameter takes this today as a bare property-name string; `@Key` is the strongly-typed alternative for consumers that resolve the key by reflection instead of by name.

No parameters.

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.keys.Key

@EventType
data class PickTicketOpened(@Key val orderId: String, val warehouse: String)
```

***

## @ContextKey

[Section titled “@ContextKey”](#contextkey)

Marks a function as deriving its key from the event context — for example the event source id, or a correlation id — rather than from a property on the event payload.

| Parameter  | Type     | Default      | Description                     |
| ---------- | -------- | ------------ | ------------------------------- |
| `property` | `String` | *(required)* | `EventContext` property to use. |

```kotlin
import io.cratis.chronicle.keys.ContextKey

class PickTicketHandlers {
    @ContextKey(property = "EventSourceId")
    fun pickTicketOpened(event: PickTicketOpened) = Unit
}
```

`IKeyBuilder`/`KeyBuilder` build the same resolution fluently instead of declaratively — see the `io.cratis.chronicle.keys` package.

***

## @SetFrom

[Section titled “@SetFrom”](#setfrom)

Applied to a read model property to override auto-mapping by name and declare which event field populates it. It is repeatable, so one property can be mapped differently per event type.

| Parameter      | Type        | Default          | Description                  |
| -------------- | ----------- | ---------------- | ---------------------------- |
| `propertyPath` | `String`    | `""`             | Path to the source property. |
| `eventType`    | `KClass<*>` | `Nothing::class` | Event it applies to.         |

`propertyPath` is a dot-separated path on the event, and defaults to the annotated property’s own name. The default `eventType` applies the mapping to every event in the read model’s `@FromEvent` list that has a matching source property.

***

## @SetValue

[Section titled “@SetValue”](#setvalue)

Sets a read model property to a constant value when a specific event occurs, or clears it back to no value. It is repeatable, so the same property can hold a different constant per event type.

| Parameter   | Type        | Default | Description                                      |
| ----------- | ----------- | ------- | ------------------------------------------------ |
| `eventType` | `KClass<*>` | —       | The event class to trigger on.                   |
| `value`     | `String`    | `""`    | The constant’s literal text. Ignored if `clear`. |
| `clear`     | `Boolean`   | `false` | Clears instead of setting `value`.               |

Kotlin annotation parameters cannot be nullable, so `value` is always a plain string — a numeric or boolean constant is written out as its literal text (`"42"`, `"true"`) rather than as a typed argument. Set `clear = true` to clear the property instead, which is Kotlin’s equivalent of passing `null` for `value` in the .NET client.

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.SetValue
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class SubscriptionActivated(val placeholder: Boolean = true)

@EventType
data class SubscriptionCanceled(val placeholder: Boolean = true)

@ReadModel
@FromEvent(SubscriptionActivated::class)
@FromEvent(SubscriptionCanceled::class)
data class Subscription(
    @SetValue(SubscriptionActivated::class, value = "active")
    @SetValue(SubscriptionCanceled::class, value = "canceled")
    val status: String = ""
)
```

***

## @SetFromContext

[Section titled “@SetFromContext”](#setfromcontext)

Maps a read model property from a named `EventContext` property, for one specific event. Unlike [@FromAll / @FromEvery](#fromall--fromevery), which map a context property across every event the projection observes, this ties the mapping to a single event type.

| Parameter         | Type        | Default | Description                              |
| ----------------- | ----------- | ------- | ---------------------------------------- |
| `eventType`       | `KClass<*>` | —       | The event class this mapping applies to. |
| `contextProperty` | `String`    | `""`    | The context property to read from.       |

`contextProperty` defaults to the annotated property’s own name.

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.SetFrom
import io.cratis.chronicle.projections.SetFromContext
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class OrderPlacedForAudit(val customerName: String)

@ReadModel
@FromEvent(OrderPlacedForAudit::class)
data class AuditedOrder(
    @SetFrom("customerName", OrderPlacedForAudit::class)
    val customerName: String = "",

@SetFromContext(OrderPlacedForAudit::class, contextProperty = "occurred")
    val orderedAt: String = ""
)
```

***

## @Join

[Section titled “@Join”](#join)

Populates a read model property by joining against another event type on its event source id. Use it when the triggering event doesn’t carry the read model’s own key but instead references another entity by id.

| Parameter           | Type        | Default | Description                      |
| ------------------- | ----------- | ------- | -------------------------------- |
| `eventType`         | `KClass<*>` | —       | The event class to join against. |
| `on`                | `String`    | `""`    | Read model property to join on.  |
| `eventPropertyName` | `String`    | `""`    | Property on `eventType` to read. |

`on` and `eventPropertyName` both default to the annotated property’s own name.

```kotlin
import io.cratis.chronicle.projections.Join
import io.cratis.chronicle.readModels.ReadModel

@ReadModel
data class OrderWithCustomerEmail(
    val orderId: String = "",
    val customerId: String = "",
    @Join(
        eventType = CustomerRegistered::class,
        on = "customerId",
        eventPropertyName = "email"
    )
    val customerEmail: String = ""
)
```

***

## @ChildrenFrom

[Section titled “@ChildrenFrom”](#childrenfrom)

Declares that a collection property is populated with child read model instances created or updated by a specific event type.

| Parameter      | Type        | Default           | Description                            |
| -------------- | ----------- | ----------------- | -------------------------------------- |
| `eventType`    | `KClass<*>` | —                 | The event class that creates children. |
| `key`          | `String`    | `"EventSourceId"` | Event property identifying the child.  |
| `identifiedBy` | `String`    | `""`              | Child’s own identity property.         |
| `parentKey`    | `String`    | `"EventSourceId"` | Event property for the parent.         |

`identifiedBy` defaults to the child type’s `id`/`key` property, falling back to `EventSourceId`.

***

## @Nested

[Section titled “@Nested”](#nested)

Marks a single nullable property as a nested sub-object built from its own type’s `@FromEvent`/`@SetFrom` annotations.

No parameters.

***

## @ClearWith

[Section titled “@ClearWith”](#clearwith)

Declares which event clears (nulls out) a `@Nested` property. Placed on the nested type itself, alongside its `@FromEvent` annotation.

| Parameter   | Type        | Description                                    |
| ----------- | ----------- | ---------------------------------------------- |
| `eventType` | `KClass<*>` | The event class that clears the nested object. |

***

## @Count

[Section titled “@Count”](#count)

Turns a property into an occurrence counter for a specific event type — every time `eventType` fires for the read model instance, the property is bumped by one.

| Parameter     | Type        | Default | Description                              |
| ------------- | ----------- | ------- | ---------------------------------------- |
| `eventType`   | `KClass<*>` | —       | The event class to count occurrences of. |
| `constantKey` | `String`    | `""`    | See “Constant keys” below.               |

***

## @Increment / @Decrement

[Section titled “@Increment / @Decrement”](#increment--decrement)

Bumps a numeric property up (`@Increment`) or down (`@Decrement`) by one every time `eventType` fires for the read model instance.

| Parameter     | Type        | Default | Description                              |
| ------------- | ----------- | ------- | ---------------------------------------- |
| `eventType`   | `KClass<*>` | —       | The event class that bumps the property. |
| `constantKey` | `String`    | `""`    | See “Constant keys” below.               |

```kotlin
import io.cratis.chronicle.projections.Increment
import io.cratis.chronicle.readModels.ReadModel

@ReadModel
data class OrderShipmentStats(
    val orderId: String = "",
    @Increment(OrderShipped::class) val shipmentCount: Int = 0
)
```

**Constant keys:** when `constantKey` is set on `@Count`, `@Increment`, or `@Decrement`, every occurrence of `eventType` updates the same read model instance, identified by that constant value, instead of the projection’s normal per-instance key resolution.

***

## @AddFrom / @SubtractFrom

[Section titled “@AddFrom / @SubtractFrom”](#addfrom--subtractfrom)

Adds (`@AddFrom`) or subtracts (`@SubtractFrom`) the value of an event property into/from a numeric property every time `eventType` fires.

| Parameter           | Type        | Default | Description                         |
| ------------------- | ----------- | ------- | ----------------------------------- |
| `eventType`         | `KClass<*>` | —       | The event class carrying the value. |
| `eventPropertyName` | `String`    | `""`    | Property on `eventType` to read.    |

`eventPropertyName` defaults to the annotated property’s own name.

***

## @FromAll / @FromEvery

[Section titled “@FromAll / @FromEvery”](#fromall--fromevery)

Projects a property from every event type the projection observes, rather than a single one. `@FromAll` and `@FromEvery` are equivalent aliases.

| Parameter         | Type     | Default | Description                             |
| ----------------- | -------- | ------- | --------------------------------------- |
| `property`        | `String` | `""`    | Triggering event property to read from. |
| `contextProperty` | `String` | `""`    | Event context property to read from.    |

Both default to the annotated property’s own name. `contextProperty` (e.g. the causing identity) takes precedence over `property` when both are set.

***

## @NotRewindable

[Section titled “@NotRewindable”](#notrewindable)

Marks a projection as forward-only — it cannot be rewound and replayed from scratch. Placed on the read model class.

No parameters.

***

## @RemovedWith

[Section titled “@RemovedWith”](#removedwith)

Declares which event removes a read model instance, or — when placed on a `@ChildrenFrom` property — which event removes a single child from that collection.

| Parameter   | Type        | Default           | Description                            |
| ----------- | ----------- | ----------------- | -------------------------------------- |
| `eventType` | `KClass<*>` | —                 | The event class that triggers removal. |
| `key`       | `String`    | `"EventSourceId"` | Event property for what to remove.     |
| `parentKey` | `String`    | `"EventSourceId"` | Event property for the parent.         |

`parentKey` only applies when removing a single child from a `@ChildrenFrom` collection.

***

## @RemovedWithJoin

[Section titled “@RemovedWithJoin”](#removedwithjoin)

Like `@RemovedWith`, but the removal event doesn’t directly carry the id — it’s resolved via a join instead.

| Parameter   | Type        | Default           | Description                                |
| ----------- | ----------- | ----------------- | ------------------------------------------ |
| `eventType` | `KClass<*>` | —                 | The event class that triggers the removal. |
| `key`       | `String`    | `"EventSourceId"` | Property used in the join lookup.          |

***

## @NoAutoMap

[Section titled “@NoAutoMap”](#noautomap)

Disables AutoMap. Placed on a read model, `@ChildrenFrom` element, or `@Nested` type, it disables AutoMap entirely for that type. Placed on a single property, it excludes just that property from AutoMap while siblings keep auto-mapping.

No parameters.

***

## @Webhook

[Section titled “@Webhook”](#webhook)

Marks a class as a discoverable Chronicle webhook definition. The class must implement `IWebhookDefiner`.

| Parameter   | Type     | Default | Description                                |
| ----------- | -------- | ------- | ------------------------------------------ |
| `id`        | `String` | `""`    | Stable identifier. Defaults to class name. |
| `targetUrl` | `String` | —       | The URL to send events to.                 |

```kotlin
import io.cratis.chronicle.webhooks.IWebhookDefiner
import io.cratis.chronicle.webhooks.IWebhookDefinitionBuilder
import io.cratis.chronicle.webhooks.Webhook

@Webhook(targetUrl = "https://hooks.example.com/orders")
class OrderPlacedWebhook : IWebhookDefiner {
    override fun define(builder: IWebhookDefinitionBuilder) {
        builder.withEventType(OrderPlaced::class)
    }
}
```

# Configuration

## ChronicleOptions

[Section titled “ChronicleOptions”](#chronicleoptions)

```kotlin
data class ChronicleOptions(
    val connectionString: ChronicleConnectionString,
    val programIdentifier: String = "Unknown",
    val defaultSinkTypeId: String = System.getenv("CHRONICLE_SINK_TYPE") ?: WellKnownSinkTypes.MONGODB,
    val autoDiscoverAndRegister: Boolean = true,
    val artifacts: IClientArtifacts = ClientArtifacts.default,
    val artifactActivator: IArtifactActivator = ArtifactActivator,
    val openTelemetry: OpenTelemetry? = null
)
```

| Property                  | Default                   | Description                                                               |
| ------------------------- | ------------------------- | ------------------------------------------------------------------------- |
| `connectionString`        | *(required)*              | Parsed address of the server                                              |
| `programIdentifier`       | `"Unknown"`               | Name of the connecting program                                            |
| `defaultSinkTypeId`       | `MongoDB`                 | Sink for reducers and projections                                         |
| `autoDiscoverAndRegister` | `true`                    | Register artifacts on connect                                             |
| `artifacts`               | `ClientArtifacts.default` | What the application is made of                                           |
| `artifactActivator`       | `ArtifactActivator`       | How artifacts are created                                                 |
| `openTelemetry`           | `null`                    | Where spans go — see [Tracing](/chronicle/clients/kotlin/guides/tracing/) |

`programIdentifier` is a human-readable label that shows up in diagnostics. `defaultSinkTypeId` defaults to `WellKnownSinkTypes.MONGODB`, and can be overridden per process with the `CHRONICLE_SINK_TYPE` environment variable — for example `CHRONICLE_SINK_TYPE=SQL`.

The last three control artifact discovery and registration. Two helpers cover the common adjustments — see [Artifact Registration](/chronicle/clients/kotlin/guides/artifact-registration/) for the full picture:

```kotlin
ChronicleOptions.development().withoutAutoRegistration()
ChronicleOptions.development().withArtifactsFrom("com.acme.ordering")
```

There are two factories on the companion object:

```kotlin
ChronicleOptions.fromConnectionString("chronicle://chronicle.internal:35000")
ChronicleOptions.development()
```

From Java, reach them through `Companion`:

```java
ChronicleOptions.Companion.fromConnectionString("chronicle://chronicle.internal:35000");
ChronicleOptions.Companion.development();
```

## Connection string format

[Section titled “Connection string format”](#connection-string-format)

```text
chronicle://<host>[:<port>][,<host>[:<port>]...][?<options>]
chronicle://<username>:<password>@<host>[:<port>][,...][?<options>]
chronicle+srv://<host>[:<port>][?<options>]
```

The port defaults to `35000` when omitted. IPv6 literals use bracket notation — `chronicle://[::1]:35000`. A `chronicle+srv://` connection string accepts exactly one host, and DNS SRV records supply the real targets and ports.

### Query string options

[Section titled “Query string options”](#query-string-options)

| Option              | Default            | Description                           |
| ------------------- | ------------------ | ------------------------------------- |
| `disableTls`        | `false`            | Connect over plaintext instead of TLS |
| `skipTlsValidation` | `true`             | Accept any server certificate         |
| `apiKey`            | *(none)*           | API key to authenticate with          |
| `loadBalancer`      | `leastConnections` | Policy across multiple addresses      |
| `srvNameServer`     | *(none)*           | DNS server for `chronicle+srv://`     |

`skipTlsValidation` accepts self-signed certificates. Set it to `false` to require full certificate chain validation.

```kotlin
val options = ChronicleOptions.fromConnectionString(
    "chronicle://my-client:my-secret@chronicle.internal:35000?skipTlsValidation=false"
)
```

### Round-tripping to a string

[Section titled “Round-tripping to a string”](#round-tripping-to-a-string)

`ChronicleConnectionString.toString()` renders a parsed connection string back to its `chronicle://`/`chronicle+srv://` textual form. The result isn’t guaranteed to be byte-identical to whatever was originally parsed — for example a host without an explicit port is rendered with the resolved default port — but re-parsing it always yields an equal `ChronicleConnectionString`. This is useful for logging or persisting a connection string that was built up programmatically rather than typed by hand:

```kotlin
import io.cratis.chronicle.connection.ChronicleConnectionString

val original = ChronicleConnectionString.parse(
    "chronicle://my-client:my-secret@chronicle.internal:35000?skipTlsValidation=false"
)
val rendered = original.toString()
val reparsed = ChronicleConnectionString.parse(rendered)
check(reparsed == original)
```

## Development shortcut

[Section titled “Development shortcut”](#development-shortcut)

```kotlin
val client = ChronicleClient(ChronicleOptions.development())
```

Equivalent to a connection string of `chronicle://chronicle-dev-client:chronicle-dev-secret@localhost:35000`. It connects over TLS but skips certificate validation, so it works against the Kernel’s self-signed development certificate without further configuration.

## TLS and authentication

[Section titled “TLS and authentication”](#tls-and-authentication)

The client connects over TLS by default. Certificate validation is skipped unless you set `skipTlsValidation=false`, which makes the client validate the certificate chain against the platform trust manager — do that whenever the server’s certificate is verifiable. Set `disableTls=true` only for plaintext environments.

Credentials are supplied either as a username and password in the connection string’s user info section, or as an `apiKey` query option.

## Namespace

[Section titled “Namespace”](#namespace)

See [Namespaces](/chronicle/concepts/namespaces/) for the full tenancy model. The default namespace is `"Default"`. Override it when calling `getEventStore`:

```kotlin
val store = client.getEventStore("MyApp", namespace = "production")
```

The `namespace` default applies to Kotlin callers only — from Java, pass both arguments:

```java
import io.cratis.chronicle.EventStore;

EventStore store = client.getEventStore("MyApp", "production");
```

`BlockingChronicleClient` has both forms, so a Java application using it can name the namespace or leave it at the default — see [Java interop](/chronicle/clients/kotlin/reference/event-store-api/#java-interop).

# EventStore API

## IChronicleClient

[Section titled “IChronicleClient”](#ichronicleclient)

Entry point for the library.

```kotlin
interface IChronicleClient : AutoCloseable {
    fun getEventStore(
        name: String,
        namespace: String = EventStoreNamespaceName.default.value
    ): EventStore

suspend fun getEventStores(): List<String>
    fun evictEventStores()
    fun dispose()
}
```

Construct it with [ChronicleOptions](/chronicle/clients/kotlin/reference/configuration/):

```kotlin
// localhost:35000
ChronicleClient(ChronicleOptions.development())

// any server
ChronicleClient(
    ChronicleOptions.fromConnectionString("chronicle://chronicle.internal")
)
```

`getEventStores` lists every event store known to the kernel — not just the ones this client has already opened via `getEventStore`. `evictEventStores` clears this client’s internal cache of `EventStore` instances (and their per-store subscriptions) without disposing the client itself — useful between test classes that share a client instance.

***

## IEventStore

[Section titled “IEventStore”](#ieventstore)

```kotlin
interface IEventStore {
    val name: String
    val namespace: String
    val eventLog: IEventLog
    val reactors: IReactorsService
    val reducers: IReducersService
    val projections: IProjectionsService
    val constraints: IConstraintsService
    val seeding: IEventSeedingService
    val readModels: IReadModelsService
    val unitOfWorkManager: UnitOfWorkManager
    val compliance: IComplianceService
    val eventTypes: IEventTypesService
    val namespaces: INamespacesService
    val externalServices: IExternalServicesService
    val jobs: IJobsService
    val eventStoreSubscriptions: IEventStoreSubscriptionsService
    val webhooks: IWebhooksService
    val identities: IIdentityManagerService
    val failedPartitions: IFailedPartitions

fun getEventSequence(id: EventSequenceId): IEventSequence
}
```

Every service is now on the interface itself — `compliance`, `eventTypes`, `namespaces`, `externalServices`, `jobs`, `eventStoreSubscriptions`, `webhooks`, and `identities` used to be available only on the concrete `EventStore` class; code written against `IEventStore` (for example in tests, behind a fake) now sees the full surface.

`eventLog` is the default event log sequence (`EventSequenceId.eventLog`). Use `getEventSequence(id)` to get any other, non-default `IEventSequence` by id — for example one used exclusively by a specific subsystem.

***

## IEventSequence and IEventLog

[Section titled “IEventSequence and IEventLog”](#ieventsequence-and-ieventlog)

`IEventLog` is `IEventSequence` plus a `transactional` entry point; both share the same read/write surface.

```kotlin
interface IEventSequence {
    val id: EventSequenceId
    val appendOperations: SharedFlow<List<AppendedEventWithResult>>

suspend fun append(
        eventSourceId: String,
        event: Any,
        options: AppendOptions? = null
    ): AppendResult
    suspend fun appendMany(
        eventSourceId: String,
        events: List<Any>,
        options: AppendOptions? = null
    ): List<AppendResult>
    suspend fun appendMany(
        events: List<EventForEventSourceId>,
        concurrencyScopes: Map<String, ConcurrencyScope> = emptyMap(),
        correlationId: UUID? = null
    ): List<AppendResult>
    suspend fun hasEventsFor(eventSourceId: String): Boolean

suspend fun getTailSequenceNumber(
        eventSourceId: String? = null
    ): EventSequenceNumber
    suspend fun getForEventSourceIdAndEventTypes(
        eventSourceId: String,
        eventTypes: List<KClass<*>>,
        eventStreamType: String? = null,
        eventStreamId: String? = null,
        eventSourceType: String? = null
    ): List<AppendedEvent>
    suspend fun getFromSequenceNumber(
        sequenceNumber: EventSequenceNumber,
        eventSourceId: String? = null,
        eventTypes: List<KClass<*>>? = null
    ): List<AppendedEvent>
    suspend fun getNextSequenceNumber(): EventSequenceNumber
    suspend fun getTailSequenceNumberForObserver(
        observerType: KClass<*>
    ): EventSequenceNumber

suspend fun completeStream(
        eventStreamType: String,
        eventStreamId: String
    ): CompleteStreamResult

suspend fun redact(
        sequenceNumber: EventSequenceNumber,
        reason: RedactionReason
    )
    suspend fun redactForEventSource(
        eventSourceId: String,
        reason: RedactionReason,
        eventTypes: List<KClass<*>> = emptyList()
    )
}

interface IEventLog : IEventSequence {
    val transactional: ITransactionalEventSequence
}
```

### Appending across event sources

[Section titled “Appending across event sources”](#appending-across-event-sources)

The `eventSourceId` overload of `appendMany` shapes every event in the batch the same way. The `List<EventForEventSourceId>` overload instead lets each event carry its own event source id and its own shaping, so one atomic batch can span many event sources and many streams. `concurrencyScopes` is keyed by event source id — only the sources present in the map are concurrency checked, and any source left out is appended unchecked.

```kotlin
data class EventForEventSourceId(
    val eventSourceId: String,
    val event: Any,
    val eventStreamType: String? = null,
    val eventStreamId: String? = null,
    val eventSourceType: String? = null,
    val tags: List<String> = emptyList(),
    val occurred: Instant? = null,
    val subject: String? = null,
    val causation: List<Causation> = emptyList()
)
```

Every unset field falls back to the same default a plain `append` uses, resolved against that event’s own event source id.

### Composed operations

[Section titled “Composed operations”](#composed-operations)

`IEventSequenceOperations` composes a batch that is decided in more than one place, then commits it with a single `perform()`. Start one with the `operations()` or `forEventSourceId(...)` extension on any `IEventSequence`. Nothing reaches the kernel until `perform()` runs, and `getEventsToAppend()` shows exactly what it will send.

```kotlin
interface IEventSequenceOperations {
    val eventSequence: IEventSequence

fun forEventSourceId(
        eventSourceId: String,
        configure: IEventSourceOperations.() -> Unit
    ): IEventSequenceOperations
    fun withCorrelationId(correlationId: UUID): IEventSequenceOperations
    fun withCausation(causation: List<Causation>): IEventSequenceOperations
    fun getAppendedEvents(): List<Any>
    fun getEventsToAppend(): List<EventForEventSourceId>
    fun clear()
    suspend fun perform(): List<AppendResult>
}

interface IEventSourceOperations {
    val operations: List<IEventSequenceOperation>
    val concurrencyScope: ConcurrencyScope

fun withConcurrencyScope(concurrencyScope: ConcurrencyScope): IEventSourceOperations
    fun withConcurrencyScope(
        configure: ConcurrencyScopeBuilder.() -> Unit
    ): IEventSourceOperations
    fun append(
        event: Any,
        eventStreamType: String? = null,
        eventStreamId: String? = null,
        eventSourceType: String? = null,
        tags: List<String> = emptyList(),
        occurred: Instant? = null,
        subject: String? = null
    ): IEventSourceOperations
    fun <T : IEventSequenceOperation> getOperationsOfType(type: KClass<T>): List<T>
    fun getAppendedEvents(): List<Any>
}
```

Calling `forEventSourceId` twice for the same event source adds to what is already staged rather than replacing it. The concurrency scope lives on the event source, since that is where the kernel checks it: an event source that never sets one is appended unchecked, and a scope already set is never cleared by a later `ConcurrencyScope.notSet` — so a call that expresses no expectation cannot silently disable a check that was explicitly asked for.

Causation is not composed here; it is derived from the ambient `CausationManager` when `perform()` runs.

Java reaches this through `EventSequenceOperationsJavaBridge` (`operationsFor`, `forEventSourceId`, `perform`) and `EventSourceOperationsJavaBridge` (`append`, `withConcurrencyScope`), which supply the blocking calls, `Consumer`-based configuration, and the optional parameters Kotlin default arguments cannot give Java.

### Reading events back

[Section titled “Reading events back”](#reading-events-back)

`getForEventSourceIdAndEventTypes` gets events for one event source, narrowed to specific event types and (optionally) a specific stream. `getFromSequenceNumber` instead reads forward from a position in the sequence, optionally narrowed by event source and/or event type — useful for catching up from a bookmark. `getTailSequenceNumber` and `getNextSequenceNumber` report the current end of the sequence (or of one event source’s events within it) and the sequence number the *next* appended event will receive, respectively. `getTailSequenceNumberForObserver` reports the tail relative to the event types a specific reactor or reducer type actually handles (discovered by reflection over its handler methods).

```kotlin
data class AppendedEvent(
    val context: EventContext,
    val content: String
)
```

`content` is the event’s raw stored JSON — deserialize it with the concrete event class matching `context.eventType` to get a typed event object.

### Redacting events

[Section titled “Redacting events”](#redacting-events)

`redact` permanently rewrites a single event’s content, identified by its sequence number. `redactForEventSource` does the same for every event of a given event source, optionally narrowed to specific event types (an empty list, the default, redacts every event type for that source). **Both are destructive, irreversible content rewrites — not a soft delete or a field mask.** Once either call returns, the original content is gone from the event store for good. Use them only for a confirmed compliance/erasure request (e.g. GDPR “right to be forgotten”), typically alongside [`IComplianceService.deleteEncryptionKey`](#icomplianceservice) rather than instead of it — deleting the encryption key is non-destructive to event content (it just becomes unreadable), while redaction actually erases it.

```kotlin
@JvmInline
value class RedactionReason(val value: String)

sealed class CompleteStreamResult {
    data class Success(
        val sequenceNumber: EventSequenceNumber
    ) : CompleteStreamResult()
    data object DefaultStreamCannotBeCompleted : CompleteStreamResult()
    data object AlreadyCompleted : CompleteStreamResult()
}
```

### Completing a stream

[Section titled “Completing a stream”](#completing-a-stream)

`completeStream` marks an event stream type/id pair as closed so no further events can be appended to it, returning a `CompleteStreamResult`. The default stream (`"Default"` paired with the default event stream id, the one every plain `append`/`appendMany` call writes to) can never be completed. Completing an already-completed stream returns `CompleteStreamResult.AlreadyCompleted` rather than throwing.

### Observing appends: `appendOperations`

[Section titled “Observing appends: appendOperations”](#observing-appends-appendoperations)

`appendOperations` is a hot `SharedFlow` that emits after every append made *through that specific `IEventSequence` instance* completes, whether it succeeded or failed — a single-event `append` emits a list of one element, a batch `appendMany` emits the whole batch. It does not emit for transactional appends made through `ITransactionalEventSequence` (those only emit, as part of the underlying batch, once the unit of work commits and the real append happens). Being a *hot* flow, only appends made after a subscriber starts collecting are seen — nothing is replayed.

```kotlin
data class AppendedEventWithResult(
    val context: EventContext,
    val event: Any,
    val result: AppendResult
)
```

### Concurrency control

[Section titled “Concurrency control”](#concurrency-control)

Optimistic concurrency is opt-in per append, via `AppendOptions.concurrencyScope`:

```kotlin
data class AppendOptions(
    val correlationId: UUID? = null,
    val concurrencyScope: ConcurrencyScope? = null,
    val eventSourceType: String? = null,
    val eventStreamType: String? = null,
    val eventStreamId: String? = null,
    val subject: String? = null,
    val tags: List<String> = emptyList(),
    val occurred: Instant? = null,
    val causation: List<Causation> = emptyList()
)

data class ConcurrencyScope(
    val sequenceNumber: EventSequenceNumber,
    val eventSourceId: Boolean = false,
    val eventStreamType: String? = null,
    val eventStreamId: String? = null,
    val eventSourceType: String? = null,
    val eventTypes: List<EventTypeDescriptor> = emptyList()
)
```

Build one with `ConcurrencyScopeBuilder` rather than the constructor directly — `withSequenceNumber` sets the expected position, and `withEventSourceId`/`withEventStreamType`/`withEventStreamId`/ `withEventSourceType`/`withEventType(s)` each narrow which dimension the check applies to. Leaving `concurrencyScope` unset (the default) is equivalent to `ConcurrencyScope.none` — the append is not concurrency checked. When the scope no longer matches, the append fails with `AppendResult.concurrencyViolation` set instead of throwing.

### Causation

[Section titled “Causation”](#causation)

Every append carries a causation chain describing what led to it. By default that chain is ambient: `CausationManager` builds one up per thread, and the append reads it as it goes. Nearly every append should leave it at that.

Set `AppendOptions.causation` to attribute an append to a different chain — an event imported from a legacy system, or a side effect that belongs to a chain of its own rather than to the work the current thread happens to be doing. An override deliberately leaves the ambient chain untouched, so later appends are not attributed to something they had nothing to do with.

```kotlin
import io.cratis.chronicle.auditing.Causation
import io.cratis.chronicle.auditing.CausationType
import io.cratis.chronicle.eventSequences.AppendOptions
import java.time.Instant

store.eventLog.append(
    "employee-1",
    EmployeeHired("Ada", "Lovelace", "Engineer"),
    AppendOptions(
        causation = listOf(
            Causation(
                Instant.parse("1998-06-01T09:00:00Z"),
                CausationType("LegacyImport"),
                mapOf("file" to "1998.csv")
            )
        )
    )
)
```

`EventForEventSourceId` carries the same field, which is how a reactor side effect names its own chain. One caveat applies to batches: the kernel carries a single chain per `appendMany`, not one per event, so a batch whose events declare different chains throws `CausationDiffersAcrossBatch` rather than silently keeping one of them. Give them the same causation, leave it unset, or append them as separate batches. For a composed operation, set it once for the whole batch with `withCausation`.

From Java, use `AppendOptionsBuilder.causation(...)`.

### AppendResult

[Section titled “AppendResult”](#appendresult)

| Property               | Type                        | Description                                   |
| ---------------------- | --------------------------- | --------------------------------------------- |
| `isSuccess`            | `Boolean`                   | `true` when there are no violations or errors |
| `sequenceNumber`       | `EventSequenceNumber`       | Position in the event log                     |
| `constraintViolations` | `List<ConstraintViolation>` | On failure                                    |
| `errors`               | `List<AppendError>`         | On failure                                    |
| `concurrencyViolation` | `ConcurrencyViolation?`     | Set on stale scope                            |

***

## Unit of work

[Section titled “Unit of work”](#unit-of-work)

`IEventStore.unitOfWorkManager` returns an `IUnitOfWorkManager`, which creates and tracks `IUnitOfWork` instances scoped to the current thread.

```kotlin
interface IUnitOfWorkManager {
    val current: IUnitOfWork
    val hasCurrent: Boolean
    fun tryGetFor(correlationId: CorrelationId): IUnitOfWork?
    fun begin(): IUnitOfWork
    fun begin(correlationId: CorrelationId): IUnitOfWork
    fun setCurrent(unitOfWork: IUnitOfWork)
}

interface IUnitOfWork {
    val isCompleted: Boolean
    val correlationId: CorrelationId
    val isSuccess: Boolean

fun addEvent(
        eventSequenceId: EventSequenceId,
        eventSourceId: String,
        event: Any,
        options: AppendOptions? = null
    )
    fun getEvents(): List<Any>
    fun getConstraintViolations(): List<ConstraintViolation>
    fun getConcurrencyViolations(): List<ConcurrencyViolation>
    fun getAppendErrors(): List<AppendError>

suspend fun commit()
    suspend fun rollback()

fun onCompleted(callback: (IUnitOfWork) -> Unit)
    fun tryGetLastCommittedEventSequenceNumber(): EventSequenceNumber?
}
```

`current` throws `NoUnitOfWorkHasBeenStarted` if `begin` hasn’t been called on this thread — check `hasCurrent` first if that’s expected. Prefer staging events through `store.eventLog.transactional.append`/`appendMany` (see [Transactions](/chronicle/clients/kotlin/guides/transactions/)) over calling `addEvent` directly; the transactional event sequence resolves the right `EventSequenceId` for you.

After `commit()`, `isSuccess` reflects whether every staged event was appended without a constraint violation, concurrency violation, or append error; `getConstraintViolations()`/`getConcurrencyViolations()`/ `getAppendErrors()` report the specifics, and `tryGetLastCommittedEventSequenceNumber()` returns the highest sequence number actually committed (`null` if nothing committed). `onCompleted` registers a callback invoked once, whether the unit of work ends via `commit()` or `rollback()` — it can be called multiple times to register several callbacks.

***

## IIdentityManagerService

[Section titled “IIdentityManagerService”](#iidentitymanagerservice)

```kotlin
interface IIdentityManagerService {
    suspend fun rename(subject: String, name: String)
}
```

Renames the human-readable name the kernel has stored for the identity identified by `subject`. This only updates the stored display name; it does not change the `Identity` objects your process is currently using — see [Correlation and identity](/chronicle/concepts/correlation-identity-causation/).

***

## INamespacesService

[Section titled “INamespacesService”](#inamespacesservice)

```kotlin
interface INamespacesService {
    suspend fun ensure(namespaceName: String)
    suspend fun getAll(): List<String>
}
```

`ensure` creates a namespace if it doesn’t already exist (idempotent). `getAll` lists every namespace in the event store.

***

## IReactorsService

[Section titled “IReactorsService”](#ireactorsservice)

```kotlin
interface IReactorsService {
    suspend fun register(reactor: Any): Job
}
```

A handler takes the event first, and after that anything the client can supply for it — an `EventContext`, a read model resolved for the event’s event source, or whatever an `IReactorMethodArgumentResolver` claims. Handlers may suspend. `IReactorMiddleware` wraps every invocation. See [Artifact Registration](/chronicle/clients/kotlin/guides/artifact-registration/) for both.

### Being told about a replay

[Section titled “Being told about a replay”](#being-told-about-a-replay)

Implement `ICanBeNotifiedAboutReplay` and declare `replayBegan` and/or `replayEnded`. Each takes a `ReplayContext` or nothing at all, and may suspend. Chronicle replays each event source independently, so the notifications arrive once per partition rather than once overall.

```kotlin
data class ReplayContext(
    val observerId: String,
    val partition: String,
    val sequenceNumber: EventSequenceNumber
)
```

The kernel flags the first and last event of a replay rather than sending a separate signal, so `replayBegan` runs immediately before the first replayed event is handled and `replayEnded` immediately after the last. A replay that delivers no events produces no notification — there was no first event to flag.

Implementing the interface and declaring neither method is rejected at registration: a marker with nothing behind it would silently do nothing.

***

## IFailedPartitions

[Section titled “IFailedPartitions”](#ifailedpartitions)

A handler that throws stops the event source it threw on and leaves every other one running. That keeps one bad event from halting the system, and it also means a stuck partition announces itself nowhere. `store.failedPartitions` is how an application finds out, and how an operator recovers once the cause is fixed.

```kotlin
interface IFailedPartitions {
    suspend fun getFor(observerId: String): List<FailedPartition>
    suspend fun getFor(observerClass: KClass<*>): List<FailedPartition>
    suspend fun retry(
        observerId: String,
        partition: String,
        eventSequenceId: EventSequenceId = EventSequenceId.eventLog
    )
    suspend fun retry(observerClass: KClass<*>, partition: String)
}

data class FailedPartition(
    val id: UUID,
    val observerId: String,
    val partition: String,
    val attempts: List<FailedPartitionAttempt>
) {
    val lastAttempt: FailedPartitionAttempt?
}

data class FailedPartitionAttempt(
    val occurred: Instant,
    val sequenceNumber: EventSequenceNumber,
    val messages: List<String>,
    val stackTrace: String
)
```

The overloads taking a `KClass` read the observer’s id — and, when retrying, the sequence it observes — off the class exactly as registration does, so an observer can be asked about by type rather than by remembering what its id came out as.

`attempts` is the history of the problem, oldest first: `lastAttempt` is the one still standing in the way. Retrying an observer whose cause has not been fixed simply adds another attempt, so fix first and retry after.

***

## IReducersService

[Section titled “IReducersService”](#ireducersservice)

```kotlin
interface IReducersService {
    suspend fun register(reducer: Any): Job
}
```

***

## IReadModelsService

[Section titled “IReadModelsService”](#ireadmodelsservice)

```kotlin
interface IReadModelsService {
    suspend fun register(vararg readModelClasses: KClass<*>)

suspend fun <T : Any> getInstanceByKey(
        readModelClass: KClass<T>,
        key: String
    ): T?

suspend fun <T : Any> getInstances(
        readModelClass: KClass<T>,
        eventCount: Long? = null
    ): List<T>

suspend fun <T : Any> getSnapshotsById(
        readModelClass: KClass<T>,
        key: String
    ): List<ReadModelSnapshot<T>>

fun <T : Any> watch(readModelClass: KClass<T>): Flow<ReadModelChangeset<T>>

suspend fun dehydrateSession(
        readModelClass: KClass<*>,
        key: String,
        sessionId: String
    )

suspend fun <T : Any> release(instance: T, subject: String? = null): T
    suspend fun <T : Any> releaseMany(instances: List<T>): List<T>

val materialized: IMaterializedReadModels
}
```

* `getInstances` replays events in-process to produce every instance of a read model, optionally capped to the first `eventCount` events.
* `getSnapshotsById` returns the full history of intermediate states for one read model key, grouped by correlation id — each `ReadModelSnapshot` carries the deserialized `instance`, the `events` that produced it, and (when known) when they `occurred` and their `correlationId`. Unlike `getInstanceByKey`, which only returns the latest state, this is the way to inspect how a read model got to where it is.
* `watch` returns a `Flow<ReadModelChangeset<T>>` of live changes, deserialized straight into `T` — no polling, no manual JSON parsing. Each `ReadModelChangeset` carries the `modelKey`, the `changeType` (`Added`/`Modified`/`Removed`), the deserialized `readModel` (`null` when `removed`), and the triggering event’s `eventSequenceNumber`/`occurred`/ `correlationId` when known.
* `release`/`releaseMany` decrypt `@Pii`-annotated properties on one or a batch of read model instances. The compliance subject defaults to each instance’s `id` property if present; pass `subject` explicitly to `release` when there is no `id` property or it isn’t the compliance subject.

***

## IReadModelReactors

[Section titled “IReadModelReactors”](#ireadmodelreactors)

```kotlin
interface IReadModelReactors {
    fun register(reactor: IReadModelReactor): Job
    fun stop()
}
```

Construct the implementation with the read models to watch through and the event log any side-effect events are appended to: `ReadModelReactors(store.readModels, store.eventLog)`. It is not reached through `IEventStore`.

* `IReadModelReactor` is a marker interface. Dispatch is by convention: a method named `added`, `modified` or `removed` (matched case-insensitively) handles the corresponding `ReadModelChangeType`. Its first parameter is the read model — a single instance or a `List` of them — and that type selects which read model is watched. An optional second parameter of type `ReadModelChangeset` carries the change metadata.
* A removal never carries an instance, so a Kotlin `removed` handler must declare its read model parameter nullable. Handlers that cannot be dispatched to are rejected at registration with `InvalidHandlerSignature`.
* A handler may return an event, an `EventForEventSourceId`, or a `List` of either, to be appended as a side effect — bare events use the changed instance’s key as the event source id. Return values that are not event types are ignored.
* `register` is not a suspending function and returns the `Job` backing that reactor’s subscriptions; `stop` cancels every reactor registered through the instance.

See the [read model reactors guide](/chronicle/clients/kotlin/guides/read-model-reactors/) for worked Kotlin and Java examples.

***

## IProjectionsService

[Section titled “IProjectionsService”](#iprojectionsservice)

```kotlin
interface IProjectionsService {
    suspend fun register(vararg projections: Any)
    suspend fun query(
        declaration: String,
        eventSequenceId: EventSequenceId = EventSequenceId.eventLog
    ): ProjectionQueryResult
}
```

### Ad-hoc queries

[Section titled “Ad-hoc queries”](#ad-hoc-queries)

A registered projection is the right answer when a read model is part of the system: the kernel keeps it up to date and the client hands you a type. `query` is for the questions that are not part of the system — a one-off question of the event log during an incident, a report nobody wants to deploy a projection for, a declaration being written in an editor and tried out as it is typed.

Nothing is registered, nothing is persisted, and nothing observes afterwards. The kernel projects over the sequence and hands back the result.

```kotlin
val result = store.projections.query(
    """
    from EmployeeHired
        set name to firstName
    """
)

when (result) {
    is ProjectionQueryResult.Projected ->
        result.instancesOf(EmployeeName::class).forEach(::println)
    is ProjectionQueryResult.Invalid ->
        result.errors.forEach(::println)
}
```

A declaration is a piece of text, so the first thing that can go wrong is that the kernel cannot parse it. That is an ordinary outcome of asking a question in a language rather than an exception, so it comes back as `Invalid` carrying a line and column per error — which is what you show whoever wrote it.

An ad-hoc declaration has no registered read model type, so `entries` is raw JSON and `instancesOf` deserializes it into whatever shape the declaration produced.

From Java, use `ProjectionsServiceJavaBridge.query(...)`.

***

## IConstraintsService

[Section titled “IConstraintsService”](#iconstraintsservice)

```kotlin
interface IConstraintsService {
    suspend fun register(vararg constraints: Any)
}
```

`IConstraintBuilder`, passed into `IConstraint.define`, can additionally scope every constraint added through it — see [Constraint scoping](/chronicle/clients/kotlin/guides/constraints/).

***

## IEventTypesService

[Section titled “IEventTypesService”](#ieventtypesservice)

```kotlin
interface IEventTypesService {
    suspend fun register(vararg eventClasses: KClass<*>)
    suspend fun registerSingle(eventClass: KClass<*>)
    suspend fun getAllGenerationsForEventType(
        eventTypeId: String
    ): List<Events.EventTypeRegistration>
    fun getRegisteredEventTypes(): List<EventTypeDescriptor>
}
```

`register`/`registerSingle` accept both plain `@EventType`-annotated classes and [`IEventTypeMigration`](/chronicle/clients/kotlin/guides/event-evolution/) classes, merging them into one registration per event type id, schema included (generated from the latest generation’s class — see [Annotations](/chronicle/clients/kotlin/reference/annotations/)). `getRegisteredEventTypes` returns every event type registered through this instance so far; it’s what `eventStoreSubscriptions.subscribe` falls back to when a subscription isn’t narrowed to specific event types.

***

## IEventSeedingService

[Section titled “IEventSeedingService”](#ieventseedingservice)

```kotlin
interface IEventSeedingService {
    suspend fun seed(vararg seeders: Any)
}
```

See [Seeding](/chronicle/clients/kotlin/guides/seeding/) for `IEventSeedingBuilder`, including namespace-scoped seed data via `forNamespace`.

***

## IComplianceService

[Section titled “IComplianceService”](#icomplianceservice)

```kotlin
interface IComplianceService {
    suspend fun release(
        subject: String,
        schema: String,
        payload: String
    ): String
    suspend fun deleteEncryptionKey(identifier: String)
}
```

`deleteEncryptionKey` deletes the encryption key for a compliance subject — a “right to be forgotten” erasure that leaves existing encrypted PII content permanently undecryptable, without rewriting the events themselves. Compare with [`redact`/`redactForEventSource`](#redacting-events), which instead rewrites event content directly.

***

## Java interop

[Section titled “Java interop”](#java-interop)

Every service method above is a Kotlin `suspend` function, which Java cannot call directly — a `suspend fun` carries a hidden continuation on the JVM.

### Start here: the blocking client

[Section titled “Start here: the blocking client”](#start-here-the-blocking-client)

`io.cratis.chronicle.java` carries a blocking view of the client. It is what a Java application should use, and it reads the same as the Kotlin one:

```java
var client = BlockingChronicleClient.connect(ChronicleOptions.development());
var eventStore = client.getEventStore("ChronicleConsole");

eventStore.getEventLog().append("some-event-source", new TestEvent("Hello world!"));
```

Artifacts still register themselves, and the append waits for that to finish — so there is nothing to declare and nothing to sequence.

* `BlockingChronicleClient` — `connect`, `getEventStore(s)`, `dispose`. Closeable.
* `BlockingEventStore` — the event log and other sequences, transactional appends, read models, reactors, units of work, and registration.
* `BlockingEventSequence` — `append`, `appendMany`, `hasEventsFor`, sequence numbers, reading events back, `redact`.
* `BlockingTransactionalEventSequence` — `append` and `appendMany`, staged against the current unit of work.
* `BlockingReadModels` — `getInstanceByKey` and `register`, by plain `Class`.
* `BlockingReactors` — `register`.
* `BlockingUnitOfWork` — `commit`, `rollback`. Closeable, rolling back unless it was committed.

Every call blocks until the kernel answers, which is what a `main`, a controller method or a scheduled job wants. Do not call them from inside a coroutine — Kotlin should use the suspending API directly. `unwrap()` on any of them returns the suspending object underneath.

A unit of work reads as try-with-resources, so a throw needs no `catch`:

```java
var eventStore = new BlockingEventStore(store);

try (var unitOfWork = eventStore.beginUnitOfWork()) {
    var transactional = eventStore.getTransactional();

transactional.append("order-123", new OrderPlaced(99.95));
    transactional.append("inventory-widget", new InventoryReserved("widget", 1));

unitOfWork.commit();
}
```

### The lower-level bridges

[Section titled “The lower-level bridges”](#the-lower-level-bridges)

Underneath, the same package provides static bridges — each takes the service (or sequence) as its first argument. Reach for these for the corners the blocking client does not wrap.

A few Kotlin value classes (`EventSequenceNumber`, `EventSequenceId`, `EventTypeId`, `RedactionReason`, `CausationType`) have mangled constructors on the JVM ABI, so anything Java-facing takes and returns plain `long`/`String` instead. Reading one back works — `getValue()` is the one accessor Kotlin leaves unmangled — but Java can never construct one, which is why none appears in a Java-facing signature. `Causation.of(timestamp, type)` exists for the same reason.

* `EventLogJavaBridge` — `append`, `appendMany`, `hasEventsFor`, `getForEventSourceIdAndEventTypes`, `getFromSequenceNumber`, `getTailSequenceNumber`, `getNextSequenceNumber`, `completeStream`, `redact`, `redactForEventSource`, `watchAppendOperations`
* `TransactionalEventSequenceJavaBridge` — `append`, `appendMany`
* `ConcurrencyScopeBuilderJavaBridge` — `withSequenceNumber`
* `EventTypesServiceJavaBridge` — `register`, `registerSingle`, `getAllGenerationsForEventType`
* `ReadModelsJavaBridge` — `register`, `getInstanceByKey`, `getInstances`, `getSnapshotsById`, `watch`, `dehydrateSession`, `release`, `releaseMany`, `getMaterializedInstances`
* `ReactorsServiceJavaBridge` — `register`
* `ReducersServiceJavaBridge` — `register`
* `ProjectionsServiceJavaBridge` — `register`
* `ConstraintsServiceJavaBridge` — `register`
* `EventSeedingServiceJavaBridge` — `seed`
* `EventSeedingBuilderJavaBridge` / `EventSeedingScopeBuilderJavaBridge` — `forEventType`
* `NamespacesServiceJavaBridge` — `ensure`, `getAll`
* `IdentityManagerServiceJavaBridge` — `rename`
* `UnitOfWorkJavaBridge` — `commit`, `rollback`
* `ComplianceServiceJavaBridge` — `release`, `deleteEncryptionKey`

`ReadModelReactors` needs no bridge — its constructor takes plain types and neither `register` nor `stop` is a suspending function, so Java calls both directly.

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

var result = EventLogJavaBridge.append(
    store.getEventLog(),
    "emp-001",
    new EmployeeHired("emp-001", "Jane", "Smith", "Engineering"),
    null);
```

`EventSequenceNumber` is a Kotlin value class, so an `AppendResult` has no ordinary getter for it on the JVM. Read it with `EventLogJavaBridge.getSequenceNumber(result)`. The same applies to `getTailSequenceNumber`/`getNextSequenceNumber` (they return `long` directly) and to `redact`/`redactForEventSource` (they take a `long` sequence number and a plain `String` reason rather than `EventSequenceNumber`/`RedactionReason`).

`ConstraintBuilderJavaBridge`, `UniqueConstraintBuilderJavaBridge`, `ProjectionBuilderJavaBridge`, and `CausationManagerJavaBridge` cover the builder APIs that take a `KClass` in Kotlin, accepting a `Class` instead.

# Geospatial types

Chronicle recognizes a value as geospatial by its [GeoJSON](https://geojson.org) shape. The client ships three types that serialize to that shape, so the sink can index and query them geospatially. A hand-rolled coordinate class serializes as an ordinary nested object and gets none of that.

They live in `io.cratis.chronicle.geospatial` and are usable on any event, read model, or reducer state.

## Types

[Section titled “Types”](#types)

| Type         | Constructor                  | GeoJSON `type`     | Schema `format` |
| ------------ | ---------------------------- | ------------------ | --------------- |
| `Point`      | `Point(longitude, latitude)` | `Point`            | `point`         |
| `LineString` | `LineString(coordinates)`    | `LineString`       | `linestring`    |
| `Polygon`    | `Polygon(shell, holes)`      | `Polygon`          | `polygon`       |
| `LinearRing` | `LinearRing(coordinates)`    | *(a polygon ring)* | —               |

```kotlin
data class Point(val longitude: Double, val latitude: Double)

data class LineString(val coordinates: List<Point>)

data class LinearRing(val coordinates: List<Point>)

data class Polygon(
    val shell: LinearRing,
    val holes: List<LinearRing> = emptyList()
)
```

Longitude comes first, matching GeoJSON coordinate order — not the “latitude, longitude” order used in everyday speech.

`LineString` and `LinearRing` also take loose points (`LineString(a, b, c)`), which is what Java uses in place of a list literal. `Polygon` is `@JvmOverloads`, so `new Polygon(shell)` works from Java for a polygon with no holes.

## Using them on an event

[Section titled “Using them on an event”](#using-them-on-an-event)

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.geospatial.Point

@EventType
data class WarehouseInspected(
    val warehouseId: String = "",
    val inspectedAt: Point = Point(0.0, 0.0)
)
```

```java
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.geospatial.Point;

@EventType
public record WarehouseInspected(String warehouseId, Point inspectedAt) {}
```

Appending is unchanged — the client serializes the point as GeoJSON on the way out:

```kotlin
import io.cratis.chronicle.geospatial.Point

store.eventLog.append(
    eventSourceId = "warehouse-1",
    event = WarehouseInspected("warehouse-1", Point(10.75, 59.91))
)
```

The event content on the wire:

```json
{
  "warehouseId": "warehouse-1",
  "inspectedAt": { "type": "Point", "coordinates": [10.75, 59.91] }
}
```

## Building a polygon

[Section titled “Building a polygon”](#building-a-polygon)

A polygon’s shell must be closed — its last point repeats its first — and needs at least four points. Holes follow the same rule.

```kotlin
import io.cratis.chronicle.geospatial.LinearRing
import io.cratis.chronicle.geospatial.Point
import io.cratis.chronicle.geospatial.Polygon

val deliveryZone = Polygon(
    shell = LinearRing(
        Point(10.70, 59.90),
        Point(10.80, 59.90),
        Point(10.80, 59.95),
        Point(10.70, 59.90)
    )
)
```

GeoJSON stores the shell and the holes in one flat array of rings, with the shell first. Reading a polygon back takes the first ring as the shell and the rest as holes.

## Validation on read

[Section titled “Validation on read”](#validation-on-read)

Deserialization rejects geometries the sink would refuse, so a malformed value fails at the client rather than deep in the kernel.

| Geometry     | Rejected when                                |
| ------------ | -------------------------------------------- |
| `Point`      | `coordinates` is not `[longitude, latitude]` |
| `LineString` | fewer than 2 points                          |
| `Polygon`    | it carries no rings at all                   |
| `LinearRing` | fewer than 4 points, or it does not close    |
| all          | the declared `type` is not the expected one  |

Construction is not validated — only what comes off the wire is.

## Serializing yourself

[Section titled “Serializing yourself”](#serializing-yourself)

`io.cratis.chronicle.json.ChronicleGson.chronicleGson` is the `Gson` instance the client serializes event content and read model state with. Use it when you need to produce the same JSON the client would.

```kotlin
import io.cratis.chronicle.geospatial.Point
import io.cratis.chronicle.json.chronicleGson

val json = chronicleGson.toJson(Point(10.75, 59.91))
```

```java
import io.cratis.chronicle.geospatial.Point;
import io.cratis.chronicle.json.ChronicleGson;

String json = ChronicleGson.chronicleGson.toJson(new Point(10.75, 59.91));
```

# Chronicle TypeScript Client

`@cratis/chronicle` is the TypeScript SDK for Chronicle. It builds on top of the [`@cratis/chronicle.contracts`](https://www.npmjs.com/package/@cratis/chronicle.contracts) gRPC contracts package and provides TypeScript APIs for event stores, event logs, observers, read models, jobs, sinks, and metadata.

Use this section for TypeScript installation, connection setup, decorators, generated APIs, and runtime integration details. Shared Chronicle concepts and workflows live in the main Chronicle docs and use language tabs when code differs by client.

## Shared Chronicle topics

[Section titled “Shared Chronicle topics”](#shared-chronicle-topics)

## TypeScript-specific pages

[Section titled “TypeScript-specific pages”](#typescript-specific-pages)

* [Getting Started](/chronicle/clients/typescript/getting-started/) — install and connect the TypeScript client
* [Sinks](/chronicle/clients/typescript/sinks/) — configuring read-model persistence targets
* [Jobs](/chronicle/clients/typescript/jobs/) — managing Chronicle jobs from TypeScript
* [Webhooks](/chronicle/clients/typescript/webhooks/) — registering and discovering client webhooks
* [Identity](/chronicle/clients/typescript/identity/), [Causation](/chronicle/clients/typescript/auditing/), and [Correlation](/chronicle/clients/typescript/correlation/) — TypeScript call-context metadata

# Auditing — Causation

See [Correlation, identity, and causation](/chronicle/concepts/correlation-identity-causation/) for what causation means and why Chronicle tracks it. This page covers the TypeScript-specific API in depth. The causation chain is stored with every event and enables full audit-trail tracing.

## Concepts

[Section titled “Concepts”](#concepts)

| Type                | Role                                                                              |
| ------------------- | --------------------------------------------------------------------------------- |
| `CausationType`     | A named string wrapper identifying the *kind* of operation that caused something. |
| `Causation`         | A single node in the chain — a timestamp, a `CausationType`, and a property bag.  |
| `ICausationManager` | Interface for reading and mutating the chain in the current call context.         |
| `CausationManager`  | Default `AsyncLocalStorage`-backed implementation.                                |

## `CausationType`

[Section titled “CausationType”](#causationtype)

```typescript
import { CausationType } from '@cratis/chronicle';

// Built-in types
CausationType.root              // 'Root'     — the process-level root
CausationType.unknown           // 'Unknown'
CausationType.appendEvent       // 'TypeScriptClient.Append'
CausationType.appendManyEvents  // 'TypeScriptClient.AppendMany'

// Custom types
const myType = new CausationType('MyApp.CreateEmployee');
```

## `Causation`

[Section titled “Causation”](#causation)

```typescript
import { Causation, CausationType } from '@cratis/chronicle';

const entry = new Causation(
    new Date(),                                  // occurred
    new CausationType('MyApp.CreateEmployee'),   // type
    { employeeId: '123' }                        // properties (string→string map)
);

// Factory for a placeholder
const placeholder = Causation.unknown();
```

## Managing the causation chain

[Section titled “Managing the causation chain”](#managing-the-causation-chain)

The module exports a singleton `causationManager` that uses Node.js [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) so the chain is scoped automatically to the active async context.

### Reading the current chain

[Section titled “Reading the current chain”](#reading-the-current-chain)

```typescript
import { causationManager } from '@cratis/chronicle';

const chain = causationManager.getCurrentChain();
// chain[0] is always the root causation
// chain[n] are additional entries added in this context
```

### Adding causation

[Section titled “Adding causation”](#adding-causation)

Call `add()` before performing an operation to push a new entry onto the chain:

```typescript
import { causationManager, CausationType } from '@cratis/chronicle';

causationManager.add(
    new CausationType('MyApp.CreateEmployee'),
    { correlatedCommand: 'HireEmployee', tenantId: 'acme' }
);

// Now append an event — the event will carry this entry in its Causation chain
await store.eventLog.append(eventSourceId, new EmployeeHired(...));
```

### Defining the process root

[Section titled “Defining the process root”](#defining-the-process-root)

By default the root causation is a bare `CausationType.root` entry. Call `defineRoot()` once at start-up to attach application-specific properties:

```typescript
import { causationManager } from '@cratis/chronicle';

causationManager.defineRoot({
    application: 'hr-service',
    version: '2.1.0'
});
```

### Command-handler middleware example

[Section titled “Command-handler middleware example”](#command-handler-middleware-example)

```typescript
import { causationManager, CausationType } from '@cratis/chronicle';

async function handleCommand(commandName: string, handler: () => Promise<void>) {
    causationManager.add(new CausationType(`MyApp.Command.${commandName}`), {});
    await handler();
}
```

## How causation flows into events

[Section titled “How causation flows into events”](#how-causation-flows-into-events)

When you call `eventLog.append()` or `eventLog.appendMany()`, the Chronicle client automatically reads `causationManager.getCurrentChain()` and sends the full chain as the `Causation` field of the gRPC request. You do not need to pass it manually.

# Compliance

Compliance and PII handling are shared Chronicle topics. The shared docs own the concepts, storage behavior, and client-tabbed examples.

* [Compliance](/chronicle/compliance/)
* [PII](/chronicle/compliance/pii/)
* [Compliance in read models](/chronicle/compliance/read-models/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

# PII

PII classification and release behavior are shared Chronicle compliance topics.

* [PII](/chronicle/compliance/pii/)
* [Compliance](/chronicle/compliance/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

# Compliance in Read Models

Read-model compliance is documented in the shared Chronicle compliance section so all clients use the same rules.

* [Compliance in read models](/chronicle/compliance/read-models/)
* [Read models](/chronicle/read-models/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

# Correlation

See [Correlation, identity, and causation](/chronicle/concepts/correlation-identity-causation/) for what a correlation ID is and why Chronicle tracks it. This page covers the TypeScript-specific API in depth. A `CorrelationId` is sent with every event append as the `CorrelationId` field.

## `CorrelationId`

[Section titled “CorrelationId”](#correlationid)

```typescript
import { CorrelationId } from '@cratis/chronicle';

// Generate a new unique correlation ID
const id = CorrelationId.create();

// Wrap an existing string (e.g. from an incoming X-Correlation-Id header)
const fromHeader = new CorrelationId('d4e5f6a7-...');

// Well-known sentinel for an unset ID
const empty = CorrelationId.notSet;

console.log(id.toString()); // 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
```

## Managing the correlation ID for a call context

[Section titled “Managing the correlation ID for a call context”](#managing-the-correlation-id-for-a-call-context)

The module exports a singleton `correlationIdManager` backed by Node.js [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage). The ID is scoped automatically to the active async context — no need to pass it through every function call.

### Reading the current ID

[Section titled “Reading the current ID”](#reading-the-current-id)

```typescript
import { correlationIdManager } from '@cratis/chronicle';

const id = correlationIdManager.current;
// If nothing has been set in this context, a new GUID is generated on each access.
```

### Setting a fixed ID

[Section titled “Setting a fixed ID”](#setting-a-fixed-id)

```typescript
import { correlationIdManager, CorrelationId } from '@cratis/chronicle';

correlationIdManager.setCurrent(new CorrelationId('d4e5f6a7-...'));
```

### Resetting to a new ID

[Section titled “Resetting to a new ID”](#resetting-to-a-new-id)

```typescript
correlationIdManager.clear(); // replaces the stored ID with a fresh GUID
```

### Express middleware example

[Section titled “Express middleware example”](#express-middleware-example)

```typescript
import express from 'express';
import { correlationIdManager, CorrelationId } from '@cratis/chronicle';

app.use((req, res, next) => {
    const header = req.headers['x-correlation-id'];
    const id = header
        ? new CorrelationId(String(header))
        : CorrelationId.create();

correlationIdManager.setCurrent(id);
    res.setHeader('x-correlation-id', id.toString());
    res.on('finish', () => correlationIdManager.clear());
    next();
});
```

## Interface segregation

[Section titled “Interface segregation”](#interface-segregation)

`CorrelationIdManager` implements two separate interfaces, following the same pattern as the .NET client:

| Interface                | Purpose                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `ICorrelationIdAccessor` | Read-only access — exposes `current`. Inject this where you only need to read the ID.                   |
| `ICorrelationIdSetter`   | Write access — exposes `setCurrent()` and `clear()`. Inject this where you need to set or reset the ID. |

```typescript
import { ICorrelationIdAccessor, ICorrelationIdSetter, CorrelationIdManager } from '@cratis/chronicle';

// Narrow the type for read-only consumers
function logCorrelation(accessor: ICorrelationIdAccessor) {
    console.log('Correlation:', accessor.current.toString());
}

// Narrow the type for writers (e.g. middleware, test setup)
function resetForTest(setter: ICorrelationIdSetter) {
    setter.clear();
}

const manager = new CorrelationIdManager();
logCorrelation(manager);
resetForTest(manager);
```

## How correlation flows into events

[Section titled “How correlation flows into events”](#how-correlation-flows-into-events)

When you call `eventLog.append()` or `eventLog.appendMany()`, the Chronicle client automatically uses `correlationIdManager.current` as the `CorrelationId` for the gRPC request unless you provide an explicit `correlationId` in `AppendOptions`:

```typescript
import { CorrelationId } from '@cratis/chronicle';

// Uses correlationIdManager.current automatically
await store.eventLog.append(eventSourceId, new EmployeeHired(...));

// Override for this single append
await store.eventLog.append(eventSourceId, new EmployeeHired(...), {
    correlationId: CorrelationId.create()
});
```

# Event Log

The event log is Chronicle’s primary event sequence and is documented in the shared Chronicle docs.

* [Events and event logs](/chronicle/events/)
* [Appending events](/chronicle/events/appending/)
* [Appending many events](/chronicle/events/appending-many/)
* [Optimistic concurrency](/chronicle/events/concurrency/)
* [Getting events](/chronicle/events/getting-events/)
* [Observing appends](/chronicle/events/observing-appends/)
* [Event redaction](/chronicle/events/redaction/)
* [Closing streams](/chronicle/closing-streams/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

## TypeScript client notes

[Section titled “TypeScript client notes”](#typescript-client-notes)

* `eventLog.redact(sequenceNumber, reason)` and `eventLog.redactForEventSource(eventSourceId, reason, eventTypes?)` permanently rewrite an event’s (or an entire event source’s) content — a destructive GDPR/compliance erasure, never a field-level mask.
* `eventLog.getForEventSourceIdAndEventTypes(eventSourceId, eventTypes, ...)` and `eventLog.getFromSequenceNumber(sequenceNumber, eventSourceId?, eventTypes?)` read appended events back, filtered by event source and/or event type.
* `eventLog.getNextSequenceNumber()` returns the sequence number the next append will receive (`EventSequenceNumber.first` when the sequence is empty).
* `eventLog.completeStream(eventStreamType, eventStreamId)` permanently closes a non-default stream; further appends to it are rejected with a `StreamClosed` constraint violation.
* `eventLog.appendOperations` is a hot, multicast `AsyncIterable` of every append this event log instance makes, together with its result.
* `appendResult.waitForCompletion(timeoutMs?)` waits for every observer affected by an append to catch up (or fail) before you read a read model back — see [Failed Partitions](/chronicle/clients/typescript/failed-partitions/).
* The `appendMany(events: EventForEventSourceId[], options?)` overload now applies a distinct `options.concurrencyScopes` entry per event source id in the batch, instead of one shared scope applied to every event source.

# Event Type Migrations

Event type migrations are shared Chronicle behavior. The shared documentation owns the migration model and client-tabbed examples.

* [Event type migrations concept](/chronicle/concepts/event-type-migrations/)
* [Understanding event evolution](/chronicle/understanding-event-evolution/)
* [Migrations](/chronicle/migrations/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

# Event Types

Event types are a shared Chronicle concept. Use the shared documentation for the model, naming rules, generations, and schema evolution flow.

* [Event type concept](/chronicle/concepts/event-type/)
* [Events and event logs](/chronicle/events/)
* [Event evolution](/chronicle/understanding-event-evolution/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

# External Services

See [External Services](/chronicle/external-services/) for what an external service is. External services are usually configured in the Workbench, but the TypeScript client also exposes a programmatic API on `eventStore.externalServices`.

## Register an HTTP service with bearer token authentication

[Section titled “Register an HTTP service with bearer token authentication”](#register-an-http-service-with-bearer-token-authentication)

```typescript
import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';

const client = new ChronicleClient(ChronicleOptions.development());
const eventStore = await client.getEventStore('MyStore');

await eventStore.externalServices.register('CustomersApi', builder => builder
    .http('https://api.example.com')
    .withBearerToken(token)
    .withHeader('X-Tenant', 'acme'));

client.dispose();
```

## Register a PostgreSQL database service

[Section titled “Register a PostgreSQL database service”](#register-a-postgresql-database-service)

```typescript
await eventStore.externalServices.register('CustomersDb', builder => builder
    .postgreSql('db.example.com', 'customers', 'postgres', password, 5432));
```

Registering the same name again overwrites the previous definition, so this is safe to call repeatedly (for example, on every application startup).

## API

[Section titled “API”](#api)

`eventStore.externalServices` exposes:

* `register(name, configure)`

The builder passed to `configure` exposes:

* `http(url)`
* `withBasicAuth(username, password)`
* `withBearerToken(token)`
* `withOAuth(authority, clientId, clientSecret)`
* `withHeader(key, value)`
* `msSql(host, database, username, password, port?)`
* `postgreSql(host, database, username, password, port?)`
* `withOption(key, value)`

# Failed Partitions

Chronicle partitions the events an observer (a reactor, reducer, or projection) processes — typically by event source id — so many partitions can make progress independently. When a handler keeps failing for a partition, Chronicle stops retrying it and marks it failed, without blocking any other partition; events already applied to *other* partitions keep flowing. Use `eventStore.failedPartitions` to inspect the partitions an observer has given up on.

## API

[Section titled “API”](#api)

`eventStore.failedPartitions` exposes:

* `getAllFailedPartitions()` — every failed partition, across every observer.
* `getFailedPartitionsFor(observerId)` — failed partitions for one specific observer (reactor/reducer) identifier.

Both return a `FailedPartition[]`:

| Property     | Description                                                                |
| ------------ | -------------------------------------------------------------------------- |
| `id`         | Unique identifier of the failed partition registration.                    |
| `observerId` | The identifier of the observer (reactor/reducer) the partition failed for. |
| `partition`  | The partition key that failed (typically an event source id).              |
| `attempts`   | Every attempt Chronicle made at processing the partition, oldest first.    |

Each `FailedPartitionAttempt` carries:

| Property         | Description                                                 |
| ---------------- | ----------------------------------------------------------- |
| `occurred`       | When the attempt happened.                                  |
| `sequenceNumber` | The sequence number being processed at the time of failure. |
| `messages`       | Error message(s) captured for the attempt.                  |
| `stackTrace`     | The associated stack trace, if any.                         |

## Example

[Section titled “Example”](#example)

```typescript
import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';

const client = new ChronicleClient(ChronicleOptions.development());
const eventStore = await client.getEventStore('MyStore');

client.dispose();
```

## Get failed partitions for a specific observer

[Section titled “Get failed partitions for a specific observer”](#get-failed-partitions-for-a-specific-observer)

```typescript
const reactorFailures = await eventStore.failedPartitions.getFailedPartitionsFor('HrNotificationReactor');
```

## Waiting for completion instead of polling

[Section titled “Waiting for completion instead of polling”](#waiting-for-completion-instead-of-polling)

Rather than polling `failedPartitions` after an append, `AppendResult.waitForCompletion()` waits (5 second default timeout) for every observer affected by that specific append to either catch up or fail, and reports any failed partitions directly:

```typescript
const result = await eventStore.eventLog.append('order-123', new OrderShipped());
const completion = await result.waitForCompletion();
if (!completion.isSuccess) {
    for (const failedPartition of completion.failedPartitions) {
        console.log(`Observer ${failedPartition.observerId} failed partition ${failedPartition.partition}`);
    }
}
```

See [Event Log](/chronicle/clients/typescript/event-log/) for more on `waitForCompletion`.

# Getting Started

## Prerequisite: Chronicle Kernel

[Section titled “Prerequisite: Chronicle Kernel”](#prerequisite-chronicle-kernel)

You need a running Chronicle Kernel before connecting with the TypeScript client.

The easiest local setup is the development Docker image:

```bash
docker run -p 35000:35000 cratis/chronicle:latest-development
```

## Installation

[Section titled “Installation”](#installation)

```bash
yarn add @cratis/chronicle reflect-metadata
```

> **Note:** `reflect-metadata` is required for TypeScript decorators to work at runtime. Import it once at the entry point of your application.

## Setup

[Section titled “Setup”](#setup)

Import `reflect-metadata` at the top of your application entry point:

```typescript
import 'reflect-metadata';
```

## Connecting to Chronicle

[Section titled “Connecting to Chronicle”](#connecting-to-chronicle)

Create a `ChronicleClient` with a connection string pointing to your Chronicle Kernel instance:

```typescript
import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';

const options = ChronicleOptions.fromConnectionString('chronicle://localhost:35000');
const client = new ChronicleClient(options);

// Get an event store
const store = await client.getEventStore('MyStore');

// ... use the store

// Always dispose when done
client.dispose();
```

## Connection String Format

[Section titled “Connection String Format”](#connection-string-format)

Chronicle connection strings use the `chronicle://` scheme:

```plaintext
chronicle://localhost:35000
chronicle://username:password@chronicle.example.com:35000
```

## Development Mode

[Section titled “Development Mode”](#development-mode)

For local development, use:

```typescript
const options = ChronicleOptions.development();
```

This connects to `chronicle://localhost:35000` by default.

## Where to next

[Section titled “Where to next”](#where-to-next)

* [Events and event logs](/chronicle/clients/typescript/event-log/), [Event Types](/chronicle/clients/typescript/event-types/), and [Event Evolution](/chronicle/clients/typescript/event-type-migrations/) to model and evolve your event schema.
* [Reducers](/chronicle/clients/typescript/reducers/), [Reactors](/chronicle/clients/typescript/reactors/), and [Projections](/chronicle/clients/typescript/projections/) to build read models and side effects from your events.
* [Read Models](/chronicle/clients/typescript/read-models/) to query projected state.
* [Event Seeding](/chronicle/clients/typescript/seeding/) and [Transactions](/chronicle/clients/typescript/transactions/) for test data and unit-of-work semantics.
* [Compliance](/chronicle/clients/typescript/compliance/) for PII handling and GDPR erasure.

# Identity

See [Correlation, identity, and causation](/chronicle/concepts/correlation-identity-causation/) for what identity means and why Chronicle tracks it. This page covers the TypeScript-specific API in depth. The `Identity` class is sent with every event append as the `CausedBy` field.

## The `Identity` class

[Section titled “The Identity class”](#the-identity-class)

```typescript
import { Identity } from '@cratis/chronicle';

// Create a user identity
const identity = new Identity(
    'a1b2c3d4-...',  // subject — unique identifier (e.g. a user's ID or OAuth subject claim)
    'Jane Doe',       // name
    'jane.doe'        // userName (optional, defaults to '')
);

// On-behalf-of chains are supported
const delegatedIdentity = new Identity(
    'service-id-...',
    'My Service',
    'my-service',
    identity          // onBehalfOf
);
```

### Well-known statics

[Section titled “Well-known statics”](#well-known-statics)

| Static             | Subject                                | Description                                |
| ------------------ | -------------------------------------- | ------------------------------------------ |
| `Identity.system`  | `5d032c92-9d5e-41eb-947a-ee5314ed0032` | Default — used when no identity is set.    |
| `Identity.notSet`  | `1efc9b81-0612-4466-962c-86acc4e9a028` | Sentinel for an explicitly unset identity. |
| `Identity.unknown` | `3321cf62-db16-425e-8173-99fcfefe11dd` | Sentinel for an unknown identity.          |

### Removing duplicate subjects

[Section titled “Removing duplicate subjects”](#removing-duplicate-subjects)

If a `CausedBy` chain contains the same subject more than once (can happen with intermediary services), call `withoutDuplicates()` to collapse duplicates while keeping the first occurrence:

```typescript
const clean = delegatedIdentity.withoutDuplicates();
```

## Setting the identity for a call context

[Section titled “Setting the identity for a call context”](#setting-the-identity-for-a-call-context)

The module exports a singleton `identityProvider` backed by Node.js [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage), so the identity is automatically scoped to the active async call — there is no need to thread it through function signatures.

```typescript
import { identityProvider, Identity } from '@cratis/chronicle';

// Set once at the entry-point of a request / command handler
identityProvider.setCurrentIdentity(new Identity(userId, displayName, userName));

// Anywhere deeper in the same async context, the identity is available:
const identity = identityProvider.getCurrent(); // returns the identity set above

// Reset to Identity.system when the context ends
identityProvider.clearCurrentIdentity();
```

### Express middleware example

[Section titled “Express middleware example”](#express-middleware-example)

```typescript
import express from 'express';
import { identityProvider, Identity } from '@cratis/chronicle';

app.use((req, res, next) => {
    const subject = req.auth?.sub ?? 'anonymous';
    const name    = req.auth?.name ?? '[Anonymous]';
    identityProvider.setCurrentIdentity(new Identity(subject, name));
    res.on('finish', () => identityProvider.clearCurrentIdentity());
    next();
});
```

## Implementing a custom provider

[Section titled “Implementing a custom provider”](#implementing-a-custom-provider)

If you need to derive the identity from a framework-specific source (e.g. an HTTP context, a gRPC call, a message-bus header), implement `IIdentityProvider`:

```typescript
import { IIdentityProvider, Identity } from '@cratis/chronicle';

class MyIdentityProvider implements IIdentityProvider {
    getCurrent(): Identity {
        return ...; // pull from your context
    }

setCurrentIdentity(identity: Identity): void { /* ... */ }
    clearCurrentIdentity(): void { /* ... */ }
}
```

Then pass it wherever `IIdentityProvider` is expected, or replace usages of the `identityProvider` singleton with your instance.

# Jobs

See [Jobs](/chronicle/jobs/) for what a job is. Use `eventStore.jobs` to inspect and control Chronicle jobs in a namespace.

## API

[Section titled “API”](#api)

`eventStore.jobs` exposes:

* `stop(jobId)`
* `resume(jobId)`
* `delete(jobId)`
* `getJob(jobId)`
* `getJobs()`
* `getJobSteps(jobId)`

For `jobId`, you can pass:

* `JobId`
* `Guid`
* `string` (guid text)

## Example

[Section titled “Example”](#example)

```typescript
import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';

const client = new ChronicleClient(ChronicleOptions.development());
const eventStore = await client.getEventStore('MyStore');

const jobId = '94ba2c17-0977-478e-a278-70f6757aac2d';
await eventStore.jobs.stop(jobId);
await eventStore.jobs.resume(jobId);

client.dispose();
```

## Get a single job

[Section titled “Get a single job”](#get-a-single-job)

`getJob(jobId)` returns `undefined` when the job is not found.

```typescript
const job = await eventStore.jobs.getJob('94ba2c17-0977-478e-a278-70f6757aac2d');
if (!job) {
    console.log('Job not found');
}
```

# Projections

Projections are shared Chronicle read-model behavior. Use the shared docs for projection styles, model-bound projections, declarative projections, and client-tabbed examples.

* [Projections](/chronicle/projections/)
* [Choosing a read model style](/chronicle/projections/choosing-a-read-model-style/)
* [Model-bound projections](/chronicle/projections/model-bound/)
* [Declarative projections](/chronicle/projections/declarative/)
* [Composite keys](/chronicle/projections/declarative/composite-keys/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

## TypeScript client notes

[Section titled “TypeScript client notes”](#typescript-client-notes)

Several projection capabilities that previously threw `not implemented yet.` at registration time now work end to end:

* The model-bound arithmetic decorators — `@addFrom`, `@subtractFrom`, `@increment`, `@decrement`, `@count` — and their fluent equivalents (`.add()`/`.subtract()`/`.count()` on `IFromBuilder`/`IJoinBuilder`).
* The model-bound `@childrenFrom`, `@nested`, and class- or property-level `@clearWith` decorators, and the matching fluent `.children()`/`.nested()` builders (plus `.addChild()`/`.setThisValue()` on `IFromBuilder`/`IJoinBuilder`).
* `.usingCompositeKey()`/`.usingParentCompositeKey()` on the fluent `IFromBuilder`/`IJoinBuilder`, for read models whose key is composed from more than one event property (see [Composite keys](/chronicle/projections/declarative/composite-keys/)).

If you tried any of these before and hit a `not implemented yet.` error, they are safe to use now.

# Reactors

Reactors are documented in the shared Chronicle docs with synchronized examples for C#, Kotlin, Java, Elixir, and TypeScript.

* [Getting started with reactors](/chronicle/reactors/getting-started/)
* [Reactor event processing](/chronicle/reactors/event-processing/)
* [Returning side effects](/chronicle/reactors/side-effects/)
* [Replay](/chronicle/reactors/replay/)
* [Reactors overview](/chronicle/reactors/)

Use the [TypeScript get started page](/chronicle/clients/typescript/getting-started/) for package installation and connection setup.

## TypeScript client notes

[Section titled “TypeScript client notes”](#typescript-client-notes)

A reactor handler method can now return a side effect instead of only observing: a single event, an array of events, a single `EventForEventSourceId` (to target an event source other than the one that triggered the reactor), an array of those, or a mix. Whatever is returned is appended in one atomic `appendMany` call once the handler completes — a bare event uses the triggering event’s own event source id, stream, and subject; an `EventForEventSourceId` entry keeps its own target. If the side-effect append fails, the reactor’s partition is marked Failed, the same as if the handler itself had thrown.

A `@reactor`/`@reducer`-decorated class instance can also optionally implement `ICanBeNotifiedWhenReplay` (`beginReplay`/`endReplay`) and/or `ICanBeNotifiedWhenPartitionReplayed` (`beginReplayPartition`/`endReplayPartition`, both given the partition) to be notified when a replay begins and ends, at the full-observer or per-partition granularity.

# Read Models

Read models are shared Chronicle concepts. Querying, snapshots, watching, and consistency are documented in the shared Chronicle section.

* [Read models](/chronicle/read-models/)
* [Getting a single read model](/chronicle/read-models/getting-single-instance/)
* [Getting read model collections](/chronicle/read-models/getting-collection-instances/)
* [Watching read models](/chronicle/read-models/watching-read-models/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

# Reducers

Reducers are shared Chronicle read-model behavior. Use the shared reducer docs for the model, lifecycle, filtering, and client-tabbed examples.

* [Reducers](/chronicle/reducers/)
* [Getting started with reducers](/chronicle/reducers/getting-started/)
* [Reducer event processing](/chronicle/reducers/event-processing/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

# Seeding

This page shows how to seed events using the Chronicle TypeScript client. Seeding is sent to the Chronicle Server when the event store connects, and the server applies it once per namespace. See [Event Seeding](/chronicle/event-seeding/) for the concept this page assumes.

## Define events

[Section titled “Define events”](#define-events)

```typescript
import { eventType } from '@cratis/chronicle';

@eventType()
class AccountOpened {
    constructor(
        readonly accountId: string,
        readonly ownerName: string,
        readonly initialBalance: number
    ) {}
}

@eventType()
class FundsDeposited {
    constructor(
        readonly accountId: string,
        readonly amount: number
    ) {}
}
```

## Implement a seeder

[Section titled “Implement a seeder”](#implement-a-seeder)

Decorate a class with `@seeder()`, implement `ICanSeedEvents`, and use the builder’s `for`/`forEventSource` to accumulate events:

```typescript
import { seeder, ICanSeedEvents, IEventSeedingBuilder } from '@cratis/chronicle';

@seeder()
class AccountSeeder implements ICanSeedEvents {
    seed(builder: IEventSeedingBuilder): void {
        builder.for('account-1', [
            new AccountOpened('account-1', 'Alice', 1000)
        ]);
    }
}
```

## Seed multiple events of the same type

[Section titled “Seed multiple events of the same type”](#seed-multiple-events-of-the-same-type)

```typescript
seed(builder: IEventSeedingBuilder): void {
    builder.for('account-1', [
        new AccountOpened('account-1', 'Alice', 1000)
    ]);
}
```

## Seed mixed event types

[Section titled “Seed mixed event types”](#seed-mixed-event-types)

Use `forEventSource` to seed several different event types for the same event source:

```typescript
seed(builder: IEventSeedingBuilder): void {
    builder.forEventSource('account-1', [
        new AccountOpened('account-1', 'Alice', 1000),
        new FundsDeposited('account-1', 500)
    ]);
}
```

## Namespace-scoped seed data

[Section titled “Namespace-scoped seed data”](#namespace-scoped-seed-data)

By default, seed data applies to all namespaces in the event store. To target a specific namespace, use `forNamespace` to get a scoped builder:

```typescript
seed(builder: IEventSeedingBuilder): void {
    builder
        .forNamespace('production')
        .for('account-1', [new AccountOpened('account-1', 'Alice', 1000)]);
}
```

The scoped builder supports the same `for`/`forEventSource` methods as the top-level builder. Each namespace receives only its own scoped events in addition to any global events.

## Running seeders

[Section titled “Running seeders”](#running-seeders)

Discover and register seeders explicitly through the event store:

```typescript
import { IEventStore } from '@cratis/chronicle';

async function runSeeders(store: IEventStore): Promise<void> {
    await store.seeding.discover();
    await store.seeding.register();
}
```

## How it runs

[Section titled “How it runs”](#how-it-runs)

## Best practices

[Section titled “Best practices”](#best-practices)

* Keep seed data minimal and deterministic.
* Use clear event source IDs to make debugging easier.
* Group seeders by scenario so you can remove or adjust them easily.
* Only call `store.seeding.discover()`/`.register()` when you want seeding to run — for example, guard it behind a development-only build flag or configuration check.
* Use `forNamespace` when seed data is tenant-specific or environment-specific to avoid polluting other namespaces.

# Sinks

See [Sinks](/chronicle/sinks/) for what a sink is and the storage backends Chronicle ships with. By default the client uses **MongoDB**, so most applications never need to think about sinks at all. You only configure a sink type when you want your read models stored somewhere else — for example, a SQL database.

## Well-Known Sink Types

[Section titled “Well-Known Sink Types”](#well-known-sink-types)

The `WellKnownSinks` constant exposes the sink types Chronicle ships with:

```typescript
import { WellKnownSinks } from '@cratis/chronicle';

WellKnownSinks.MongoDB;   // 'MongoDB' — the default
WellKnownSinks.SQL;       // 'SQL'
WellKnownSinks.InMemory;  // 'InMemory'
WellKnownSinks.NotSet;    // 'NotSet' — no sink
```

A sink type identifier is just a string, so you can also pass the identifier of a custom sink registered in your Chronicle Kernel.

## Configuring the Default Sink Type

[Section titled “Configuring the Default Sink Type”](#configuring-the-default-sink-type)

The default sink type is configured on `ChronicleOptions` through `defaultSinkTypeId`. Every projection, reducer, and read model registered by the client uses this sink type unless overridden by the Kernel configuration.

When you don’t set it, it defaults to `WellKnownSinks.MongoDB`.

To persist read models into SQL instead, pass `defaultSinkTypeId` when creating the options:

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

const options = ChronicleOptions.fromConnectionString(
    'chronicle://localhost:35000',
    { defaultSinkTypeId: WellKnownSinks.SQL });

const client = new ChronicleClient(options);
```

The same option works with the development factory:

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

const options = ChronicleOptions.development({ defaultSinkTypeId: WellKnownSinks.SQL });
const client = new ChronicleClient(options);
```

## Reading the Configured Sink Type

[Section titled “Reading the Configured Sink Type”](#reading-the-configured-sink-type)

The configured value is available on the options as `defaultSinkTypeId`:

```typescript
console.log(client.options.defaultSinkTypeId); // 'SQL'
```

# Transactions and Unit of Work

Unit-of-work transactions are now documented as a shared Chronicle workflow with synchronized client examples.

* [Transactions and unit of work](/chronicle/events/transactions/)
* [Appending many events](/chronicle/events/appending-many/)
* [TypeScript client setup](/chronicle/clients/typescript/getting-started/)

## TypeScript client notes

[Section titled “TypeScript client notes”](#typescript-client-notes)

Alongside `unitOfWork.getAppendResults()` (the full per-event detail from the latest commit), `IUnitOfWork` exposes three purpose-built accessors — thin filters over the same append results, so you don’t have to filter `getAppendResults()` yourself:

* `getConstraintViolations()` — every constraint violation across the commit.
* `getConcurrencyViolations()` — every concurrency violation across the commit.
* `getAppendErrors()` — every append error across the commit.

```typescript
await unitOfWork.commit();

const constraintViolations = unitOfWork.getConstraintViolations();
const concurrencyViolations = unitOfWork.getConcurrencyViolations();
const appendErrors = unitOfWork.getAppendErrors();
```

# Webhooks

See [Webhooks](/chronicle/webhooks/) for what a webhook is. Use `eventStore.webhooks` to register webhook observers for event streams.

## Register a webhook programmatically

[Section titled “Register a webhook programmatically”](#register-a-webhook-programmatically)

```typescript
import { ChronicleClient, ChronicleOptions, eventType } from '@cratis/chronicle';

@eventType()
class EmployeeHired {
    constructor(readonly firstName: string, readonly lastName: string) {}
}

const client = new ChronicleClient(ChronicleOptions.development());
const eventStore = await client.getEventStore('MyStore');

await eventStore.webhooks.register(
    'employee-audit',
    'https://example.internal/webhooks/employee-audit',
    builder => {
        builder
            .withEventType(EmployeeHired)
            .withHeader('x-source', 'chronicle')
            .withBearerToken('token-value');
    }
);

client.dispose();
```

## Define discoverable webhooks with decorators

[Section titled “Define discoverable webhooks with decorators”](#define-discoverable-webhooks-with-decorators)

The `@webhook(...)` decorator registers a webhook class for discovery:

* `@webhook(targetUrl)`
* `@webhook(id, targetUrl)`
* `@webhook(id, targetUrl, eventSequenceId)`

```typescript
import 'reflect-metadata';
import { IWebhook, IWebhookDefinitionBuilder, webhook } from '@cratis/chronicle';

@webhook('employee-webhook', 'https://example.internal/webhooks/employees')
class EmployeeWebhook implements IWebhook {
    define(builder: IWebhookDefinitionBuilder): void {
        builder
            .notReplayable()
            .withHeader('x-client', 'chronicle-ts');
    }
}
```

When the event store registers artifacts, webhooks are discovered and registered automatically.

## API

[Section titled “API”](#api)

`eventStore.webhooks` exposes:

* `discover()`
* `registerDiscovered()`
* `register(webhookId, targetUrl, configure)`
* `getWebhooks()`
* `remove(webhookId)`

# Closing Streams

Event streams can be permanently closed to prevent further appends. Once a stream is closed, any attempt to append events to it will result in a constraint violation of type `StreamClosed`.

Client coverage

Closing a stream is currently C#-only — grepped all three other client SDKs for anything resembling `CompleteStream` and found no equivalent anywhere.

## Why close a stream?

[Section titled “Why close a stream?”](#why-close-a-stream)

Closing a stream is useful when a logical unit of work is complete and no further events should be recorded for that stream. Examples include:

* Finalizing an invoice — once issued, no further line items should be added.
* Archiving a case — the case is resolved and the event history is sealed.
* Completing an order — the order lifecycle has ended and further mutations are disallowed.

## How to close a stream

[Section titled “How to close a stream”](#how-to-close-a-stream)

Call `CompleteStream` on the event log with the stream type and stream identifier you want to close:

* C#

```csharp
  using Cratis.Chronicle.EventSequences;

public class ClosingStreamsInvoiceCloser(IEventLog eventLog)
  {
      public async Task CloseInvoiceStream(EventStreamId invoiceStreamId)
      {
          var result = await eventLog.CompleteStream(new EventStreamType("invoices"), invoiceStreamId);

result.Switch(
              sequenceNumber => Console.WriteLine($"Stream closed at sequence number {sequenceNumber}"),
              error => Console.WriteLine($"Failed to close stream: {error}"));
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.CompleteStreamResult

/**
   * Closes the invoice stream so no further line items can be appended to it once the invoice
   * has been issued.
   */
  suspend fun closeInvoiceStream(store: IEventStore, invoiceStreamId: String) {
      when (val result = store.eventLog.completeStream("invoices", invoiceStreamId)) {
          is CompleteStreamResult.Success -> println("Stream closed at sequence ${result.sequenceNumber.value}")
          CompleteStreamResult.AlreadyCompleted -> println("Failed to close stream: already completed")
          CompleteStreamResult.DefaultStreamCannotBeCompleted -> println("Failed to close stream: the default stream cannot be completed")
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;

import io.cratis.chronicle.java.EventLogJavaBridge;

class ClosingStreamsIndexCompleteStream {
      // Closes the invoice stream so no further line items can be appended to it. Returns false
      // when the stream was already completed, or when it is the default stream (which can never
      // be completed).
      boolean closeInvoiceStream(EventStore store, String invoiceStreamId) {
          return EventLogJavaBridge.completeStream(store.getEventLog(), "invoices", invoiceStreamId);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ClosingStreamsInvoiceCloser do
    alias Chronicle.EventSequences.EventLog

def close_invoice_stream(invoice_stream_id) do
      case EventLog.complete_stream("invoices", invoice_stream_id) do
        {:ok, sequence_number} ->
          IO.puts("Stream closed at sequence number #{sequence_number}")

{:error, reason} ->
          IO.puts("Failed to close stream: #{inspect(reason)}")
      end
    end
  end
  ```

* TypeScript

```typescript
  import { IEventLog } from '@cratis/chronicle';

async function closeInvoiceStream(eventLog: IEventLog, invoiceStreamId: string): Promise<void> {
      const result = await eventLog.completeStream('invoices', invoiceStreamId);

if (result.isSuccess) {
          console.log(`Stream closed at sequence number ${result.sequenceNumber.value}`);
      } else {
          console.log(`Failed to close stream: ${result.error}`);
      }
  }
  ```

The method returns `Result<EventSequenceNumber, CompleteStreamError>`.

## Error cases

[Section titled “Error cases”](#error-cases)

| Error                            | Meaning                                                                                |
| -------------------------------- | -------------------------------------------------------------------------------------- |
| `AlreadyCompleted`               | The stream has already been closed.                                                    |
| `DefaultStreamCannotBeCompleted` | The default stream (`EventStreamType.All` / `EventStreamId.Default`) cannot be closed. |

## What happens after closing

[Section titled “What happens after closing”](#what-happens-after-closing)

After a stream is closed, any append targeting that stream is rejected with a `StreamClosed` constraint violation:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;
  using Cratis.Chronicle.EventSequences;
  using System.Linq;

[EventType]
  public record ClosingStreamsInvoiceLineAdded(string Description, decimal Amount);

public class ClosingStreamsInvoiceLineAppender(IEventLog eventLog)
  {
      public async Task<bool> TryAppendLine(EventSourceId invoiceId)
      {
          var appendResult = await eventLog.Append(
              invoiceId,
              new ClosingStreamsInvoiceLineAdded("Consulting", 500m),
              new EventStreamType("invoices"),
              new EventStreamId("invoice-42"));

if (!appendResult.IsSuccess)
          {
              var violation = appendResult.ConstraintViolations
                  .FirstOrDefault(v => v.ConstraintType == ConstraintType.StreamClosed);
              return violation is null;
          }

return true;
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions

@EventType
  data class ClosingStreamsInvoiceLineAdded(val description: String = "", val amount: Double = 0.0)

/**
   * Appends a line item to an invoice stream. Once the stream has been closed, the append is
   * rejected with a "StreamClosed" constraint violation and no further lines can be added.
   */
  suspend fun tryAppendLine(store: IEventStore, invoiceId: String): Boolean {
      val result = store.eventLog.append(
          invoiceId,
          ClosingStreamsInvoiceLineAdded("Consulting", 500.0),
          AppendOptions(eventStreamType = "invoices", eventStreamId = "invoice-42")
      )

if (!result.isSuccess) {
          return result.constraintViolations.none { it.constraintId == "StreamClosed" }
      }

return true
  }
  ```

* Java

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

@EventType
  record ClosingStreamsInvoiceLineAdded(String description, double amount) {}

class ClosingStreamsIndexAppendRejected {
      // Appends a line item to an invoice stream. Once the stream has been closed, the append is
      // rejected with a "StreamClosed" constraint violation and no further lines can be added.
      boolean tryAppendLine(EventStore store, String invoiceId) {
          AppendOptions options = new AppendOptionsBuilder()
              .eventStreamType("invoices")
              .eventStreamId("invoice-42")
              .build();

AppendResult result = EventLogJavaBridge.append(
              store.getEventLog(), invoiceId, new ClosingStreamsInvoiceLineAdded("Consulting", 500.0), options);

if (!result.isSuccess()) {
              for (ConstraintViolation violation : result.getConstraintViolations()) {
                  if (violation.getConstraintId().equals("StreamClosed")) {
                      return false;
                  }
              }
          }

return true;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ClosingStreamsInvoiceLineAdded do
    use Chronicle.Events.EventType, id: "closing-streams-invoice-line-added"

defstruct [:description, :amount]
  end

defmodule MyApp.ClosingStreamsInvoiceLineAppender do
    alias Chronicle.EventSequences.EventLog
    alias MyApp.Events.ClosingStreamsInvoiceLineAdded

def try_append_line(invoice_id) do
      case EventLog.append(
             invoice_id,
             %ClosingStreamsInvoiceLineAdded{description: "Consulting", amount: 500},
             event_stream_type: "invoices",
             event_stream_id: "invoice-42"
           ) do
        :ok ->
          true

{:error, {:constraint_violations, violations}} ->
          not Enum.any?(violations, &stream_closed?/1)

{:error, _reason} ->
          true
      end
    end

# Mirrors the wire Constraint's Type field (seen as :Unique / :UniqueEventType
    # when registering constraints) — a rejection caused by a closed stream comes
    # back as a violation whose type is :StreamClosed.
    defp stream_closed?(violation) when is_map(violation) do
      Map.get(violation, :Type) == :StreamClosed or Map.get(violation, :type) == :stream_closed
    end

defp stream_closed?(_violation), do: false
  end
  ```

* TypeScript

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

@eventType()
  class ClosingStreamsInvoiceLineAdded {
      constructor(readonly description: string = '', readonly amount: number = 0) {}
  }

async function tryAppendLine(eventLog: IEventLog, invoiceId: string): Promise<boolean> {
      const [appendResult] = await eventLog.appendMany([{
          eventSourceId: invoiceId,
          event: new ClosingStreamsInvoiceLineAdded('Consulting', 500),
          eventStreamType: 'invoices',
          eventStreamId: 'invoice-42'
      }]);

if (!appendResult.isSuccess) {
          const wasStreamClosed = appendResult.constraintViolations.some(violation => violation.constraintId === 'StreamClosed');
          return !wasStreamClosed;
      }

return true;
  }
  ```

The rejection is enforced by the `ClosedStreamConstraintValidator` which is automatically active for every event sequence — no additional configuration is required.

# Code Analysis Rules

This section documents the code analysis rules provided by the Chronicle Code Analyzer for the .NET client.

All rules follow the identifier format `CHR####`. Numbers are assigned sequentially; an occasional id is reserved for a rule still in progress, so a gap in the published set is expected.

## Rules Overview

[Section titled “Rules Overview”](#rules-overview)

| Rule ID                                      | Title                                                                                  | Severity | Description                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------- | -------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CHR0001](/chronicle/code-analysis/chr0001/) | Event type must have \[EventType] attribute                                            | Error    | Types appended to event sequences must be marked with \[EventType] attribute                                                                                                                                                                                                                                                                                   |
| [CHR0002](/chronicle/code-analysis/chr0002/) | Declarative projection event type must have \[EventType] attribute                     | Error    | Declarative projection generic arguments must reference types with \[EventType] attribute                                                                                                                                                                                                                                                                      |
| [CHR0003](/chronicle/code-analysis/chr0003/) | Model bound projection attribute must reference event type with \[EventType] attribute | Error    | Model bound projection attributes must reference types with \[EventType] attribute                                                                                                                                                                                                                                                                             |
| [CHR0004](/chronicle/code-analysis/chr0004/) | Reactor method has a parameter that cannot be resolved                                 | Warning  | Reactor method dependencies must be resolvable from event context, read models, or services                                                                                                                                                                                                                                                                    |
| [CHR0005](/chronicle/code-analysis/chr0005/) | Reactor event parameter must have \[EventType] attribute                               | Error    | Event parameters in reactor methods must be marked with \[EventType] attribute                                                                                                                                                                                                                                                                                 |
| [CHR0006](/chronicle/code-analysis/chr0006/) | Reducer method signature must match allowed signatures                                 | Warning  | Reducer methods must follow allowed signatures                                                                                                                                                                                                                                                                                                                 |
| [CHR0007](/chronicle/code-analysis/chr0007/) | Reducer event parameter must have \[EventType] attribute                               | Error    | Event parameters in reducer methods must be marked with \[EventType] attribute                                                                                                                                                                                                                                                                                 |
| [CHR0012](/chronicle/code-analysis/chr0012/) | Event types should avoid nullable properties                                           | Warning  | Nullable properties are supported on events but are often better modeled as separate event types                                                                                                                                                                                                                                                               |
| [CHR0013](/chronicle/code-analysis/chr0013/) | Reactor cannot combine EventStore with explicit event sequence                         | Error    | Reactors with \[EventStore] must not also configure an explicit event sequence                                                                                                                                                                                                                                                                                 |
| [CHR0014](/chronicle/code-analysis/chr0014/) | Reducer cannot combine EventStore with explicit event sequence                         | Error    | Reducers with \[EventStore] must not also configure an explicit event sequence                                                                                                                                                                                                                                                                                 |
| [CHR0015](/chronicle/code-analysis/chr0015/) | Projection must not have side effects                                                  | Error    | Projections must not inject ICommandPipeline or IEventLog                                                                                                                                                                                                                                                                                                      |
| [CHR0016](/chronicle/code-analysis/chr0016/) | Projection Define() must not contain imperative code                                   | Error    | Projection Define() must only contain builder calls, not imperative statements                                                                                                                                                                                                                                                                                 |
| [CHR0017](/chronicle/code-analysis/chr0017/) | Constraint must not have side effects                                                  | Error    | Constraints must not inject ICommandPipeline or IEventLog                                                                                                                                                                                                                                                                                                      |
| [CHR0018](/chronicle/code-analysis/chr0018/) | Constraint Define() must not contain imperative code                                   | Error    | Constraint Define() must only contain builder calls, not imperative statements                                                                                                                                                                                                                                                                                 |
| [CHR0019](/chronicle/code-analysis/chr0019/) | Projection expression lambda must only access members                                  | Error    | Expression lambdas in projection builder methods must be simple member-access expressions                                                                                                                                                                                                                                                                      |
| [CHR0020](/chronicle/code-analysis/chr0020/) | Constraint expression lambda must only access members                                  | Error    | Expression lambdas in constraint builder methods must be simple member-access expressions                                                                                                                                                                                                                                                                      |
| [CHR0021](/chronicle/code-analysis/chr0021/) | Event types should be record types                                                     | Warning  | Event types should be declared as record types for immutability                                                                                                                                                                                                                                                                                                |
| [CHR0022](/chronicle/code-analysis/chr0022/) | Reactor methods returning event side effects must be marked with \[OnceOnly]           | Warning  | Reactor methods that return events must be \[OnceOnly] to avoid appending duplicates during replay                                                                                                                                                                                                                                                             |
| [CHR0023](/chronicle/code-analysis/chr0023/) | Ambiguous parent key for \[ChildrenFrom] collection                                    | Warning  | Parent-key inference is ambiguous when the child event has more than one property of the parent identifier type; specify parentKey                                                                                                                                                                                                                             |
| [CHR0024](/chronicle/code-analysis/chr0024/) | Read model property has no mapping source                                              | Warning  | A model-bound read model property has no mapping attribute and no subscribed event carries a same-named property, so AutoMap can never populate it                                                                                                                                                                                                             |
| [CHR0025](/chronicle/code-analysis/chr0025/) | Explicitly sourced read model property may be overwritten by AutoMap                   | Info     | A property set with \[SetFrom]/\[SetValue]/… collides by name with another referenced event that AutoMap writes on top; add \[NoAutoMap] or accept the update                                                                                                                                                                                                  |
| [CHR0026](/chronicle/code-analysis/chr0026/) | \[Key] or \[Subject] on an `EventSourceId<T>` is redundant                             | Warning  | An `EventSourceId<T>`-derived property already is the key and compliance subject, so \[Key]/\[Subject] on it is redundant — remove the attribute                                                                                                                                                                                                               |
| [CHR0027](/chronicle/code-analysis/chr0027/) | Ambiguous event stream id                                                              | Error    | A type both implements ICanProvideEventStreamId and declares a non-null \[EventStreamId]; this throws at startup                                                                                                                                                                                                                                               |
| [CHR0028](/chronicle/code-analysis/chr0028/) | Redundant .AutoMap() call                                                              | Warning  | .AutoMap() has no effect because AutoMap is enabled by default on projection builders; remove the call                                                                                                                                                                                                                                                         |
| [CHR0029](/chronicle/code-analysis/chr0029/) | Redundant .Set().To() with matching property names                                     | Warning  | A `.Set(x => x.P).To(e => e.P)` mapping with identical names duplicates what AutoMap already does; remove it                                                                                                                                                                                                                                                   |
| [CHR0030](/chronicle/code-analysis/chr0030/) | \[ChildrenFrom] child collection property auto-maps to nothing                         | Warning  | A \[ChildrenFrom] child collection property matching no event property and with no explicit mapping always projects empty; rename it or bridge with `[SetFrom<T>]`                                                                                                                                                                                             |
| [CHR0031](/chronicle/code-analysis/chr0031/) | Reactor must not have mutable state                                                    | Warning  | Reactors are re-created and replayed, so mutable instance state is unreliable; use readonly, primary-constructor-injected dependencies                                                                                                                                                                                                                         |
| [CHR0032](/chronicle/code-analysis/chr0032/) | Reactor must not access storage directly                                               | Warning  | Injecting a storage primitive like `IMongoCollection<T>` couples the reactor to a sink; read state via a read model or IReadModels.GetInstanceById                                                                                                                                                                                                             |
| [CHR0034](/chronicle/code-analysis/chr0034/) | \[PII] cannot be applied to an `EventSourceId<T>`                                      | Error    | The event source id is the encryption-key lookup identity, so it cannot be encrypted; \[PII] on it throws PIINotSupportedOnEventSourceId at runtime                                                                                                                                                                                                            |
| [CHR0035](/chronicle/code-analysis/chr0035/) | Read model declares a reserved compliance subject property                             | Error    | Chronicle reserves `_subject`, `__subject`, and `__subjects` for internal compliance-subject tracking; a same-named property collides with stored metadata                                                                                                                                                                                                     |
| [CHR0036](/chronicle/code-analysis/chr0036/) | Reducer must not have mutable state                                                    | Warning  | Reducers are re-created and replayed, so mutable instance state or direct storage injection makes the fold non-deterministic; keep them stateless                                                                                                                                                                                                              |
| [CHR0037](/chronicle/code-analysis/chr0037/) | Event type migration generations must belong to one event type                         | Warning  | The two generations referenced by an EventTypeMigration must resolve to the same event type id and differ only by generation, or the migration never applies — checked for both `EventTypeGenerationFor<T>` and the older explicit-id \[EventType] style                                                                                                       |
| [CHR0039](/chronicle/code-analysis/chr0039/) | Assertion result is discarded and can never fail                                       | Warning  | An awaitable-returning `Should*` assertion on a Cratis testing surface whose result is discarded throws on an awaitable nobody observes, so the assertion silently passes regardless of behavior and CS4014 does not fire outside an async method                                                                                                              |
| [CHR0040](/chronicle/code-analysis/chr0040/) | Several \[SetFromContext] for the same event type on one member                        | Warning  | They write the same property in the definition, so only the last declared is kept and the earlier capture is silently dropped; capturing from several *different* event types is the supported use and is not flagged                                                                                                                                          |
| [CHR0041](/chronicle/code-analysis/chr0041/) | Event filter attribute on a projection has no effect                                   | Warning  | A projection observes every event of the types it declares and cannot filter on event metadata — only reactors and reducers can — so \[EventStreamType], \[EventSourceType], and \[FilterEventsByTag] on a projection are silently ignored                                                                                                                     |
| [CHR0042](/chronicle/code-analysis/chr0042/) | A joined property is also written locally                                              | Warning  | A property written by both a local mapping and a join — model-bound or fluent — always ends up with the joined value regardless of arrival order, so a local write can never reset it; a flag latched from both sides silently sticks                                                                                                                          |
| [CHR0043](/chronicle/code-analysis/chr0043/) | Key redirection carries a \[PII] value across the compliance subject                   | Warning  | A root key or child parent-key redirect carries PII onto a document whose resolved compliance subject is not provably the value owner’s                                                                                                                                                                                                                        |
| [CHR0045](/chronicle/code-analysis/chr0045/) | Event stream metadata attribute on an event type has no effect                         | Warning  | An append resolves its event source type and event stream type from the append itself, never from the event’s CLR type, so \[EventStreamType] and \[EventSourceType] on an \[EventType] are read by nothing — declare them on the appending command, the observing reactor/reducer, or (for \[EventStreamType]) the aggregate root whose appends they identify |
| [CHR0046](/chronicle/code-analysis/chr0046/) | Passive read model redirects the document key away from the event’s own stream         | Warning  | A passive read model has no sink, so a read replays one event stream constrained to the requested key; a root key redirection points that replay at a stream the events were never appended to and the read returns a default-initialized model                                                                                                                |
| [CHR0047](/chronicle/code-analysis/chr0047/) | A clear declaration is never applied by projection construction                        | Retired  | Both declarations it reported - a null \[SetValue] and a member-level \[ClearWith] - are a working scalar clear now, so the rule was removed; the id stays reserved and is never reused                                                                                                                                                                        |
| [CHR0048](/chronicle/code-analysis/chr0048/) | A clear is declared for a member that cannot hold null                                 | Warning  | Clearing means returning a member to no value; a non-nullable member has no such state, so the only thing the projection could write is the type default - a different fact the read model cannot tell apart from a real value                                                                                                                                 |
| [CHR0049](/chronicle/code-analysis/chr0049/) | `EventTypeGenerationFor<T>` must reference a type marked with \[EventType]             | Error    | A type marked with `EventTypeGenerationFor<T>` references a type that is not itself marked with \[EventType], so there is no id to resolve the previous generation’s identity from                                                                                                                                                                             |

## Quick Fixes

[Section titled “Quick Fixes”](#quick-fixes)

* CHR0001, CHR0002, CHR0003, CHR0005, and CHR0007 provide a code fix that adds the missing `[EventType]` attribute to the referenced type.
* CHR0026 provides a code fix that removes the redundant `[Key]`/`[Subject]` attribute.
* CHR0028 provides a code fix that removes the redundant `.AutoMap()` call.
* CHR0029 provides a code fix that removes the redundant `.Set(...).To(...)` mapping.

## Installation

[Section titled “Installation”](#installation)

The analyzer is automatically included when you reference the `Cratis.Chronicle` NuGet package.

# CHR0001: Event type must have [EventType] attribute

## Rule Description

[Section titled “Rule Description”](#rule-description)

Types that are appended to event sequences must be marked with the `[EventType]` attribute. This ensures that all events in the event store are properly identified and can be correctly deserialized.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

// Missing [EventType] attribute
  public record Chr0001UserCreated(string Username, string Email);

public class Chr0001UserService(IEventSequence eventSequence)
  {
      public Task CreateUser(EventSourceId userId, string username, string email) =>
          // CHR0001: Type 'Chr0001UserCreated' must be marked with [EventType] attribute
          eventSequence.Append(userId, new Chr0001UserCreated(username, email));
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

[EventType]
  public record Chr0001UserCreatedFixed(string Username, string Email);

public class Chr0001UserServiceFixed(IEventSequence eventSequence)
  {
      public Task CreateUser(EventSourceId userId, string username, string email) =>
          // Now valid
          eventSequence.Append(userId, new Chr0001UserCreatedFixed(username, email));
  }
  ```

## Quick Fix

[Section titled “Quick Fix”](#quick-fix)

The analyzer provides a code fix that automatically:

1. Adds the `[EventType]` attribute to the event type
2. Adds the required using directive if not already present

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

The `[EventType]` attribute is crucial for Chronicle’s event handling:

* It uniquely identifies the event type in the event store
* It enables proper event serialization and deserialization
* It allows Chronicle to track event type generations and schemas
* It ensures type safety when working with events

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0003](/chronicle/code-analysis/chr0003/): Model bound projection attributes
* [CHR0005](/chronicle/code-analysis/chr0005/): Reactor event parameters
* [CHR0007](/chronicle/code-analysis/chr0007/): Reducer event parameters

# CHR0002: Declarative projection event type must have [EventType] attribute

## Rule Description

[Section titled “Rule Description”](#rule-description)

Generic type arguments in declarative projections that reference event types must be marked with the `[EventType]` attribute.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Projections;

// Missing [EventType] attribute
  public record Chr0002OrderCreated(Guid OrderId, decimal Amount);

public class Chr0002OrderReadModel
  {
      public Guid Id { get; set; }
      public decimal Amount { get; set; }
  }

public class Chr0002OrderProjection : IProjectionFor<Chr0002OrderReadModel>
  {
      public void Define(IProjectionBuilderFor<Chr0002OrderReadModel> builder) =>
          // CHR0002: Type 'Chr0002OrderCreated' must be marked with [EventType] attribute
          builder.From<Chr0002OrderCreated>(_ => _
              .Set(m => m.Id).To(e => e.OrderId)
              .Set(m => m.Amount).To(e => e.Amount));
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record Chr0002OrderCreatedFixed(Guid OrderId, decimal Amount);

public class Chr0002OrderReadModelFixed
  {
      public Guid Id { get; set; }
      public decimal Amount { get; set; }
  }

public class Chr0002OrderProjectionFixed : IProjectionFor<Chr0002OrderReadModelFixed>
  {
      public void Define(IProjectionBuilderFor<Chr0002OrderReadModelFixed> builder) =>
          // Now valid
          builder.From<Chr0002OrderCreatedFixed>(_ => _
              .Set(m => m.Id).To(e => e.OrderId)
              .Set(m => m.Amount).To(e => e.Amount));
  }
  ```

## Quick Fix

[Section titled “Quick Fix”](#quick-fix)

The analyzer provides a code fix that automatically adds the `[EventType]` attribute to the referenced type.

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Declarative projections define how events are projected into read models. All event types used in these projections must be properly identified to ensure:

* Correct event routing and handling
* Proper schema tracking
* Type-safe projection definitions

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0001](/chronicle/code-analysis/chr0001/): Event sequence append operations
* [CHR0003](/chronicle/code-analysis/chr0003/): Model bound projection attributes

# CHR0003: Model bound projection attribute must reference event type with [EventType] attribute

## Rule Description

[Section titled “Rule Description”](#rule-description)

Model bound projection attributes (such as `FromEventAttribute<TEvent>`, `RemovedWithAttribute<TEvent>`, etc.) must reference types that are marked with the `[EventType]` attribute.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Projections.ModelBound;

// Missing [EventType] attribute
  public record Chr0003ProductAdded(Guid ProductId, string Name, decimal Price);

// CHR0003: Type 'Chr0003ProductAdded' must be marked with [EventType] attribute
  [FromEvent<Chr0003ProductAdded>]
  public class Chr0003ProductReadModel
  {
      public Guid Id { get; set; }
      public string Name { get; set; } = string.Empty;
      public decimal Price { get; set; }
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record Chr0003ProductAddedFixed(Guid ProductId, string Name, decimal Price);

// Now valid
  [FromEvent<Chr0003ProductAddedFixed>]
  public class Chr0003ProductReadModelFixed
  {
      public Guid Id { get; set; }
      public string Name { get; set; } = string.Empty;
      public decimal Price { get; set; }
  }
  ```

## Applicable Attributes

[Section titled “Applicable Attributes”](#applicable-attributes)

This rule applies to the following model bound projection attributes:

* `FromEventAttribute<TEvent>`
* `RemovedWithAttribute<TEvent>`
* `RemovedWithJoinAttribute<TEvent>`
* `JoinAttribute<TEvent>`
* `ChildrenFromAttribute<TEvent>`
* `FromEveryAttribute<TEvent>`

## Quick Fix

[Section titled “Quick Fix”](#quick-fix)

The analyzer provides a code fix that automatically adds the `[EventType]` attribute to the referenced event type.

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Model bound projections use attributes to define how events map to read models. These attributes must reference valid event types to ensure:

* Proper event-to-model mapping
* Correct projection materialization
* Type-safe projection definitions
* Accurate event handling

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0001](/chronicle/code-analysis/chr0001/): Event sequence append operations
* [CHR0002](/chronicle/code-analysis/chr0002/): Declarative projection event types

# CHR0004: Reactor method has a parameter that cannot be resolved

## Rule Description

[Section titled “Rule Description”](#rule-description)

A reactor handler method takes the event it reacts to as its first parameter. Any further parameters are resolved as dependencies when the method is invoked:

* The `EventContext` for the triggering event.
* A read model — a type that has a reducer or projection. It is materialized strongly consistent from that reducer or projection.
* A service resolved from the service provider.

A parameter that is a primitive, value type, or string can never be a read model and is almost never a service, so it is flagged: at runtime it would fail to resolve and the partition would fail.

## Severity

[Section titled “Severity”](#severity)

Warning

## Allowed Signatures

[Section titled “Allowed Signatures”](#allowed-signatures)

* C#

```csharp
  using Cratis.Chronicle.Events;

public interface ValidReactorMethodSignatures<TEvent, TReadModel, IService>
  {
      void MethodName(TEvent @event);
      Task MethodNameAsync(TEvent @event);

void MethodName(TEvent @event, EventContext context);
      Task MethodNameAsync(TEvent @event, EventContext context);

Task MethodNameAsync(TEvent @event, EventContext context, TReadModel readModel, IService service);
      Task MethodNameAsync(TEvent @event, TReadModel readModel);
  }
  ```

Where `TEvent` is a type marked with `[EventType]`, and `TReadModel` is a type that has a reducer or projection.

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record Chr0004OrderUpdated;

public class InvalidOrderReactor : IReactor
  {
      public Task OrderUpdated(Chr0004OrderUpdated @event, int count) =>
          Task.CompletedTask;
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record Chr0004FixedOrderUpdated;

public record Chr0004Order(int Count);

public class ValidOrderReactor : IReactor
  {
      public Task OrderUpdated(Chr0004FixedOrderUpdated @event, Chr0004Order order) =>
          Task.CompletedTask;
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Reactors take dependencies on their handler methods. Read models are resolved directly by Chronicle, and other dependencies come from the service provider. A primitive, value type, or string is neither, so flagging it early prevents a runtime resolution failure that would pause the event source partition.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0005](/chronicle/code-analysis/chr0005/): Reactor event parameter must have \[EventType] attribute
* [CHR0006](/chronicle/code-analysis/chr0006/): Reducer method signatures

# CHR0005: Reactor event parameter must have [EventType] attribute

## Rule Description

[Section titled “Rule Description”](#rule-description)

Event parameters in reactor methods must be types marked with the `[EventType]` attribute. This ensures that reactors only handle properly identified event types.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Reactors;

// Missing [EventType] attribute
  public record Chr0005CustomerRegistered(Guid CustomerId, string Email);

public class Chr0005CustomerReactor : IReactor
  {
      // CHR0005: Type 'Chr0005CustomerRegistered' must be marked with [EventType] attribute
      public Task Registered(Chr0005CustomerRegistered @event) => Task.CompletedTask;
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record Chr0005CustomerRegisteredFixed(Guid CustomerId, string Email);

public class Chr0005CustomerReactorFixed : IReactor
  {
      // Now valid
      public Task Registered(Chr0005CustomerRegisteredFixed @event) => Task.CompletedTask;
  }
  ```

## Quick Fix

[Section titled “Quick Fix”](#quick-fix)

The analyzer provides a code fix that automatically adds the `[EventType]` attribute to the event parameter type.

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Reactors handle side effects when events occur. Ensuring all event types are properly marked:

* Guarantees proper event routing to reactors
* Enables type-safe event handling
* Ensures events are correctly serialized/deserialized
* Maintains schema tracking for events

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0001](/chronicle/code-analysis/chr0001/): Event sequence append operations
* [CHR0004](/chronicle/code-analysis/chr0004/): Reactor method signatures
* [CHR0007](/chronicle/code-analysis/chr0007/): Reducer event parameters

# CHR0006: Reducer method signature must match allowed signatures

## Rule Description

[Section titled “Rule Description”](#rule-description)

Methods in reducer classes must follow one of the allowed signatures for event handling. This ensures proper integration with Chronicle’s reducer infrastructure.

## Severity

[Section titled “Severity”](#severity)

Warning

## Allowed Signatures

[Section titled “Allowed Signatures”](#allowed-signatures)

Event handler methods in reducers must have one of the following signatures:

* C#

```csharp
  using Cratis.Chronicle.Events;

public interface Chr0006ValidReducerMethodSignatures<TEvent>
  {
      // Async with event only
      Task MethodNameAsync(TEvent @event);

// Async with event and context
      Task MethodNameAsync(TEvent @event, EventContext context);

// Synchronous with event only
      void MethodName(TEvent @event);

// Synchronous with event and context
      void MethodName(TEvent @event, EventContext context);
  }
  ```

Where `TEvent` is a type marked with `[EventType]`.

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

public record Chr0006ItemAdded(string ProductId);

public record Chr0006ItemRemoved(string ProductId);

public class Chr0006ShoppingCart
  {
      public int ItemCount { get; set; }
  }

public class Chr0006InvalidShoppingCartReducer : IReducerFor<Chr0006ShoppingCart>
  {
      // CHR0006: Invalid signature - returns Task<int> instead of Task
      public async Task<int> ItemAdded(Chr0006ItemAdded @event)
      {
          await Task.CompletedTask;
          return 1;
      }

// CHR0006: Invalid signature - too many parameters
      public Task ItemRemoved(Chr0006ItemRemoved @event, EventContext context, bool validate) =>
          Task.CompletedTask;
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

public record Chr0006ItemAddedFixed(string ProductId);

public record Chr0006ItemRemovedFixed(string ProductId);

public record Chr0006CartCleared;

public class Chr0006ShoppingCartFixed
  {
      public int ItemCount { get; set; }
  }

public class Chr0006ValidShoppingCartReducer : IReducerFor<Chr0006ShoppingCartFixed>
  {
      // Valid signature
      public Task ItemAdded(Chr0006ItemAddedFixed @event) => Task.CompletedTask;

// Valid signature with context
      public Task ItemRemoved(Chr0006ItemRemovedFixed @event, EventContext context) => Task.CompletedTask;

// Valid synchronous signature
      public void CartCleared(Chr0006CartCleared @event)
      {
      }
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Reducers maintain state by processing events in sequence. Standardized method signatures ensure:

* Predictable reducer behavior
* Proper infrastructure integration
* Clear code patterns across the codebase
* Reliable state management

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0004](/chronicle/code-analysis/chr0004/): Reactor method signatures
* [CHR0007](/chronicle/code-analysis/chr0007/): Reducer event parameter must have \[EventType] attribute

# CHR0007: Reducer event parameter must have [EventType] attribute

## Rule Description

[Section titled “Rule Description”](#rule-description)

Event parameters in reducer methods must be types marked with the `[EventType]` attribute. This ensures that reducers only handle properly identified event types.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Reducers;

// Missing [EventType] attribute
  public record Chr0007InventoryAdjusted(string ProductId, int Quantity);

public class Chr0007InventoryState
  {
      public int Quantity { get; set; }
  }

public class Chr0007InventoryReducer : IReducerFor<Chr0007InventoryState>
  {
      // CHR0007: Type 'Chr0007InventoryAdjusted' must be marked with [EventType] attribute
      public void Adjusted(Chr0007InventoryAdjusted @event)
      {
      }
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

[EventType]
  public record Chr0007InventoryAdjustedFixed(string ProductId, int Quantity);

public class Chr0007InventoryStateFixed
  {
      public int Quantity { get; set; }
  }

public class Chr0007InventoryReducerFixed : IReducerFor<Chr0007InventoryStateFixed>
  {
      // Now valid
      public void Adjusted(Chr0007InventoryAdjustedFixed @event)
      {
      }
  }
  ```

## Quick Fix

[Section titled “Quick Fix”](#quick-fix)

The analyzer provides a code fix that automatically adds the `[EventType]` attribute to the event parameter type.

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Reducers build state from events in a deterministic way. Ensuring all event types are properly marked:

* Guarantees proper event routing to reducers
* Enables type-safe state reduction
* Ensures events are correctly serialized/deserialized
* Maintains schema tracking for events
* Allows for proper reducer replay and catchup

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0001](/chronicle/code-analysis/chr0001/): Event sequence append operations
* [CHR0005](/chronicle/code-analysis/chr0005/): Reactor event parameters
* [CHR0006](/chronicle/code-analysis/chr0006/): Reducer method signatures

# CHR0012: Event types should avoid nullable properties

## Rule Description

[Section titled “Rule Description”](#rule-description)

Event types can contain nullable properties, but this is often an anti-pattern in event sourcing. A nullable field can hide multiple meanings in one event. Prefer expressing optional facts with a dedicated event type when possible.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

### Warning

[Section titled “Warning”](#warning)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record Chr0012MissionAccepted(
      string MissionId,
      DateOnly? StartDate);
  ```

### Preferred

[Section titled “Preferred”](#preferred)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record Chr0012MissionAcceptedFixed(
      string MissionId,
      DateOnly StartDate);

[EventType]
  public record Chr0012MissionAcceptedWithoutStartDate(
      string MissionId);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Events represent immutable facts. Nullable properties can blur the meaning of those facts and force consumers to branch on missing values.

Keeping event types explicit:

* improves readability
* reduces ambiguity for projections, reducers, and reactors
* keeps event history easier to understand

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0001](/chronicle/code-analysis/chr0001/): Event sequence append operations

# CHR0013: Reactor cannot combine EventStore with explicit event sequence

## Rule Description

[Section titled “Rule Description”](#rule-description)

A reactor that declares `[EventStore("...")]` must use implicit inbox routing. It cannot also define an explicit event sequence.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventStore("identity-service")]
  [Reactor(eventSequence: "custom-sequence")]
  public class Chr0013UserSyncReactor : IReactor;
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventStore("identity-service")]
  [Reactor]
  public class Chr0013UserSyncReactorFixed : IReactor;
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

`[EventStore]` on a reactor is intended to drive outbox-to-inbox routing. Combining it with explicit event sequence configuration creates ambiguous routing intent.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0014](/chronicle/code-analysis/chr0014/): Reducer cannot combine EventStore with explicit event sequence

# CHR0014: Reducer cannot combine EventStore with explicit event sequence

## Rule Description

[Section titled “Rule Description”](#rule-description)

A reducer that declares `[EventStore("...")]` must use implicit inbox routing. It cannot also define an explicit event sequence.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

[EventStore("identity-service")]
  [Reducer(eventSequence: "custom-sequence")]
  public class Chr0014UserSummaryReducer : IReducer;
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

[EventStore("identity-service")]
  [Reducer]
  public class Chr0014UserSummaryReducerFixed : IReducer;
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

`[EventStore]` on a reducer is intended to drive outbox-to-inbox routing. Combining it with explicit event sequence configuration creates ambiguous routing intent.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0013](/chronicle/code-analysis/chr0013/): Reactor cannot combine EventStore with explicit event sequence

# CHR0015: Projection must not have side effects

## Rule Description

[Section titled “Rule Description”](#rule-description)

A class implementing `IProjectionFor<T>` must not inject `ICommandPipeline` or `IEventLog` via its constructor. Projections are pure state builders that derive read models from events and must not produce side effects.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Projections;

[EventType]
  public record Chr0015UserRegistered;

public class Chr0015UserReadModel;

public class Chr0015UserProjection : IProjectionFor<Chr0015UserReadModel>
  {
      readonly IEventLog _eventLog;

// CHR0015: Projections must not take dependencies through the constructor
      public Chr0015UserProjection(IEventLog eventLog)
      {
          _eventLog = eventLog;
      }

public void Define(IProjectionBuilderFor<Chr0015UserReadModel> builder) =>
          builder.From<Chr0015UserRegistered>();
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record Chr0015UserRegisteredFixed;

public class Chr0015UserReadModelFixed;

public class Chr0015UserProjectionFixed : IProjectionFor<Chr0015UserReadModelFixed>
  {
      // Now valid - no constructor dependencies
      public void Define(IProjectionBuilderFor<Chr0015UserReadModelFixed> builder) =>
          builder.From<Chr0015UserRegisteredFixed>();
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Projections declare how to build a read model from a stream of events. They are evaluated at replay time and must be purely declarative. Injecting `IEventLog` or `ICommandPipeline` implies intent to perform side effects during projection evaluation, which breaks idempotency and replay safety.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0016](/chronicle/code-analysis/chr0016/): Projection Define() must not contain imperative code
* [CHR0017](/chronicle/code-analysis/chr0017/): Constraint must not have side effects

# CHR0016: Projection Define() must not contain imperative code

## Rule Description

[Section titled “Rule Description”](#rule-description)

The `Define()` method of a class implementing `IProjectionFor<T>` must not contain imperative statements such as `if`/`else`, loops, variable declarations, or assignments. Projection definitions only declare the shape; they do not execute.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record Chr0016UserRegistered;

public class Chr0016UserReadModel;

public class Chr0016UserProjection : IProjectionFor<Chr0016UserReadModel>
  {
      public bool SomeCondition { get; init; }

// CHR0016: Define must not contain conditional logic
      public void Define(IProjectionBuilderFor<Chr0016UserReadModel> builder)
      {
          if (SomeCondition)
          {
              builder.From<Chr0016UserRegistered>();
          }
      }
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record Chr0016UserRegisteredFixed;

public class Chr0016UserReadModelFixed;

public class Chr0016UserProjectionFixed : IProjectionFor<Chr0016UserReadModelFixed>
  {
      // Now valid - unconditional
      public void Define(IProjectionBuilderFor<Chr0016UserReadModelFixed> builder) =>
          builder.From<Chr0016UserRegisteredFixed>();
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

The `Define()` method is called once at registration time to declare the projection shape. Chronicle serializes the resulting definition and sends it to the server for use during both live processing and replay. Any imperative code such as conditionals or loops creates non-determinism: different runs could produce different projection definitions, breaking replay consistency.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0015](/chronicle/code-analysis/chr0015/): Projection must not have side effects
* [CHR0018](/chronicle/code-analysis/chr0018/): Constraint Define() must not contain imperative code

# CHR0017: Constraint must not have side effects

## Rule Description

[Section titled “Rule Description”](#rule-description)

A class implementing `IConstraint` must not inject `ICommandPipeline` or `IEventLog` via its constructor. Constraints are pure rule builders and must not produce side effects.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;
  using Cratis.Chronicle.EventSequences;

[EventType]
  public record Chr0017UserRegistered;

public class Chr0017UniqueEmailConstraint : IConstraint
  {
      readonly IEventLog _eventLog;

// CHR0017: Constraints must not take dependencies through the constructor
      public Chr0017UniqueEmailConstraint(IEventLog eventLog)
      {
          _eventLog = eventLog;
      }

public void Define(IConstraintBuilder builder) =>
          builder.Unique<Chr0017UserRegistered>();
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record Chr0017UserRegisteredFixed;

public class Chr0017UniqueEmailConstraintFixed : IConstraint
  {
      // Now valid - no constructor dependencies
      public void Define(IConstraintBuilder builder) =>
          builder.Unique<Chr0017UserRegisteredFixed>();
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Constraints declare rules about what combinations of events are valid. They are evaluated by the server in a pure, stateless fashion. Injecting `IEventLog` or `ICommandPipeline` implies side effects that cannot be guaranteed to execute at constraint-check time, leading to unpredictable behaviour.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0018](/chronicle/code-analysis/chr0018/): Constraint Define() must not contain imperative code
* [CHR0015](/chronicle/code-analysis/chr0015/): Projection must not have side effects

# CHR0018: Constraint Define() must not contain imperative code

## Rule Description

[Section titled “Rule Description”](#rule-description)

The `Define()` method of a class implementing `IConstraint` must not contain imperative statements such as `if`/`else`, loops, variable declarations, or assignments. Constraint definitions only declare rules; they do not execute.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record Chr0018UserRegistered;

public class Chr0018UniqueEmailConstraint : IConstraint
  {
      public bool SomeCondition { get; init; }

// CHR0018: Define must not contain conditional logic
      public void Define(IConstraintBuilder builder)
      {
          if (SomeCondition)
          {
              builder.Unique<Chr0018UserRegistered>();
          }
      }
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record Chr0018UserRegisteredFixed;

public class Chr0018UniqueEmailConstraintFixed : IConstraint
  {
      // Now valid - unconditional
      public void Define(IConstraintBuilder builder) =>
          builder.Unique<Chr0018UserRegisteredFixed>();
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

The `Define()` method is called once at registration time to declare constraint rules. The resulting definition is serialized and sent to the server. Imperative code such as conditionals or loops creates non-determinism: different runs could produce different constraint definitions, breaking consistency.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0017](/chronicle/code-analysis/chr0017/): Constraint must not have side effects
* [CHR0016](/chronicle/code-analysis/chr0016/): Projection Define() must not contain imperative code

# CHR0019: Projection expression lambda must only access members

## Rule Description

[Section titled “Rule Description”](#rule-description)

Expression lambdas passed to projection builder methods (e.g. `Set(x => ...)`, `To(e => ...)`, `IdentifiedBy(x => ...)`, `UsingKey(e => ...)`) must only contain simple member access. They cannot contain method calls, arithmetic, conditional expressions, or any other executable code.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

public class Chr0019UserReadModel
  {
      public string Name { get; set; } = string.Empty;
  }

[EventType]
  public record Chr0019UserRegistered(string Name);

public class Chr0019UserProjection : IProjectionFor<Chr0019UserReadModel>
  {
      public void Define(IProjectionBuilderFor<Chr0019UserReadModel> builder) =>
          builder.From<Chr0019UserRegistered>(_ => _
              .Set(x => x.Name)
              .To(e => e.Name.ToUpper())); // CHR0019: method call - never executed
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

public class Chr0019UserReadModelFixed
  {
      public string Name { get; set; } = string.Empty;
  }

[EventType]
  public record Chr0019UserRegisteredFixed(string Name);

public class Chr0019UserProjectionFixed : IProjectionFor<Chr0019UserReadModelFixed>
  {
      public void Define(IProjectionBuilderFor<Chr0019UserReadModelFixed> builder) =>
          builder.From<Chr0019UserRegisteredFixed>(_ => _
              .Set(x => x.Name)
              .To(e => e.Name)); // Now valid - simple member access
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

In Chronicle’s projection builder, any parameter typed as `Expression<Func<...>>` is **parsed at startup** to extract a property path for the read-model mapping—the lambda body is **never executed at runtime**. Writing method calls, arithmetic (`e.Count + 1`), conditional expressions (`e.Flag ? e.A : e.B`), or similar executable code in such a lambda will be silently ignored, producing an incorrect or incomplete projection definition that is very difficult to debug.

The only valid lambda body is a direct property access chain, for example `x => x.Property` or `x => x.Parent.Child`.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0016](/chronicle/code-analysis/chr0016/): Projection Define() must not contain imperative code
* [CHR0020](/chronicle/code-analysis/chr0020/): Constraint expression lambda must only access members

# CHR0020: Constraint expression lambda must only access members

## Rule Description

[Section titled “Rule Description”](#rule-description)

Expression lambdas passed to constraint builder methods (e.g. `On<TEvent>(e => ...)`) must only contain simple member access. They cannot contain method calls, arithmetic, conditional expressions, or any other executable code.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record Chr0020OrderPlaced(string OrderId);

public class Chr0020OrderConstraint : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(u => u.On<Chr0020OrderPlaced>(e => e.OrderId.ToLower())); // CHR0020: method call - never executed
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record Chr0020OrderPlacedFixed(string OrderId);

public class Chr0020OrderConstraintFixed : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(u => u.On<Chr0020OrderPlacedFixed>(e => e.OrderId)); // Now valid - simple member access
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

In Chronicle’s constraint builder, any parameter typed as `Expression<Func<...>>` is **parsed at startup** to extract a property name for the constraint rule—the lambda body is **never executed at runtime**. Writing method calls, arithmetic, conditional expressions, or similar executable code in such a lambda will be silently ignored, producing an incorrect or incomplete constraint definition.

The only valid lambda body is a direct property access, for example `e => e.Email` or `e => e.OrderId`.

If case-insensitive comparison is needed, use `builder.Unique(u => u.On<OrderPlaced>(e => e.Email).IgnoreCasing())` instead of transforming the value in the lambda.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0018](/chronicle/code-analysis/chr0018/): Constraint Define() must not contain imperative code
* [CHR0019](/chronicle/code-analysis/chr0019/): Projection expression lambda must only access members

# CHR0021: Event types should be record types

## Rule Description

[Section titled “Rule Description”](#rule-description)

Types decorated with `[EventType]` should be declared as `record` types rather than classes.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType("f47ac10b-58cc-4372-a567-0e02b2c3d479")]
  public class Chr0021UserRegistered // CHR0021: mutable class
  {
      public string UserId { get; set; } = string.Empty;
      public string Email { get; set; } = string.Empty;
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType("f47ac10b-58cc-4372-a567-0e02b2c3d479")]
  public record Chr0021UserRegisteredFixed(string UserId, string Email); // Immutable record
  ```

Or with init-only property syntax for events with many properties:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType("f47ac10b-58cc-4372-a567-0e02b2c3d480")]
  public record Chr0021UserRegisteredWithInit
  {
      public string UserId { get; init; } = string.Empty;
      public string Email { get; init; } = string.Empty;
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Events in Chronicle are **permanent, immutable facts** appended to the event log and replayed to rebuild read-model state. Using a `class` allows the event object to be mutated after creation, which can lead to subtle bugs—for example, modifying an event during a handler before it is fully processed, or producing different results across replays.

Using a `record` type provides:

* **Immutability by default** — positional parameters are init-only
* **Structural equality** — two events with the same data are considered equal
* **Concise syntax** — positional record syntax keeps event definitions compact and self-documenting
* **Intent clarity** — a `record` signals to readers that the type is a value/fact, not a mutable entity

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0012](/chronicle/code-analysis/chr0012/): Event types should avoid nullable properties

# CHR0022: Reactor methods returning event side effects must be marked with [OnceOnly]

## Rule Description

[Section titled “Rule Description”](#rule-description)

A reactor handler method that returns event(s) as a side effect causes Chronicle to append those events to the event log. Unless the method is marked with `[OnceOnly]`, it runs again during replay operations — appending duplicate events.

Mark such a method with `[OnceOnly]`.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record Chr0022OrderPlaced(Guid OrderId, decimal Total);

[EventType]
  public record Chr0022InvoiceRaised(Guid OrderId, decimal Total);

public class Chr0022Invoicing : IReactor
  {
      // Warning CHR0022: this method returns a side-effect event, so Chronicle appends Chr0022InvoiceRaised
      // whenever Chr0022OrderPlaced is observed — including during replay, which would append it again.
      public Chr0022InvoiceRaised OrderPlaced(Chr0022OrderPlaced @event) =>
          new(@event.OrderId, @event.Total);
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record Chr0022OrderPlacedFixed(Guid OrderId, decimal Total);

[EventType]
  public record Chr0022InvoiceRaisedFixed(Guid OrderId, decimal Total);

public class Chr0022InvoicingFixed : IReactor
  {
      // [OnceOnly] makes Chronicle run the handler a single time per event source and skip it during
      // replays, so the side-effect event is appended exactly once.
      [OnceOnly]
      public Chr0022InvoiceRaisedFixed OrderPlaced(Chr0022OrderPlacedFixed @event) =>
          new(@event.OrderId, @event.Total);
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

A reactor observes events and produces side effects. When a handler **returns** an event, Chronicle appends it to the event log as a follow-up fact. Reactors are also re-run during replay operations — observer rewind, redaction, and revision — so a handler that appends an event and is not idempotent would append that event a second time on every replay, producing duplicate facts and, in turn, incorrect projected state.

`[OnceOnly]` tells Chronicle to run the handler a single time per event source and to skip it during replays, so the side-effect event is appended exactly once. Side effects that are naturally idempotent, or that do not append events, don’t need it — which is why the rule targets specifically the methods that *return* events.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [Reactors](/chronicle/reactors/) — reactor side effects and idempotency.

# CHR0023: Ambiguous parent key for [ChildrenFrom] collection

## Rule Description

[Section titled “Rule Description”](#rule-description)

When a `[ChildrenFrom]` collection omits its `parentKey` argument, Chronicle infers the parent key by matching the parent read model’s identifier type against the child event’s properties (excluding the child `key`). When more than one property still matches that type, the inference is ambiguous — it would resolve by declaration order, which is fragile.

Specify the `parentKey` argument to make the relationship explicit.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

public record Chr0023Ledger(
      [Key] Guid Id,

// Warning CHR0023: Chr0023EntryRecorded has two Guid-typed properties (LedgerId and
      // OffsetLedgerId), so Chronicle cannot infer which one links an entry to its parent ledger.
      [ChildrenFrom<Chr0023EntryRecorded>(key: nameof(Chr0023EntryRecorded.EntryId))]
      IEnumerable<Chr0023Entry> Entries);

[EventType]
  public record Chr0023EntryRecorded(Guid EntryId, Guid LedgerId, Guid OffsetLedgerId, decimal Amount);

public record Chr0023Entry([Key] Guid EntryId, decimal Amount);
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  public record Chr0023LedgerFixed(
      [Key] Guid Id,

// parentKey names the event property that links the child back to its parent, so the
      // relationship is explicit and no longer depends on declaration order.
      [ChildrenFrom<Chr0023EntryRecordedFixed>(
          key: nameof(Chr0023EntryRecordedFixed.EntryId),
          parentKey: nameof(Chr0023EntryRecordedFixed.LedgerId))]
      IEnumerable<Chr0023EntryFixed> Entries);

[EventType]
  public record Chr0023EntryRecordedFixed(Guid EntryId, Guid LedgerId, Guid OffsetLedgerId, decimal Amount);

public record Chr0023EntryFixed([Key] Guid EntryId, decimal Amount);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

A `[ChildrenFrom]` collection projects child rows from an event stream and attaches them to a parent read model. Chronicle needs to know which event property carries the **parent** identifier so it can place each child under the right parent.

When `parentKey` is omitted, Chronicle infers it: it takes the parent read model’s identifier type and looks for a single event property of that type (the child `key` property is excluded, since one property can’t be both the child key and the parent key). If exactly one property matches, the inference is safe. If **two or more** match, the choice is ambiguous — the projection would silently pick one by declaration order, so reordering the event’s parameters, or adding another property of the same type later, could quietly re-point every child at a different parent.

Naming `parentKey` explicitly removes that fragility: the relationship is stated in the read model, survives refactoring of the event, and makes the intent obvious to readers.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [Model-bound children](/chronicle/projections/model-bound/children/) — the full `[ChildrenFrom]` reference.

# CHR0024: Read model property has no mapping source

## Rule Description

[Section titled “Rule Description”](#rule-description)

In a model-bound projection read model, AutoMap populates a property only when a subscribed event carries a property of the same name. A property that has no property-level mapping attribute *and* no same-named property on any subscribed event will silently never be populated.

Add an explicit mapping attribute (for example `[SetFrom<T>(nameof(...))]`), or subscribe to an event that carries the value.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<Chr0024AccountRegistered>]
  public record Chr0024Account(
      [Key] Guid Id,

// Warning CHR0024: Name has no mapping attribute, and Chr0024AccountRegistered — the only
      // subscribed event — carries no same-named property, so AutoMap can never populate it.
      string Name);

[EventType]
  public record Chr0024AccountRegistered(Guid Reference);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

A model-bound projection builds its read model from the events it subscribes to. Chronicle wires each subscribed event’s properties onto identically named read-model properties (AutoMap), and every other property is expected to carry a mapping attribute that names its source.

When a property has neither — no mapping attribute, and no subscribed event with a matching name — nothing can ever write it. The read model compiles and the projection runs, but that property stays at its default value forever. This is a silent gap: no error, no warning at runtime, just a column that is always empty.

The rule flags the property at the source so the omission surfaces at build time rather than as missing data in production. No code fix is offered, because no subscribed event carries the value — resolving it requires a human decision: subscribe to an event that carries the value, or add the mapping attribute that names its true source.

The identifier property and any `EventSourceId<T>`-typed property are excluded — they resolve from the key/stream identity, not AutoMap. A property already sourced by a mapping attribute is excluded too.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* **CHR0030** — the child-collection counterpart: a `[ChildrenFrom]` collection that auto-maps to *nothing*.
* [CHR0025](/chronicle/code-analysis/chr0025/) — an explicitly sourced property that AutoMap can *overwrite* from another event.
* [Model-bound projections](/chronicle/projections/model-bound/) — the full reference.

# CHR0025: Explicitly sourced read model property may be overwritten by AutoMap

## Rule Description

[Section titled “Rule Description”](#rule-description)

AutoMap runs per *event* across every event a model-bound projection references — it does **not** defer to your explicit setters. A property set with `[SetFrom<A>]` (or `[SetValue]`, `[AddFrom]`, `[SubtractFrom]`, `[SetFromContext]`, `[Join]`) can therefore be overwritten when another referenced event `B` carries a property of the same name, because AutoMap writes `B`’s value on top of the value you mapped explicitly.

This is reported as **information**, not a warning: the collision has two legitimate resolutions and only you know which was intended.

## Severity

[Section titled “Severity”](#severity)

Info

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<Chr0025Opened>]
  public record Chr0025Account(
      [Key] Guid Id,

// Info CHR0025: Location is set explicitly from Chr0025Opened, but Chr0025WorkModeSet — also
      // referenced by this projection (for WorkMode) — carries a Location that AutoMap writes on top of it.
      [SetFrom<Chr0025Opened>]
      string Location,

[SetFrom<Chr0025WorkModeSet>]
      string WorkMode);

[EventType]
  public record Chr0025Opened(string Location);

[EventType]
  public record Chr0025WorkModeSet(string WorkMode, string Location);
  ```

## Resolving

[Section titled “Resolving”](#resolving)

There are two valid resolutions, depending on intent:

* **The other event should not overwrite it** — fence the property with property-level `[NoAutoMap]` so only your explicit setter writes it:

```csharp
  [SetFrom<Chr0025Opened>]
  [NoAutoMap]
  string Location,
  ```

* **Updates from the other event are intended** — for example a later event legitimately updating the value by name-match (the *create-then-rename* pattern). In that case leave it as is; no change is needed.

Because either can be correct, CHR0025 is informational and offers no code fix — it must not push you toward one of two valid answers.

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

In a model-bound projection, Chronicle wires each referenced event’s properties onto identically named read-model properties (AutoMap). It does this for *every* referenced event, and it does not know that a property is “owned” by an explicit `[SetFrom]`. So when two referenced events both carry a `Location`, the one that runs last wins — and that can silently be the event you did **not** mean, producing an actively wrong value rather than a missing one.

The escape hatch is property-level `[NoAutoMap]`, which is deliberately opt-in: leaving AutoMap on is exactly what enables the common create-then-rename pattern, where a later event updates a property by name. A blanket “explicit beats implicit” rule was tried and reverted for breaking that pattern.

An event referenced only through an aggregate (`[Count]`, `[Increment]`, `[Decrement]`) does not auto-map its other properties, so it cannot collide and is not flagged. Name matching compares the C# member names case-insensitively and does not account for explicit `[SetFrom<T>("eventProperty")]` targets or a custom naming policy, so the diagnostic is an approximation.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* **CHR0030** — the mirror image: a `[ChildrenFrom]` child collection that auto-maps to *nothing*.
* [Model-bound projections](/chronicle/projections/model-bound/) — the full reference.

# CHR0026: [Key] or [Subject] on an EventSourceId<T> is redundant

## Rule Description

[Section titled “Rule Description”](#rule-description)

A property or record parameter whose type derives from `EventSourceId<T>` already is both the key (stream identity) and the compliance subject. `[Key]` and `[Subject]` exist for non-`EventSourceId<T>` values; on an `EventSourceId<T>` they are at best redundant and at worst mask an ambiguous multi-identity design that should be split into distinct types rather than annotated around.

Remove the attribute.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;

public record Chr0026AccountId(Guid Value) : EventSourceId<Guid>(Value);

public record Chr0026Account(
      // Warning CHR0026: Chr0026AccountId derives from EventSourceId<T>, so it already is the
      // key/stream identity and compliance subject — the [Key] attribute is redundant.
      [Key] Chr0026AccountId Id,
      string Name);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

`EventSourceId<T>` is the strongly-typed event-source identity. Being that identity, it is automatically the key Chronicle resolves the stream by, and it is automatically the compliance subject a value’s PII is encrypted under. `[Key]` and `[Subject]` exist precisely to designate those roles on values that would not otherwise carry them — a plain `Guid`, a string, another concept. On an `EventSourceId<T>` there is nothing to designate; the type already says it.

At best the attribute is noise. At worst it is a signal that the design is trying to carry more than one identity on a single type — for example annotating a second `EventSourceId<T>`-derived property as the `[Key]` to disambiguate. That ambiguity should be resolved by splitting the identities into distinct types, not papered over with an attribute. Removing the attribute keeps the identity’s meaning where it belongs: in the type.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [Event source](/chronicle/concepts/event-source/) — how `EventSourceId<T>` identifies a stream.
* [Subject](/chronicle/concepts/subject/) — how the compliance subject is resolved.

# CHR0027: Ambiguous event stream id

## Rule Description

[Section titled “Rule Description”](#rule-description)

A type that implements `ICanProvideEventStreamId` supplies the event stream id dynamically at runtime. Declaring a non-null `[EventStreamId]` attribute on the same type conflicts with that interface, and Chronicle throws `AmbiguousEventStreamId` when it starts.

Remove either the interface or the attribute. The sanctioned `[EventStreamId(null)]` defers to the interface and is allowed.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;

// Error CHR0027: Chr0027PlaceOrder both implements ICanProvideEventStreamId and declares a
  // non-null [EventStreamId] — Chronicle throws AmbiguousEventStreamId at startup. Remove one;
  // use [EventStreamId(null)] to defer to the interface.
  [EventStreamId("orders")]
  public class Chr0027PlaceOrder : ICanProvideEventStreamId
  {
      public EventStreamId GetEventStreamId() => "orders";
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

There are two ways to set an event stream id: statically, with the `[EventStreamId("...")]` attribute, or dynamically, by implementing `ICanProvideEventStreamId.GetEventStreamId()`. They are mutually exclusive — Chronicle cannot know which one wins, so it refuses to guess and throws `AmbiguousEventStreamId` at startup rather than silently picking one.

That failure happens when the application boots, not when the offending type is written — so without this analyzer the mistake ships and only surfaces as a startup crash. Reporting it as an **error** at build time turns a runtime bootstrapping failure into a compile-time one, right at the declaration.

Pick one mechanism. If the id is known at compile time, keep the attribute and drop the interface. If it is only known at runtime, keep the interface and remove the attribute — or set the attribute value to `null` (`[EventStreamId(null)]`), the sanctioned way to declare “the interface decides.”

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [Event sequence](/chronicle/concepts/event-sequence/) — event streams and where events are appended.

# CHR0028: Redundant .AutoMap() call

## Rule Description

[Section titled “Rule Description”](#rule-description)

AutoMap is enabled by default on projection builders, so calling `.AutoMap()` explicitly has no effect. Remove the redundant call. Use `.NoAutoMap()` when you need to disable the default behavior.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

public record Chr0028Product(string Name);

[EventType]
  public record Chr0028ProductRegistered(string Name);

public class Chr0028ProductProjection : IProjectionFor<Chr0028Product>
  {
      public void Define(IProjectionBuilderFor<Chr0028Product> builder) =>
          builder
              .From<Chr0028ProductRegistered>()
              // Warning CHR0028: '.AutoMap()' is redundant — AutoMap is enabled by default. Remove the call.
              .AutoMap();
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

A fluent `IProjectionFor<T>` projection maps each referenced event’s properties onto identically named read model properties on its own — AutoMap is on from the moment the builder starts. Calling `.AutoMap()` therefore only restates the default: it changes nothing and adds noise that suggests mapping is being configured when it is not.

The method exists for one narrow purpose — re-enabling AutoMap inside a scope where you first turned it off with `.NoAutoMap()`. Outside that scope the call is redundant. When you actually want to take control of mapping, reach for `.NoAutoMap()` and set the properties yourself; a bare `.AutoMap()` never expresses intent.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* **CHR0029** — a `.Set(...).To(...)` mapping whose source and target names match, which AutoMap already handles.
* [Model-bound projections](/chronicle/projections/model-bound/) — the full reference.

# CHR0029: Redundant .Set(...).To(...) with matching property names

## Rule Description

[Section titled “Rule Description”](#rule-description)

AutoMap is enabled by default and maps event properties to identically named read model properties. A `.Set(x => x.P).To(e => e.P)` mapping where the source and target property names are the same duplicates what AutoMap already does. Remove the redundant mapping and rely on AutoMap.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

public record Chr0029Customer(string Name);

[EventType]
  public record Chr0029CustomerRegistered(string Name);

public class Chr0029CustomerProjection : IProjectionFor<Chr0029Customer>
  {
      public void Define(IProjectionBuilderFor<Chr0029Customer> builder) =>
          builder.From<Chr0029CustomerRegistered>(customer => customer
              // Warning CHR0029: '.Set(x => x.Name).To(e => e.Name)' is redundant — AutoMap already maps
              // identically named properties. Remove the mapping.
              .Set(x => x.Name).To(e => e.Name));
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

`.Set(...).To(...)` is for the cases AutoMap cannot infer — a read model property whose name differs from the event property that feeds it. When both lambdas name the *same* property, the mapping restates the default AutoMap already applies, so the line carries no information and only obscures the mappings that do matter.

The analyzer is deliberately conservative: it fires only when both lambdas are simple `param => param.Member` member accesses and the two names are identical. A mapping that renames (`Set(x => x.DisplayName).To(e => e.Name)`) or transforms the value is doing real work and is left alone.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* **CHR0028** — an explicit `.AutoMap()` call, which is redundant for the same reason.
* [Model-bound projections](/chronicle/projections/model-bound/) — the full reference.

# CHR0030: [ChildrenFrom] child collection property auto-maps to nothing

## Rule Description

[Section titled “Rule Description”](#rule-description)

A collection property on a `[ChildrenFrom]` child is filled by AutoMap, which matches the event’s property of the same name. When no source event carries a matching property and nothing maps it explicitly, the property silently projects as an empty collection. Rename the property to match the event, or bridge the names with `[SetFrom<TEvent>(nameof(...))]`.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

public record Chr0033Note(string Text);

[EventType]
  public record Chr0033LineAdded(string LineNumber, string Description, IReadOnlyList<Chr0033Note> Annotations);

public record Chr0033Line(
      [Key] string LineNumber,
      string Description,
      IReadOnlyList<Chr0033Note> Notes);

public record Chr0033Order(
      [Key] Guid Id,

// Warning CHR0030: the child property 'Notes' matches no property on Chr0033LineAdded (the event
      // carries 'Annotations'), so AutoMap fills it from nothing and it always projects as empty.
      [ChildrenFrom<Chr0033LineAdded>(key: nameof(Chr0033LineAdded.LineNumber))]
      IEnumerable<Chr0033Line> Lines);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

A `[ChildrenFrom]` child is projected from its own event, and each of its properties is filled by AutoMap — Chronicle copies the event property of the same name onto it. When the child declares a collection property whose name matches **no** property on that event, and no `[SetFrom]` (or other mapping attribute) bridges the gap, there is nothing for AutoMap to copy. The child still projects, but that collection is always empty — a silent data loss rather than a compile or runtime error.

There are two fixes, depending on which name is right:

* **Rename the property to match the event** — call the child property what the event calls it, and AutoMap wires it automatically.
* **Bridge the names explicitly** — keep the property name and point it at the event property with `[SetFrom<TEvent>(nameof(TEvent.Property))]`.

This is the child-collection mirror of the scalar mapping-source rules: the same empty-projection trap the runtime projection engine also reports as a warning, surfaced here at build time so it never reaches production data.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* **CHR0024** — the scalar version: a read model property with no mapping source that AutoMap cannot populate.
* **CHR0025** — the inverse collision: an explicitly sourced property that AutoMap *overwrites* from another event.
* [Model-bound projections](/chronicle/projections/model-bound/) — the full reference.

# CHR0031: Reactor must not have mutable state

## Rule Description

[Section titled “Rule Description”](#rule-description)

A class implementing `IReactor` declares a mutable instance field or settable property. Reactors observe events and produce side effects; Chronicle re-creates and replays them, so mutable instance state is unreliable and leaks context between invocations.

Keep reactors stateless: express dependencies as `readonly`, primary-constructor-injected fields, and derive everything else from the event and event context.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

public class Chr0031OrderCounter : IReactor
  {
      // Warning CHR0031: Reactor declares mutable state '_count'; reactors are re-created and
      // replayed by Chronicle, so instance state is unreliable and leaks context between
      // invocations. Use readonly, primary-constructor-injected dependencies.
      int _count;

public Task OrderPlaced(Chr0031OrderPlaced @event, EventContext context)
      {
          _count++;
          return Task.CompletedTask;
      }
  }

[EventType]
  public record Chr0031OrderPlaced(string OrderNumber);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

A reactor has no reliable lifetime you can accumulate state across. Chronicle re-creates reactor instances and replays event streams through them, and a single event source may be processed more than once (recovery, rewind, redaction, revision). A mutable field or settable property therefore holds a value that depends on which events happened to run through this particular instance — a counter that is wrong after a replay, or a value that bleeds from one event source into the next.

Everything a reactor needs is already available: the collaborators it calls (injected once through the primary constructor as `readonly` fields) and the facts of the event it is handling (the event payload and `EventContext`). Anything derived should be computed from those inputs each time the handler runs, not stored on the instance. `static const`, `static readonly`, `readonly`, and `init`-only members are fine — the rule flags only mutable non-static fields and properties with a non-`init` setter.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0032: Reactor must not access storage directly](/chronicle/code-analysis/chr0032/) — reactors read state through read models.
* **CHR0022** — a reactor handler returning side-effect events must be marked `[OnceOnly]`.

# CHR0032: Reactor must not access storage directly

## Rule Description

[Section titled “Rule Description”](#rule-description)

A class implementing `IReactor` injects a storage primitive such as `IMongoCollection<T>` through its constructor. Injecting a sink couples the reactor to the persistence layer and bypasses Chronicle’s read-model abstraction.

Read keyed state through an injected read model parameter or `IReadModels.GetInstanceById` instead.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;
  using MongoDB.Driver;

// Warning CHR0032: Reactor injects storage primitive 'orders' directly; this couples the
  // reactor to a sink and bypasses Chronicle's read-model abstraction. Read keyed state
  // through an injected read model parameter or IReadModels.GetInstanceById instead.
  public class Chr0032OrderProcessor(IMongoCollection<Chr0032Order> orders) : IReactor
  {
      public async Task OrderPlaced(Chr0032OrderPlaced @event, EventContext context) =>
          await orders.Find(order => order.OrderNumber == @event.OrderNumber).FirstOrDefaultAsync();
  }

[EventType]
  public record Chr0032OrderPlaced(string OrderNumber);

public record Chr0032Order(string OrderNumber);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

A reactor should express intent, not reach into the persistence layer. Injecting `IMongoCollection<T>` ties the reactor to a specific sink (the MongoDB collection backing a read model) and lets it read or write documents directly — outside the projection pipeline that owns that state. The reactor then depends on storage-layer details and can observe or corrupt read-model state that Chronicle is responsible for building.

When a reactor needs current state, it reads it through the read-model abstraction: declare a read-model parameter on the handler, or call `IReadModels.GetInstanceById`. Either way Chronicle resolves it from the materialized store, or computes it from the events when the read model is `[Passive]` — mark it passive when the reactor needs the state to be strongly consistent for the event being handled. The read model stays the single source of derived state, and the reactor stays decoupled from where that state is persisted.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0031: Reactor must not have mutable state](/chronicle/code-analysis/chr0031/) — reactors must be stateless.
* **CHR0022** — a reactor handler returning side-effect events must be marked `[OnceOnly]`.

# CHR0034: [PII] cannot be applied to an EventSourceId<T>

## Rule Description

[Section titled “Rule Description”](#rule-description)

A property or record parameter whose type derives from `EventSourceId<T>` is marked with `[PII]`. The event source id is the identity Chronicle uses to look up the encryption key for a subject, so it cannot itself be encrypted. Applying `[PII]` to it throws `PIINotSupportedOnEventSourceId` at runtime.

Remove the `[PII]` attribute. The id is already the compliance subject.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;

// Error CHR0034: 'CustomerId' is typed as 'CustomerId' (derives from EventSourceId<T>);
  // [PII] cannot be applied to an event source id — Chronicle throws
  // PIINotSupportedOnEventSourceId at runtime. Remove [PII].
  [EventType]
  public record CustomerRegistered([PII] Chr0034CustomerId CustomerId, string Name);

public record Chr0034CustomerId(Guid Value) : EventSourceId<Guid>(Value)
  {
      public static implicit operator Chr0034CustomerId(Guid value) => new(value);
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Chronicle encrypts `[PII]` values per subject, and the subject is resolved from the event source id. That makes the id the key-lookup identity for every other encrypted value on the event. If the id itself were encrypted, there would be nothing left to resolve the key by — a circular dependency Chronicle cannot satisfy, so it throws `PIINotSupportedOnEventSourceId`.

This analyzer turns that runtime failure into a compile-time error, caught the moment you write the attribute rather than the first time the event is appended.

If the identifier itself is sensitive, do not try to encrypt the id. Instead use a random `Guid`-backed surrogate as the event source id and store the sensitive value in a separate `[PII]` property, which Chronicle can encrypt under the surrogate subject.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0026: \[Key\] or \[Subject\] on an EventSourceId\<T> is redundant](/chronicle/code-analysis/chr0026/) — the id is already the key and the compliance subject.
* [Subject](/chronicle/concepts/subject/) — how the compliance subject is resolved.

# CHR0035: Read model declares a reserved compliance subject property

## Rule Description

[Section titled “Rule Description”](#rule-description)

A read model — a record or class marked with `[ReadModel]` — declares a property or record parameter named `_subject`, `__subject`, or `__subjects`. Chronicle reserves these fields in stored read model documents for internal compliance-subject tracking, so a same-named property silently collides with them.

Rename the property.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Arc.Queries.ModelBound;

// Error CHR0035: Read model 'Customer' declares a property named '_subject', which
  // Chronicle reserves as an internal MongoDB field. Rename it.
  [ReadModel]
  public record Customer(Guid Id, string Name, string _subject);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Every managed read-model document carries an internal `__subject` field that Chronicle uses as the default identity its `[PII]` values are encrypted under and erased by. A document composed from several subjects can also carry `__subjects`, which maps individual properties to their owners. These fields are infrastructure, not part of your model. `_subject` remains reserved for compatibility with earlier stored shapes.

A read-model property with any reserved name maps to the same document field, so your value and Chronicle’s internal tracking value fight over one slot. The projected value can overwrite the tracking value or read back as Chronicle’s, and after a right-to-erasure key deletion the behavior is undefined. Because the collision is by name in the persisted document, nothing surfaces at compile time without this rule — it just misbehaves at runtime.

Rename the property to anything else (for example `Subject`, without the leading underscore, if you genuinely need to expose the subject).

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [Subject](/chronicle/concepts/subject/) — how the compliance subject is resolved and tracked.
* [CHR0034: \[PII\] cannot be applied to an EventSourceId\<T>](/chronicle/code-analysis/chr0034/) — the id is the compliance subject.

# CHR0036: Reducer must not have mutable state

## Rule Description

[Section titled “Rule Description”](#rule-description)

A class implementing `IReducerFor<T>` declares mutable instance state — a non-`readonly` field or a settable (non-`init`) property — or injects a storage primitive such as `IMongoCollection<T>` through its constructor. Reducers fold events into read-model state and Chronicle re-creates and replays them, so they must be stateless and deterministic.

Keep the reducer stateless: express dependencies as `readonly`, primary-constructor-injected fields, read keyed state through an injected read model or `IReadModels.GetInstanceById`, and derive everything else from the current state and the event.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

// Warning CHR0036: Reducer 'Chr0036BalanceReducer' declares mutable state '_runningTotal'.
  // Reducers must be stateless for deterministic replay.
  public class Chr0036BalanceReducer : IReducerFor<Chr0036Balance>
  {
      decimal _runningTotal;

public Chr0036Balance Reduce(Chr0036AmountDeposited @event, Chr0036Balance? current)
      {
          _runningTotal += @event.Amount;
          return new(_runningTotal);
      }
  }

[EventType]
  public record Chr0036AmountDeposited(decimal Amount);

public record Chr0036Balance(decimal Total);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

A reducer is a pure function of `(current state, event) → next state`. Chronicle drives that function by replaying the event stream — during initial projection, after a rewind, on recovery, or when rebuilding a read model — and a single event source may be folded more than once.

Mutable instance state breaks that contract. A running total accumulated in a field is wrong the moment the stream replays, and a value can bleed from one event source into the next when the instance is reused. Everything the next state depends on is already available: the `current` state parameter (the fold’s accumulator, which Chronicle persists between events) and the event being handled. Anything derived should be computed from those inputs each time, not stored on the instance.

Injecting a storage primitive like `IMongoCollection<T>` is the same failure from the other side: it lets the reducer read or write the sink directly, outside the deterministic fold, coupling it to where state is persisted. Read state through the read-model abstraction instead.

This rule mirrors [CHR0031](/chronicle/code-analysis/chr0031/) and [CHR0032](/chronicle/code-analysis/chr0032/) for reactors — reducers carry the identical statelessness requirement.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0031: Reactor must not have mutable state](/chronicle/code-analysis/chr0031/) — the same requirement for reactors.
* [CHR0032: Reactor must not access storage directly](/chronicle/code-analysis/chr0032/) — read state through a read model, not a sink.

# CHR0037: Event type migration generations must belong to one event type

## Rule Description

[Section titled “Rule Description”](#rule-description)

A class deriving from `EventTypeMigration<TUpgrade, TPrevious>` references two event type generations that don’t resolve to the same event type id. Chronicle keys generations of the same event by their event type id, so both generations must resolve to the same id and differ only by their generation number.

This is checked for both ways of declaring a previous generation:

* **`[EventTypeGenerationFor<T>]`** (recommended) — the rule verifies that `T` really is the migration’s `TUpgrade`. Referencing any other type here is always a mistake: the migration would upcast a generation that doesn’t belong to the event type it claims to.
* **`[EventType]` on both generations** (the older, explicit-id style) — the rule verifies both ids are present and identical. An absent id (silently defaulting to the CLR type name) or a mismatched id makes Chronicle treat the two records as unrelated event types.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

// Warning CHR0037: Event type generations 'Chr0037ViolationCustomerRegisteredV2' and
  // 'Chr0037ViolationCustomerRegisteredV1' referenced by migration
  // 'Chr0037ViolationCustomerRegisteredMigration' must resolve to the same event type
  // and differ only by generation.
  [EventType("Customer.Registered", generation: 1)]
  public record Chr0037ViolationCustomerRegisteredV1(string Name);

[EventType("Customer.Renamed", generation: 2)]
  public record Chr0037ViolationCustomerRegisteredV2(string FirstName, string LastName);

public class Chr0037ViolationCustomerRegisteredMigration
      : EventTypeMigration<Chr0037ViolationCustomerRegisteredV2, Chr0037ViolationCustomerRegisteredV1>
  {
      public override void Upcast(IEventMigrationBuilder<Chr0037ViolationCustomerRegisteredV2, Chr0037ViolationCustomerRegisteredV1> builder) { }
      public override void Downcast(IEventMigrationBuilder<Chr0037ViolationCustomerRegisteredV1, Chr0037ViolationCustomerRegisteredV2> builder) { }
  }
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("Customer.Renamed", generation: 2)]
  public record Chr0037FixCustomerRegisteredV2(string FirstName, string LastName);

[EventTypeGenerationFor<Chr0037FixCustomerRegisteredV2>(1)]
  public record Chr0037FixCustomerRegisteredV1(string Name);

public class Chr0037FixCustomerRegisteredMigration
      : EventTypeMigration<Chr0037FixCustomerRegisteredV2, Chr0037FixCustomerRegisteredV1>
  {
      public override void Upcast(IEventMigrationBuilder<Chr0037FixCustomerRegisteredV2, Chr0037FixCustomerRegisteredV1> builder) { }
      public override void Downcast(IEventMigrationBuilder<Chr0037FixCustomerRegisteredV1, Chr0037FixCustomerRegisteredV2> builder) { }
  }
  ```

## How To Fix It

[Section titled “How To Fix It”](#how-to-fix-it)

* **Preferred:** mark the previous generation with `[EventTypeGenerationFor<TUpgrade>(N)]` instead of giving it its own `[EventType]`. The id is then resolved from `TUpgrade` directly, so the two generations can never drift apart.
* **If you keep the `[EventType]`-on-both style:** give both generations the exact same explicit id string, and vary only `generation:`.

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

When an event’s schema changes after events of the old shape are already stored, you add a new generation of the same event type and an `EventTypeMigration<TUpgrade, TPrevious>` that upcasts the stored events into the new shape. Chronicle recognizes the two records as generations of *one* event type by a shared event type id — not by their C# type names.

If the two generations resolve to different ids, the migration never applies: stored events of the previous generation are never upcast, and consumers read the old shape. Because both records compile and the migration is discovered by convention, nothing surfaces the mistake without this rule — and the same mismatch is caught again, one layer later and much louder, by `MigrationGenerationsMustShareEventTypeId` thrown from the migration’s constructor at runtime.

`[EventTypeGenerationFor<T>]` was added specifically to make this class of mistake structurally impossible: with no independent id to type on the previous generation, there is nothing left to mismatch. This rule keeps checking the older style for callers who haven’t migrated to it yet, and additionally verifies that `[EventTypeGenerationFor<T>]` points at the right type — see [CHR0049](/chronicle/code-analysis/chr0049/) for what happens when it doesn’t point at an event type at all.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0049](/chronicle/code-analysis/chr0049/): `[EventTypeGenerationFor<T>]` must reference a type marked with `[EventType]`.
* [CHR0021](/chronicle/code-analysis/chr0021/): Event types should be record types — event types are immutable records.

# CHR0039: Assertion result is discarded and can never fail

## Rule Description

[Section titled “Rule Description”](#rule-description)

The event-sequence assertions in `Cratis.Chronicle.Testing` — `ShouldHaveAppendedEvent<T>(...)` and `ShouldHaveTailSequenceNumber(...)`, in every overload — return a `Task`. They signal failure by throwing an `EventSequenceAssertionException` on that `Task`. The kernel-backed integration assertions in `Cratis.Chronicle.XUnit.Integration.Events` — `ShouldHaveAppendedEvent<T>(...)`, `ShouldHaveNextSequenceNumber(...)` and `ShouldHaveTailSequenceNumber(...)` — work the same way.

Call one from a `void`-bodied fact and the awaitable is discarded, so the exception is never observed. The assertion becomes a no-op that passes no matter what the system under test does.

Await the assertion and declare the containing member `async Task`, or return the `Task` so the test runner awaits it.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Testing.EventSequences;
  using Xunit;

[EventType]
  public record Chr0039AuthorRegistered(string Name);

public class Chr0039WhenRegisteringAnAuthor
  {
      readonly IEventLog _eventLog = default!;

// Warning CHR0039: 'ShouldHaveAppendedEvent' returns an awaitable that is never awaited, so the
      // assertion can never fail. The fact is 'void', so the compiler's own CS4014 stays silent —
      // this spec passes even though no Chr0039AuthorRegistered carries that name.
      [Fact]
      void should_have_appended_the_event() =>
          _eventLog.ShouldHaveAppendedEvent<Chr0039AuthorRegistered>(e => e.Name == "Jane Austen");

// Warning CHR0039: the same trap in a block body.
      [Fact]
      void should_have_appended_exactly_one_event()
      {
          _eventLog.ShouldHaveTailSequenceNumber(EventSequenceNumber.First);
      }
  }
  ```

The fix:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Testing.EventSequences;
  using Xunit;

[EventType]
  public record Chr0039AuthorRegisteredFixed(string Name);

public class Chr0039WhenRegisteringAnAuthorFixed
  {
      readonly IEventLog _eventLog = default!;

// Declaring the fact 'async Task' and awaiting the assertion makes the exception it throws
      // observable, so the assertion can actually fail.
      [Fact]
      async Task should_have_appended_the_event() =>
          await _eventLog.ShouldHaveAppendedEvent<Chr0039AuthorRegisteredFixed>(e => e.Name == "Jane Austen");

// Returning the Task works too — the test runner awaits it.
      [Fact]
      Task should_have_appended_exactly_one_event() =>
          _eventLog.ShouldHaveTailSequenceNumber(EventSequenceNumber.First);
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

The compiler already has a rule for a discarded `Task` — CS4014 — but it fires **only inside an `async` method**. A `void`-bodied fact is the natural and dominant shape of a spec, and it is exactly the shape where CS4014 says nothing. A zero-warning build is therefore blind to it.

What makes this a genuine trap rather than ordinary async carelessness is that the *sibling* assertions on the same surface are synchronous and `void`:

* `ShouldBeSuccessful()`
* `ShouldHaveValidationErrors()`
* `ShouldHaveConstraintViolation()` / `ShouldNotHaveConstraintViolation()`
* `ShouldHaveConcurrencyViolations()`

Discarding “the result” of those is exactly how they are meant to be used. Nothing at the call site signals that the event-sequence assertions behave differently, so the two shapes sit side by side in the same file and only one of them works.

The failure mode is the worst one a test suite has: an assertion that appears to test something and tests nothing. The resulting false confidence survives review, CI, and time — and it hides real defects, because the assertion that would have caught a regression silently passes instead.

The rule is scoped to `Should*` methods on the Cratis testing surfaces — namespaces under `Cratis.` containing a `.Testing.` or `.XUnit.` segment — that return `Task`, `Task<T>`, `ValueTask` or `ValueTask<T>`, and only where the result is genuinely discarded: a statement on its own line, or the expression body of a `void` member. Awaiting, returning, assigning, or passing the awaitable along all count as observing it and are not flagged, and a `Should*` API outside those namespaces is never flagged.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [Writing specs](/chronicle/testing/) — the testing surfaces this rule covers.

# CHR0040: Several [SetFromContext] for the same event type on one member

## Rule Description

[Section titled “Rule Description”](#rule-description)

One read model member carries more than one `[SetFromContext<TEvent>]` for the *same* event type. They write the same property in the projection definition, so only the last declared is kept — the earlier capture is silently discarded, with no build, registration, or runtime signal.

Allowing multiple `[SetFromContext]` on one member is deliberate and load-bearing: a property capturing context from several *different* event types is exactly what the attribute is for, and that use never triggers this rule. Two for the same event type is different — a single value cannot hold two context values under any configuration, naming policy, or event shape.

Keep the capture that was intended, or move the other onto its own property.

Every spelling of “one member” is covered. On a positional record the constructor parameter and the property generated from it are two distinct symbols — `[property:]` is the only way to reach the second — and both write the same key into the same event type’s definition. A duplicate split across the two spellings is reported exactly as one placed twice on a single symbol.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record Chr0040OrderPlaced(decimal Amount);

// Warning CHR0040: 'PlacedAt' carries more than one [SetFromContext<Chr0040OrderPlaced>],
  // and they map to the same property - only the last declared is kept. The CorrelationId
  // capture is silently dropped: a single member cannot hold both context values. Move it
  // onto its own property instead.
  [FromEvent<Chr0040OrderPlaced>]
  public record Chr0040Order(
      [Key] Guid Id,
      decimal Amount,
      [SetFromContext<Chr0040OrderPlaced>(nameof(EventContext.CorrelationId))]
      [SetFromContext<Chr0040OrderPlaced>(nameof(EventContext.Occurred))]
      DateTimeOffset PlacedAt);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

The failure is maximally quiet. The property *is* populated — with the other context value — so nothing is null, nothing throws, and a spec asserting the property has a value stays green. It reads as a projection written wrong, and the natural way to debug it — re-reading the attributes and finding both present and correctly spelled — confirms the wrong conclusion.

This is a warning where the neighboring AutoMap collision rule ([CHR0025](/chronicle/code-analysis/chr0025/)) deliberately only informs, and the difference is the point: that collision has two legitimate resolutions and only the author knows which was meant, while here there is no second reading to defer to.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0025: Explicitly sourced read model property may be overwritten by AutoMap](/chronicle/code-analysis/chr0025/) — the sibling collision that *is* sometimes intended, and is therefore only informational.
* [CHR0042: A joined property is also written locally](/chronicle/code-analysis/chr0042/) — another shape where two writes to one property silently resolve to one winner.

# CHR0041: Event filter attribute on a projection has no effect

## Rule Description

[Section titled “Rule Description”](#rule-description)

An event-metadata filter attribute — `[EventStreamType]`, `[EventSourceType]`, or `[FilterEventsByTag]` — is applied to a projection, where it does nothing. A projection observes *every* event of the types its definition declares; there is no field for a metadata filter anywhere in a projection’s definition, so no client can express one and no kernel could honor it.

Filtering observed events on metadata is what reactors and reducers do — see [appended event metadata filters](/chronicle/events/filtering/). To narrow a projection, narrow the event types it declares, or pair it with a reactor or reducer that owns the filtered subset.

Both projection spellings are covered: a model-bound `[ReadModel]` carrying projection attributes, and a fluent `IProjectionFor<T>`.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record Chr0041TemperatureRead(double Degrees);

// Warning CHR0041: '[FilterEventsByTag]' on projection 'Chr0041LatestTemperature' has no
  // effect - a projection observes every event of the types it declares and cannot filter
  // on event metadata. Readings from every sensor land in this read model, not just sensor-a's.
  [FilterEventsByTag("sensor-a")]
  [FromEvent<Chr0041TemperatureRead>]
  public record Chr0041LatestTemperature(
      [Key] Guid Id,
      double Degrees);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

The filter attributes’ own documentation used to say a projection could filter, and that is what an IDE tooltip shows at the moment of authoring. A developer who trusts it designs a filtered projection that silently observes everything — no build error, no startup failure, no runtime signal, just a read model carrying values from streams it was never meant to see. The natural way to debug that — re-reading the attribute to confirm it is present and spelled right — confirms the wrong conclusion.

Correcting the documentation helps the reader who reads it; this rule helps the one who does not.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0045: Event stream metadata attribute on an event type has no effect](/chronicle/code-analysis/chr0045/) — the same attributes on the other placement that reads as stream identity and is not one.
* [CHR0024: Read model property has no mapping source](/chronicle/code-analysis/chr0024/) — another declaration that looks wired but silently does nothing.
* [CHR0028: Redundant .AutoMap() call](/chronicle/code-analysis/chr0028/) — another call with no effect, though there the surprise is harmless.

# CHR0042: A joined property is also written locally

## Rule Description

[Section titled “Rule Description”](#rule-description)

A read model property is written by both a local mapping and a join. The joined value always wins — a local write cannot reset the property, in whichever order the events arrive.

A projection re-resolves its joins every time it handles one of the read model’s own events and applies the joined properties *after* the local mappings. A property written from both sides therefore always ends up with the joined value once the joined stream has an event to pull from — see [join precedence](/chronicle/projections/model-bound/joins/#join-precedence).

The trap this catches is the latch: a `bool` that a local event sets and a joined event clears. The shape compiles and reads correctly, but re-setting the flag locally is silently overwritten the next time any local event is handled — a permanent, errorless wrong value. If the property must reflect whichever fact happened most recently, give each fact its own property (for example, two timestamps) and compare them instead.

Both spellings are covered: a model-bound member carrying both a local-write attribute (`[SetFrom<T>]`, `[SetValue<T>]`, `[SetFromContext<T>]`, an aggregate) and a `[Join<T>]`, and a fluent `From<T>` block whose `.Set(...)` property is also set explicitly by a sibling `.Join<T>(...)` in the same projection. Collisions caused by AutoMap rather than an explicit mapping are reported by [CHR0025](/chronicle/code-analysis/chr0025/) instead.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record Chr0042SideReleasedForSigning(Guid RequestId);

[EventType]
  public record Chr0042RequestLost(bool IsContractRoundLive);

// Warning CHR0042: Property 'IsContractRoundLive' is written both locally by
  // [SetValue<Chr0042SideReleasedForSigning>] and by the join with 'Chr0042RequestLost'.
  // The re-release writes true, but the join re-applies false on top — the latch
  // silently sticks and the row is withheld forever.
  [FromEvent<Chr0042SideReleasedForSigning>]
  public record Chr0042ContractSide(
      [Key] Guid Id,
      Guid RequestId,
      [SetValue<Chr0042SideReleasedForSigning>(true)]
      [Join<Chr0042RequestLost>(on: "RequestId")]
      bool IsContractRoundLive);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

The precedence itself is by design: a joined property is a mirror of the joined stream, and re-applying it is what keeps denormalized values (a name, a price) fresh — and what backfills them when the read model is created after the joined event already happened. When you combine a join with a local write *deliberately* — seed the value locally, let the join keep it fresh — the behavior is exactly what you want; suppress this diagnostic at the site to record that intent.

What the rule exists for is the other reading of the same code: expecting the two writes to merge in stream order. Nothing fails when they don’t — the read model just quietly holds the joined value — and on a surface built to catch missing work, a stuck latch means rows are withheld forever with no error and no log line. This rule turns that silent wrong value into a visible decision at compile time.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0025: Explicitly sourced read model property may be overwritten by AutoMap](/chronicle/code-analysis/chr0025/) — the same collision when AutoMap, not an explicit mapping, is what writes on top.

# CHR0043: Key redirection carries a [PII] value across the compliance subject

## Rule Description

[Section titled “Rule Description”](#rule-description)

A projection redirects the resolved document key and carries a `[PII]` value onto that document.

A read model document holds exactly one stored compliance subject. The kernel uses an explicit persisted event subject when it differs from the event source id; otherwise it uses the resolved document key. A root `UsingKey`, `UsingKeyFromContext`, composite key, or constant key changes that document key. In a child scope, `UsingKey` only identifies the child; `UsingParentKey`, `UsingParentKeyFromContext`, a parent composite key, or a constant parent key routes the containing document. The model-bound equivalents are `[FromEvent]` and `[ChildrenFrom]`.

Declaring `[Subject]` on the event type is not a suppression. Its runtime value can be null or empty, append metadata can override it, and already-stored historical events retain the subject metadata they were appended with. `EventSourceId` selects the stream; it is the default subject only when no different explicit subject was persisted. The analyzer recognizes the fluent controls that key directly from `EventContext.Subject` or `EventContext.EventSourceId`, because either choice stays aligned with the kernel’s explicit-subject-or-resolved-key rule.

PII reach is recursive. A mapped event member counts when `[PII]` occurs directly, on its type, in an inherited member, or inside a nested value object, array, or collection element. The fluent analyzer follows the real public mapping surface: nested expression paths, Set/To, Add/Subtract, AddChild, SetThisValue, `PropertyPath` Set/To, and the final AutoMap state.

Nothing has to fail at read time. The cost can remain hidden as erasure reach: crypto-shredding the owner’s key does not touch a copy resting under a different subject, so the value survives an erasure that reports success.

Keep the personal value on a read model keyed and subjected by its owner, or resolve it at the query edge under the owner-scoped read model. Do not move it onto a request-, case-, tenant-, or other subject’s document merely to make a query convenient.

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using System;
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections;

[EventType]
  public record Chr0043AdvisorNamed(Guid RequestId, [property: PII] string FullName);

public record Chr0043RequestSummary([property: Key] Guid Id, string AdvisorName);

public class Chr0043RequestSummaryProjection : IProjectionFor<Chr0043RequestSummary>
  {
      public void Define(IProjectionBuilderFor<Chr0043RequestSummary> builder) => builder
          .From<Chr0043AdvisorNamed>(_ => _
              // Warning CHR0043: the resolved document is routed through RequestId while
              // FullName belongs to the persisted event subject, which may be another identity.
              .UsingKey(e => e.RequestId)
              .Set(m => m.AdvisorName).To(e => e.FullName));
  }
  ```

## Existing Stored Documents

[Section titled “Existing Stored Documents”](#existing-stored-documents)

Fixing the projection prevents future wrong-subject materialization; it does not remove or re-encrypt copies already stored under the wrong subject. Before claiming erasure coverage, replace the affected read-model storage by dropping and rebuilding the projection into a clean container, rebuilding into a new container and switching readers, or performing an audited migration that proves the owner of every personal value and rewrites or removes each wrong-subject document. Replaying corrected code over the existing container is not sufficient evidence that stale copies are gone.

## Severity

[Section titled “Severity”](#severity)

The default severity is **warning**. This is a rollout signal, not a compatibility guarantee or an erasure grace period: repositories that treat warnings as errors can fail immediately, and affected persisted read models still require the cleanup above. Any later promotion to error is a separate compatibility decision; suppressing or retaining warning severity does not make the storage shape safe.

## Suppressing

[Section titled “Suppressing”](#suppressing)

Suppress with `#pragma warning disable CHR0043` around the declaration, or set `dotnet_diagnostic.CHR0043.severity = none` in `.editorconfig`. Suppressing leaves the value outside its owner’s erasure — the defect is not decryptability, so nothing at runtime will report it.

# CHR0045: Event stream metadata attribute on an event type has no effect

## Rule Description

[Section titled “Rule Description”](#rule-description)

`[EventStreamType]` or `[EventSourceType]` is applied to a type marked with `[EventType]`, where it does nothing. An append resolves its event source type and event stream type from the arguments it is given — the appending command’s metadata, the reactor’s, or the explicit parameters — never from the CLR type of the event being appended. Nothing reads either attribute off an event type, so the value is not transmitted, never reaches the appended event’s context, and narrows nothing on the way back out.

Three placements work, and none of them is affected by this rule:

* A **command**, where both values tag the events its append produces and, with `concurrency: true`, join the server-side concurrency scope.
* An **observer** — a reactor or a reducer — where both values narrow which appended events are dispatched. See [appended event metadata filters](/chronicle/events/filtering/).
* An **aggregate root**, where `[EventStreamType]` becomes the event stream type of every event that aggregate appends. Without the attribute the aggregate’s own type name is used, so deleting it does not error — it silently moves every subsequent append to a different stream type. (`[EventSourceType]` is *not* read off an aggregate root; the event source type is supplied when the aggregate is fetched.)

A type is allowed to be more than one thing. A `[Command]`, reactor, reducer, or aggregate root that *also* carries `[EventType]` is not reported, because the attribute is live on it — it is read off that very type.

A **projection** is a placement that does nothing, reported separately as [CHR0041](/chronicle/code-analysis/chr0041/).

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Arc.Commands.ModelBound;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

// Warning CHR0045: 'EventStreamTypeAttribute' on event type 'Chr0045AccountOpened' has no
  // effect - an append resolves its stream metadata from the append itself, never from the
  // event's type. Every append of this event still lands under the default stream type, and a
  // reactor filtering on "onboarding" observes none of them.
  [EventStreamType("onboarding")]
  [EventType]
  public record Chr0045AccountOpened(string Name);

// The command that appends the event is a placement that works - here the value tags the
  // appended events and, with concurrency, joins the server-side concurrency scope.
  [EventStreamType("onboarding", concurrency: true)]
  [Command]
  public record Chr0045OpenAccount(string Name)
  {
      public Chr0045AccountOpened Handle() => new(Name);
  }

// The observer is another - here the value narrows which appended events are dispatched. An
  // aggregate root is the third: [EventStreamType] there becomes the stream type of every event
  // the aggregate appends, and the aggregate's type name is used when it is absent.
  [EventStreamType("onboarding")]
  public class Chr0045AccountNotifier : IReactor
  {
      public Task AccountOpened(Chr0045AccountOpened @event) => Task.CompletedTask;
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

The attributes’ own documentation used to say an event type was a valid placement, and that is what an IDE tooltip shows at the moment of authoring. A developer who trusts it tags the event once at its declaration and expects every append of it to carry that stream identity. What happens instead is that events land under the default source and stream type, observers that filter on those values match nothing, and there is no build error, startup failure, or runtime signal anywhere to say why. The natural way to debug that — re-reading the attribute to confirm it is present and spelled right — confirms the wrong conclusion.

The placement is refused rather than honored, and deliberately so. Both values are persisted in every appended event’s context and are load-bearing keys for the concurrency scope and for observer filtering. Letting an event’s CLR type contribute them would retroactively change stream identity for every event type already declared, against events already written.

The same reasoning is why the rule keys on the *role* of the type rather than on the mere presence of `[EventType]`. Where the attribute is read — a command, an observer, an aggregate root — removing it changes real behavior, so a warning that says “move it” there would be advice with nowhere to go, and under warnings-as-errors it would break the build outright.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0041: Event filter attribute on a projection has no effect](/chronicle/code-analysis/chr0041/) — the same attributes on the other placement that reads as a filter and is not one.
* [CHR0024: Read model property has no mapping source](/chronicle/code-analysis/chr0024/) — another declaration that looks wired but silently does nothing.

# CHR0046: Passive read model redirects the document key away from the event's own stream

## Rule Description

[Section titled “Rule Description”](#rule-description)

A read model is **passive** — declared with `[Passive]`, or with `.Passive()` on the projection builder — *and* its projection redirects the **root** document key with `UsingKey`, `UsingKeyFromContext`, `UsingCompositeKey`, `UsingConstantKey`, or model-bound `[FromEvent(key:)]`.

A passive read model has no sink. Nothing writes its documents ahead of a read, so the kernel answers a read by replaying the event sequence with the cursor constrained to `eventSourceId = ReadModelKey` — exactly one physical event stream. A top-level key redirection is routing metadata for a materialized write; it is not a lookup index over the event log, and it cannot make a replay find events that live on another stream.

So if the events were appended to `user-1` and the projection re-keys the document by `Hash`, a passive read by `Hash` replays the `Hash` stream, reaches no events, and returns a **default-initialized** model. Registration succeeds, and a `ReadModelScenario<T>` that appends and reads in one namespace still passes.

Shapes that are **not** reported:

* The same redirection on a read model that keeps its sink — an observer materializes the redirected document, and the read is answered from storage.
* `UsingKeyFromContext(c => c.EventSourceId)`, which restates the identity the replay already walks.
* A child or parent key — `UsingParentKey`, or `UsingKey` inside `Children`/`AddChild` — which identifies a child inside a document the replay does reach.
* A reducer-backed passive read model, which declares no projection and therefore no document key.

## Severity

[Section titled “Severity”](#severity)

Warning

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections;
  using Cratis.Chronicle.ReadModels;

[EventType]
  public record Chr0046UserSignedUp(string Hash, string Region);

// Warning CHR0046: 'UsingKey' keys the 'Chr0046UserByHash' document by 'Hash', but
  // 'Chr0046UserByHash' is passive. The events were appended to the user's own stream, so a read
  // by hash replays the hash stream, reaches nothing, and hands back a default-initialized model.
  [Passive]
  public record Chr0046UserByHash(
      [Key] string Id,
      string Region);

public class Chr0046UserByHashProjection : IProjectionFor<Chr0046UserByHash>
  {
      public void Define(IProjectionBuilderFor<Chr0046UserByHash> builder) => builder
          .From<Chr0046UserSignedUp>(_ => _
              .UsingKey(e => e.Hash)
              .Set(m => m.Region).To(e => e.Region));
  }

// The same redirection on a read model that keeps its sink is not reported: an observer
  // materializes the redirected document, and the read is answered from storage.
  public record Chr0046UserByHashMaterialized(
      [Key] string Id,
      string Region);

public class Chr0046UserByHashMaterializedProjection : IProjectionFor<Chr0046UserByHashMaterialized>
  {
      public void Define(IProjectionBuilderFor<Chr0046UserByHashMaterialized> builder) => builder
          .From<Chr0046UserSignedUp>(_ => _
              .UsingKey(e => e.Hash)
              .Set(m => m.Region).To(e => e.Region));
  }
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

Nothing fails. The projection registers, the read returns an object rather than throwing or returning “not found”, and the only symptom is that every field holds its default. A developer reading that model back sees an empty region and an empty name, and the natural first suspicion is the projection’s mappings — which are correct. The declaration that actually caused it, `[Passive]`, sits on the read model and looks unrelated to the key.

The documentation now states the limitation where a reader looking up single-instance reads will meet it: replay walks one event source, so it cannot reconstruct state built from events belonging to a different key. That is an explanation after the fact. This rule is the part that catches it before the model ships.

It is a warning rather than an error for its first release. A consumer may knowingly accept a passive read model that only ever answers for the redirected stream — for instance where the redirected key *is* the event source id for every append in practice — and a new error would break those builds outright under warnings-as-errors.

The rule under-reports rather than guessing. `UsingKeyFromContext(c => c.Subject)` is left alone even though a subject can differ from the event source id, on the same reasoning recorded for [CHR0043](/chronicle/code-analysis/chr0043/): source declarations cannot prove what append metadata put in the context.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0043: Key redirection carries a \[PII\] value across the compliance subject](/chronicle/code-analysis/chr0043/) — the same set of key redirections, read for a compliance defect instead of a reachability one.
* [CHR0024: Read model property has no mapping source](/chronicle/code-analysis/chr0024/) — another declaration that registers cleanly and leaves the model empty.

# CHR0047: A clear declaration is never applied by projection construction (retired)

## Rule Description

[Section titled “Rule Description”](#rule-description)

**This rule has been retired and no longer reports anything.** It warned that two declarations looked like a clear, compiled, registered, and did nothing:

* `[SetValue<TEvent>(null)]`, which projection construction dropped where the set-value mappings were built.
* `[ClearWith<TEvent>]` on a property or a parameter, which only the class-level form on a nested type was ever read from.

Both are a working [scalar clear](/chronicle/projections/model-bound/clearing/) now: they write the member back to no value every time the event is observed, replay included. Every reading of the rule became false, so it was removed rather than narrowed.

The identifier stays reserved and will never be reused. Anyone who suppressed `CHR0047` did so to accept a clear that did nothing; carrying that suppression silently onto a different rule would hide something they never agreed to.

## Severity

[Section titled “Severity”](#severity)

None — the rule is no longer reported.

## What To Do Instead

[Section titled “What To Do Instead”](#what-to-do-instead)

Nothing. If you suppressed `CHR0047` — with `#pragma warning disable`, a `NoWarn`, or an `.editorconfig` entry — remove the suppression: the declaration it covered now does what it says.

One shape still has no correct reading, and [CHR0048](/chronicle/code-analysis/chr0048/) reports it: clearing a member that cannot hold null. Declare the member as nullable, or set the value you actually want with `[SetValue<TEvent>(...)]`.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0048: A clear is declared for a member that cannot hold null](/chronicle/code-analysis/chr0048/) — the rule that took over the shapes that are still wrong.
* [CHR0024: Read model property has no mapping source](/chronicle/code-analysis/chr0024/) — a null `[SetValue]` no longer suppresses it, because a clear is not a mapping source.

# CHR0048: A clear is declared for a member that cannot hold null

## Rule Description

[Section titled “Rule Description”](#rule-description)

Clearing a read model member means returning it to *no value*. A member declared non-nullable has no such state, so the declaration has nothing correct to write.

The rule fires on every spelling of a clear — the model-bound `[ClearWith<TEvent>]` on a member and `[SetValue<TEvent>(null)]`, and the fluent `.Clear(...)` and `.Set(...).ToValue(null)` — when the member cannot hold null:

* a reference type declared non-nullable in a nullable-aware context (`string`, not `string?`);
* any value type that is not `Nullable<T>` (`int`, `DateTimeOffset`, an enum, a `ConceptAs<T>` struct).

A reference type in a file that has opted out of nullable analysis is *oblivious* rather than non-null. That promises nothing, so it is left alone — and the projection builder makes the same call at runtime.

Not reported: a class-level `[ClearWith]` on a nested type, or one on the member holding it. Those clear a whole nested object, which is nullable by construction.

## Severity

[Section titled “Severity”](#severity)

Warning — **scheduled to become an error in the next major release.**

Warning rather than error for its first release, following the precedent recorded on the retired [CHR0047](/chronicle/code-analysis/chr0047/): these analyzers ship inside the `Cratis.Chronicle` package, so under `TreatWarningsAsErrors` — the Cratis default — a new warning already breaks a consumer build on upgrade. An error is a strictly stronger break and buys little, because the declaration it reports never worked in the first place.

The declaration has no correct reading, so the escalation to an error is announced here rather than sprung later. Treat this warning as a build failure in waiting, and note that it is the *softer* of the two signals: building the projection refuses the declaration outright (see below), so leaving the warning unaddressed fails at application startup instead of at build time.

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record Chr0048SliceCommandCleared();

[EventType]
  public record Chr0048SliceCommandSet(string Command, int Attempts);

public record Chr0048Slice(
      [Key] string Id,

// Warning CHR0048: 'Command' is declared as a non-nullable string, so there is no value the clear
      // could write except the empty string - a different fact the read model cannot tell apart from a
      // real value. Declare it as string? to clear it, or say what you mean with [SetValue<T>("")].
      [SetFrom<Chr0048SliceCommandSet>(nameof(Chr0048SliceCommandSet.Command))]
      [ClearWith<Chr0048SliceCommandCleared>]
      string Command,

// Warning CHR0048: a value type cannot hold null whatever the nullable context says, and zero is a
      // count rather than the absence of one. Declare it as int? to clear it.
      [SetFrom<Chr0048SliceCommandSet>(nameof(Chr0048SliceCommandSet.Attempts))]
      [SetValue<Chr0048SliceCommandCleared>(null)]
      int Attempts);

// The declarations that are correct: both members can hold the value a clear writes, so both spellings
  // of the clear are accepted and the member really does go back to no value - replay included.
  public record Chr0048SliceFixed(
      [Key] string Id,

[SetFrom<Chr0048SliceCommandSet>(nameof(Chr0048SliceCommandSet.Command))]
      [ClearWith<Chr0048SliceCommandCleared>]
      string? Command,

[SetFrom<Chr0048SliceCommandSet>(nameof(Chr0048SliceCommandSet.Attempts))]
      [SetValue<Chr0048SliceCommandCleared>(null)]
      int? Attempts);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

The only value a projection could write to a non-nullable member is its type default — an empty string, a zero, `DateTimeOffset.MinValue`. That is a *different fact* from “not set”, and the read model cannot tell the two apart: a reader seeing `""` cannot know whether the value was cleared or genuinely empty.

Standing a type default in for “not set” is precisely the workaround the scalar clear exists to remove. Consumers used to invent type-specific sentinels because Chronicle had no clear; defining clear *as* the sentinel would ship the workaround under a name that promises something else. So the declaration is refused rather than reinterpreted.

No shipping code can depend on this declaration working. Until a scalar clear existed, `[ClearWith]` on a member and a null `[SetValue]` were both reported as inert by the retired [CHR0047](/chronicle/code-analysis/chr0047/) — the projection emitted no mapping at all for the member — and the fluent `ToValue(null)` silently wrote the four-character string `"null"`. There is no reading under which the declaration was what its author meant.

The same rule is enforced when the projection is built, where it throws `CannotClearNonNullableMember` — for the model-bound attributes and for the fluent `.Clear(...)` alike. That covers what the analyzer never sees — a read model from an assembly compiled without the Chronicle analyzers, or one whose diagnostic was suppressed — so the failure is loud at startup rather than a quiet type default in storage.

The rule could not be moved into the type system. C# cannot express “a nullable-annotated reference type” as a generic constraint: a non-nullable argument converts to a nullable parameter without complaint, so `Clear<TProperty>(Expression<Func<TReadModel, TProperty?>>)` accepts `m => m.NonNullableName` silently. Constraining to `struct` does refuse a non-nullable *value* type at compile time, but only that half, and it reports as `CS0411 — type arguments cannot be inferred`, which explains nothing about the actual problem. One rule that says what is wrong beats a compile error for half the cases and silence for the rest.

## How To Fix It

[Section titled “How To Fix It”](#how-to-fix-it)

Decide which fact you actually mean:

* **You mean “no value”.** Declare the member nullable — `string?`, `int?`, `DateTimeOffset?` — and keep the clear.
* **You mean a specific value.** Use `[SetValue<TEvent>("")]`, `[SetValue<TEvent>(0)]`, or whatever the value is. It says so in the declaration, and a reader of the read model can see it was set on purpose.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0047: A clear declaration is never applied by projection construction](/chronicle/code-analysis/chr0047/) — retired; this rule took over the shapes that are still wrong.
* [CHR0024: Read model property has no mapping source](/chronicle/code-analysis/chr0024/) — a member whose only declaration is a clear has no source and is still reported.

# CHR0049: [EventTypeGenerationFor<T>] must reference a type marked with [EventType]

## Rule Description

[Section titled “Rule Description”](#rule-description)

`[EventTypeGenerationFor<T>]` marks a record as a previous generation of the event type `T` represents. Chronicle resolves the shared event type id directly from `T`’s own `[EventType]` attribute — so `T` must carry `[EventType]` directly.

This is reported whenever `T`:

* has no `[EventType]` attribute at all, or
* is itself marked with `[EventTypeGenerationFor<T>]` instead — chaining generation markers is rejected for the same reason: there is still no `[EventType]` at the end of the chain to resolve an id from.

## Severity

[Section titled “Severity”](#severity)

Error

## Example

[Section titled “Example”](#example)

### Violation

[Section titled “Violation”](#violation)

* C#

```csharp
  using Cratis.Chronicle.Events;

public record Chr0049ViolationCustomerRegisteredV2(string FirstName, string LastName);

// Error CHR0049: 'Chr0049ViolationCustomerRegisteredV1' declares itself as a generation for
  // 'Chr0049ViolationCustomerRegisteredV2', but 'Chr0049ViolationCustomerRegisteredV2' is not
  // marked with [EventType].
  [EventTypeGenerationFor<Chr0049ViolationCustomerRegisteredV2>(1)]
  public record Chr0049ViolationCustomerRegisteredV1(string Name);
  ```

### Fix

[Section titled “Fix”](#fix)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType("customer-registered", generation: 2)]
  public record Chr0049FixCustomerRegisteredV2(string FirstName, string LastName);

[EventTypeGenerationFor<Chr0049FixCustomerRegisteredV2>(1)]
  public record Chr0049FixCustomerRegisteredV1(string Name);
  ```

## Why This Rule Exists

[Section titled “Why This Rule Exists”](#why-this-rule-exists)

`[EventTypeGenerationFor<T>]` exists so a previous-generation record never carries its own, independently-typed event type id — the id comes from `T` instead, so the two can never drift apart. That only works if `T` actually has an id to give: a type with no `[EventType]` attribute has none, and neither does a type that is itself only a generation marker.

Without this check, a record marked `[EventTypeGenerationFor<T>]` where `T` isn’t an event type compiles cleanly but fails only when the client connects to Chronicle, throwing `EventTypeGenerationReferencesNonEventType` at startup. This rule surfaces the same mistake at compile time instead.

The same analyzer class also reports **CHR0050** (`EventTypeGenerationForCannotCombineWithEventType`, Error) when a type carries both `[EventType]` and `[EventTypeGenerationFor<T>]` at once. A type is either the current generation or a previous one — never both — and combining them throws `EventTypeGenerationForCannotBeCombinedWithEventType` at runtime for the same reason this rule’s violation does: Chronicle can no longer tell which attribute owns the id.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0037](/chronicle/code-analysis/chr0037/): Event type migration generations must belong to one event type — validates that a migration’s `[EventTypeGenerationFor<T>]` points at the migration’s own upgrade type, once it already resolves to an event type.

# CRUD, EF Core, and Chronicle

> If you build apps with EF Core and think in tables, rows, and SaveChanges, here's how those ideas translate to Chronicle.

If your instinct is to add a table, map an entity, and call `SaveChanges()`, you already have useful muscle memory. This page maps the CRUD/EF Core model onto Chronicle so the differences are explicit.

## The mental shift in one sentence

[Section titled “The mental shift in one sentence”](#the-mental-shift-in-one-sentence)

In CRUD you **store the current state and overwrite it**; in Chronicle you **store what happened and derive the current state** from those facts. The current state still exists — it’s a [read model](/chronicle/read-models/) — you just build it from events instead of editing it in place.

## How the pieces map

[Section titled “How the pieces map”](#how-the-pieces-map)

| You know (CRUD / EF Core)    | In Chronicle                                                                                                  |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| A table / entity             | An [event source](/chronicle/concepts/event-source/) and its stream of events                                 |
| `INSERT` a row               | Append a “created” [event](/chronicle/concepts/event/)                                                        |
| `UPDATE` a column            | Append an event describing *what changed* (e.g. `AddressChanged`)                                             |
| `DELETE` a row               | Append a “removed/closed” event — history is never erased                                                     |
| `DbContext.SaveChanges()`    | `EventLog.Append(...)`                                                                                        |
| `SELECT` / LINQ query        | A query over a [read model](/chronicle/read-models/) built by a [projection](/chronicle/concepts/projection/) |
| A computed/denormalized view | A purpose-built read model — make as many as you need                                                         |
| `ALTER TABLE` / EF migration | [Event type migration](/chronicle/concepts/event-type-migrations/) + replay the projection                    |
| Optimistic concurrency token | Constraints and the event stream’s ordering                                                                   |

## What stays the same

[Section titled “What stays the same”](#what-stays-the-same)

* You still use C# records and dependency injection.
* You still query data and render it — the read side looks like querying a collection.
* You can still keep a relational/document database for the genuinely-CRUD parts of your app; Chronicle doesn’t demand all-or-nothing.

## What changes (and why)

[Section titled “What changes (and why)”](#what-changes-and-why)

* **You model verbs, not just nouns.** Instead of one mutable `Customer` row, you record `CustomerRegistered`, `AddressChanged`, `AccountClosed`. Each is an immutable fact. This is the part that feels new — and it’s where the value (audit, history, replay) comes from.
* **Reads are eventually consistent — by default.** A projection materializes the read model *after* the event is appended, so a stored read immediately after a write may lag by a moment. Usually fine; occasionally something to design around. When read-after-write matters, Chronicle can also compute a read model on demand with strong consistency — see [Read model consistency](/chronicle/read-models/consistency/).
* **You don’t write update statements.** A projection *declares* how events map onto a read model; Chronicle keeps it current. No `UPDATE`, no merge logic.
* **You don’t delete history.** “Delete” becomes an event. For real erasure obligations (GDPR), see [Compliance](/chronicle/compliance/).

## Side by side

[Section titled “Side by side”](#side-by-side)

CRUD: update a row, then read it back. This is illustrative EF Core pseudocode, not a compiled example:

```text
customer.Address = newAddress;
await db.SaveChangesAsync();
var current = await db.Customers.FindAsync(id);
```

Chronicle: the same change is a fact you append and a read side you declare. First, define the verbs as event types:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record CrudComparisonCustomerRegistered(string Name, string Address);

[EventType]
  public record CrudComparisonAddressChanged(string Address);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class CrudComparisonCustomerRegistered(val name: String, val address: String)

@EventType
  data class CrudComparisonAddressChanged(val address: String)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record CrudComparisonCustomerRegistered(String name, String address) {}

@EventType
  record CrudComparisonAddressChanged(String address) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.CrudComparisonCustomerRegistered do
    use Chronicle.Events.EventType, id: "crud-comparison-customer-registered"

defstruct [:name, :address]
  end

defmodule MyApp.Events.CrudComparisonAddressChanged do
    use Chronicle.Events.EventType, id: "crud-comparison-address-changed"

defstruct [:address]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class CrudComparisonCustomerRegistered {
      constructor(readonly name: string, readonly address: string) {}
  }

@eventType()
  class CrudComparisonAddressChanged {
      constructor(readonly address: string) {}
  }
  ```

Then declare the read side. This is the [projection](/chronicle/concepts/projection/) — and notice it is *not* a 1:1 copy of the CRUD `Customer` entity. It’s shaped for the screen that reads it, and it answers something the overwritten row never could:

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<CrudComparisonCustomerRegistered>]
  [FromEvent<CrudComparisonAddressChanged>]
  public record CrudComparisonCustomerCard(
      [Key] Guid Id,
      string Name,
      string Address,
      [Count<CrudComparisonAddressChanged>] int TimesRelocated);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.CrudComparisonCustomerCard do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{CrudComparisonCustomerRegistered, CrudComparisonAddressChanged}

defstruct id: nil, name: nil, address: nil, times_relocated: 0

from CrudComparisonCustomerRegistered,
      set: [id: :event_source_id, name: :name, address: :address]

from CrudComparisonAddressChanged,
      set: [address: :address],
      count: :times_relocated
  end
  ```

* TypeScript

```typescript
  import { count, fromEvent, Guid, readModel } from '@cratis/chronicle';

@readModel()
  @fromEvent(CrudComparisonCustomerRegistered)
  @fromEvent(CrudComparisonAddressChanged)
  class CrudComparisonCustomerCard {
      id: Guid = Guid.empty;
      name = '';
      address = '';

@count(CrudComparisonAddressChanged)
      timesRelocated = 0;
  }
  ```

`[FromEvent<T>]` (`@fromEvent` in TypeScript) maps event properties onto the record by name — the name arrives with `CustomerRegistered`, and the address is kept current by every `AddressChanged`. The counter tracks the moves. There is no `UPDATE` statement anywhere: Chronicle derives the card from the facts.

Now the write and the read-back:

* C#

```csharp
  using Cratis.Chronicle.Events;

public class CrudComparisonCustomerAddressUpdater(IEventStore eventStore)
  {
      public async Task<CrudComparisonCustomerCard> ChangeAddress(EventSourceId customerId, string newAddress)
      {
          await eventStore.EventLog.Append(customerId, new CrudComparisonAddressChanged(newAddress));
          return await eventStore.ReadModels.GetInstanceById<CrudComparisonCustomerCard>(customerId);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ComingFromCrudWriteAndReadAddressChanged do
    use Chronicle.Events.EventType, id: "crud-comparison-write-and-read-address-changed"

defstruct [:address]
  end

defmodule MyApp.ReadModels.ComingFromCrudWriteAndReadCustomerCard do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.ComingFromCrudWriteAndReadAddressChanged

defstruct id: nil, address: nil

from ComingFromCrudWriteAndReadAddressChanged,
      set: [id: :event_source_id, address: :address]
  end

defmodule MyApp.ComingFromCrudCustomerAddressUpdater do
    alias MyApp.Events.ComingFromCrudWriteAndReadAddressChanged
    alias MyApp.ReadModels.ComingFromCrudWriteAndReadCustomerCard

def change_address(customer_id, new_address) do
      :ok =
        Chronicle.append(customer_id, %ComingFromCrudWriteAndReadAddressChanged{
          address: new_address
        })

Chronicle.read_model(ComingFromCrudWriteAndReadCustomerCard, customer_id)
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async changeAddress(customerId: string, newAddress: string): Promise<CrudComparisonCustomerCard> {
          await this.store.eventLog.append(customerId, new CrudComparisonAddressChanged(newAddress));
          return this.store.readModels.getInstanceById(CrudComparisonCustomerCard, customerId);
      }
  }
  ```

`GetInstanceById` hands back the card Chronicle derives from those events — `TimesRelocated` included, a fact the CRUD row lost the moment `SaveChanges` ran. Chronicle keeps that card up to date as events land, so a read right after an append can be a beat behind; when a read must reflect the append that preceded it, [consistency](/chronicle/read-models/consistency/) shows how.

## Not sure it’s worth it?

[Section titled “Not sure it’s worth it?”](#not-sure-its-worth-it)

Read [When to use event sourcing](/chronicle/concepts/when-to-use-event-sourcing/) for an honest take — there are domains where plain CRUD is the right answer, and that’s fine.

## Next

[Section titled “Next”](#next)

* [Get started](/chronicle/get-started/) — scaffold and run in minutes.
* [Tutorial](/chronicle/tutorial/) — build a small system from events up.

# Compliance

Modern applications collect and store personal data. Regulations such as the General Data Protection Regulation (GDPR) require that this data be protected, identifiable, and erasable on demand. Chronicle provides first-class support for compliance requirements directly in the event sourcing model, so that protection is applied consistently and automatically rather than scattered across application code.

## Why compliance belongs in the event store

[Section titled “Why compliance belongs in the event store”](#why-compliance-belongs-in-the-event-store)

Event-sourced systems have a structural challenge: the event log is append-only and immutable. Once an event is written, it cannot be changed. This property is what makes event sourcing reliable for audit trails and replays — but it conflicts directly with regulations that grant individuals the right to have their personal data erased.

Chronicle solves this by separating the *structure* of the event log (which remains immutable) from the *content* of values that must be protectable. Two mechanisms work together:

* **Encryption at rest** — Values marked as personally identifiable information (PII) are encrypted when written to the event log. The encryption key is tied to the identity of the person the data belongs to. Revoking the key — which happens during erasure — makes the data permanently unreadable without altering the event log itself.
* **Event redaction** — For cases where the entire event payload must be removed (for example, to comply with a specific erasure request), Chronicle can replace the event’s content with a redaction marker that preserves the sequence number and audit metadata without retaining the personal data.

## How encryption works

[Section titled “How encryption works”](#how-encryption-works)

When an event is appended to the event log, Chronicle inspects the event’s schema for properties marked as PII. For each such property, the kernel:

1. Looks up the encryption key for the event source identifier associated with the event. If no key exists yet, a new one is generated and stored.
2. Encrypts the property value using that key.
3. Stores the ciphertext in place of the plaintext value.

When a projection or observer reads the event, Chronicle performs the reverse: it retrieves the key, decrypts each PII property, and delivers the plaintext value to the consumer. If the key has been deleted (because an erasure was requested), decryption fails gracefully and the value is returned as an empty string — the data is gone, but the event slot and all non-PII fields remain intact.

Encryption keys are managed by the `IPIIManager` grain in the Chronicle kernel. Keys are stored and retrieved by event source identifier, so every individual whose data lives in the event store has their own key. Deleting a key is the Chronicle equivalent of GDPR erasure.

A key belongs to one event store and one namespace, and an event store subscription copies a subject’s key into the event store it forwards to. An erasure therefore covers every event store in the namespace it is issued in, and records itself there so that nothing provisions or copies a key for that subject afterwards. [Erasing a subject](/chronicle/compliance/erasing-a-subject/) walks through the call and what it reaches; [The encryption key lifecycle](/chronicle/compliance/key-lifecycle/) explains the mechanism and its limits.

## Marking data as PII

[Section titled “Marking data as PII”](#marking-data-as-pii)

Chronicle supports two complementary approaches for marking data as personally identifiable:

| Approach                         | When to use                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `[PII]` on an event property     | The property is a primitive type or an untyped value that holds personal data in a specific event.           |
| `[PII]` on a `ConceptAs<T>` type | The concept itself is inherently personal — any use of this type anywhere in any event is PII by definition. |

The `ConceptAs<T>` approach is the preferred one. It is declared once and applies everywhere the type is used, so there is no risk of forgetting to mark a property in a future event. See [Declaring PII on a concept](/chronicle/compliance/pii-with-concepts/) for details.

For a full description of the `[PII]` marker and its rules, see [Marking data as PII](/chronicle/compliance/pii/).

## Event source identifiers cannot be encrypted

[Section titled “Event source identifiers cannot be encrypted”](#event-source-identifiers-cannot-be-encrypted)

Event source identifiers are the keys used to look up encryption keys, group related events, and drive projections. Encrypting them would make it impossible to retrieve the encryption key in order to decrypt the very event that contains the identifier. Chronicle explicitly disallows applying `[PII]` to any type that inherits from `EventSourceId` or `EventSourceId<T>`.

If the identifier itself is sensitive, use a non-sensitive surrogate key as the event source identifier (for example, a randomly generated `Guid`) and store the sensitive value in a regular event property marked with `[PII]`.

## Related topics

[Section titled “Related topics”](#related-topics)

| Topic                                                                    | Description                                                              |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [Marking data as PII](/chronicle/compliance/pii/)                        | The `[PII]` marker — rules, usage, and constraints                       |
| [Declaring PII on a concept](/chronicle/compliance/pii-with-concepts/)   | How to mark domain value types as PII once and apply everywhere          |
| [Working with compliance from the client](/chronicle/compliance/client/) | How to annotate events and ConceptAs types in your .NET client code      |
| [Read models and PII](/chronicle/compliance/read-models/)                | How PII encryption affects projections, reducers, and read model queries |
| [Erasing a subject](/chronicle/compliance/erasing-a-subject/)            | What one erasure reaches, and how to erase across every event store      |
| [Compliance in Arc applications](/chronicle/compliance/arc/)             | Using read models and queries with compliance in Arc                     |
| [Event Redaction](/chronicle/events/redaction/)                          | Removing event content for GDPR right-to-erasure requests                |

# Compliance in Arc applications

Chronicle compliance — PII encryption, key-based erasure, and automatic decryption — works transparently when you use Arc read models and queries. No additional configuration is required: the same encryption and decryption behavior described in [Read models and PII](/chronicle/compliance/read-models/) applies whether you access read models directly or through Arc’s generated command and query proxies.

For detailed guidance on using compliance features from an Arc application, see `Arc.Chronicle.Compliance`.

# Working with compliance from the client

Chronicle’s PII encryption is applied transparently by the kernel. From a client perspective, your responsibility is to annotate your domain model correctly so that the kernel knows which values to encrypt. There are two places to put this annotation, and you will typically use both in the same codebase.

Client coverage

Both options work in every client. C#, Kotlin/Java and TypeScript have a `ConceptAs<T>`; Elixir has `Chronicle.Concept`. All four serialize a concept as the value it wraps, so adopting one for a property already in production changes neither the wire format nor the registered schema.

The DI-container registration step is genuinely C#-specific — it is `IServiceCollection` wiring, and each other client discovers its artifacts its own way. See [Marking data as PII](/chronicle/compliance/pii/) for the full per-path support matrix.

## Option 1 — Annotate your event types

[Section titled “Option 1 — Annotate your event types”](#option-1--annotate-your-event-types)

Apply `[PII]` directly to individual properties on your event records. This is the simplest starting point and works well when a value is PII only in the context of one specific event.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;

[EventType]
  public record ComplianceClientEmployeeRegistered(
      [PII] string FirstName,
      [PII] string LastName,
      string Department,
      DateTimeOffset StartDate);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.events.EventType
  import java.time.Instant

@EventType
  data class ComplianceClientEmployeeRegistered(
      @Pii val firstName: String,
      @Pii val lastName: String,
      val department: String,
      val startDate: Instant
  )
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.events.EventType;

import java.time.Instant;

@EventType
  record ComplianceClientEmployeeRegistered(
          @Pii String firstName,
          @Pii String lastName,
          String department,
          Instant startDate) {
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ComplianceClientEmployeeRegistered do
    use Chronicle.Events.EventType, id: "compliance-client-employee-registered"

defstruct [:first_name, :last_name, :department, :start_date]

pii(:first_name)
    pii(:last_name)
  end
  ```

* TypeScript

```typescript
  import { eventType, pii } from '@cratis/chronicle';

@eventType()
  class ComplianceClientEmployeeRegistered {
      @pii() firstName = '';
      @pii() lastName = '';
      department = '';
      startDate = new Date();
  }
  ```

`FirstName` and `LastName` are encrypted when the event is written. `Department` and `StartDate` are stored as plaintext.

### When to use this approach

[Section titled “When to use this approach”](#when-to-use-this-approach)

Use property-level annotation when:

* The property type is a primitive (`string`, `int`) and you do not need a dedicated concept type.
* The value is PII in this event but is conceptually not a PII concept elsewhere.
* You are incrementally adding compliance to an existing model and want to make targeted changes.

### Limitation

[Section titled “Limitation”](#limitation)

The main drawback of property-level annotation is that you must remember to add `[PII]` every time a new event carries the same kind of value. If a future event includes an employee’s name without the attribute, it will be written as plaintext.

## Option 2 — Annotate your ConceptAs types

[Section titled “Option 2 — Annotate your ConceptAs types”](#option-2--annotate-your-conceptas-types)

Apply `[PII]` to a `ConceptAs<T>` concept type. Chronicle then encrypts every event property that uses that type, automatically, across all events.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;

[PII]
  public record ComplianceClientPersonName(string Value) : ConceptAs<string>(Value)
  {
      public static readonly ComplianceClientPersonName NotSet = new(string.Empty);
      public static implicit operator string(ComplianceClientPersonName name) => name.Value;
      public static implicit operator ComplianceClientPersonName(string value) => new(value);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs

@Pii
  data class ComplianceClientPersonName(override val value: String) : ConceptAs<String>
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;

@Pii
  record ComplianceClientPersonName(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.Client.PersonName do
    use Chronicle.Concept, type: :string
    pii()
  end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii()
  class ComplianceClientPersonName extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }
  ```

Any event that uses `PersonName` is automatically encrypted — no further annotation is needed:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record ComplianceClientEmployeeRegisteredWithConcept(ComplianceClientPersonName Name, string Department);

[EventType]
  public record ComplianceClientEmployeeNameChanged(ComplianceClientPersonName NewName);  // also encrypted
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class ComplianceClientEmployeeRegisteredWithConcept(val name: ComplianceClientPersonName, val department: String)

// also encrypted
  @EventType
  data class ComplianceClientEmployeeNameChanged(val newName: ComplianceClientPersonName)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record ComplianceClientEmployeeRegisteredWithConcept(ComplianceClientPersonName name, String department) {
  }

// also encrypted
  @EventType
  record ComplianceClientEmployeeNameChanged(ComplianceClientPersonName newName) {
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.Client.ConceptUsagePersonName do
    use Chronicle.Concept, type: :string
    pii()
  end

defmodule MyApp.Compliance.Client.EmployeeRegisteredWithConcept do
    use Chronicle.Events.EventType, id: "compliance-client-employee-registered-with-concept"

defstruct name: %MyApp.Compliance.Client.ConceptUsagePersonName{}, department: ""
  end

defmodule MyApp.Compliance.Client.EmployeeNameChanged do
    use Chronicle.Events.EventType, id: "compliance-client-employee-name-changed"

# Also encrypted — reuses the same concept.
    defstruct new_name: %MyApp.Compliance.Client.ConceptUsagePersonName{}
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class ComplianceClientEmployeeRegisteredWithConcept {
      constructor(readonly name: ComplianceClientPersonName, readonly department: string) {}
  }

@eventType()
  class ComplianceClientEmployeeNameChanged {
      constructor(readonly newName: ComplianceClientPersonName) {} // also encrypted
  }
  ```

Tip

For the full `ConceptAs<T>` declaration pattern and placement rules, see [Declaring PII on a concept](/chronicle/compliance/pii-with-concepts/) and `Fundamentals.Concepts`.

### When to use this approach

[Section titled “When to use this approach”](#when-to-use-this-approach-1)

Use concept-level annotation when:

* The value represents a domain concept that is inherently personal (a person’s name, email address, phone number, national ID).
* The same kind of value appears in multiple events and you want consistent protection without repeating the attribute.
* You are building a new domain model and want compliance baked in from the start.

This is the **recommended approach** for any value that is personal by nature.

## Combining both approaches

[Section titled “Combining both approaches”](#combining-both-approaches)

The two approaches complement each other. Use concept types for inherently personal domain values, and use property-level annotation for one-off cases where creating a concept type is not warranted.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;

[PII]
  public record ComplianceClientEmailAddress(string Value) : ConceptAs<string>(Value)
  {
      public static readonly ComplianceClientEmailAddress NotSet = new(string.Empty);
      public static implicit operator string(ComplianceClientEmailAddress email) => email.Value;
      public static implicit operator ComplianceClientEmailAddress(string value) => new(value);
  }

[EventType]
  public record ComplianceClientCustomerRegistered(
      ComplianceClientPersonName Name,            // encrypted via concept type
      ComplianceClientEmailAddress Email,         // encrypted via concept type
      [PII] string PhoneNumber,                   // encrypted via property annotation
      string Country);                            // plaintext
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs
  import io.cratis.chronicle.events.EventType

@Pii
  data class ComplianceClientEmailAddress(override val value: String) : ConceptAs<String>

@EventType
  data class ComplianceClientCustomerRegistered(
      val name: ComplianceClientPersonName,      // encrypted via concept type
      val email: ComplianceClientEmailAddress,   // encrypted via concept type
      @Pii val phoneNumber: String,              // encrypted via property annotation
      val country: String                        // plaintext
  )
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;
  import io.cratis.chronicle.events.EventType;

@Pii
  record ComplianceClientEmailAddress(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }

@EventType
  record ComplianceClientCustomerRegistered(
          ComplianceClientPersonName name,       // encrypted via concept type
          ComplianceClientEmailAddress email,    // encrypted via concept type
          @Pii String phoneNumber,               // encrypted via property annotation
          String country) {                      // plaintext
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.Client.CombiningPersonName do
    use Chronicle.Concept, type: :string
    pii()
  end

defmodule MyApp.Compliance.Client.CombiningEmailAddress do
    use Chronicle.Concept, type: :string
    pii()
  end

defmodule MyApp.Compliance.Client.CustomerRegistered do
    use Chronicle.Events.EventType, id: "compliance-client-customer-registered"

defstruct name: %MyApp.Compliance.Client.CombiningPersonName{},
              email: %MyApp.Compliance.Client.CombiningEmailAddress{},
              phone_number: "",
              country: ""

# name and email are encrypted via their concept types; phone_number is
    # encrypted via this property-level annotation; country stays plaintext.
    pii(:phone_number)
  end
  ```

* TypeScript

```typescript
  import { eventType, pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii()
  class ComplianceClientEmailAddress extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }

@eventType()
  class ComplianceClientCustomerRegistered {
      name: ComplianceClientPersonName = new ComplianceClientPersonName('');       // encrypted via concept type
      email: ComplianceClientEmailAddress = new ComplianceClientEmailAddress('');  // encrypted via concept type
      @pii() phoneNumber = '';                                                    // encrypted via property annotation
      country = '';                                                               // plaintext
  }
  ```

## EventSourceId cannot be marked PII

[Section titled “EventSourceId cannot be marked PII”](#eventsourceid-cannot-be-marked-pii)

Do not apply `[PII]` to types that inherit from `EventSourceId` or `EventSourceId<T>`. Chronicle throws `PIINotSupportedOnEventSourceId` because event source identifiers are required for key lookup and cannot be encrypted.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;

// ❌ This will throw PIINotSupportedOnEventSourceId at startup
  [PII]
  public record ComplianceClientCustomerId(Guid Value) : EventSourceId<Guid>(Value);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.EventSourceId

// This will throw PiiNotSupportedOnEventSourceId at registration
  @Pii
  data class ComplianceClientCustomerId(override val value: String) : EventSourceId
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.EventSourceId;

// This will throw PiiNotSupportedOnEventSourceId at registration
  @Pii
  record ComplianceClientCustomerId(String value) implements EventSourceId {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  # Raises ArgumentError at compile time — the event source id is used to look
  # up the encryption key, so it cannot itself be an encrypted value.
  #
  # defmodule MyApp.Compliance.Client.CustomerId do
  #   use Chronicle.Concept, type: :uuid, event_source_id: true
  #   pii()
  # end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';

// TypeScript represents the event source identifier as the conventional 'eventSourceId'
  // property rather than a dedicated EventSourceId<T> type. Marking it @pii() throws
  // PIINotSupportedOnEventSourceId - event source identifiers are required for key lookup and
  // cannot be encrypted.
  class ComplianceClientCustomerId {
      @pii() eventSourceId = '';
  }
  ```

If the identifier itself is sensitive, use a non-sensitive surrogate key as the event source identifier (a randomly generated `Guid` works well) and store the sensitive value in a `[PII]`-marked event property.

## Registering compliance services

[Section titled “Registering compliance services”](#registering-compliance-services)

Compliance support is registered with a single extension method in your ASP.NET Core setup:

* C#

```csharp
  using Microsoft.Extensions.DependencyInjection;

public static class ComplianceClientRegistration
  {
      public static void Configure(IServiceCollection services) => services.AddCompliance();
  }
  ```

* Elixir

```elixir
  # No separate compliance registration step exists. Compliance metadata is
  # resolved automatically — from pii/1,2 declarations and from
  # Chronicle.Concept field types — whenever an event type or read model is
  # registered, as part of the normal Chronicle.Client supervision tree entry.
  {Chronicle.Client,
    connection_string: "chronicle://localhost:35000",
    event_store: "my-store",
    event_types: [MyApp.Compliance.Client.CustomerRegistered],
    read_models: [MyApp.Compliance.Client.Customer]}
  ```

* TypeScript

```typescript
  import { ChronicleClient } from '@cratis/chronicle';

// TypeScript has no DI-container registration step for compliance support - the PII manager
  // is available automatically as soon as you have an event store, with no separate wiring.
  async function getPIIManager(chronicleClient: ChronicleClient) {
      const eventStore = await chronicleClient.getEventStore('Sales');
      return eventStore.pii;
  }
  ```

This registers `PIIMetadataProvider` and all supporting infrastructure needed for the kernel to discover and encrypt PII properties.

# Erasing a subject

import { Tabs, TabItem } from ‘@astrojs/starlight/components’;

A right-to-erasure request arrives naming one person, and Chronicle gives you exactly one call to make. This page covers what that call reaches, what happens to that person afterwards, and what you still have to do yourself before you can certify the erasure as complete.

## The one call

[Section titled “The one call”](#the-one-call)

Erasure in Chronicle is the deletion of an encryption key. Every `[PII]` value is encrypted at append time under a key held for the event’s [subject](/chronicle/concepts/subject/), so deleting that key makes every PII value for that subject unreadable at once, without touching the append-only log:

```csharp
public static class ComplianceErasureDeleteKey
{
    public static async Task Delete(ChronicleClient chronicleClient)
    {
        var eventStore = await chronicleClient.GetEventStore("Sales");
        await eventStore.PII.DeleteEncryptionKeyFor("person-42");
    }
}
```

```elixir
defmodule MyApp.Compliance.Erasure.DeleteKey do
  def delete do
    Chronicle.Compliance.delete_encryption_key("person-42")
  end
end
```

```typescript
import { ChronicleClient } from '@cratis/chronicle';

async function deletePersonEncryptionKey(chronicleClient: ChronicleClient): Promise<void> {
    const eventStore = await chronicleClient.getEventStore('Sales');
    await eventStore.pii.deleteEncryptionKey('person-42');
}
```

`IEventStore.PII` is an `IPIIManager`. `DeleteEncryptionKeyFor` removes every revision of the key, evicts it from every silo’s cache, and records the erasure so that nothing puts the key back afterwards.

Read one of that subject’s events afterwards and nothing breaks. The event is still there, its sequence number is still there, and every field that was not marked `[PII]` still holds its value — only the PII properties come back as empty strings. That is the whole point of crypto-shredding: the log stays immutable and the personal data stops existing.

## What one call reaches

[Section titled “What one call reaches”](#what-one-call-reaches)

The erasure covers **every event store in the namespace you erased in**, not only the event store you resolved `PII` from.

That is not generosity, it is arithmetic. When an [event store subscription](/chronicle/subscriptions/) forwards a subject’s events from one event store to another, Chronicle copies that subject’s encryption key into the target event store — and it never copies across namespaces. So the set of places the key can have reached is exactly *every event store, in this namespace*, and that is the set the erasure covers:

```
Namespace 'tenant-b'

Namespace 'Default'

forwarded events copy the key

never

Event store

Sales

Event store

Support

Event store

Billing

Event store

Sales

DeleteEncryptionKeyFor(person-42)
```

The erasure runs in two phases across that set: it records the erasure in every event store first, and only then destroys the key material. Fencing everything before destroying anything is what closes the window a per-store fan-out could not — between the first delete and the last, one event store still held the key and another did not, and an event forwarded in that interval copied the survivor into a store that had just been cleared.

Every phase attempts every event store even when one of them fails, and the failures are reported together as `EncryptionKeyErasureIncomplete`. **A partial erasure is not an erasure** — repeat the call once the failing store is reachable. A call that returns without throwing reached everything.

Note

The namespace is the boundary. In a multi-tenant deployment the same person in two namespaces has two keys and is, as far as Chronicle is concerned, two subjects. Erasing in one namespace deliberately leaves the other untouched — issue one erasure per namespace the person appears in.

## The subject is fenced, not banned

[Section titled “The subject is fenced, not banned”](#the-subject-is-fenced-not-banned)

Deleting the key is only half of an erasure; the other half is making sure nothing puts it back. Chronicle records the erasure beside the keys, and from then on that store refuses to provision a key for the subject, refuses to accept the destroyed key material back, and refuses to let a subscription copy a key in.

The practical consequence is worth knowing before you erase:

**Appending a `[PII]` value for an erased subject fails.** It does not quietly mint a new key, and it does not quietly blank the value — both of those would be a silent surprise, one restarting protection for a person who asked to be forgotten and the other losing data with no signal. It fails with `EncryptionKeyErased` instead.

If the same person later has a lawful basis to be protected again, say so:

```csharp
public static class ComplianceErasureAllowNewKey
{
    public static async Task Allow(ChronicleClient chronicleClient)
    {
        var eventStore = await chronicleClient.GetEventStore("Sales");
        await eventStore.PII.AllowNewEncryptionKeyFor("person-42");
    }
}
```

```text
Elixir does not support this workflow yet.
```

```typescript
import { ChronicleClient } from '@cratis/chronicle';

async function allowNewEncryptionKeyForPerson(chronicleClient: ChronicleClient): Promise<void> {
    const eventStore = await chronicleClient.getEventStore('Sales');
    await eventStore.pii.allowNewEncryptionKeyFor('person-42');
}
```

That creates no key. It authorizes the next `[PII]` value written for the subject to provision a fresh, independent one — which protects data written from then on and can decrypt nothing that came before. The erased key itself never comes back. Like the erasure, the authorization covers every event store in the namespace.

The mechanics of the fence, and what it cannot protect you against, are in [The encryption key lifecycle](/chronicle/compliance/key-lifecycle/).

## What you still have to do

[Section titled “What you still have to do”](#what-you-still-have-to-do)

Chronicle erases keys. It does not know what else your system did with the data.

* **Erase in every namespace the person appears in.** One call per namespace; there is no cross-namespace erasure, by design.
* **Deal with the failed partition, if there is one.** An event carrying `[PII]` for a subject you erased cannot be appended, so a forwarding subscription or a reactor that keeps producing them will report a failed partition for that event source. That is the signal that something is still writing the person’s data — either stop it, or authorize a new key.
* **Expect the same refusal when you replay.** Rebuilding a stored read model re-writes the protected values it holds, so a replay that covers an erased subject is refused for that subject’s partition too. Authorize a new key for anyone you intend to keep protecting before a rebuild that has to cover them.
* **Record the *who*.** Chronicle logs that an erasure completed, which event stores it reached, and the subject as a one-way binding rather than by name — see [what Chronicle records](/chronicle/compliance/key-lifecycle/). What it cannot know, and therefore cannot record, is who asked for the erasure and under what legal basis. That part is yours.
* **Chase the copies outside Chronicle.** Read models exported to a warehouse, search indexes, backups, and anything a reactor sent to a third party are outside the key store and outside the erasure.

## See also

[Section titled “See also”](#see-also)

| Topic                                                                               | Description                                               |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [The encryption key lifecycle](/chronicle/compliance/key-lifecycle/)                | How the fence works, and what it does not protect against |
| [Compliance](/chronicle/compliance/)                                                | How Chronicle protects personal data in an immutable log  |
| [Subject](/chronicle/concepts/subject/)                                             | The identity a PII encryption key is held under           |
| [Compliance and PII in subscriptions](/chronicle/subscriptions/compliance-and-pii/) | What forwarding preserves, and what it no longer copies   |
| [Compliance Storage](/chronicle/hosting/configuration/compliance-storage/)          | Where encryption keys are stored                          |
| [Event Redaction](/chronicle/events/redaction/)                                     | Removing an event’s content rather than its key           |

# The encryption key lifecycle

import { Tabs, TabItem } from ‘@astrojs/starlight/components’;

Crypto-shredding only works if a destroyed key stays destroyed. Deleting a key is easy; making sure nothing puts it back is the hard part, and it is what this page is about.

Read [Erasing a subject](/chronicle/compliance/erasing-a-subject/) first if you only need to know which call to make. This page explains the machinery underneath it: the states a subject’s key moves through, what stops an erased key coming back, how a person who returns gets a new key, and — just as important — what Chronicle *cannot* protect you from.

## Why deleting the key is not enough

[Section titled “Why deleting the key is not enough”](#why-deleting-the-key-is-not-enough)

A key store that only ever holds key material has exactly two states for a subject: there is a key, or there is not. Those two states have to carry three different meanings:

| Meaning                                               | What the store shows |
| ----------------------------------------------------- | -------------------- |
| This subject was never protected here                 | no key               |
| This subject’s key was destroyed for right-to-erasure | no key               |
| This subject’s key has not been provisioned *yet*     | no key               |

Because the last two look identical, every code path that provisions a key on demand treats a completed erasure as an invitation to create a fresh one — and any path that still holds the *original* key material puts the original back. Chronicle has two such paths:

* **Provisioning on append.** Appending a `[PII]` value for a subject with no key mints one. After an erasure, that is a new key, and it cannot read the old ciphertext — but it silently restarts protection for a person who asked to be forgotten.
* **The cross-event-store copy.** An [event store subscription](/chronicle/subscriptions/compliance-and-pii/) copies the subject’s key into the event store it forwards into, whenever the target has none. “The target has none” is precisely the state an erasure creates, so a forwarded event puts the *pre-erasure key material* back and personal data that was already shredded reads in clear again.

Both are resurrections, and neither can be fixed by deleting harder.

## The erasure fence

[Section titled “The erasure fence”](#the-erasure-fence)

Chronicle records the erasure itself, next to the keys, in the same key store. That record is the **erasure fence**, and it is what makes “erased” a state the store can tell apart from “never provisioned”.

A fence for one `(event store, namespace, subject)` carries three things:

| Field                   | Meaning                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `ErasedThrough`         | The highest key revision the erasure covered. No key at or below this revision may ever be provisioned, saved, healed or copied again. |
| `ErasedKeyFingerprints` | The SHA-256 fingerprints of the public keys that were destroyed. That exact key material may never be stored again, at any revision.   |
| `NewKeyAllowed`         | Whether an explicitly authorized new lifecycle may mint a fresh key *above* the fence. Set to `false` by every erasure.                |

The fence lives in the key store because that is the only place it can be written in the same breath as the deletion, and the only place that travels with the store — into its backups, its replicas, and every composed store that serves it. A fence held in memory expires; a fence held beside the key does not.

```
first PII value appended

rotation mints a higher revision

erasure - fence written, then key material destroyed

erasure - fence written even where no key existed

appending PII fails loudly

AllowNewEncryptionKeyFor - explicit and authorized

next append mints a fresh key above the fence

a later erasure closes it again

NeverProvisioned

Active

Erased

NewLifecycleAllowed
```

### What the fence refuses

[Section titled “What the fence refuses”](#what-the-fence-refuses)

Once a fence exists, the key store refuses, in every backend:

* **Provisioning.** `GetOrAddFor` no longer mints a key. It throws `EncryptionKeyErased` instead of quietly creating one, so a resurrection is a loud failure rather than an invisible restart.
* **Saving at or below the floor.** `SaveFor` refuses any revision at or below `ErasedThrough`. This is what stops a composed store healing a survivor back into the store that was erased.
* **Restoring the destroyed material.** Any save of a key whose public-key fingerprint matches a destroyed one is refused, *at any revision, even after a new lifecycle is authorized*. This is the one that closes the cross-store copy: the copy carries the very same key bytes, and those bytes are exactly what the fingerprint fence names.

Reads are untouched. `TryGetFor`, `HasFor` and `GetFor` answer about key material and keep answering exactly as they did — an erased subject has no key, so `[PII]` values release as empty strings and queries keep working.

### What it does *not* refuse

[Section titled “What it does not refuse”](#what-it-does-not-refuse)

The fence is not a ban on the subject identifier. Ada’s D98 ruling settled that erasure removes the key incarnation that exists now, not the person’s ability to ever be a customer again — so a later, lawful lifecycle for the same identifier is a supported operation. It is just not an accident.

## Erasure reaches every event store in the namespace

[Section titled “Erasure reaches every event store in the namespace”](#erasure-reaches-every-event-store-in-the-namespace)

A subscription copies a subject’s key across event stores, but never across namespaces — the namespace is the tenancy boundary and the copy always stays inside it. So the set of places a key can have reached is exactly *every event store, in the namespace you erased in*, and that is the set a single erasure now covers:

```elixir
defmodule MyApp.Compliance.Erasure.DeleteKey do
  def delete do
    Chronicle.Compliance.delete_encryption_key("person-42")
  end
end
```

```typescript
import { ChronicleClient } from '@cratis/chronicle';

That one call now runs in three phases:

```
Every event store in the namespaceKernelCallerEvery event store in the namespaceKernelCallerno store will provision or accept the key from here onDeleteEncryptionKeyFor(person-42)1. Write the erasure fence everywhere2. Destroy the key material everywhere3. Evict the key from every silo's cachecomplete, or a reported incomplete erasure
```

Fencing everywhere *before* destroying anything is what closes the window the previous fan-out could not: between the first delete and the last, one event store still held the key and another did not, and an event forwarded in that interval copied the survivor into a store that had just been cleared. With the fence written first, there is no interval in which any store will accept the key.

Every phase attempts every event store even after one fails, and the failures are reported together as `EncryptionKeyErasureIncomplete`. A partial erasure is not an erasure — repeat the call once the failing store is reachable.

The fence is written even in event stores that never held a key for the subject. That is deliberate: it makes the erasure uniform, it removes the ordering hazard above, and it means a subscription cannot later carry the subject’s personal data into a store the erasure did not visit.

## A later lifecycle for the same person

[Section titled “A later lifecycle for the same person”](#a-later-lifecycle-for-the-same-person)

When a person who was erased has a lawful basis to be protected again, authorize a new key explicitly:

```text
Elixir does not support this workflow yet.
```

```typescript
import { ChronicleClient } from '@cratis/chronicle';

Like erasure, this reaches every event store in the namespace, and like erasure it is a deliberate, explicit act rather than something ordinary traffic can cause. It does **not** create a key. It sets `NewKeyAllowed` on the fence, and the next `[PII]` value appended for that subject mints a fresh key at revision `ErasedThrough + 1`.

## What Chronicle records, and what is still yours

[Section titled “What Chronicle records, and what is still yours”](#what-chronicle-records-and-what-is-still-yours)

Both acts are logged, because the one that makes crypto-shredding reversible is the one an incident review will ask about. Chronicle records the **completion** of each — an erasure and an authorization that reached every event store — at information level:

```text
Erased the encryption key for the subject bound to 'a3f1…' in namespace 'Default', across all 3 event stores
in it: Sales, Support, Billing. Every PII value protected under that key is now permanently unreadable, and no
event store in the namespace will provision or accept a key for the subject until a new one is explicitly
authorized
```

```text
Authorized a new encryption key for the erased subject bound to 'a3f1…' in namespace 'Default', across all 3
event stores in it: Sales, Support, Billing. The erased key does not come back - the next PII value written for
the subject provisions a fresh, independent one that can decrypt nothing written before the erasure
```

An erasure or authorization that did **not** reach every event store is a different message at error level, saying so in as many words — a partial erasure can never be mistaken for a completed one in the log.

Three things about what is in those lines:

* **The subject appears as a binding, not by name.** It is a stable one-way derivation of the subject identifier, so you can compute it for a person you are investigating and find the act — but a log aggregator, whose retention and access sit outside the deployment, does not end up holding the name of someone whose data the erasure existed to remove. It is a pseudonym, not an anonymization: a small or guessable identifier space can be worked backwards, which is the trade a pseudonymous binding makes.
* **No key material is ever logged** — not the key, not its fingerprint, nothing derived from it.
* **The actor is not recorded, because Chronicle does not know it.** Who asked for the erasure, who authorized the new key, under what legal basis, and on whose instruction is yours to record. Chronicle can tell you an erasure completed across three event stores at a given moment; it cannot tell you who decided it should.

The new key is independent of the erased one in every sense that matters:

* It is generated from scratch — it cannot decrypt anything written before the erasure. Values from the old lifecycle stay blank forever.
* It cannot *be* the old key. The fingerprint fence survives the authorization, so the destroyed material is still refused.
* It protects only data written after the new lifecycle begins.

Until you make that call, appending a `[PII]` value for an erased subject fails with `EncryptionKeyErased` rather than silently minting a key or silently blanking the value. That failure is the point: after an erasure, storing that person’s personal data again is a decision somebody has to make on purpose.

Note

A forwarded event carrying `[PII]` for an erased subject fails to append in the target event store, and the observer partition for that event source enters a failed state. The rest of the subscription keeps flowing. Either stop appending that subject’s personal data, or authorize a new key — both are deliberate acts, which is the intent.

The same refusal reaches anything that *writes* protected values, not only appends. Replaying a projection or reducer into a stored read model re-applies what the release produced, so a rebuild that touches an erased subject asks for a key and is refused for that subject’s partition. This is deliberate: the alternative is to store the subject’s slot in the clear, which changes what a unique constraint over a `[PII]` property means, or to mint a key on replay, which is the resurrection the fence exists to stop. Authorize a new key for the subjects you intend to keep protecting before a rebuild that has to cover them.

## The threat model

[Section titled “The threat model”](#the-threat-model)

What the fence stops, and what it does not, stated plainly.

### Stopped

[Section titled “Stopped”](#stopped)

| Attempted resurrection                                                                        | What refuses it                                                                                                                             |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetOrAddFor` minting a fresh revision 1 after an erasure                                     | The fence: provisioning throws `EncryptionKeyErased`                                                                                        |
| A cross-event-store subscription copying the pre-erasure key back in                          | The fence in the target, plus the fingerprint of the destroyed key                                                                          |
| A composed key store healing a surviving member’s copy into the erased member                 | `SaveFor` refusing every revision at or below `ErasedThrough`                                                                               |
| A composed store *serving* a copy that survived in one member after another member was erased | Every member is asked whether it recorded that key’s material as destroyed; if any did, the read returns nothing and reports the divergence |
| A silo cache handing back a key after the erasure landed                                      | The fence invalidates the local cache, and the erasure evicts every silo’s cache cluster-wide                                               |
| An erasure that reached three stores out of four reporting success                            | `EncryptionKeyErasureIncomplete`, listing every failure                                                                                     |
| A key erased for subject A being provisioned for subject B                                    | Fences and keys are per subject; nothing in this path is shared between subjects                                                            |

### Not stopped

[Section titled “Not stopped”](#not-stopped)

Be honest about these when you write your erasure procedure — the fence is a mechanism inside one deployment, not a proof about the physical world.

* **Restoring a backup.** A restore that predates the erasure brings back the key material *and* removes the fence that would have refused it, so it is undetectable from inside Chronicle. A blocking restore-and-re-erase procedure is still required; the fence does not replace it.
* **Copies made outside Chronicle.** A key exported from the key store, an application-level cache, a dump of the backing database, or a secrets-manager audit trail is outside the fence’s reach.
* **Mixed-version silos.** A silo running a version without the fence will happily provision over it. Upgrade every silo before relying on the contract; a cluster running both is unsupported while an erasure is in force.
* **A third-party key store.** A custom `IEncryptionKeyStorage` that does not implement the fence fails loudly the first time an erasure is attempted through it, rather than silently erasing reversibly. That is the safe failure, not a working erasure.
* **A composed store whose only fenced member is unreachable.** When key stores are composed, a member that cannot be reached is skipped rather than allowed to fail every read — otherwise one backend’s outage would blank every protected value in the deployment. While it is down, a fence that only it holds is invisible, so provisioning can mint a fresh key for a subject it had erased. Its erasure was reported incomplete when it happened; repeat it once the store is back.
* **A provisioning already in flight when the fence lands.** Reading the fence and writing the key are two operations, not one, in every backend except the in-memory store. A provisioning that read “not erased” a moment before the fence was recorded can still persist its key a moment after. Recording the fence everywhere before destroying anything narrows that window to the width of a single write, and the erasure destroys whatever it finds — but a key minted in the gap between the destruction and the last write survives until the erasure is repeated. Erase again after forwarding and appends for the subject have stopped.
* **Ciphertext already read.** Erasure makes stored values unreadable. Anything already decrypted, projected into an external system, or displayed is beyond it.
* **The fence itself is a durable record.** It states that *some* identifier was erased in a given store. It holds no key material and no personal data beyond the subject identifier, which every appended event already carries in the clear — but it does outlive the key, by design, because that is what makes the erasure stick.

## Upgrading an existing deployment

[Section titled “Upgrading an existing deployment”](#upgrading-an-existing-deployment)

There is no data migration and no rewrite of existing keys. A key store that has never recorded an erasure has no fences, and no fence means no change: provisioning, reading, rotation and deletion all behave exactly as before. Deployments that do not use `[PII]` are unaffected entirely.

Two things do need your attention.

**Erasures performed before the upgrade are not fenced.** They left the same absence as “never provisioned” — that is the defect — so the upgrade has nothing to recognize. They stay resurrectable until you erase those subjects again. **Re-run the erasure for every subject erased before the upgrade.** It is idempotent, it costs one call per subject, and it is the only way to lay down a fence retroactively.

**Upgrade every silo together.** The fence is enforced by the key store, so a silo that predates it provisions straight over one. Do not run mixed versions while an erasure is in force.

Backend by backend, the fence needs:

| Backend         | What is added                                                                                |
| --------------- | -------------------------------------------------------------------------------------------- |
| MongoDB         | An `encryption-key-erasures` collection per `(event store, namespace)`, created on first use |
| SQL             | An `EncryptionKeyErasures` table, created by a migration that runs automatically on startup  |
| HashiCorp Vault | An `erasure` secret beside the revisions under `{store}/{namespace}/{identifier}`            |
| Azure Key Vault | A `chronicle--{store}--{namespace}--{identifier}--erasure` secret                            |
| In-memory       | Nothing persisted; the fence lives as long as the process                                    |

## See also

[Section titled “See also”](#see-also)

| Topic                                                                               | Description                                                 |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [Erasing a subject](/chronicle/compliance/erasing-a-subject/)                       | The call to make, and how to certify an erasure is complete |
| [Compliance](/chronicle/compliance/)                                                | How Chronicle protects personal data in an immutable log    |
| [Compliance and PII in subscriptions](/chronicle/subscriptions/compliance-and-pii/) | What forwarding preserves, and what it no longer copies     |
| [Compliance Storage](/chronicle/hosting/configuration/compliance-storage/)          | Where encryption keys and their fences are stored           |
| [Subject](/chronicle/concepts/subject/)                                             | The identity a PII encryption key is held under             |

# Marking data as PII

Marking a value `[PII]` tells Chronicle it holds personally identifiable information under GDPR — a C# attribute, a Kotlin/Java `@Pii` annotation, a TypeScript `@pii()` decorator, or an Elixir `pii` macro, depending on the client. When Chronicle sees the marker on an event property or a type, it encrypts the value automatically when the event is written to the event log and decrypts it transparently on read.

Personal data rarely sits in a flat list of properties. A date of birth arrives wrapped in a `VerifiedDateOfBirth` value object alongside who verified it; a diagnosis carries the condition and the clinician together. Chronicle follows the marker down through that structure: whether you mark a concept nested inside a value object, or the value object type itself, encryption lands on the individual values at the bottom. The document keeps its shape, each value stays independently encrypted, and the release on read mirrors the encryption on write.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  ```

* Elixir

```elixir
  # No explicit import is required. `pii/1,2` becomes available automatically
  # from `use Chronicle.Events.EventType` or `use Chronicle.ReadModels.ReadModel`,
  # and `pii/0,1` becomes available automatically from `use Chronicle.Concept`.
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';
  ```

Client coverage

Chronicle resolves `[PII]` on a property through four paths, checked in this order: a marker on the property itself, a marker on the type that declares the property, a marker on the property’s own type (the concept case), and a marker on a matching constructor parameter. C#‘s `PIIMetadataProvider` implements all four.

| Path                    | C#  | Kotlin/Java | TypeScript | Elixir |
| ----------------------- | --- | ----------- | ---------- | ------ |
| Property                | yes | yes         | yes        | yes    |
| Declaring type          | yes | yes         | yes        | no     |
| Property type (concept) | yes | yes         | yes        | yes    |
| Constructor parameter   | yes | yes         | no         | n/a    |

Every client covers the **property** path, and every client resolves a marker on the property’s **concept type** — declare it once on the concept and every event and read model using that type is covered. That is the preferred approach; see [Declaring PII on a concept](/chronicle/compliance/pii-with-concepts/).

Two gaps remain. Elixir has no way to mark a whole multi-field struct as PII in one declaration — a concept wraps a single value, so mark the fields you need. And the TypeScript decorator does not read a constructor parameter, which matters only for classes that take their values positionally rather than as declared properties.

Whichever path applies, the marker lands on the individual **leaf** values in the schema, not on the object that contains them — so a concept nested inside a value object is still encrypted, and the document keeps its shape on release.

## Marker signatures

[Section titled “Marker signatures”](#marker-signatures)

The marker, in each client:

```text
// C#
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Property | AttributeTargets.Parameter)]
public sealed class PIIAttribute(string details = "") : Attribute

// Kotlin / Java
@Target(AnnotationTarget.FIELD, AnnotationTarget.PROPERTY, AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Pii(val description: String = "")

// TypeScript
export function pii(details?: string): PropertyDecorator & ClassDecorator

// Elixir
defmacro pii(field, details \\ "")
```

The optional `details` parameter lets you record *why* the value is classified as PII — for example, the legal basis under which it is collected or the retention period. This information is stored in the event schema and can be used by compliance reporting tools.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;

[PII("Collected under GDPR Art. 6(1)(b) — necessary for contract performance")]
  public record PiiAttrPersonName(string Value) : ConceptAs<string>(Value);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs

@Pii(description = "Collected under GDPR Art. 6(1)(b) — necessary for contract performance")
  data class PiiAttrPersonName(override val value: String) : ConceptAs<String>
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;

@Pii(description = "Collected under GDPR Art. 6(1)(b) — necessary for contract performance")
  record PiiAttrPersonName(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.Pii.PersonNameWithDetails do
    use Chronicle.Concept, type: :string
    pii("Collected under GDPR Art. 6(1)(b) — necessary for contract performance")
  end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii('Collected under GDPR Art. 6(1)(b) — necessary for contract performance')
  class PiiAttrPersonName extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }
  ```

## Where you can mark PII

[Section titled “Where you can mark PII”](#where-you-can-mark-pii)

| Target                                        | Supported | Notes                                                                                                                                                                                              |
| --------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ConceptAs<T>` class                          | Yes       | Preferred approach — marks the concept type itself as PII                                                                                                                                          |
| Event property                                | Yes       | Marks a single property of an event as PII                                                                                                                                                         |
| Value object class                            | Yes       | Marks every value the type holds as PII, however deeply nested                                                                                                                                     |
| Property typed as a value object              | Yes       | Same effect, scoped to that one property                                                                                                                                                           |
| Collection property                           | Yes       | The collection is encrypted as a whole — see [Collections are encrypted as a whole](#collections-are-encrypted-as-a-whole)                                                                         |
| Geospatial (`Point`, `LineString`, `Polygon`) | **No**    | Never classified inside, and marking one encrypts a value that cannot be materialized back after erasure — see [Geospatial values are not looked inside](#geospatial-values-are-not-looked-inside) |
| Polymorphic base type or dictionary           | **No**    | Chronicle cannot classify values inside either and fails rather than store them unprotected                                                                                                        |
| `EventSourceId` or `EventSourceId<T>`         | **No**    | Throws `PIINotSupportedOnEventSourceId` at runtime                                                                                                                                                 |

This table describes what the C# client validates. No other client performs the same checks yet: Kotlin/Java, TypeScript, and Elixir don’t verify that a `[PII]`-marked type actually extends the client’s `ConceptAs<T>` equivalent, and none of them throws an equivalent of `PIINotSupportedOnEventSourceId` when you mark an event-source identifier type — the marker is silently accepted rather than rejected. Treat both restrictions as rules to follow across every client, not ones every client enforces for you today.

## Applying to an event property

[Section titled “Applying to an event property”](#applying-to-an-event-property)

You can mark a single property on an event record as PII. This is useful when the property type is a primitive and you cannot or do not want to introduce a dedicated concept type.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;

[EventType]
  public record PiiAttrEmployeeRegistered(
      [PII] string FirstName,
      [PII] string LastName,
      string Department);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.events.EventType

@EventType
  data class PiiAttrEmployeeRegistered(
      @Pii val firstName: String,
      @Pii val lastName: String,
      val department: String
  )
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.events.EventType;

@EventType
  record PiiAttrEmployeeRegistered(
          @Pii String firstName,
          @Pii String lastName,
          String department) {
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.PiiAttrEmployeeRegistered do
    use Chronicle.Events.EventType, id: "pii-attr-employee-registered"

defstruct [:first_name, :last_name, :department]

pii(:first_name)
    pii(:last_name)
  end
  ```

* TypeScript

```typescript
  import { eventType, pii } from '@cratis/chronicle';

@eventType()
  class PiiAttrEmployeeRegistered {
      @pii() firstName = '';
      @pii() lastName = '';
      department = '';
  }
  ```

When this event is written, `FirstName` and `LastName` are encrypted. `Department` is stored as plaintext.

## Applying to a ConceptAs type

[Section titled “Applying to a ConceptAs type”](#applying-to-a-conceptas-type)

The preferred approach is to mark the `ConceptAs<T>` type itself as PII. Every property across every event that uses this type is then automatically encrypted — you declare the rule once and it applies everywhere.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;

[PII]
  public record PiiAttrConceptPersonName(string Value) : ConceptAs<string>(Value)
  {
      public static readonly PiiAttrConceptPersonName NotSet = new(string.Empty);
      public static implicit operator string(PiiAttrConceptPersonName name) => name.Value;
      public static implicit operator PiiAttrConceptPersonName(string value) => new(value);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs

@Pii
  data class PiiAttrConceptPersonName(override val value: String) : ConceptAs<String>
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;

@Pii
  record PiiAttrConceptPersonName(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.Pii.PersonName do
    use Chronicle.Concept, type: :string
    pii()
  end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii()
  class PiiAttrConceptPersonName extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }
  ```

Tip

Use `Fundamentals.Concepts` as a reference for the full `ConceptAs<T>` pattern. For guidance on declaring compliance on concept types, see [Declaring PII on a concept](/chronicle/compliance/pii-with-concepts/).

## Applying to a value object

[Section titled “Applying to a value object”](#applying-to-a-value-object)

Not every piece of personal data is a single value. When a whole value object is personal — a diagnosis, a passport, a home address — mark the type itself. Every value it holds is then treated as PII wherever that type appears, without annotating each member.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;

// Every value this type holds is personal, so mark the type once.
  [PII]
  public record PiiAttrDiagnosis(string Condition, string DiagnosedBy);

// Both Condition and DiagnosedBy are encrypted wherever a PiiAttrDiagnosis appears.
  public record PiiAttrPatientRecord(string Name, PiiAttrDiagnosis Diagnosis);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii

// Every value this type holds is personal, so mark the type once.
  @Pii
  data class PiiAttrDiagnosis(val condition: String, val diagnosedBy: String)

// Both condition and diagnosedBy are encrypted wherever a PiiAttrDiagnosis appears.
  data class PiiAttrPatientRecord(val name: String, val diagnosis: PiiAttrDiagnosis)
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;

// Every value this type holds is personal, so mark the type once.
  @Pii
  record PiiAttrDiagnosis(String condition, String diagnosedBy) {
  }

// Both condition and diagnosedBy are encrypted wherever a PiiAttrDiagnosis appears.
  record PiiAttrPatientRecord(String name, PiiAttrDiagnosis diagnosis) {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';

// Every value this type holds is personal, so mark the type once.
  @pii()
  class PiiAttrDiagnosis {
      condition = '';
      diagnosedBy = '';
  }

// Both condition and diagnosedBy are encrypted wherever a PiiAttrDiagnosis appears.
  class PiiAttrPatientRecord {
      name = '';
      diagnosis: PiiAttrDiagnosis = new PiiAttrDiagnosis();
  }
  ```

Chronicle pushes the marker down to the individual values rather than encrypting the object as one blob. In storage you still see a `Diagnosis` sub-document with a `Condition` and a `DiagnosedBy` field; both hold ciphertext. That matters for more than tidiness: the shape is what lets the read model materialize back into its value-object type, and it keeps each value separately encrypted rather than fused into a single opaque string.

The same happens when you mark a *property* whose type is a value object — the effect is identical, just scoped to that one property instead of to the type everywhere.

## Nesting

[Section titled “Nesting”](#nesting)

The marker does not have to sit at the top level. A `ConceptAs<T>` marked `[PII]` is found wherever it ends up — directly on an event, one level down inside a value object, or deeper still.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;

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

// The concept sits one level down, inside a value object.
  public record PiiAttrVerifiedDateOfBirth(PiiAttrDateOfBirth DateOfBirth, string VerifiedBy);

// Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
  public record PiiAttrExpressVerification(string Name, PiiAttrVerifiedDateOfBirth DateOfBirth);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs

@Pii
  data class PiiAttrDateOfBirth(override val value: String) : ConceptAs<String>

// The concept sits one level down, inside a value object.
  data class PiiAttrVerifiedDateOfBirth(val dateOfBirth: PiiAttrDateOfBirth, val verifiedBy: String)

// Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
  data class PiiAttrExpressVerification(val name: String, val dateOfBirth: PiiAttrVerifiedDateOfBirth)
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;

@Pii
  record PiiAttrDateOfBirth(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }

// The concept sits one level down, inside a value object.
  record PiiAttrVerifiedDateOfBirth(PiiAttrDateOfBirth dateOfBirth, String verifiedBy) {
  }

// Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
  record PiiAttrExpressVerification(String name, PiiAttrVerifiedDateOfBirth dateOfBirth) {
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.Pii.DateOfBirth do
    use Chronicle.Concept, type: :string
    pii()
  end

# The concept sits one level down, inside a plain (non-concept) value object.
  defmodule MyApp.Compliance.Pii.VerifiedDateOfBirth do
    defstruct date_of_birth: %MyApp.Compliance.Pii.DateOfBirth{}, verified_by: ""
  end

# Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
  defmodule MyApp.Compliance.Pii.ExpressVerification do
    use Chronicle.Events.EventType, id: "pii-express-verification"
    defstruct name: "", date_of_birth: %MyApp.Compliance.Pii.VerifiedDateOfBirth{}
  end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii()
  class PiiAttrDateOfBirth extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }

// The concept sits one level down, inside a value object.
  class PiiAttrVerifiedDateOfBirth {
      dateOfBirth: PiiAttrDateOfBirth = new PiiAttrDateOfBirth('');
      verifiedBy = '';
  }

// Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
  class PiiAttrExpressVerification {
      name = '';
      dateOfBirth: PiiAttrVerifiedDateOfBirth = new PiiAttrVerifiedDateOfBirth();
  }
  ```

Here only `dateOfBirth.dateOfBirth` is encrypted. `verifiedBy` sits beside it in the same value object and stays readable, because the concept carries the classification, not its container.

This is what makes concept-level `[PII]` worth reaching for: you declare the rule once on the type, and it holds no matter how the value is later composed into events and read models.

## Constraints

[Section titled “Constraints”](#constraints)

### EventSourceId is not supported

[Section titled “EventSourceId is not supported”](#eventsourceid-is-not-supported)

Applying `[PII]` to a type that inherits from `EventSourceId` or `EventSourceId<T>` throws `PIINotSupportedOnEventSourceId` at runtime:

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;

// ❌ This will throw PIINotSupportedOnEventSourceId
  [PII]
  public record PiiAttrEmployeeId(Guid Value) : EventSourceId<Guid>(Value);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.EventSourceId

// This will throw PiiNotSupportedOnEventSourceId
  @Pii
  data class PiiAttrEmployeeId(override val value: String) : EventSourceId
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.EventSourceId;

// This will throw PiiNotSupportedOnEventSourceId
  @Pii
  record PiiAttrEmployeeId(String value) implements EventSourceId {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  # Raises ArgumentError at compile time — PII is not supported on a
  # Chronicle.Concept declared with event_source_id: true.
  #
  # defmodule MyApp.Compliance.Pii.EmployeeId do
  #   use Chronicle.Concept, type: :uuid, event_source_id: true
  #   pii()
  # end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';

// TypeScript has no dedicated EventSourceId<T> type - the event source identifier is always
  // the conventional 'eventSourceId' property. Marking it @pii() throws
  // PIINotSupportedOnEventSourceId at decoration time, for the same reason C# forbids [PII] on
  // EventSourceId<T>: encrypting it would make its own decryption key unfindable.
  class PiiAttrEmployeeId {
      @pii() eventSourceId = '';
  }
  ```

Event source identifiers are used to look up encryption keys and group events. Encrypting them would make key lookup impossible. If the identifier itself is sensitive, use a non-sensitive surrogate (such as a random `Guid`) as the event source identifier and store the sensitive value in a `[PII]`-marked event property.

### Geospatial values are not looked inside

[Section titled “Geospatial values are not looked inside”](#geospatial-values-are-not-looked-inside)

One `[PII]` marker anywhere turns the compliance pass on for the **whole** document, so every other value in that event or read model is visited too. Most of them are ordinary properties the schema declares, and Chronicle walks straight through them looking for markers.

A geospatial value is different. `Point`, `LineString` and `Polygon` are objects on the wire — GeoJSON, a `type` and a `coordinates` pair — but Chronicle stores and materializes each as one typed value, so its schema is a leaf carrying only a `format` and those wire members belong to the type’s own converter. The compliance pass stops there and leaves the value exactly as it is: written and read back verbatim, in the clear.

That is normally what you want, because a venue sitting beside a `[PII]` organizer name is public data. Marking the geospatial property `[PII]` is **not** a supported alternative — see [Geospatial values alongside PII](/chronicle/concepts/geospatial/#geospatial-values-alongside-pii) for why.

Note

Two other shapes have members the schema does not declare: a polymorphic base type, kept open so a derived payload round-trips verbatim, and a dictionary, whose keys are runtime data rather than declared properties. Chronicle cannot classify values inside either — and rather than write values it was told are personal into the store unprotected, it **fails**: applying compliance to a document holding one raises `CompliancePropertyNotFoundInSchema`. Model the data as a value object with declared properties instead; the marker travels down through anything the schema declares, however deeply nested.

### Collections are encrypted as a whole

[Section titled “Collections are encrypted as a whole”](#collections-are-encrypted-as-a-whole)

A `[PII]` marker on a collection property behaves differently from one on a value object. The collection is encrypted as a single value rather than element by element, and its shape is restored when it is released. That keeps the data protected, but the individual elements are not separately encrypted and cannot be queried or indexed on the server.

When you need per-element encryption, model the collection as its own person-scoped read model keyed by the subject and join at the query edge, rather than nesting it inside a larger document.

## Details parameter

[Section titled “Details parameter”](#details-parameter)

The `details` parameter is a free-text description stored in the event schema. It is never used for encryption — it exists solely to record *why* a value is classified as PII for compliance documentation and auditing purposes.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;

[PII("Full legal name — required for contract identification")]
  public record PiiAttrLegalName(string Value) : ConceptAs<string>(Value);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs

@Pii(description = "Full legal name — required for contract identification")
  data class PiiAttrLegalName(override val value: String) : ConceptAs<String>
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;

@Pii(description = "Full legal name — required for contract identification")
  record PiiAttrLegalName(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.Pii.LegalName do
    use Chronicle.Concept, type: :string
    pii("Full legal name — required for contract identification")
  end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii('Full legal name — required for contract identification')
  class PiiAttrLegalName extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }
  ```

# Declaring PII on a concept

The most robust way to declare that a value is personally identifiable is to mark the `ConceptAs<T>` type itself with `[PII]`. Doing so means the declaration lives exactly once — on the type — and every event property that uses that type is automatically encrypted, regardless of where or how many times it appears across your event model.

Client coverage

This page covers the **property type** path — Chronicle resolves `[PII]` through four paths in total (property, declaring type, property type, constructor parameter), and marking a concept’s type once is not C#-only:

**Every client supports the pattern on this page.** C#, Kotlin/Java and TypeScript each have a `ConceptAs<T>`; Elixir has `Chronicle.Concept`, which serializes as the value it wraps in the same way. Declare the marker once on the concept and every event and read model property using that type is encrypted — see [Marking data as PII](/chronicle/compliance/pii/) for the full path table and the two remaining gaps.

Tip

For background on the `ConceptAs<T>` pattern, see `Fundamentals.Concepts`.

## Why concept-level declaration is preferred

[Section titled “Why concept-level declaration is preferred”](#why-concept-level-declaration-is-preferred)

When you mark a property directly with `[PII]`, you must remember to repeat the attribute on every event or read model that carries that value. If a new event is added months later and the developer forgets the annotation, a plaintext value is written to the event log with no warning.

A concept type solves this by making the protection part of the type’s identity. You cannot use `PersonName` without the encryption — the two are inseparable.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;

// ❌ Property-level: requires repetition across every event
  [EventType]
  public record PiiConceptsComparisonEmployeeRegistered([PII] string Name, string Department);

[EventType]
  public record PiiConceptsComparisonEmployeeNameChanged([PII] string NewName);  // must remember [PII] again

// ✅ Concept-level: declare once, apply everywhere automatically
  [PII]
  public record PiiConceptsComparisonPersonName(string Value) : ConceptAs<string>(Value)
  {
      public static readonly PiiConceptsComparisonPersonName NotSet = new(string.Empty);
      public static implicit operator string(PiiConceptsComparisonPersonName name) => name.Value;
      public static implicit operator PiiConceptsComparisonPersonName(string value) => new(value);
  }

[EventType]
  public record PiiConceptsComparisonEmployeeRegisteredGood(PiiConceptsComparisonPersonName Name, string Department);  // Name is encrypted

[EventType]
  public record PiiConceptsComparisonEmployeeNameChangedGood(PiiConceptsComparisonPersonName NewName);  // also encrypted, no extra annotation needed
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs
  import io.cratis.chronicle.events.EventType

// Property-level: requires repetition across every event
  @EventType
  data class PiiConceptsComparisonEmployeeRegistered(@Pii val name: String, val department: String)

@EventType
  data class PiiConceptsComparisonEmployeeNameChanged(@Pii val newName: String) // must remember @Pii again

// Concept-level: declare once, apply everywhere automatically
  @Pii
  data class PiiConceptsComparisonPersonName(override val value: String) : ConceptAs<String>

// name is encrypted
  @EventType
  data class PiiConceptsComparisonEmployeeRegisteredGood(val name: PiiConceptsComparisonPersonName, val department: String)

// also encrypted, no extra annotation needed
  @EventType
  data class PiiConceptsComparisonEmployeeNameChangedGood(val newName: PiiConceptsComparisonPersonName)
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;
  import io.cratis.chronicle.events.EventType;

// Property-level: requires repetition across every event
  @EventType
  record PiiConceptsComparisonEmployeeRegistered(@Pii String name, String department) {
  }

// must remember @Pii again
  @EventType
  record PiiConceptsComparisonEmployeeNameChanged(@Pii String newName) {
  }

// Concept-level: declare once, apply everywhere automatically
  @Pii
  record PiiConceptsComparisonPersonName(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }

// name is encrypted
  @EventType
  record PiiConceptsComparisonEmployeeRegisteredGood(PiiConceptsComparisonPersonName name, String department) {
  }

// also encrypted, no extra annotation needed
  @EventType
  record PiiConceptsComparisonEmployeeNameChangedGood(PiiConceptsComparisonPersonName newName) {
  }
  ```

* Elixir

```elixir
  # Property-level: requires repeating pii/1,2 on every event.
  defmodule MyApp.Compliance.PiiWithConcepts.EmployeeRegisteredComparison do
    use Chronicle.Events.EventType, id: "pii-with-concepts-employee-registered-comparison"
    defstruct [:name, :department]

pii(:name)
  end

defmodule MyApp.Compliance.PiiWithConcepts.EmployeeNameChangedComparison do
    use Chronicle.Events.EventType, id: "pii-with-concepts-employee-name-changed-comparison"
    defstruct [:new_name]

# Easy to forget — a plaintext value would be written with no warning.
    pii(:new_name)
  end

# Concept-level: declare once, apply everywhere automatically.
  defmodule MyApp.Compliance.PiiWithConcepts.PersonNameComparison do
    use Chronicle.Concept, type: :string
    pii()
  end

defmodule MyApp.Compliance.PiiWithConcepts.EmployeeRegisteredComparisonGood do
    use Chronicle.Events.EventType, id: "pii-with-concepts-employee-registered-comparison-good"

defstruct name: %MyApp.Compliance.PiiWithConcepts.PersonNameComparison{}, department: ""
  end

defmodule MyApp.Compliance.PiiWithConcepts.EmployeeNameChangedComparisonGood do
    use Chronicle.Events.EventType, id: "pii-with-concepts-employee-name-changed-comparison-good"

# Also encrypted — no extra annotation needed.
    defstruct new_name: %MyApp.Compliance.PiiWithConcepts.PersonNameComparison{}
  end
  ```

* TypeScript

```typescript
  import { eventType, pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

// ❌ Property-level: requires repetition across every event
  @eventType()
  class PiiConceptsComparisonEmployeeRegistered {
      @pii() name = '';
      department = '';
  }

@eventType()
  class PiiConceptsComparisonEmployeeNameChanged {
      @pii() newName = ''; // must remember @pii() again
  }

// ✅ Concept-level: declare once, apply everywhere automatically
  @pii()
  class PiiConceptsComparisonPersonName extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }

@eventType()
  class PiiConceptsComparisonEmployeeRegisteredGood {
      name: PiiConceptsComparisonPersonName = new PiiConceptsComparisonPersonName(''); // encrypted
      department = '';
  }

@eventType()
  class PiiConceptsComparisonEmployeeNameChangedGood {
      newName: PiiConceptsComparisonPersonName = new PiiConceptsComparisonPersonName(''); // also encrypted, no extra annotation needed
  }
  ```

## Defining a PII concept type

[Section titled “Defining a PII concept type”](#defining-a-pii-concept-type)

Follow the standard `ConceptAs<T>` pattern and add `[PII]` to the record declaration:

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;

[PII]
  public record PiiConceptsPersonName(string Value) : ConceptAs<string>(Value)
  {
      public static readonly PiiConceptsPersonName NotSet = new(string.Empty);

public static implicit operator string(PiiConceptsPersonName name) => name.Value;
      public static implicit operator PiiConceptsPersonName(string value) => new(value);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs

@Pii
  data class PiiConceptsPersonName(override val value: String) : ConceptAs<String>
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;

@Pii
  record PiiConceptsPersonName(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.PiiWithConcepts.PersonName do
    use Chronicle.Concept, type: :string
    pii()
  end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii()
  class PiiConceptsPersonName extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }
  ```

Another example, documenting why the value is sensitive with the optional `details` parameter:

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;

[PII("National ID number — sensitive personal identifier")]
  public record PiiConceptsNationalIdNumber(string Value) : ConceptAs<string>(Value)
  {
      public static readonly PiiConceptsNationalIdNumber NotSet = new(string.Empty);

public static implicit operator string(PiiConceptsNationalIdNumber id) => id.Value;
      public static implicit operator PiiConceptsNationalIdNumber(string value) => new(value);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs

@Pii(description = "National ID number — sensitive personal identifier")
  data class PiiConceptsNationalIdNumber(override val value: String) : ConceptAs<String>
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;

@Pii(description = "National ID number — sensitive personal identifier")
  record PiiConceptsNationalIdNumber(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.PiiWithConcepts.NationalIdNumber do
    use Chronicle.Concept, type: :string
    pii("National ID number — sensitive personal identifier")
  end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii('National ID number — sensitive personal identifier')
  class PiiConceptsNationalIdNumber extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }
  ```

## Placement

[Section titled “Placement”](#placement)

Concept types belong in the feature folder they are primarily associated with, or at the feature root if they are shared across slices. Do not create a separate `Concepts/` folder — keep concepts co-located with the code that uses them.

```text
Features/
├── Employees/
│   ├── PersonName.cs          ← shared across Registration and Updates slices
│   ├── Registration/
│   │   ├── Registration.cs    ← uses PersonName
│   └── Updates/
│       ├── Updates.cs         ← also uses PersonName — encryption is automatic
```

## Combining with details

[Section titled “Combining with details”](#combining-with-details)

Use the optional `details` parameter on `[PII]` to document the legal basis or purpose of the PII classification. This is stored in the event schema and can be surfaced by compliance tooling.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;

[PII("Collected under GDPR Art. 6(1)(b) — necessary for contract performance. Retention: contract duration + 7 years.")]
  public record PiiConceptsLegalName(string Value) : ConceptAs<string>(Value)
  {
      public static readonly PiiConceptsLegalName NotSet = new(string.Empty);

public static implicit operator string(PiiConceptsLegalName name) => name.Value;
      public static implicit operator PiiConceptsLegalName(string value) => new(value);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.ConceptAs

@Pii(
      description = "Collected under GDPR Art. 6(1)(b) — necessary for contract performance. " +
          "Retention: contract duration + 7 years."
  )
  data class PiiConceptsLegalName(override val value: String) : ConceptAs<String>
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.ConceptAs;

@Pii(
      description = "Collected under GDPR Art. 6(1)(b) — necessary for contract performance. "
          + "Retention: contract duration + 7 years."
  )
  record PiiConceptsLegalName(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.PiiWithConcepts.LegalName do
    use Chronicle.Concept, type: :string

pii(
      "Collected under GDPR Art. 6(1)(b) — necessary for contract performance. " <>
        "Retention: contract duration + 7 years."
    )
  end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii('Collected under GDPR Art. 6(1)(b) — necessary for contract performance. Retention: contract duration + 7 years.')
  class PiiConceptsLegalName extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }
  ```

## What cannot be marked PII

[Section titled “What cannot be marked PII”](#what-cannot-be-marked-pii)

### EventSourceId types

[Section titled “EventSourceId types”](#eventsourceid-types)

Any type inheriting from `EventSourceId` or `EventSourceId<T>` cannot be marked with `[PII]`. Chronicle throws `PIINotSupportedOnEventSourceId` if you attempt this.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;

// ❌ Throws PIINotSupportedOnEventSourceId
  [PII]
  public record PiiConceptsEmployeeId(Guid Value) : EventSourceId<Guid>(Value);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.concepts.EventSourceId

// Throws PiiNotSupportedOnEventSourceId
  @Pii
  data class PiiConceptsEmployeeId(override val value: String) : EventSourceId
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.concepts.EventSourceId;

// Throws PiiNotSupportedOnEventSourceId
  @Pii
  record PiiConceptsEmployeeId(String value) implements EventSourceId {
      @Override
      public String getValue() {
          return value;
      }
  }
  ```

* Elixir

```elixir
  # Raises ArgumentError at compile time — any Chronicle.Concept declared with
  # event_source_id: true cannot also declare pii/0,1.
  #
  # defmodule MyApp.Compliance.PiiWithConcepts.EmployeeId do
  #   use Chronicle.Concept, type: :uuid, event_source_id: true
  #   pii()
  # end
  ```

* TypeScript

```typescript
  import { pii } from '@cratis/chronicle';

// TypeScript has no dedicated EventSourceId<T> type to mark PII on directly - the event
  // source identifier is always the conventional 'eventSourceId' property, and marking it
  // @pii() throws PIINotSupportedOnEventSourceId for the same reason C# forbids [PII] on a
  // concept deriving from EventSourceId<T>.
  class PiiConceptsEmployeeId {
      @pii() eventSourceId = '';
  }
  ```

Use a non-sensitive surrogate key as the event source identifier and store sensitive identity values in a separate event property:

* C#

```csharp
  using Cratis.Chronicle.Events;

// ✅ Surrogate key as event source identifier
  public record PiiConceptsSurrogateEmployeeId(Guid Value) : EventSourceId<Guid>(Value)
  {
      public static PiiConceptsSurrogateEmployeeId New() => new(Guid.NewGuid());
  }

// ✅ Sensitive value stored in a PII-marked concept type
  [EventType]
  public record PiiConceptsSurrogateEmployeeRegistered(PiiConceptsNationalIdNumber NationalId, PiiConceptsPersonName Name);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.concepts.EventSourceId
  import io.cratis.chronicle.events.EventType

// Surrogate key as event source identifier - not marked @Pii
  data class PiiConceptsSurrogateEmployeeId(override val value: String) : EventSourceId

// Sensitive values stored in PII-marked concept types instead
  @EventType
  data class PiiConceptsSurrogateEmployeeRegistered(
      val nationalId: PiiConceptsNationalIdNumber,
      val name: PiiConceptsPersonName
  )
  ```

* Java

```java
  import io.cratis.chronicle.concepts.EventSourceId;
  import io.cratis.chronicle.events.EventType;

// Surrogate key as event source identifier - not marked @Pii
  record PiiConceptsSurrogateEmployeeId(String value) implements EventSourceId {
      @Override
      public String getValue() {
          return value;
      }
  }

// Sensitive values stored in PII-marked concept types instead
  @EventType
  record PiiConceptsSurrogateEmployeeRegistered(
          PiiConceptsNationalIdNumber nationalId,
          PiiConceptsPersonName name) {
  }
  ```

* Elixir

```elixir
  # Surrogate key as event source identifier — no pii declared.
  defmodule MyApp.Compliance.PiiWithConcepts.SurrogateEmployeeId do
    use Chronicle.Concept, type: :uuid, event_source_id: true
  end

defmodule MyApp.Compliance.PiiWithConcepts.SurrogateNationalId do
    use Chronicle.Concept, type: :string
    pii("National ID number — sensitive personal identifier")
  end

defmodule MyApp.Compliance.PiiWithConcepts.SurrogatePersonName do
    use Chronicle.Concept, type: :string
    pii()
  end

# Sensitive values stored in PII-marked concept fields instead.
  defmodule MyApp.Compliance.PiiWithConcepts.SurrogateEmployeeRegistered do
    use Chronicle.Events.EventType, id: "pii-with-concepts-surrogate-employee-registered"

defstruct national_id: %MyApp.Compliance.PiiWithConcepts.SurrogateNationalId{},
              name: %MyApp.Compliance.PiiWithConcepts.SurrogatePersonName{}
  end
  ```

* TypeScript

```typescript
  import { eventType, Guid } from '@cratis/chronicle';

// ✅ Surrogate key as event source identifier - TypeScript event source identifiers are
  // plain strings, so a randomly generated Guid works well with no dedicated identity type
  // required.
  function createSurrogateEmployeeId(): string {
      return Guid.create().toString();
  }

// ✅ Sensitive values stored in PII-marked concept properties instead
  @eventType()
  class PiiConceptsSurrogateEmployeeRegistered {
      constructor(readonly nationalId: PiiConceptsNationalIdNumber, readonly name: PiiConceptsPersonName) {}
  }
  ```

# Read models and PII

Chronicle stores PII fields encrypted at rest in both the event log and managed read models (projections and reducers). The encryption and decryption is handled automatically by the kernel — your application code works with plaintext values at all times.

Client coverage

The C# examples on this page combine several mechanisms already covered elsewhere for their per-client support ([PII property annotation](/chronicle/compliance/pii/), [projections](/chronicle/projections/), [reducers](/chronicle/reducers/)) — this page’s specific focus (automatic PII lineage through model-bound AutoMap, and the `_subject`/GDPR-erasure mechanics) hasn’t been individually re-verified per client yet.

## Observer decryption

[Section titled “Observer decryption”](#observer-decryption)

All observers — reactors, webhooks, reducers, and projections — receive decrypted events from a single, central decryption point in `Observer.Handle()`. This means encryption is applied consistently regardless of the observer type, and no observer implementation needs to handle decryption itself.

The compliance identifier used for key lookup follows this rule: if an explicit `Subject` was set on the event at append time, that value is used. Otherwise, the `EventSourceId` is used as the fallback identifier. This mirrors the encryption key that was used when the event was originally written to the event log.

## Projections — automatic PII lineage

[Section titled “Projections — automatic PII lineage”](#projections--automatic-pii-lineage)

Projection-backed read models benefit from automatic PII lineage. The kernel knows which read model properties are mapped from PII event properties and encrypts them transparently before writing to storage. No `[PII]` attribute is needed on the read model type.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[PII]
  public record ComplianceReadModelsPersonName(string Value) : ConceptAs<string>(Value)
  {
      public static readonly ComplianceReadModelsPersonName NotSet = new(string.Empty);
      public static implicit operator string(ComplianceReadModelsPersonName name) => name.Value;
      public static implicit operator ComplianceReadModelsPersonName(string value) => new(value);
  }

[EventType]
  public record ComplianceReadModelsEmployeeRegistered(ComplianceReadModelsPersonName Name, string Department);

[FromEvent<ComplianceReadModelsEmployeeRegistered>]
  public record ComplianceReadModelsEmployee(
      [Key] Guid Id,
      string Name,        // mapped from ComplianceReadModelsPersonName — stored encrypted at rest
      string Department);
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.ReadModels.PersonName do
    use Chronicle.Concept, type: :string
    pii()
  end

defmodule MyApp.Compliance.ReadModels.EmployeeRegistered do
    use Chronicle.Events.EventType, id: "compliance-read-models-employee-registered"

defstruct name: %MyApp.Compliance.ReadModels.PersonName{}, department: ""
  end

defmodule MyApp.Compliance.ReadModels.Employee do
    use Chronicle.ReadModels.ReadModel

# name reuses the same concept as the source event, so it is stored
    # encrypted at rest without repeating the pii declaration here.
    defstruct id: nil, name: %MyApp.Compliance.ReadModels.PersonName{}, department: nil

from MyApp.Compliance.ReadModels.EmployeeRegistered,
      set: [id: :event_source_id, name: :name, department: :department]
  end
  ```

* TypeScript

```typescript
  import { eventType, fromEvent, pii, readModel } from '@cratis/chronicle';
  import { ConceptAs } from '@cratis/fundamentals';

@pii()
  class ComplianceReadModelsPersonName extends ConceptAs<string> {
      constructor(value: string) {
          super(value);
      }
  }

@eventType()
  class ComplianceReadModelsEmployeeRegistered {
      constructor(readonly name: ComplianceReadModelsPersonName, readonly department: string) {}
  }

// Chronicle's projection pipeline carries PII lineage automatically from the source event
  // property into the read model - no @pii() is needed here even though `name` is a plain
  // string. It is still encrypted at rest because it came from a PII-marked event property.
  @readModel()
  @fromEvent(ComplianceReadModelsEmployeeRegistered)
  class ComplianceReadModelsEmployee {
      name = '';
      department = '';
  }
  ```

The `Name` property is stored encrypted in MongoDB because `PersonName` is a PII-marked type. When a query returns `Employee` records, the kernel decrypts the values before they reach the caller.

## Reducers — explicit `[PII]` required

[Section titled “Reducers — explicit \[PII\] required”](#reducers--explicit-pii-required)

Reducers use arbitrary C# logic to compute state. The kernel cannot infer which properties derive from PII fields because the transformation is opaque. You must annotate PII properties on the read model record with `[PII]`.

* C#

```csharp
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

[EventType]
  public record ComplianceReadModelsPatientAdmitted(ComplianceReadModelsPersonName Name, DateTimeOffset AdmittedAt);

public record ComplianceReadModelsPatientSummary(Guid PatientId, [PII] string Name, DateTimeOffset LastAdmittedAt);

public class ComplianceReadModelsPatientSummaryReducer : IReducerFor<ComplianceReadModelsPatientSummary>
  {
      public ComplianceReadModelsPatientSummary Admitted(ComplianceReadModelsPatientAdmitted @event, ComplianceReadModelsPatientSummary? current, EventContext context) =>
          new(
              Guid.Parse(context.EventSourceId.Value),
              @event.Name,
              @event.AdmittedAt);
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.ReadModels.ReducerPersonName do
    use Chronicle.Concept, type: :string
    pii()
  end

defmodule MyApp.Compliance.ReadModels.PatientAdmitted do
    use Chronicle.Events.EventType, id: "compliance-read-models-patient-admitted"

defstruct name: %MyApp.Compliance.ReadModels.ReducerPersonName{}, admitted_at: nil
  end

defmodule MyApp.Compliance.ReadModels.PatientSummary do
    use Chronicle.ReadModels.ReadModel

defstruct patient_id: nil, name: "", last_admitted_at: nil

# A reducer assigns name as a plain string, so it needs its own explicit
    # pii/1,2 declaration — it is not itself a Chronicle.Concept field here.
    pii(:name)
  end

defmodule MyApp.Compliance.ReadModels.PatientSummaryReducer do
    use Chronicle.Reducers.Reducer, model: MyApp.Compliance.ReadModels.PatientSummary

@handles MyApp.Compliance.ReadModels.PatientAdmitted

@impl true
    def reduce(%MyApp.Compliance.ReadModels.PatientAdmitted{} = event, _model, context) do
      %MyApp.Compliance.ReadModels.PatientSummary{
        patient_id: context.event_source_id,
        name: event.name,
        last_admitted_at: context.occurred
      }
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, pii, reducer } from '@cratis/chronicle';

@eventType()
  class ComplianceReadModelsPatientAdmitted {
      constructor(readonly name: string, readonly admittedAt: Date) {}
  }

// Reducer-backed read models do not inherit PII lineage from the source event automatically -
  // mark the property explicitly.
  class ComplianceReadModelsPatientSummary {
      @pii() name = '';
      lastAdmittedAt = new Date();
  }

@reducer('PatientSummaryReducer', undefined, ComplianceReadModelsPatientSummary)
  class ComplianceReadModelsPatientSummaryReducer {
      async patientAdmitted(
          event: ComplianceReadModelsPatientAdmitted,
          current?: ComplianceReadModelsPatientSummary
      ): Promise<ComplianceReadModelsPatientSummary> {
          return { name: event.name, lastAdmittedAt: event.admittedAt };
      }
  }
  ```

The `[PII]` attribute on `Name` tells the kernel to encrypt that property before storage and decrypt it on retrieval.

## Stored subjects

[Section titled “Stored subjects”](#stored-subjects)

Every managed read model document written by Chronicle contains a reserved `__subject` field. It stores the default compliance identifier used for PII on that document. Existing single-subject documents need no other metadata and remain compatible.

A projection can compose PII from events belonging to different subjects. Chronicle derives that ownership from the events that populate each property and stores only the exceptions to the default in a reserved `__subjects` object:

```json
{
  "__subject": "employee-42",
  "__subjects": {
    "advisorName": "advisor-17"
  }
}
```

In this example, `advisorName` is encrypted, released, and erased under `advisor-17`; every other PII property falls back to `employee-42`. The map is maintained automatically as projection events replace values. No read model attributes or manual migration are required. Rows written before this capability have no `__subjects` field and continue using `__subject` for every property.

> **Do not** declare properties named `__subject` or `__subjects` in your read model records. Chronicle reserves both names for internal use.

## GDPR erasure

[Section titled “GDPR erasure”](#gdpr-erasure)

Deleting an encryption key is the Chronicle mechanism for GDPR erasure:

1. Delete the key for the subject (the data subject’s identifier) via the Compliance API.
2. Trigger a re-projection or re-reduction of the affected read models.

After key deletion, decryption of PII properties for that subject fails gracefully — Chronicle writes empty values for erased PII fields. Existing read model documents that were written before erasure continue to contain encrypted ciphertext until they are re-projected.

Note

Re-projection is required for a complete, verifiable erasure. Until re-projection runs, the ciphertext remains in the read model store. Chronicle cannot decrypt it, but the ciphertext is still present.

For full erasure of event content, combine key deletion with [event redaction](/chronicle/events/redaction/).

## Querying

[Section titled “Querying”](#querying)

Read model queries are transparent to PII encryption. No changes to query code are needed:

* C#

```csharp
  using Cratis.Chronicle;

public class ComplianceReadModelsEmployeeService(IEventStore eventStore)
  {
      public Task<ComplianceReadModelsEmployee> GetEmployee(Guid id) =>
          eventStore.ReadModels.GetInstanceById<ComplianceReadModelsEmployee>(id);
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Compliance.ReadModels.QueryingPersonName do
    use Chronicle.Concept, type: :string
    pii()
  end

defmodule MyApp.Compliance.ReadModels.QueryingEmployee do
    use Chronicle.ReadModels.ReadModel

defstruct id: nil, name: %MyApp.Compliance.ReadModels.QueryingPersonName{}, department: nil
  end

defmodule MyApp.Compliance.ReadModels.EmployeeService do
    # PII decryption is transparent here — the caller just gets the plain,
    # decrypted value back.
    def get_employee(id) do
      Chronicle.ReadModels.get(MyApp.Compliance.ReadModels.QueryingEmployee, id)
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

class ComplianceReadModelsEmployeeService {
      constructor(private readonly eventStore: IEventStore) {}

getEmployee(id: string): Promise<ComplianceReadModelsEmployee> {
          return this.eventStore.readModels.getInstanceById(ComplianceReadModelsEmployee, id);
      }
  }
  ```

Chronicle decrypts PII fields automatically before returning results to the caller. When the encryption key has been deleted for a subject, `Name` returns an empty string — the caller receives an `Employee` record with an empty name, never an exception or partial result.

That automatic decryption covers `IReadModels`’ query methods. For an instance that arrived some other way — built from raw storage, restored from a cache, or delivered through `Watch`, which streams changes without releasing them — call `IReadModels.Release` yourself; see [Releasing PII](/chronicle/read-models/releasing-pii/).

### One property never fails the whole read

[Section titled “One property never fails the whole read”](#one-property-never-fails-the-whole-read)

Decryption is resolved per property, and a property that cannot be read never fails the read model or the query returning it:

| The stored value                                                     | What the caller gets                                                                                                      |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Encrypted under this subject                                         | The decrypted value.                                                                                                      |
| Encrypted, but the subject’s key was deleted                         | An empty value — the erasure case above.                                                                                  |
| Never encrypted under this subject                                   | The value, untouched.                                                                                                     |
| Encrypted under a *different* subject and missing ownership metadata | An empty value for that property, plus an error in the Kernel log naming the property, the subject, and the likely cause. |

The third row matters when a `[PII]`-typed property is resolved in memory at the query edge — for display on a view whose own compliance subject is not that person — or when a property was marked `[PII]` after values had already been stored. Chronicle recognizes the shape of the values it encrypts, so a value it never encrypted is passed through rather than blanked or rejected.

The fourth row can occur for legacy data that was written before per-property ownership was tracked, or for data written outside Chronicle’s managed projection sinks. New projection writes keep the ownership map with the ciphertext, so joined PII releases under the subject of the event it came from.

Note

Applying PII behaves the opposite way, and deliberately so: if encryption fails on the way *in*, the operation fails. Storing a value that was meant to be protected, unprotected, is never an acceptable degradation.

## Composing read models outside Chronicle

[Section titled “Composing read models outside Chronicle”](#composing-read-models-outside-chronicle)

Per-property ownership is storage metadata maintained by Chronicle’s projection pipeline. If application code manually constructs an object from raw ciphertext, `IReadModels.Release` can only resolve the object’s own `[Subject]` member or `Id` and cannot infer where each copied value originated. Prefer querying managed read models through Chronicle so their stored ownership metadata is honored before composition.

# Concepts

This area contains explanations and guidance on the concepts in Cratis.

| Topic                                                                         | Description                                                                                   |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [Event](/chronicle/concepts/event/)                                           | What constitutes an event                                                                     |
| [Event Type](/chronicle/concepts/event-type/)                                 | What is an event type                                                                         |
| [Modeling events well](/chronicle/concepts/modeling-events/)                  | How to design events that are clear today and still make sense in five years                  |
| [Event Type Migrations](/chronicle/concepts/event-type-migrations/)           | How event schemas evolve without breaking existing events                                     |
| [Event Source](/chronicle/concepts/event-source/)                             | What is an event source                                                                       |
| [Subject](/chronicle/concepts/subject/)                                       | The identity an event is *about* — used to key compliance concerns                            |
| [Event Store](/chronicle/concepts/event-store/)                               | Where your events live — durably persisted in a database                                      |
| [Namespaces](/chronicle/concepts/namespaces/)                                 | What are namespaces within an event store                                                     |
| [Event Sequence](/chronicle/concepts/event-sequence/)                         | What is an event sequence                                                                     |
| [Observer](/chronicle/concepts/observers/)                                    | What is an observer                                                                           |
| [Projections, reducers, and reactors](/chronicle/concepts/observer-patterns/) | The three observer patterns side by side — deriving state from events vs causing side effects |
| [Projection](/chronicle/concepts/projection/)                                 | How a projection declaratively maps events onto a read model instance                         |
| [Designing read models](/chronicle/concepts/designing-read-models/)           | Specialize each read model for the query it serves, not for reuse                             |
| [Deep dive: consistency](/chronicle/concepts/consistency/)                    | Immediate vs eventual consistency, and how to choose                                          |
| [Constraints](/chronicle/concepts/constraints/)                               | What are constraints                                                                          |
| [Event Metadata Tags](/chronicle/concepts/event-metadata-tags/)               | Metadata tags attached to events                                                              |
| [Tagging](/chronicle/concepts/tagging/)                                       | How to tag events for organization and filtering                                              |
| [Tagging Reactors](/chronicle/concepts/tagging-reactors/)                     | How to use tags with reactors                                                                 |
| [Geospatial Types](/chronicle/concepts/geospatial/)                           | Built-in geospatial types for events and read models                                          |
| [When to use event sourcing](/chronicle/concepts/when-to-use-event-sourcing/) | An honest look at where event sourcing pays off — and where it doesn’t                        |
| [Glossary](/chronicle/concepts/glossary/)                                     | One definition for each core Chronicle term                                                   |

Note

Where these pages say *database*, you have a choice: Chronicle can persist the [event store](/chronicle/concepts/event-store/) and its read models in MongoDB, PostgreSQL, Microsoft SQL Server, or SQLite.

One nuance worth carrying with you: [projections and reducers](/chronicle/concepts/observer-patterns/) are not only factories for materialized, queryable views. The state they derive from events can be stored in a database for fast queries — or computed on demand, with strong consistency, for anything that must trust the current state: validation rules, command handlers, or [aggregate roots in Arc](/arc/backend/chronicle/aggregates/defining-an-aggregate-root/).

# Deep dive: consistency

> Immediate vs eventual consistency, the Dynamic Consistency Boundary, and how to choose — the model that trips people up most, explained.

Consistency is where event sourcing feels different from CRUD, and where most early confusion lives. The short version: **writes are validated immediately; reads are usually eventual.** This page unpacks that and shows how to choose the right tool for each decision.

## The two sides

[Section titled “The two sides”](#the-two-sides)

In a CRUD system, you write a row and read it straight back — one place, one consistency model. Event sourcing splits the write side from the read side, and they have different guarantees:

```
append, validated now

projected shortly after

query, may briefly lag

Command

Event log

Read model

Reader
```

* **The write side is consistent now.** When you append an event, it’s committed and ordered immediately. Invariants enforced at append time (constraints, the boundary below) hold the moment the command returns.
* **The read side is eventual.** A [projection](/chronicle/concepts/projection/) updates the read model *after* the append. The window is usually milliseconds, but a read taken instantly after a write may not reflect it yet.

## Why not just make reads immediate?

[Section titled “Why not just make reads immediate?”](#why-not-just-make-reads-immediate)

Because eventual reads are what make the model scale and stay simple: projections run independently, read models specialize per use case, and the write path doesn’t wait on every view being updated. The cost is the small lag — and most UIs handle it naturally, especially with [observable queries](/chronicle/scenarios/real-time-query/) that update the moment the projection catches up.

When you genuinely need read-after-write for a specific case, Chronicle offers **immediate projections** — a read model materialized synchronously so it’s current the instant the command returns. Use them deliberately and sparingly; they trade the benefits above for strong read consistency. See [Immediate projections](/chronicle/projections/immediate-projections/).

## Protecting invariants: don’t read, constrain

[Section titled “Protecting invariants: don’t read, constrain”](#protecting-invariants-dont-read-constrain)

The classic mistake is enforcing a rule by reading a model first: “is this email taken? no → append.” Because the read is eventual, two commands can race and both pass. Enforce invariants on the **write side** instead:

* A [constraint](/chronicle/constraints/) rejects an append that would violate a rule (uniqueness, for example) — evaluated against authoritative state at append time.
* A **Dynamic Consistency Boundary** scopes a decision to exactly the events it depends on, so the decision is made against consistent state without loading a whole aggregate.

## The Dynamic Consistency Boundary

[Section titled “The Dynamic Consistency Boundary”](#the-dynamic-consistency-boundary)

Traditional event sourcing draws the consistency boundary around a fixed **aggregate** — you load all of an entity’s events to make any decision about it. That’s rigid: real decisions often span more or less than one entity.

A [Dynamic Consistency Boundary](/chronicle/dynamic-consistency-boundary/) lets the *decision* define the boundary. You scope to precisely the events that matter for the rule you’re enforcing — no more, no less — and Chronicle guarantees consistency over that scope. It’s the boundary, made to fit the decision instead of the other way around.

## How to choose

[Section titled “How to choose”](#how-to-choose)

| You need…                              | Use                                                                                          |
| -------------------------------------- | -------------------------------------------------------------------------------------------- |
| A view to read and render              | A normal [projection](/chronicle/concepts/projection/) — embrace eventual consistency        |
| The UI to update as data changes       | An [observable query](/chronicle/scenarios/real-time-query/)                                 |
| An invariant guaranteed at write time  | A [constraint](/chronicle/constraints/) or a [DCB](/chronicle/dynamic-consistency-boundary/) |
| Read-after-write for one specific case | An [immediate projection](/chronicle/projections/immediate-projections/), deliberately       |

## See also

[Section titled “See also”](#see-also)

* [Read Models](/chronicle/read-models/) — consistency and retrieval in depth.
* [Dynamic Consistency Boundary](/chronicle/dynamic-consistency-boundary/) — the full model.
* [Designing read models](/chronicle/concepts/designing-read-models/) — designing for eventual consistency.

# Constraints

To keep integrity within typically an [event source](/chronicle/concepts/event-source/) when appending events to an [event sequence](/chronicle/concepts/event-sequence/), you can leverage constraints. Constraints are rules that run on a database level within Chronicle, allowing or not allowing an event to be appended. This is one of the main ways Chronicle enforces the [Dynamic Consistency Boundary](/chronicle/dynamic-consistency-boundary/chronicle/) by validating that the decision remains correct at append time.

```
rule holds

rule violated

Append event

Constraint check at append time, in the database

Appended to the event sequence

Rejected — constraint violation
```

## Unique Constraint

[Section titled “Unique Constraint”](#unique-constraint)

A **unique constraint** specifies events that work on a specific value you want to keep unique within an event source. For instance, let’s say you’re creating a system for registering users, the username is typically something you want to keep a unique constraint on. Any events that either create the user or modify the user name in any way would typically then be included in the constraint definition.

## Unique Event Type Constraint

[Section titled “Unique Event Type Constraint”](#unique-event-type-constraint)

The **unique event type constraint** lets you constrain on a specific event type being unique per event source. If any attempt is made to append the same event type twice for an event source, it will be a constraint violation.

# Correlation, identity, and causation

> The three pieces of context Chronicle carries with every event — who caused it, what operation it belongs to, and why it happened.

Every event Chronicle appends carries more than its own data. Three pieces of context travel alongside it, scoped to the current call and captured automatically on every append:

* **Correlation ID** — ties together every event, command, and side effect that belong to the same logical operation (a single HTTP request, a message-bus handler invocation).
* **Identity** — records *who* caused the change: a user, a system, or a service.
* **Causation** — records *why*: the chain of operations, from a root action down to the specific command that triggered this event.

All three are set once at the start of an operation (a request, a background job) and flow into every event appended during it, without threading them through every function call.

## Correlation ID

[Section titled “Correlation ID”](#correlation-id)

* C#

```csharp
  using Cratis.Execution;

public class CorrelationIdentityCausationCorrelation(ICorrelationIdAccessor accessor, ICorrelationIdModifier modifier)
  {
      public CorrelationId GetCurrent() => accessor.Current;

public void SetForRequest() => modifier.Modify(CorrelationId.New());
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.correlation.correlationIdManager
  import java.util.UUID

class CorrelationIdentityCausationCorrelation {
      fun getCurrent(): UUID = correlationIdManager.current

fun setForRequest() = correlationIdManager.set(UUID.randomUUID())
  }
  ```

* Java

```java
  import io.cratis.chronicle.correlation.CorrelationIdManagerKt;
  import java.util.UUID;

class CorrelationIdentityCausationCorrelation {
      UUID getCurrent() {
          return CorrelationIdManagerKt.getCorrelationIdManager().getCurrent();
      }

void setForRequest() {
          CorrelationIdManagerKt.getCorrelationIdManager().set(UUID.randomUUID());
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.CorrelationIdentityCausationCorrelation do
    alias Chronicle.Correlation.CorrelationId

def get_current do
      Chronicle.current_correlation_id()
    end

def set_for_request do
      Chronicle.set_correlation_id(CorrelationId.create())
    end
  end
  ```

* TypeScript

```typescript
  import { correlationIdManager, CorrelationId } from '@cratis/chronicle';

class CorrelationIdentityCausationCorrelation {
      getCurrent(): CorrelationId {
          return correlationIdManager.current;
      }

setForRequest(): void {
          correlationIdManager.setCurrent(CorrelationId.create());
      }
  }
  ```

Kotlin’s correlation manager scopes the id per-thread (`ThreadLocal`); Elixir and TypeScript scope it per logical call context (Elixir’s process dictionary, TypeScript’s `AsyncLocalStorage`) — in both cases automatically, without extra code, as long as you don’t spawn new threads/processes/async contexts without carrying the value across explicitly.

## Identity

[Section titled “Identity”](#identity)

* C#

```csharp
  using Cratis.Chronicle.Identities;

public class CorrelationIdentityCausationIdentity(IIdentityProvider identityProvider)
  {
      public void SetForRequest(string subject, string name, string userName) =>
          identityProvider.SetCurrentIdentity(new Identity(subject, name, userName));

public Identity GetCurrent() => identityProvider.GetCurrent();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.identity.Identity
  import io.cratis.chronicle.identity.identityProvider

class CorrelationIdentityCausationIdentity {
      fun setForRequest(subject: String, name: String, userName: String) {
          identityProvider.setCurrentIdentity(Identity(subject, name, userName))
      }

fun getCurrent(): Identity = identityProvider.currentIdentity
  }
  ```

* Java

```java
  import io.cratis.chronicle.identity.Identity;
  import io.cratis.chronicle.identity.IdentityProviderKt;

class CorrelationIdentityCausationIdentity {
      void setForRequest(String subject, String name, String userName) {
          IdentityProviderKt.getIdentityProvider().setCurrentIdentity(new Identity(subject, name, userName, null));
      }

Identity getCurrent() {
          return IdentityProviderKt.getIdentityProvider().getCurrentIdentity();
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.CorrelationIdentityCausationIdentity do
    alias Chronicle.Identity

def set_for_request(subject, name, user_name) do
      Chronicle.set_identity(Identity.new(subject, name, user_name))
    end

def get_current do
      Chronicle.current_identity()
    end
  end
  ```

* TypeScript

```typescript
  import { identityProvider, Identity } from '@cratis/chronicle';

class CorrelationIdentityCausationIdentity {
      setForRequest(subject: string, name: string, userName: string): void {
          identityProvider.setCurrentIdentity(new Identity(subject, name, userName));
      }

getCurrent(): Identity {
          return identityProvider.getCurrent();
      }
  }
  ```

Every client provides the same three sentinel identities for well-known cases — `System`, `NotSet`, and `Unknown` — and supports on-behalf-of delegation chains (an identity that acted *for* another identity) via a `withoutDuplicates()`/`without_duplicates/1` helper that collapses repeated subjects in a long chain.

### Renaming an identity

[Section titled “Renaming an identity”](#renaming-an-identity)

The name recorded alongside an identity is a display name, and people’s names change. Renaming updates it in one place for every event that identity has ever caused — the events themselves are untouched, since the name is not part of the fact they record.

* C#

```csharp
  using Cratis.Chronicle;

public static class RenamingAnIdentity
  {
      public static async Task Rename(IEventStore eventStore)
      {
          await eventStore.Identities.Rename("subject-42", "Jane Austen");
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore

class CorrelationIdentityCausationRenamingAnIdentity {
      suspend fun rename(eventStore: IEventStore) {
          eventStore.identities.rename("subject-42", "Jane Austen")
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;

import io.cratis.chronicle.java.IdentityManagerServiceJavaBridge;

class CorrelationIdentityCausationRenamingAnIdentity {
      void rename(IEventStore eventStore) {
          IdentityManagerServiceJavaBridge.rename(eventStore.getIdentities(), "subject-42", "Jane Austen");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.CorrelationIdentityCausationRenamingAnIdentity do
    alias Chronicle.Identities

def rename do
      Identities.rename("subject-42", "Jane Austen")
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

async function renameAnIdentity(eventStore: IEventStore): Promise<void> {
      await eventStore.identities.rename('subject-42', 'Jane Austen');
  }
  ```

The subject is the identity’s stable key. It is what events are recorded against, so it does not change.

## Causation

[Section titled “Causation”](#causation)

* C#

```csharp
  using Cratis.Chronicle.Auditing;

public class CorrelationIdentityCausationCausation(ICausationManager causationManager)
  {
      public void RecordPlaceOrder(string orderId) =>
          causationManager.Add(
              "MyApp.Commands.PlaceOrder",
              new Dictionary<string, string> { ["orderId"] = orderId });
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.auditing.CausationType
  import io.cratis.chronicle.auditing.causationManager

class CorrelationIdentityCausationCausation {
      fun recordPlaceOrder(orderId: String) {
          causationManager.add(CausationType("MyApp.Commands.PlaceOrder"), mapOf("orderId" to orderId))
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.java.CausationManagerJavaBridge;

import java.util.Map;

import static io.cratis.chronicle.auditing.CausationManagerKt.getCausationManager;

class CorrelationIdentityCausationCausation {
      void recordPlaceOrder(String orderId) {
          CausationManagerJavaBridge.add(
              getCausationManager(),
              "MyApp.Commands.PlaceOrder",
              Map.of("orderId", orderId));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.CorrelationIdentityCausationCausation do
    alias Chronicle.Auditing.CausationManager

def record_place_order(order_id) do
      CausationManager.add("MyApp.Commands.PlaceOrder", %{order_id: order_id})
    end
  end
  ```

* TypeScript

```typescript
  import { causationManager, CausationType } from '@cratis/chronicle';

class CorrelationIdentityCausationCausation {
      recordPlaceOrder(orderId: string): void {
          causationManager.add(new CausationType('MyApp.Commands.PlaceOrder'), { orderId });
      }
  }
  ```

TypeScript also has a real `causationManager.add(type, properties)` — the client-specific pages linked below cover it, along with more Kotlin/Elixir/TypeScript causation detail than fits here (defining/redefining the root cause, reading the full chain, framework-integration examples for scoping context per request).

## Client-specific reference

[Section titled “Client-specific reference”](#client-specific-reference)

Each client’s own documentation covers the full API in depth — provider interfaces, framework-integration examples (Express middleware, and similar), and thread/process/async-context caveats specific to that runtime:

* [.NET client](/chronicle/clients/dotnet/) — `Cratis.Execution.ICorrelationIdAccessor`/`ICorrelationIdModifier`, `Cratis.Chronicle.Identities.IIdentityProvider`, `Cratis.Chronicle.Auditing.ICausationManager`
* [Kotlin client](/chronicle/clients/kotlin/) — `io.cratis.chronicle.correlation`, `io.cratis.chronicle.identity`, `io.cratis.chronicle.auditing`
* [Elixir client](/chronicle/clients/elixir/) — `Chronicle.CorrelationId`, `Chronicle.Identity`, `Chronicle.Auditing.CausationManager`
* [TypeScript client](/chronicle/clients/typescript/) — `correlationIdManager`, `identityProvider`, `causationManager`

# Designing read models

> Read models are cheap, disposable, and meant to be specialized — design them for the query, not for reuse.

If [modeling events well](/chronicle/concepts/modeling-events/) is about capturing truth, designing read models is about *presenting* it. The events are your single source of truth; a read model is just one view of them, built for one job. That reframing changes how you design.

The guiding principle: **specialize, don’t share.** Build a focused read model per use case rather than one model stretched across conflicting screens.

## Read models are derived and disposable

[Section titled “Read models are derived and disposable”](#read-models-are-derived-and-disposable)

A read model holds no truth of its own — it’s computed from events by a [projection](/chronicle/concepts/projection/). That has a liberating consequence: you can create, change, and throw away read models freely. Got the shape wrong? Change the projection and [rebuild](/chronicle/scenarios/rebuild-a-read-model/). There’s no precious state to migrate, because the events are the state.

## Shape it for the query, not the domain

[Section titled “Shape it for the query, not the domain”](#shape-it-for-the-query-not-the-domain)

A normalized, one-size-fits-all model is a relational-database habit. Here, design each read model around *how it will be read*:

* A list screen wants a flat, denormalized row per item.
* A detail screen wants one rich document with its children embedded.
* A dashboard wants pre-aggregated counts.

These can all be **separate read models built from the same events**. Denormalize without guilt — there’s no update anomaly to fear, because you never update a read model by hand; the projection rebuilds it from the facts.

## Specialize over reuse

[Section titled “Specialize over reuse”](#specialize-over-reuse)

It’s tempting to make one `Customer` read model serve every screen. Resist it. The moment two screens want conflicting shapes, a shared model becomes a compromise that serves neither well and breaks one when you change it for the other. A dedicated model per use case is easier to reason about, faster to query, and safe to change in isolation.

```text
❌ One CustomerReadModel feeding the list, the detail page, and the billing report
✅ CustomerListItem · CustomerDetail · CustomerBillingSummary — each from the same events
```

## Reach for the declarative path first

[Section titled “Reach for the declarative path first”](#reach-for-the-declarative-path-first)

You rarely write code that *updates* a read model — you declare how events map onto it and let Chronicle do the folding. Start with [model-bound projections](/chronicle/projections/model-bound/), where attributes on the read model record describe the mapping. When the mapping needs logic the attributes can’t express cleanly, step up to the fluent [declarative projection builder](/chronicle/projections/declarative/) (`IProjectionFor<T>`), and only reach for a [reducer](/chronicle/reducers/) when the model is genuinely easier to express as code folding over previous state.

## The constructor may not run

[Section titled “The constructor may not run”](#the-constructor-may-not-run)

Sooner or later you’ll want to put a small piece of logic in the read model record itself — a normalizer that turns a `null` collection into an empty one, a computed default, a guard that rejects a value that should never arrive:

* C#

```csharp
  public record LineItem(string ProductName, int Quantity, decimal Price);

// Don't rely on this. It may never execute.
  public record OrderSummary(OrderId Id, IEnumerable<LineItem> Lines)
  {
      public IEnumerable<LineItem> Lines { get; init; } = Lines ?? [];
  }
  ```

* Kotlin

```kotlin
  data class DesigningReadModelsLineItem(val productName: String, val quantity: Int, val price: Double)

// A non-nullable property with a default in the constructor - not a body that "fixes up" a
  // value after the fact, which a document deserializer may skip entirely.
  data class DesigningReadModelsOrderSummary(
      val id: String,
      val lines: List<DesigningReadModelsLineItem> = emptyList()
  )
  ```

* Java

```java
  import java.util.Collections;
  import java.util.List;

record DesigningReadModelsLineItem(String productName, int quantity, double price) {}

// A collection defaulted at the call site, not "fixed up" by logic in a constructor body -
  // a document deserializer may build the instance without ever running one.
  record DesigningReadModelsOrderSummary(String id, List<DesigningReadModelsLineItem> lines) {
      static DesigningReadModelsOrderSummary empty(String id) {
          return new DesigningReadModelsOrderSummary(id, Collections.emptyList());
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Whether that line runs is not yours to decide. A read model instance is *materialized* by a deserializer, and a document deserializer is free to build the record without running either a constructor or the initializer. The MongoDB driver does exactly that, and it is not conditional: for a record with a primary constructor it builds no creator map at all, so it creates the instance uninitialized and assigns the members by reflection. That happens on every document — a complete one just as much as one missing a field. Read a read model through `IMongoCollection<T>` and your normalizer never runs, ever.

That makes the blast radius wider than a `null` collection. Any logic you put in the record body — a default, a clamp, a trim, a validation — is dead on that path, silently.

Chronicle’s own reader *does* construct the record, which makes this worse rather than better: the same line can work when you read through `IReadModels` and quietly fail when something reads that document with `IMongoCollection<T>`. And even where the constructor runs, a property declared in the record body gets its stored value assigned after construction, on top of whatever its initializer produced.

So a guard written in a read model record is not a guard. Put the intent somewhere that always runs:

| You want                                                   | Where it belongs                                                                                                                                                                                                      |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A collection that is never `null`                          | The declaration. A non-nullable collection property materializes as empty — see [Empty child collections](/chronicle/read-models/empty-child-collections/).                                                           |
| A meaningful default before any event assigns the property | The projection — [SetValue](/chronicle/projections/model-bound/set-value/) or [initial values](/chronicle/projections/declarative/initial-values/) — so the default is part of the projected state every reader sees. |
| A rule that rejects bad data                               | The write side, before the event is appended. A read model is derived from facts that already happened; refusing them here is too late to help.                                                                       |

## Design for eventual consistency

[Section titled “Design for eventual consistency”](#design-for-eventual-consistency)

A *materialized* read model updates *after* the event is appended, so what’s stored is [eventually consistent](/chronicle/read-models/consistency/). Design with that in mind: don’t read a stored model back inside a command or reactor to make a decision (use a [constraint](/chronicle/constraints/) for invariants instead), and prefer [observable queries](/chronicle/scenarios/real-time-query/) so the UI reflects changes the moment the projection catches up.

Eventual is the default, though — not a law. Mark the read model `[Passive]` and nothing materializes it, so `IReadModels` computes it from its events on every read — a strongly consistent read that includes an event you appended a millisecond ago:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.ReadModels;

// Passive: no observer materializes this, so Chronicle computes it from the events on every read.
  [Passive]
  public record DesigningReadModelsCustomerDetail(Guid Id, string Name);

public class DesigningReadModelsCustomerDetailService(IEventStore eventStore)
  {
      public Task<DesigningReadModelsCustomerDetail> GetDetail(Guid customerId) =>
          eventStore.ReadModels.GetInstanceById<DesigningReadModelsCustomerDetail>(customerId);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore

data class DesigningReadModelsCustomerDetail(val id: String, val name: String)

class DesigningReadModelsCustomerDetailService(private val store: IEventStore) {
      suspend fun getDetail(customerId: String): DesigningReadModelsCustomerDetail? =
          store.readModels.getInstanceByKey(DesigningReadModelsCustomerDetail::class, customerId)
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingEventStore;

record DesigningReadModelsCustomerDetail(String id, String name) {}

class DesigningReadModelsCustomerDetailService {
      private final BlockingEventStore store;

DesigningReadModelsCustomerDetailService(IEventStore store) {
          this.store = new BlockingEventStore(store);
      }

DesigningReadModelsCustomerDetail getDetail(String customerId) {
          return store.getReadModels()
              .getInstanceByKey(DesigningReadModelsCustomerDetail.class, customerId);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.DesigningReadModelsCustomerDetail do
    defstruct [:id, :name]
  end

defmodule MyApp.DesigningReadModelsCustomerDetailService do
    alias MyApp.ReadModels.DesigningReadModelsCustomerDetail

def get_detail(customer_id) do
      Chronicle.read_model(DesigningReadModelsCustomerDetail, customer_id)
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

class DesigningReadModelsCustomerDetail {
      constructor(
          readonly id: string,
          readonly name: string
      ) {}
  }

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

getDetail(customerId: string): Promise<DesigningReadModelsCustomerDetail> {
          return this.store.readModels.getInstanceById(DesigningReadModelsCustomerDetail, customerId);
      }
  }
  ```

The call site is the same either way; the read model’s own declaration decides where the answer comes from. [Deep dive: consistency](/chronicle/concepts/consistency/) covers when each model is the right call.

## Query it

[Section titled “Query it”](#query-it)

When it’s time to read, Chronicle gives you a ladder — trade consistency for cost as you descend:

* C#

```csharp
  using Cratis.Chronicle;

public record DesigningReadModelsCustomerListItem(Guid Id, string Name);

public class DesigningReadModelsCustomerListService(IEventStore eventStore)
  {
      public async Task<IEnumerable<DesigningReadModelsCustomerListItem>> GetEveryInstance()
      {
          // Every instance in one call — read from the materialized store
          return await eventStore.ReadModels.GetInstances<DesigningReadModelsCustomerListItem>();
      }

public async Task<IEnumerable<DesigningReadModelsCustomerListItem>> GetPage()
      {
          // One page of materialized instances, with paging done by the store
          return await eventStore.ReadModels.Materialized.GetInstances<DesigningReadModelsCustomerListItem>(skip: 0, take: 20);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class DesigningReadModelsCustomerListItem(val id: String = "", val name: String = "")

// Every instance in one call — read from the materialized store
  suspend fun getEveryInstance(store: IEventStore) =
      store.readModels.getInstances(DesigningReadModelsCustomerListItem::class)

// One page of materialized instances, with paging done by the store
  suspend fun getPage(store: IEventStore) =
      store.readModels.materialized.getInstances(DesigningReadModelsCustomerListItem::class, skip = 0, take = 20)
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;

import java.util.List;

@ReadModel
  class DesigningReadModelsCustomerListItem {
      private String id = "";
      private String name = "";

public DesigningReadModelsCustomerListItem() {}

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getName() { return name; }
      public void setName(String name) { this.name = name; }
  }

class DesigningReadModelsCustomerListService {
      // Every instance in one call — read from the materialized store
      List<DesigningReadModelsCustomerListItem> getEveryInstance(EventStore store) {
          return ReadModelsJavaBridge.getInstances(store.getReadModels(), DesigningReadModelsCustomerListItem.class);
      }

// One page of materialized instances, with paging done by the store
      List<DesigningReadModelsCustomerListItem> getPage(EventStore store) {
          return ReadModelsJavaBridge.getMaterializedInstances(store.getReadModels(), DesigningReadModelsCustomerListItem.class, 0, 20);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.DesigningReadModelsCustomerListItem do
    defstruct [:id, :name]
  end

defmodule MyApp.DesigningReadModelsCustomerListService do
    alias MyApp.ReadModels.DesigningReadModelsCustomerListItem

def get_all_strongly_consistent do
      # Strongly consistent — Chronicle replays the read model's events on demand
      Chronicle.all(DesigningReadModelsCustomerListItem)
    end

def get_page_eventually_consistent do
      # Eventually consistent — a page of materialized instances straight from storage
      Chronicle.ReadModels.query(DesigningReadModelsCustomerListItem, page: 1, page_size: 20)
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

class DesigningReadModelsCustomerListItem {
      constructor(
          readonly id: string,
          readonly name: string
      ) {}
  }

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

// Strongly consistent — Chronicle replays the read model's events on demand
      getAllStronglyConsistent(): Promise<DesigningReadModelsCustomerListItem[]> {
          return this.store.readModels.getInstances(DesigningReadModelsCustomerListItem);
      }

// Eventually consistent — a page of materialized instances straight from storage
      getPageEventuallyConsistent(): Promise<DesigningReadModelsCustomerListItem[]> {
          return this.store.readModels.materialized.getInstances(DesigningReadModelsCustomerListItem, 0, 20);
      }
  }
  ```

- **`GetInstances<T>()`** returns every instance in one call — read from the materialized store, or rebuilt from the event log when the read model is `[Passive]`. You can force a bounded replay with an event count (`GetInstances<T>(eventCount)`), but a capped replay may return incomplete results. Good for [reporting and small populations](/chronicle/read-models/getting-collection-instances/), not for your production list view.
- **`Materialized.GetInstances<T>(skip, take)`** reads what projections have already stored, with paging — cheap and fast, a moment behind. See [Materialized read models](/chronicle/read-models/materialized-pagination/).
- **Need filtering, sorting, or aggregation?** Go to the sink’s native query tools — `IMongoCollection<T>` or your `DbContext` — because a materialized read model is just data in a [database](/chronicle/sinks/), shaped for exactly this.

Kotlin and Java currently only support the single-instance lookup shown above — there’s no way to get all instances or page through materialized storage from those two clients yet.

## Keep the read side ignorant of the write side

[Section titled “Keep the read side ignorant of the write side”](#keep-the-read-side-ignorant-of-the-write-side)

A projection only knows about events. It must not trigger commands, call external systems, or produce side effects — that’s a [reactor’s](/chronicle/reactors/) job. Keeping projections pure is what makes them safe to replay at any time.

## Where this leads

[Section titled “Where this leads”](#where-this-leads)

* [Read Models](/chronicle/read-models/) — retrieval, snapshots, and consistency in depth.
* [Projections, reducers, and reactors](/chronicle/concepts/observer-patterns/) — how the read side is built.
* [Modeling events well](/chronicle/concepts/modeling-events/) — the source of truth your read models derive from.

# Event

Chronicle is optimized for the scenario of [domain events](https://www.martinfowler.com/eaaDev/DomainEvent.html). Figuring out the correct name of an [event type](/chronicle/concepts/event-type/) and what properties it should have can be hard. This page walks through some general guidance on how to do so. Recommend also reading the [Microsoft guide](https://docs.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/domain-events-design-implementation) on this.

> Note: Read more about the relationship to [event source](/chronicle/concepts/event-source/)

A well-designed event is a single, immutable, past-tense fact. Captured well, the lifecycle of one thing in your domain reads as a sequence of these facts in the order they happened:

```
one person · facts in order, never changed

PersonRegistered

NameChangedForPerson

AddressChangedForPerson
```

## Past tense

[Section titled “Past tense”](#past-tense)

All events should be named as past tense, something that has happened:

* ItemAddedToCart
* UserRegistered
* AddressChangedForPerson

## Singular purpose

[Section titled “Singular purpose”](#singular-purpose)

An event should never be ambiguous. It should have a clear meaning and purpose. It should not be holding information for multiple purposes. For instance holding properties that are empty and only used for specific purposes. Doing so makes the event unclear to reason about and requires logic in all observers and consumers of the event.

## Immutable

[Section titled “Immutable”](#immutable)

In an event sourced system, events are considered immutable because they represent facts that have occurred in the past. Once an event is recorded, it should not be altered, as doing so would compromise the integrity and reliability of the event log. Immutability ensures that the history of changes is preserved accurately, allowing the system to reconstruct past states and understand the sequence of events that led to the current state. This immutability is crucial for debugging, auditing, and maintaining a consistent and trustworthy system.

## Avoid nullables / empty values

[Section titled “Avoid nullables / empty values”](#avoid-nullables--empty-values)

An event has happened, and it should not represent unclear states. As with singular purpose, nullable properties are open for interpretation and require extra logic for every observer and consumer of the event.

Chronicle supports nullable properties on event types when needed. However, consider this a design smell and prefer introducing a new event type when the meaning differs. The .NET analyzer rule [CHR0012](/chronicle/code-analysis/chr0012/) warns when nullable event properties are used so you can review the design choice.

> Note: There are conditions where it makes sense to allow null, typical data collection scenario might be the case. For instance, a person might not have a middle name.

## Cohesion

[Section titled “Cohesion”](#cohesion)

Figuring out how “big” an event should be can be even harder. The things that needs to go together to represent a meaningful change in the system should constitute the boundaries. If we take a system that holds personal details, the name and social security numbers would be separate from the address.

Below are some samples of events.

### PersonRegistered

[Section titled “PersonRegistered”](#personregistered)

During registration, it might be necessary to capture all the details about a person as below:

```json
{
    "socialSecurityNumber": "12345678901",
    "firstName": "John",
    "middleName": "David",
    "lastName": "Doe",
    "address": "32nd & Main street",
    "postalCode": "123456",
    "city": "Somewhere",
    "country": "Atlantis"
}
```

### NameChangedForPerson

[Section titled “NameChangedForPerson”](#namechangedforperson)

Once registered, changing the name could then only be:

```json
{
    "firstName": "John",
    "middleName": "David",
    "lastName": "Doe"
}
```

### AddressChangedForPerson

[Section titled “AddressChangedForPerson”](#addresschangedforperson)

Similar for address:

```json
{
    "address": "32nd & Main street",
    "postalCode": "123456",
    "city": "Somewhere",
    "country": "Atlantis"
}
```

## Integrations

[Section titled “Integrations”](#integrations)

When integrating with systems that are non event sourced you would need to deduct the event types from the data structure. The same approach applies for defining the events as described in this document.

## Event discovery

[Section titled “Event discovery”](#event-discovery)

There are a couple of well known approaches to discovering events in your domain; [Event Storming](https://www.eventstorming.com) and [Event Modelling](https://eventmodeling.org). We tend to favor the latter as it has more focused building blocks. It gives a good overview of a an entire system and the flows in it.

# Event Metadata Tags

Event metadata tags provide a structured way to categorize and identify events within the Chronicle system. Below are the formalized tags available:

## EventSourceType

[Section titled “EventSourceType”](#eventsourcetype)

* **Description**: Overarching, binding concept (e.g., Account).

## EventSourceId

[Section titled “EventSourceId”](#eventsourceid)

* **Description**: Unique identifier for the event source.

## EventStreamType

[Section titled “EventStreamType”](#eventstreamtype)

* **Description**: A concrete process related to event source type (e.g., Onboarding, Transactions). Automatically linked to an AggregateRoot in Chronicle.

## EventStreamId

[Section titled “EventStreamId”](#eventstreamid)

* **Description**: A marker that can be used to separate independent streams for a stream type (e.g., Monthly, Yearly).

# Event Sequence

Chronicle has the concept of event sequences. These can be looked upon as collections of events. Every event gets assigned an incremental unique sequence number, this if the sequence number that [observers](/chronicle/concepts/observers/) uses to maintain their offset.

With every event, Chronicle collects additional metadata that is stored together with the event.

A sequence is the timeline of your system — events laid out in the order they happened, each at a fixed sequence number that never changes:

```
reads next

#0 BookAdded

#1 BookBorrowed

#2 BookReturned

#3 BookBorrowed

Observer (offset: #2)
```

The observer’s offset is just a sequence number — it remembers how far it has read, and picks up from there when new events arrive.

Chronicle has formalized the following event sequences:

| Type      |  Description                              |
| --------- | ----------------------------------------- |
| Event Log | The main sequence you typically append to |

## Event Type generations

[Section titled “Event Type generations”](#event-type-generations)

Every [event type](/chronicle/concepts/event-type/) can evolve over time. Evolutions are represented as generations. The `content` property stores event content per generation, allowing for a perfect audit trail of the events and its evolution and at the same time also supporting scenarios of delivering different versions of the events, depending on the observer.

## Revisions

[Section titled “Revisions”](#revisions)

An event sequence is append only, meaning that we do not delete anything within a sequence. Changing the content of an event is also not supported by Chronicle, instead one should perform revisions.

Revisions are replacements of the original event instance and are in fact the same event type and are stored together with the original event it replaces. Every revision is stored with the same type of metadata as for the root event.

This approach help us guarantee a perfect audit trail of the system.

> Note: Revisions are not fully implemented yet, there is no API surface for it. Internally Chronicle has been prepared for it and that is why you’ll see the revisions array on every event.

# Event Source

An event source can be viewed as instance grouping together all state changes to form a story for the particular entity in your domain. Each state change is represented as an event. With each event being completely autonomous and representing a just its part of the truth, the event source identifier is (`EventSourceId`) what what binds it together.

For instance, take the notion of a person. What identifies the person uniquely is in many systems the **social security number** assigned by the government for all residents. All state changes relevant for an instance of a person should be identified by this unique identifier, this is what we call an **event source id**.

It can be compared to the **primary key** often used in database modelling.

The diagram below shows two event sources — two people — each with its own ordered story of events, all sharing the same event source id throughout:

```
EventSourceId: person-456

PersonRegistered

NameCorrected

EventSourceId: person-123

PersonRegistered

AddressChanged

PhoneChanged
```

When events are appended in Chronicle, you’ll see that the first argument is the `EventSourceId`.

# Event Store

Chronicle offers what is called an event store which basically means a special purpose database for storing events. The events are stored in [event sequences](/chronicle/concepts/event-sequence/).

In addition to this, the Chronicle event store also maintains information about things like the [event types](/chronicle/concepts/event-type/), [observers](/chronicle/concepts/observers/), [projections](/chronicle/concepts/projection/) and more.

The Chronicle event store is built on top of [MongoDB](https://mongodb.com). In a production environment you have to bring your own MongoDB environment and configure Chronicle to work with it. For local development, Chronicle provides a development Docker image that comes with MongoDB bundled inside it.

```
append · read

Event store

tenant-a namespace

event sequences

Default namespace

event sequences (the event log)

also tracks: event types · observers · projections · …

Your application

MongoDB
```

## Namespaces

[Section titled “Namespaces”](#namespaces)

Every event store can have [namespaces](/chronicle/concepts/namespaces/). The namespaces provides a way to segregate data that is specific for a partition. Typically, a namespace can be used for multi-tenancy.

By default, Chronicle will use the **Default** namespace if a namespace is not provided.

# Event Type

Every [event](/chronicle/concepts/event/) stored in the [event store](/chronicle/concepts/event-store/) must have a type associated with it.

Any client connecting to Chronicle needs to communicate the event types before any events can be appended to an [event sequence](/chronicle/concepts/event-sequence/).

An event type can contain multiple generations. Every new event starts with generation 1 and any changes to the event should then become a new generation. This allows versioning your event types so that multiple schema generations can coexist in the same event store.

The concept of generations is important when working with systems that evolve over time. Each generation registers its own JSON schema, which Chronicle uses to validate and store events correctly for that generation.

```
migration

migration

Event type: PersonRegistered

Generation 1 + JSON schema

Generation 2 + JSON schema

Generation 3 + JSON schema
```

You keep the record for every past generation in your codebase alongside the current one. The recommended way to declare a previous generation is `[EventTypeGenerationFor<T>]`, where `T` is the current generation’s type — Chronicle resolves the shared event type id from `T`’s own `[EventType]`, so the previous generation never carries (and can never mistype) an id of its own.

For detailed information on how to define and use migrations — including this attribute, the older explicit-id style it replaces, and the operations available for transforming events between generations — see [Event Type Migrations](/chronicle/concepts/event-type-migrations/).

# Event Type Migrations

Event type migrations enable you to evolve your event schemas over time while maintaining compatibility with existing events. When an event type changes, you can define **upcasters** and **downcasters** that automatically transform events between different generations.

## Why Migrations?

[Section titled “Why Migrations?”](#why-migrations)

In evolving systems, event schemas naturally change:

* Properties are added or removed
* Properties are renamed
* Complex properties are split or combined

Chronicle’s migration system allows you to:

1. Define declarative transformation rules
2. Automatically store all generations of an event when appending
3. Read events in any generation format

## Defining Migrations

[Section titled “Defining Migrations”](#defining-migrations)

To define a migration, extend the `EventTypeMigration<TUpgrade, TPrevious>` base class (it handles generation extraction and validation for you) and override `Upcast`/`Downcast`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("author-registered", generation: 2)]
  public record MigrationsAuthorRegistered(string FirstName, string LastName);

[EventTypeGenerationFor<MigrationsAuthorRegistered>(1)]
  public record MigrationsAuthorRegisteredV1(string Name);

public class MigrationsAuthorRegisteredMigration : EventTypeMigration<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1> builder) =>
          builder.Properties(pb => pb
              .Split(m => m.FirstName, e => e.Name, PropertySeparator.Space, SplitPartIndex.First)
              .Split(m => m.LastName, e => e.Name, PropertySeparator.Space, SplitPartIndex.Second));

public override void Downcast(IEventMigrationBuilder<MigrationsAuthorRegisteredV1, MigrationsAuthorRegistered> builder) =>
          builder.Properties(pb => pb
              .Combine(m => m.Name, PropertySeparator.Space, e => e.FirstName, e => e.LastName));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "author-registered", generation = 2)
  data class MigrationsAuthorRegistered(val firstName: String, val lastName: String)

@EventType(id = "author-registered", generation = 1)
  data class MigrationsAuthorRegisteredV1(val name: String)

class MigrationsAuthorRegisteredMigration :
      EventTypeMigration<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1>(
          MigrationsAuthorRegistered::class,
          MigrationsAuthorRegisteredV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1>) {
          builder
              .split(MigrationsAuthorRegistered::firstName, MigrationsAuthorRegisteredV1::name, " ", 0)
              .split(MigrationsAuthorRegistered::lastName, MigrationsAuthorRegisteredV1::name, " ", 1)
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsAuthorRegisteredV1, MigrationsAuthorRegistered>) {
          builder.combine(MigrationsAuthorRegisteredV1::name, " ", MigrationsAuthorRegistered::firstName, MigrationsAuthorRegistered::lastName)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "author-registered", generation = 2)
  record MigrationsAuthorRegistered(String firstName, String lastName) {
  }

@EventType(id = "author-registered", generation = 1)
  record MigrationsAuthorRegisteredV1(String name) {
  }

class MigrationsAuthorRegisteredMigration
          extends EventTypeMigration<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1> {
      MigrationsAuthorRegisteredMigration() {
          super(MigrationsAuthorRegistered.class, MigrationsAuthorRegisteredV1.class);
      }

@Override
      public void upcast(EventTypeMigrationBuilder<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1> builder) {
          builder
              .split("firstName", "name", " ", 0)
              .split("lastName", "name", " ", 1);
      }

@Override
      public void downcast(EventTypeMigrationBuilder<MigrationsAuthorRegisteredV1, MigrationsAuthorRegistered> builder) {
          builder.combine("name", " ", "firstName", "lastName");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsAuthorRegisteredV1 do
    use Chronicle.Events.EventType, id: "author-registered", generation: 1

defstruct [:name]
  end

defmodule MyApp.Events.MigrationsAuthorRegistered do
    use Chronicle.Events.EventType, id: "author-registered", generation: 2

defstruct [:first_name, :last_name]
  end

defmodule MyApp.Migrations.MigrationsAuthorRegisteredMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsAuthorRegisteredV1, generation: 1},
      to: {MyApp.Events.MigrationsAuthorRegistered, generation: 2}

alias Chronicle.Events.MigrationBuilder

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

@impl true
    def downcast(builder) do
      builder
      |> MigrationBuilder.combine_properties([:first_name, :last_name], :name, " ")
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
  class MigrationsAuthorRegisteredV1 {
      constructor(readonly name: string) {}
  }

@eventType('author-registered', 2)
  class MigrationsAuthorRegistered {
      constructor(
          readonly firstName: string,
          readonly lastName: string
      ) {}
  }

@eventTypeMigration(MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1)
  class MigrationsAuthorRegisteredMigration implements IEventTypeMigration<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsAuthorRegistered, MigrationsAuthorRegisteredV1>): void {
          builder.properties(pb => pb
              .split('firstName', 'name', ' ', 0)
              .split('lastName', 'name', ' ', 1));
      }

downcast(builder: IEventMigrationBuilder<MigrationsAuthorRegisteredV1, MigrationsAuthorRegistered>): void {
          builder.properties(pb => pb
              .combine('name', ' ', 'firstName', 'lastName'));
      }
  }
  ```

The previous generation, `MigrationsAuthorRegisteredV1`, carries `[EventTypeGenerationFor<MigrationsAuthorRegistered>(1)]` instead of its own `[EventType]`. The event type id it resolves to comes straight from `MigrationsAuthorRegistered`’s own `[EventType]` — it is never independently typed on the previous-generation record, so the two generations cannot drift apart by a hand-typed, mismatched id.

The old style still works

You can still put an explicit, matching `[EventType("id", generation: N)]` on every generation — this is fully backward compatible, not deprecated. But both ids must be **identical, explicit strings**. Omit the id on a previous generation and it silently defaults to the CLR type name (`"MigrationsAuthorRegisteredV1"`), which Chronicle then treats as an entirely unrelated event type — the migration never applies, and registration fails at kernel startup with a confusing `EventTypeSchemaChanged` error. `[EventTypeGenerationFor<T>]` removes this failure mode structurally, which is why it is the recommended default for any new previous generation.

## Migration Operations

[Section titled “Migration Operations”](#migration-operations)

The migration builder supports the following operations:

### Split

[Section titled “Split”](#split)

Splits a source property into parts using a separator:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("person-registered", generation: 2)]
  public record MigrationsSplitPersonRegistered(string FirstName, string LastName);

[EventTypeGenerationFor<MigrationsSplitPersonRegistered>(1)]
  public record MigrationsSplitPersonRegisteredV1(string FullName);

public class MigrationsSplitPersonRegisteredMigration : EventTypeMigration<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1> builder) =>
          builder.Properties(pb => pb
              .Split(m => m.FirstName, e => e.FullName, PropertySeparator.Space, SplitPartIndex.First) // Gets first part
              .Split(m => m.LastName, e => e.FullName, PropertySeparator.Space, SplitPartIndex.Second)); // Gets second part

public override void Downcast(IEventMigrationBuilder<MigrationsSplitPersonRegisteredV1, MigrationsSplitPersonRegistered> builder) =>
          builder.Properties(pb => pb
              .Combine(m => m.FullName, PropertySeparator.Space, e => e.FirstName, e => e.LastName));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "person-registered", generation = 2)
  data class MigrationsSplitPersonRegistered(val firstName: String, val lastName: String)

@EventType(id = "person-registered", generation = 1)
  data class MigrationsSplitPersonRegisteredV1(val fullName: String)

class MigrationsSplitPersonRegisteredMigration :
      EventTypeMigration<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1>(
          MigrationsSplitPersonRegistered::class,
          MigrationsSplitPersonRegisteredV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1>) {
          builder
              .split(MigrationsSplitPersonRegistered::firstName, MigrationsSplitPersonRegisteredV1::fullName, " ", 0) // Gets first part
              .split(MigrationsSplitPersonRegistered::lastName, MigrationsSplitPersonRegisteredV1::fullName, " ", 1) // Gets second part
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsSplitPersonRegisteredV1, MigrationsSplitPersonRegistered>) {
          builder.combine(MigrationsSplitPersonRegisteredV1::fullName, " ", MigrationsSplitPersonRegistered::firstName, MigrationsSplitPersonRegistered::lastName)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "person-registered", generation = 2)
  record MigrationsSplitPersonRegistered(String firstName, String lastName) {
  }

@EventType(id = "person-registered", generation = 1)
  record MigrationsSplitPersonRegisteredV1(String fullName) {
  }

class MigrationsSplitPersonRegisteredMigration
          extends EventTypeMigration<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1> {
      MigrationsSplitPersonRegisteredMigration() {
          super(MigrationsSplitPersonRegistered.class, MigrationsSplitPersonRegisteredV1.class);
      }

@Override
      public void upcast(
              EventTypeMigrationBuilder<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1> builder) {
          builder
              .split("firstName", "fullName", " ", 0)  // Gets first part
              .split("lastName", "fullName", " ", 1);  // Gets second part
      }

@Override
      public void downcast(
              EventTypeMigrationBuilder<MigrationsSplitPersonRegisteredV1, MigrationsSplitPersonRegistered> builder) {
          builder.combine("fullName", " ", "firstName", "lastName");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsSplitPersonRegisteredV1 do
    use Chronicle.Events.EventType, id: "person-registered", generation: 1

defstruct [:full_name]
  end

defmodule MyApp.Events.MigrationsSplitPersonRegistered do
    use Chronicle.Events.EventType, id: "person-registered", generation: 2

defstruct [:first_name, :last_name]
  end

defmodule MyApp.Migrations.MigrationsSplitPersonRegisteredMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsSplitPersonRegisteredV1, generation: 1},
      to: {MyApp.Events.MigrationsSplitPersonRegistered, generation: 2}

alias Chronicle.Events.MigrationBuilder

@impl true
    def upcast(builder) do
      builder
      # Gets first part
      |> MigrationBuilder.split_property(:full_name, :first_name, " ", 0)
      # Gets second part
      |> MigrationBuilder.split_property(:full_name, :last_name, " ", 1)
    end

@impl true
    def downcast(builder) do
      builder
      |> MigrationBuilder.combine_properties([:first_name, :last_name], :full_name, " ")
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
  class MigrationsSplitPersonRegisteredV1 {
      constructor(readonly fullName: string) {}
  }

@eventType('person-registered', 2)
  class MigrationsSplitPersonRegistered {
      constructor(
          readonly firstName: string,
          readonly lastName: string
      ) {}
  }

@eventTypeMigration(MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1)
  class MigrationsSplitPersonRegisteredMigration implements IEventTypeMigration<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsSplitPersonRegistered, MigrationsSplitPersonRegisteredV1>): void {
          builder.properties(pb => pb
              .split('firstName', 'fullName', ' ', 0) // Gets first part
              .split('lastName', 'fullName', ' ', 1)); // Gets second part
      }

downcast(builder: IEventMigrationBuilder<MigrationsSplitPersonRegisteredV1, MigrationsSplitPersonRegistered>): void {
          builder.properties(pb => pb
              .combine('fullName', ' ', 'firstName', 'lastName'));
      }
  }
  ```

### Combine

[Section titled “Combine”](#combine)

Combines multiple source properties into a single value using a separator:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("shipping-address-recorded", generation: 2)]
  public record MigrationsCombineShippingAddressRecorded(string FormattedAddress);

[EventTypeGenerationFor<MigrationsCombineShippingAddressRecorded>(1)]
  public record MigrationsCombineShippingAddressRecordedV1(string Street, string City);

public class MigrationsCombineShippingAddressRecordedMigration : EventTypeMigration<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1> builder) =>
          builder.Properties(pb => pb
              .Combine(m => m.FormattedAddress, PropertySeparator.Space, e => e.Street, e => e.City)); // Joins with space separator

public override void Downcast(IEventMigrationBuilder<MigrationsCombineShippingAddressRecordedV1, MigrationsCombineShippingAddressRecorded> builder) =>
          builder.Properties(pb => pb
              .Split(m => m.Street, e => e.FormattedAddress, PropertySeparator.Space, SplitPartIndex.First)
              .Split(m => m.City, e => e.FormattedAddress, PropertySeparator.Space, SplitPartIndex.Second));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "shipping-address-recorded", generation = 2)
  data class MigrationsCombineShippingAddressRecorded(val formattedAddress: String)

@EventType(id = "shipping-address-recorded", generation = 1)
  data class MigrationsCombineShippingAddressRecordedV1(val street: String, val city: String)

class MigrationsCombineShippingAddressRecordedMigration :
      EventTypeMigration<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1>(
          MigrationsCombineShippingAddressRecorded::class,
          MigrationsCombineShippingAddressRecordedV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1>) {
          // Joins with space separator
          builder.combine(
              MigrationsCombineShippingAddressRecorded::formattedAddress,
              " ",
              MigrationsCombineShippingAddressRecordedV1::street,
              MigrationsCombineShippingAddressRecordedV1::city
          )
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsCombineShippingAddressRecordedV1, MigrationsCombineShippingAddressRecorded>) {
          builder
              .split(MigrationsCombineShippingAddressRecordedV1::street, MigrationsCombineShippingAddressRecorded::formattedAddress, " ", 0)
              .split(MigrationsCombineShippingAddressRecordedV1::city, MigrationsCombineShippingAddressRecorded::formattedAddress, " ", 1)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "shipping-address-recorded", generation = 2)
  record MigrationsCombineShippingAddressRecorded(String formattedAddress) {
  }

@EventType(id = "shipping-address-recorded", generation = 1)
  record MigrationsCombineShippingAddressRecordedV1(String street, String city) {
  }

class MigrationsCombineShippingAddressRecordedMigration
          extends EventTypeMigration<MigrationsCombineShippingAddressRecorded,
                                     MigrationsCombineShippingAddressRecordedV1> {
      MigrationsCombineShippingAddressRecordedMigration() {
          super(MigrationsCombineShippingAddressRecorded.class, MigrationsCombineShippingAddressRecordedV1.class);
      }

@Override
      public void upcast(EventTypeMigrationBuilder<MigrationsCombineShippingAddressRecorded,
                                                   MigrationsCombineShippingAddressRecordedV1> builder) {
          // Joins with space separator
          builder.combine("formattedAddress", " ", "street", "city");
      }

@Override
      public void downcast(EventTypeMigrationBuilder<MigrationsCombineShippingAddressRecordedV1,
                                                     MigrationsCombineShippingAddressRecorded> builder) {
          builder
              .split("street", "formattedAddress", " ", 0)
              .split("city", "formattedAddress", " ", 1);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsCombineShippingAddressRecordedV1 do
    use Chronicle.Events.EventType, id: "shipping-address-recorded", generation: 1

defstruct [:street, :city]
  end

defmodule MyApp.Events.MigrationsCombineShippingAddressRecorded do
    use Chronicle.Events.EventType, id: "shipping-address-recorded", generation: 2

defstruct [:formatted_address]
  end

defmodule MyApp.Migrations.MigrationsCombineShippingAddressRecordedMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsCombineShippingAddressRecordedV1, generation: 1},
      to: {MyApp.Events.MigrationsCombineShippingAddressRecorded, generation: 2}

alias Chronicle.Events.MigrationBuilder

@impl true
    def upcast(builder) do
      builder
      # Joins with space separator
      |> MigrationBuilder.combine_properties([:street, :city], :formatted_address, " ")
    end

@impl true
    def downcast(builder) do
      builder
      |> MigrationBuilder.split_property(:formatted_address, :street, " ", 0)
      |> MigrationBuilder.split_property(:formatted_address, :city, " ", 1)
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
  class MigrationsCombineShippingAddressRecordedV1 {
      constructor(
          readonly street: string,
          readonly city: string
      ) {}
  }

@eventType('shipping-address-recorded', 2)
  class MigrationsCombineShippingAddressRecorded {
      constructor(readonly formattedAddress: string) {}
  }

@eventTypeMigration(MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1)
  class MigrationsCombineShippingAddressRecordedMigration implements IEventTypeMigration<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsCombineShippingAddressRecorded, MigrationsCombineShippingAddressRecordedV1>): void {
          builder.properties(pb => pb
              .combine('formattedAddress', ' ', 'street', 'city')); // Joins with space separator
      }

downcast(builder: IEventMigrationBuilder<MigrationsCombineShippingAddressRecordedV1, MigrationsCombineShippingAddressRecorded>): void {
          builder.properties(pb => pb
              .split('street', 'formattedAddress', ' ', 0)
              .split('city', 'formattedAddress', ' ', 1));
      }
  }
  ```

### Rename

[Section titled “Rename”](#rename)

Renames a property from a previous name using `RenamedFrom`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("payment-processed", generation: 2)]
  public record MigrationsRenamePaymentProcessed(decimal Amount);

[EventTypeGenerationFor<MigrationsRenamePaymentProcessed>(1)]
  public record MigrationsRenamePaymentProcessedV1(decimal OldAmount);

public class MigrationsRenamePaymentProcessedMigration : EventTypeMigration<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1> builder) =>
          builder.Properties(pb => pb
              .RenamedFrom(m => m.Amount, e => e.OldAmount));

public override void Downcast(IEventMigrationBuilder<MigrationsRenamePaymentProcessedV1, MigrationsRenamePaymentProcessed> builder) =>
          builder.Properties(pb => pb
              .RenamedFrom(m => m.OldAmount, e => e.Amount));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "payment-processed", generation = 2)
  data class MigrationsRenamePaymentProcessed(val amount: Double)

@EventType(id = "payment-processed", generation = 1)
  data class MigrationsRenamePaymentProcessedV1(val oldAmount: Double)

class MigrationsRenamePaymentProcessedMigration :
      EventTypeMigration<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1>(
          MigrationsRenamePaymentProcessed::class,
          MigrationsRenamePaymentProcessedV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1>) {
          builder.renamedFrom(MigrationsRenamePaymentProcessed::amount, MigrationsRenamePaymentProcessedV1::oldAmount)
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsRenamePaymentProcessedV1, MigrationsRenamePaymentProcessed>) {
          builder.renamedFrom(MigrationsRenamePaymentProcessedV1::oldAmount, MigrationsRenamePaymentProcessed::amount)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "payment-processed", generation = 2)
  record MigrationsRenamePaymentProcessed(double amount) {
  }

@EventType(id = "payment-processed", generation = 1)
  record MigrationsRenamePaymentProcessedV1(double oldAmount) {
  }

class MigrationsRenamePaymentProcessedMigration
          extends EventTypeMigration<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1> {
      MigrationsRenamePaymentProcessedMigration() {
          super(MigrationsRenamePaymentProcessed.class, MigrationsRenamePaymentProcessedV1.class);
      }

@Override
      public void upcast(
              EventTypeMigrationBuilder<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1> builder) {
          builder.renamedFrom("amount", "oldAmount");
      }

@Override
      public void downcast(
              EventTypeMigrationBuilder<MigrationsRenamePaymentProcessedV1, MigrationsRenamePaymentProcessed> builder) {
          builder.renamedFrom("oldAmount", "amount");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsRenamePaymentProcessedV1 do
    use Chronicle.Events.EventType, id: "payment-processed", generation: 1

defstruct [:old_amount]
  end

defmodule MyApp.Events.MigrationsRenamePaymentProcessed do
    use Chronicle.Events.EventType, id: "payment-processed", generation: 2

defstruct [:amount]
  end

defmodule MyApp.Migrations.MigrationsRenamePaymentProcessedMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsRenamePaymentProcessedV1, generation: 1},
      to: {MyApp.Events.MigrationsRenamePaymentProcessed, generation: 2}

alias Chronicle.Events.MigrationBuilder

@impl true
    def upcast(builder) do
      builder
      |> MigrationBuilder.rename_property(:old_amount, :amount)
    end

@impl true
    def downcast(builder) do
      builder
      |> MigrationBuilder.rename_property(:amount, :old_amount)
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
  class MigrationsRenamePaymentProcessedV1 {
      constructor(readonly oldAmount: number) {}
  }

@eventType('payment-processed', 2)
  class MigrationsRenamePaymentProcessed {
      constructor(readonly amount: number) {}
  }

@eventTypeMigration(MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1)
  class MigrationsRenamePaymentProcessedMigration implements IEventTypeMigration<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsRenamePaymentProcessed, MigrationsRenamePaymentProcessedV1>): void {
          builder.properties(pb => pb
              .renamedFrom('amount', 'oldAmount'));
      }

downcast(builder: IEventMigrationBuilder<MigrationsRenamePaymentProcessedV1, MigrationsRenamePaymentProcessed>): void {
          builder.properties(pb => pb
              .renamedFrom('oldAmount', 'amount'));
      }
  }
  ```

### Default Value

[Section titled “Default Value”](#default-value)

Sets a default value for a new property:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("order-shipped", generation: 2)]
  public record MigrationsDefaultValueOrderShipped(string TrackingNumber, int RetryCount, string Description);

[EventTypeGenerationFor<MigrationsDefaultValueOrderShipped>(1)]
  public record MigrationsDefaultValueOrderShippedV1(string TrackingNumber);

public class MigrationsDefaultValueOrderShippedMigration : EventTypeMigration<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1> builder) =>
          builder.Properties(pb => pb
              .DefaultValue(m => m.RetryCount, 42)
              .DefaultValue(m => m.Description, "default string"));

public override void Downcast(IEventMigrationBuilder<MigrationsDefaultValueOrderShippedV1, MigrationsDefaultValueOrderShipped> builder)
      {
          // RetryCount and Description did not exist in generation 1 — nothing to map back
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "order-shipped", generation = 2)
  data class MigrationsDefaultValueOrderShipped(val trackingNumber: String, val retryCount: Int, val description: String)

@EventType(id = "order-shipped", generation = 1)
  data class MigrationsDefaultValueOrderShippedV1(val trackingNumber: String)

class MigrationsDefaultValueOrderShippedMigration :
      EventTypeMigration<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1>(
          MigrationsDefaultValueOrderShipped::class,
          MigrationsDefaultValueOrderShippedV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1>) {
          builder
              .defaultValue(MigrationsDefaultValueOrderShipped::retryCount, 42)
              .defaultValue(MigrationsDefaultValueOrderShipped::description, "default string")
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsDefaultValueOrderShippedV1, MigrationsDefaultValueOrderShipped>) {
          // retryCount and description did not exist in generation 1 — nothing to map back
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "order-shipped", generation = 2)
  record MigrationsDefaultValueOrderShipped(String trackingNumber, int retryCount, String description) {
  }

@EventType(id = "order-shipped", generation = 1)
  record MigrationsDefaultValueOrderShippedV1(String trackingNumber) {
  }

class MigrationsDefaultValueOrderShippedMigration
          extends EventTypeMigration<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1> {
      MigrationsDefaultValueOrderShippedMigration() {
          super(MigrationsDefaultValueOrderShipped.class, MigrationsDefaultValueOrderShippedV1.class);
      }

@Override
      public void upcast(
              EventTypeMigrationBuilder<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1> builder) {
          builder
              .defaultValue("retryCount", 42)
              .defaultValue("description", "default string");
      }

@Override
      public void downcast(
              EventTypeMigrationBuilder<MigrationsDefaultValueOrderShippedV1, MigrationsDefaultValueOrderShipped> builder) {
          // retryCount and description did not exist in generation 1 — nothing to map back
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsDefaultValueOrderShippedV1 do
    use Chronicle.Events.EventType, id: "order-shipped", generation: 1

defstruct [:tracking_number]
  end

defmodule MyApp.Events.MigrationsDefaultValueOrderShipped do
    use Chronicle.Events.EventType, id: "order-shipped", generation: 2

defstruct [:tracking_number, :retry_count, :description]
  end

defmodule MyApp.Migrations.MigrationsDefaultValueOrderShippedMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsDefaultValueOrderShippedV1, generation: 1},
      to: {MyApp.Events.MigrationsDefaultValueOrderShipped, generation: 2}

alias Chronicle.Events.MigrationBuilder

@impl true
    def upcast(builder) do
      builder
      |> MigrationBuilder.default_value(:retry_count, 42)
      |> MigrationBuilder.default_value(:description, "default string")
    end

@impl true
    def downcast(builder) do
      # retry_count and description did not exist in generation 1 — nothing to map back
      builder
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventTypeMigration, IEventMigrationBuilder } from '@cratis/chronicle';

@eventType()
  class MigrationsDefaultValueOrderShippedV1 {
      constructor(readonly trackingNumber: string) {}
  }

@eventType('order-shipped', 2)
  class MigrationsDefaultValueOrderShipped {
      constructor(
          readonly trackingNumber: string,
          readonly retryCount: number,
          readonly description: string
      ) {}
  }

@eventTypeMigration(MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1)
  class MigrationsDefaultValueOrderShippedMigration implements IEventTypeMigration<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsDefaultValueOrderShipped, MigrationsDefaultValueOrderShippedV1>): void {
          builder.properties(pb => pb
              .defaultValue('retryCount', 42)
              .defaultValue('description', 'default string'));
      }

downcast(_builder: IEventMigrationBuilder<MigrationsDefaultValueOrderShippedV1, MigrationsDefaultValueOrderShipped>): void {
          // retryCount and description did not exist in generation 1 — nothing to map back
      }
  }
  ```

### Value map

[Section titled “Value map”](#value-map)

The operations above move values between properties. A **value map** changes the values themselves — it states which value in one generation is which value in the other. This is what you reach for when an enum is renumbered, or a status code takes on a new set of values, and the old numbers now mean something the new generation spells differently.

Override `MapValues` on the migration rather than declaring it inside `Upcast` or `Downcast`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

public enum MigrationsSubscriptionStateV1
  {
      Unknown = 0,
      Active = 1,
      Cancelled = 2
  }

public enum MigrationsSubscriptionState
  {
      Unspecified = 100,
      Running = 101,
      Stopped = 102
  }

[EventType("subscription-state-changed", generation: 2)]
  public record MigrationsSubscriptionStateChanged(MigrationsSubscriptionState State);

[EventTypeGenerationFor<MigrationsSubscriptionStateChanged>(1)]
  public record MigrationsSubscriptionStateChangedV1(MigrationsSubscriptionStateV1 State);

public class MigrationsSubscriptionStateChangedMigration : EventTypeMigration<MigrationsSubscriptionStateChanged, MigrationsSubscriptionStateChangedV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsSubscriptionStateChanged, MigrationsSubscriptionStateChangedV1> builder)
      {
          // The value map covers State in both directions
      }

public override void Downcast(IEventMigrationBuilder<MigrationsSubscriptionStateChangedV1, MigrationsSubscriptionStateChanged> builder)
      {
          // The value map covers State in both directions
      }

public override void MapValues(IEventValueMapBuilder<MigrationsSubscriptionStateChanged, MigrationsSubscriptionStateChangedV1> builder) =>
          builder.For(current => current.State, previous => previous.State, map => map
              .Map(MigrationsSubscriptionStateV1.Unknown, MigrationsSubscriptionState.Unspecified)
              .Map(MigrationsSubscriptionStateV1.Active, MigrationsSubscriptionState.Running)
              .Map(MigrationsSubscriptionStateV1.Cancelled, MigrationsSubscriptionState.Stopped));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

A map declared this way is applied **in both directions**: forward when upcasting, inverted when downcasting. The pair of values is one fact about the two generations, so you state it once and the two directions cannot drift apart.

Three things are worth knowing:

* **Values the map does not mention are carried across unchanged.** A map says what changed meaning; it is not an exhaustive listing of an enum that is free to grow.
* **Two values collapsing onto one have no single inverse**, so the first pair declared for a target value is the one that represents it going back.
* **The map does not have to stay on the same property.** The two property expressions may name different properties, in which case the map also carries the value across — covering a rename and a re-valuing in one statement.

`MapValues` is applied *before* `Upcast` and `Downcast` run, so a direction that states its own transformation for the same property keeps it.

## How Migrations Work

[Section titled “How Migrations Work”](#how-migrations-work)

When an event is appended to the event store:

1. Chronicle identifies the event’s current generation
2. The migration system retrieves all registered migrations for the event type
3. **Upcasting**: If there are higher generations, the event is transformed upward (1→2→3)
4. **Downcasting**: If there are lower generations, the event is transformed downward (3→2→1)
5. All generations are stored in the event sequence

This ensures that:

* Older consumers can still read events in their expected format
* Newer consumers can read events with the latest schema
* No data is lost during schema evolution

## Registration

[Section titled “Registration”](#registration)

Migrations are automatically discovered and registered when you connect to Chronicle. Simply implement `IEventTypeMigrationFor<TEvent>` in your client application, and Chronicle will:

1. Discover all migrators via `IClientArtifactsProvider`
2. Build migration definitions with JmesPath transformations
3. Send the definitions to the kernel during event type registration

## Catching Misuse Early

[Section titled “Catching Misuse Early”](#catching-misuse-early)

Two runtime checks and two [code analysis](/chronicle/code-analysis/) rules exist specifically to stop a broken migration before it ever reaches a real event log:

* **`MigrationGenerationsMustShareEventTypeId`** — thrown from `EventTypeMigration<TUpgrade, TPrevious>`’s constructor the moment `TUpgrade` and `TPrevious` resolve to different event type ids. This turns the old style’s classic mistake — an omitted or mismatched id on the previous generation — into a loud failure at application startup instead of a confusing, silent rejection at the kernel.
* **`MultipleMigratorsForSameEventTypeGeneration`** — thrown by `EventTypeMigrators.GetMigratorsFor` when two different migrator classes both claim to bridge the same generation pair for one event type. Exactly one migrator may own a generation transition.
* **[CHR0037](/chronicle/code-analysis/chr0037/)** flags a migration whose two generations don’t resolve to the same event type at compile time — including validating, for the new attribute, that `[EventTypeGenerationFor<T>]`’s `T` really is the migration’s `TUpgrade`.
* **[CHR0049](/chronicle/code-analysis/chr0049/)** flags `[EventTypeGenerationFor<T>]` when `T` isn’t itself marked with `[EventType]` — the referenced type must carry the real identity directly, not another generation marker.

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Mark previous generations with `[EventTypeGenerationFor<T>]`**: it resolves the event type id from the current generation’s own `[EventType]`, so the two can never drift apart the way a hand-typed id on both generations can
2. **Incremental generations**: Always migrate between consecutive generations (1→2, 2→3, not 1→3)
3. **Reversible transformations**: Ensure downcast can recreate the original structure where possible
4. **Default values**: Use `DefaultValue()` for new properties that didn’t exist in older generations
5. **Test migrations**: Verify both upcast and downcast transformations work correctly
6. **Document changes**: Keep track of what changed between generations in your event types

# Geospatial Types

Chronicle has built-in support for geospatial types from Cratis.Fundamentals: `Point`, `LineString`, and `Polygon`. You can use them directly in events, read models, reducers, and projections without any extra setup.

Client coverage

Geospatial types are currently C#-only — Kotlin, Elixir, and TypeScript don’t have an equivalent `Point`/`LineString`/`Polygon` type in their client SDKs.

## Geospatial Types

[Section titled “Geospatial Types”](#geospatial-types)

The three geospatial types are records defined in the `Cratis.Geospatial` namespace:

* C#

```csharp
  using Cratis.Geospatial;

public static class GeospatialTypeExamples
  {
      public static Point CreatePoint() => new(10.456, 42.123);

public static LineString CreatePath() => new([
          new Point(10.456, 42.123),
          new Point(11.789, 43.456)
      ]);

public static Polygon CreateBoundary() => new(
          Shell: new LinearRing([
              new Point(0, 0),
              new Point(10, 0),
              new Point(10, 10),
              new Point(0, 10),
              new Point(0, 0)
          ]),
          Holes: []);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.geospatial.LinearRing
  import io.cratis.chronicle.geospatial.LineString
  import io.cratis.chronicle.geospatial.Point
  import io.cratis.chronicle.geospatial.Polygon

object GeospatialTypeExamples {
      fun createPoint(): Point = Point(longitude = 10.456, latitude = 42.123)

fun createPath(): LineString = LineString(
          Point(10.456, 42.123),
          Point(11.789, 43.456)
      )

fun createBoundary(): Polygon = Polygon(
          shell = LinearRing(
              Point(0.0, 0.0),
              Point(10.0, 0.0),
              Point(10.0, 10.0),
              Point(0.0, 10.0),
              Point(0.0, 0.0)
          ),
          holes = emptyList()
      )
  }
  ```

* Java

```java
  import io.cratis.chronicle.geospatial.LinearRing;
  import io.cratis.chronicle.geospatial.LineString;
  import io.cratis.chronicle.geospatial.Point;
  import io.cratis.chronicle.geospatial.Polygon;

import java.util.Collections;

class GeospatialTypeExamples {
      static Point createPoint() {
          return new Point(10.456, 42.123);
      }

static LineString createPath() {
          return new LineString(
              new Point(10.456, 42.123),
              new Point(11.789, 43.456));
      }

static Polygon createBoundary() {
          LinearRing shell = new LinearRing(
              new Point(0, 0),
              new Point(10, 0),
              new Point(10, 10),
              new Point(0, 10),
              new Point(0, 0));
          return new Polygon(shell, Collections.emptyList());
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

- **Point** represents a single geographic location in longitude-then-latitude order (GeoJSON standard).
- **LineString** represents a connected series of points forming a line or path.
- **Polygon** represents an enclosed area with a shell (outer boundary) and optional holes (inner boundaries).
- **LinearRing** is an array of points that form a closed loop (used by Polygon).

## Using Geospatial Types in Events and Read Models

[Section titled “Using Geospatial Types in Events and Read Models”](#using-geospatial-types-in-events-and-read-models)

Import the namespace and use the geospatial types as any other property type:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Geospatial;

[EventType]
  public record GeospatialAssetLocationUpdated(Point Location);

[EventType]
  public record GeospatialRouteCreated(LineString Path);

[EventType]
  public record GeospatialZoneEstablished(Polygon Boundaries);

public record GeospatialAssetReadModel(Guid Id, Point Location);
  public record GeospatialRouteReadModel(Guid Id, LineString Path);
  public record GeospatialZoneReadModel(Guid Id, Polygon Boundaries);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.geospatial.LineString
  import io.cratis.chronicle.geospatial.Point
  import io.cratis.chronicle.geospatial.Polygon

@EventType
  data class GeospatialAssetLocationUpdated(val location: Point)

@EventType
  data class GeospatialRouteCreated(val path: LineString)

@EventType
  data class GeospatialZoneEstablished(val boundaries: Polygon)

data class GeospatialAssetReadModel(val id: String, val location: Point)
  data class GeospatialRouteReadModel(val id: String, val path: LineString)
  data class GeospatialZoneReadModel(val id: String, val boundaries: Polygon)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.geospatial.LineString;
  import io.cratis.chronicle.geospatial.Point;
  import io.cratis.chronicle.geospatial.Polygon;

@EventType
  record GeospatialAssetLocationUpdated(Point location) {}

@EventType
  record GeospatialRouteCreated(LineString path) {}

@EventType
  record GeospatialZoneEstablished(Polygon boundaries) {}

record GeospatialAssetReadModel(String id, Point location) {}
  record GeospatialRouteReadModel(String id, LineString path) {}
  record GeospatialZoneReadModel(String id, Polygon boundaries) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Projections and reducers handle geospatial types like any other value type. AutoMap picks them up automatically:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;
  using Cratis.Geospatial;

[EventType]
  public record GeospatialProjAssetLocationUpdated(Point Location);

public record GeospatialProjAssetReadModel(Guid Id, Point Location);

public class GeospatialProjAssetProjection : IProjectionFor<GeospatialProjAssetReadModel>
  {
      // AutoMap picks up the Point-typed property automatically — no manual mapping needed
      public void Define(IProjectionBuilderFor<GeospatialProjAssetReadModel> builder) => builder
          .From<GeospatialProjAssetLocationUpdated>();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.geospatial.Point
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor
  import io.cratis.chronicle.projections.Projection

@EventType
  data class GeospatialProjAssetLocationUpdated(val location: Point)

data class GeospatialProjAssetReadModel(val id: String = "", val location: Point? = null)

// AutoMap picks up the Point-typed property automatically - no manual mapping needed
  @Projection
  class GeospatialProjAssetProjection : IProjectionFor<GeospatialProjAssetReadModel> {
      override fun define(builder: IProjectionBuilderFor<GeospatialProjAssetReadModel>) {
          builder.from(GeospatialProjAssetLocationUpdated::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.geospatial.Point;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;
  import io.cratis.chronicle.projections.Projection;

import io.cratis.chronicle.java.ProjectionBuilderJavaBridge;

@EventType
  record GeospatialProjAssetLocationUpdated(Point location) {}

record GeospatialProjAssetReadModel(String id, Point location) {}

// AutoMap picks up the Point-typed property automatically - no manual mapping needed
  @Projection
  class GeospatialProjAssetProjection implements IProjectionFor<GeospatialProjAssetReadModel> {
      @Override
      public void define(IProjectionBuilderFor<GeospatialProjAssetReadModel> builder) {
          ProjectionBuilderJavaBridge.from(builder, GeospatialProjAssetLocationUpdated.class);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## JSON schema

[Section titled “JSON schema”](#json-schema)

Chronicle describes a geospatial value as a **leaf**: an object carrying only its format, with no sub-properties.

```json
{ "type": "object", "format": "point" }
{ "type": "object", "format": "linestring" }
{ "type": "object", "format": "polygon" }
```

The format is the entire description, and that is deliberate. A geospatial value is stored and materialized as a single typed CLR value — `Point`, `LineString`, `Polygon` — so the members you see on the wire belong to the type’s own GeoJSON converter, not to your event or read model. Were the schema to flatten them into properties, the sink would treat the coordinates as fields of your model and drop them on the way through.

That format annotation is what every reader keys off: the storage sinks use it to materialize the typed value, and tools like the Workbench use it to recognize a geographic field and display it as one.

On the wire, the value itself is GeoJSON:

```json
{
  "pickedUpAt": { "type": "Point", "coordinates": [10.7522, 59.9139] }
}
```

Longitude comes first, then latitude — the GeoJSON convention, and the same order the `Point` constructor takes.

## Geospatial values alongside PII

[Section titled “Geospatial values alongside PII”](#geospatial-values-alongside-pii)

The two features meet more often than you might expect: a delivery has a customer name and a drop-off point, an incident report has a reporter and a location. As soon as *anything* in an event or read model is marked `[PII]`, Chronicle runs its compliance pass over the whole document — not just the personal values — so the geospatial value gets visited too.

Nothing happens to it. Chronicle stops at a geospatial value rather than descending into its GeoJSON members: those members belong to the type’s converter, and there is no schema property under them for a `[PII]` marker to sit on. The location is written and read back verbatim, in the clear — which is what you want, because a venue is public data even when the organizer’s name is not.

Don’t mark a geospatial value `[PII]`

`[PII]` on a geospatial property encrypts the whole GeoJSON object into a single ciphertext string. It survives an ordinary round trip, so it looks like it works — but once that subject exercises [erasure](/chronicle/compliance/erasing-a-subject/), the released value is empty and can no longer be materialized back into a `Point`, `LineString` or `Polygon`. The read then fails for the entire read model rather than degrading that one property.

Treat a personal location as unsupported for now. Keep the geospatial value out of the person-scoped document, or store the sensitive part as a separate `[PII]` value beside a coarser location.

## Storage

[Section titled “Storage”](#storage)

### MongoDB Sink

[Section titled “MongoDB Sink”](#mongodb-sink)

Chronicle stores geospatial values in BSON format:

**Point**: Flat document with `longitude` and `latitude`

```json
{ "longitude": 10.456, "latitude": 42.123 }
```

**LineString**: Array of points

```json
[
  { "longitude": 10.456, "latitude": 42.123 },
  { "longitude": 11.789, "latitude": 43.456 }
]
```

**Polygon**: Document with `shell` (outer ring) and `holes` (inner rings)

```json
{
  "shell": [
    { "longitude": 0, "latitude": 0 },
    { "longitude": 10, "latitude": 0 },
    { "longitude": 10, "latitude": 10 },
    { "longitude": 0, "latitude": 10 },
    { "longitude": 0, "latitude": 0 }
  ],
  "holes": []
}
```

BSON serializers are registered automatically — no configuration required.

### SQL Sink

[Section titled “SQL Sink”](#sql-sink)

Geospatial types generate as JSON objects in the schema, so the SQL sink stores them as JSON columns. No migration or configuration changes are required.

## Workbench Display

[Section titled “Workbench Display”](#workbench-display)

The Chronicle Workbench recognizes geospatial format markers in event schemas and renders them as human-readable strings rather than expanding nested structures:

```text
Point: lat: 42.123, long: 10.456
LineString: [lat: 42.123, long: 10.456], [lat: 43.456, long: 11.789]
Polygon: shell with 5 points, 0 holes
```

# Glossary

> One definition for each core Chronicle term, so the same word means the same thing everywhere in the docs.

Event sourcing comes with its own vocabulary, and the same word can mean subtly different things in different products. This page is the single source of truth for what each term means in Chronicle. Where a term has a fuller treatment, the definition links to it.

## Aggregate

[Section titled “Aggregate”](#aggregate)

A consistency boundary around a single entity’s stream of events — for example one bank account or one order. All decisions for that entity are made against its own events. When you don’t need a whole-entity boundary, prefer a [Dynamic Consistency Boundary](/chronicle/dynamic-consistency-boundary/).

## Constraint

[Section titled “Constraint”](#constraint)

A rule Chronicle enforces *as events are appended* — for example “this email address must be unique across all customers.” A constraint can reject an append, which is how invariants are protected without reading a separate read model first. See [Constraints](/chronicle/concepts/constraints/).

## Dynamic Consistency Boundary (DCB)

[Section titled “Dynamic Consistency Boundary (DCB)”](#dynamic-consistency-boundary-dcb)

A consistency boundary defined by the *decision being made* rather than by a fixed aggregate. Instead of loading an entire entity, you scope a decision to exactly the events that matter to it. See [Dynamic Consistency Boundary](/chronicle/dynamic-consistency-boundary/).

## Event

[Section titled “Event”](#event)

An immutable record of something that *happened* — a fact, in the past tense (`OrderPlaced`, `AddressChanged`). Events are never updated or deleted; new facts supersede old ones. An event carries only the data that was true at the moment it occurred. See [Event](/chronicle/concepts/event/).

## Event Log

[Section titled “Event Log”](#event-log)

The default [event sequence](/chronicle/concepts/event-sequence/) in an [event store](/chronicle/concepts/event-store/). When you append without naming a sequence, the event goes to the event log.

## Event Metadata / Tags

[Section titled “Event Metadata / Tags”](#event-metadata--tags)

Contextual information attached to an event that is not part of the domain fact itself — timestamps, correlation IDs, and user-defined **tags** used to filter or route events. See [Event Metadata Tags](/chronicle/concepts/event-metadata-tags/).

## Event Sequence

[Section titled “Event Sequence”](#event-sequence)

An ordered, append-only series of events. The [event log](#event-log) is the default sequence; you can define additional sequences for specialized streams. See [Event Sequence](/chronicle/concepts/event-sequence/).

## Event Source

[Section titled “Event Source”](#event-source)

The thing an event is *about* — the source of the change, such as a specific customer or order. Events that share an event source form that source’s stream. See [Event Source](/chronicle/concepts/event-source/).

## Event Source ID

[Section titled “Event Source ID”](#event-source-id)

The strongly-typed identifier of an [event source](/chronicle/concepts/event-source/) (for example a `CustomerId`). It is the key Chronicle uses to group and replay an entity’s events.

## Event Store

[Section titled “Event Store”](#event-store)

The top-level container for everything in a bounded context: event sequences, observers, projections, and read models. You obtain one from the client and work within it. See [Event Store](/chronicle/concepts/event-store/).

## Event Type

[Section titled “Event Type”](#event-type)

The schema and identity of a kind of event, declared with `[EventType]`. Chronicle validates appended events against their registered type and supports evolving them over time. See [Event Type](/chronicle/concepts/event-type/) and [Event Type Migrations](/chronicle/concepts/event-type-migrations/).

## Namespace

[Section titled “Namespace”](#namespace)

An isolation boundary *within* an event store, most often used for multi-tenancy — each tenant’s events live in their own namespace while sharing the same model. See [Namespaces](/chronicle/concepts/namespaces/).

## Observer

[Section titled “Observer”](#observer)

The umbrella term for anything that *watches* an event sequence and reacts as events arrive. [Projections](/chronicle/concepts/projection/), [reducers](/chronicle/reducers/), and [reactors](/chronicle/reactors/) are all observers; they differ in what they do with the events. See [Observers](/chronicle/concepts/observers/).

## Projection

[Section titled “Projection”](#projection)

An [observer](/chronicle/concepts/observers/) that builds a [read model](/chronicle/read-models/) by mapping and merging events into a document — declaratively, with no hand-written update code. Use a projection when the read side is shaped like data. See [Projection](/chronicle/concepts/projection/).

## Reactor

[Section titled “Reactor”](#reactor)

An [observer](/chronicle/concepts/observers/) that produces *side effects* — sending a notification, calling an external system, or triggering a command. Reactors do things; they do not build state. They must be idempotent because they may run more than once. See [Reactors](/chronicle/reactors/).

## Read Model

[Section titled “Read Model”](#read-model)

A purpose-built, queryable view of state derived from events — the “read” side of CQRS. Read models are specialized per use case rather than shared, so they stay simple and fast. See [Read Models](/chronicle/read-models/).

## Reducer

[Section titled “Reducer”](#reducer)

An [observer](/chronicle/concepts/observers/) that folds events into a value using imperative code you write, for cases a declarative [projection](/chronicle/concepts/projection/) can’t express cleanly. See [Reducers](/chronicle/reducers/).

## Replay

[Section titled “Replay”](#replay)

Re-running an [observer](/chronicle/concepts/observers/) over historical events to rebuild its [read model](/chronicle/read-models/) from scratch — for example after changing a projection. Because events are the source of truth, read models are always disposable and rebuildable.

## Sink

[Section titled “Sink”](#sink)

The destination a [projection](/chronicle/concepts/projection/) writes its [read model](/chronicle/read-models/) to — MongoDB by default, with other stores available through extensions. See [Sinks](/chronicle/sinks/).

## Subject

[Section titled “Subject”](#subject)

An observable stream you can subscribe to for real-time updates — the mechanism behind reactive queries that push new data to clients as events arrive. See [Subject](/chronicle/concepts/subject/).

## Tail Sequence Number

[Section titled “Tail Sequence Number”](#tail-sequence-number)

The sequence number of the most recent event in an [event sequence](/chronicle/concepts/event-sequence/). `EventSequenceNumber.First` is `0`, so an empty log has no tail and the first appended event sits at `First`.

## Tenant

[Section titled “Tenant”](#tenant)

An isolated consumer of the system whose data must not mix with others’. In Chronicle, tenants are typically separated using [namespaces](/chronicle/concepts/namespaces/).

# Modeling events well

> The single most important skill in event sourcing — how to design events that are clear today and still make sense in five years.

Events are the foundation everything else is built on. Get them right and projections, reactors, and read models fall into place. Get them wrong and no amount of clever projection code will save you. This is the guide to getting them right.

The guiding principle behind all of it: **an event is a fact — an immutable record of something that happened.** Every rule below follows from taking that seriously.

## Name events as facts, in the past tense

[Section titled “Name events as facts, in the past tense”](#name-events-as-facts-in-the-past-tense)

An event states what *happened*, so its name is a past-tense verb phrase in the language of the domain: `OrderPlaced`, `AddressChanged`, `PaymentCaptured`, `BookReturned`. Not `CreateOrder` (that’s a command — an intent), not `OrderState` (that’s a model). If you can’t name it in the past tense, it isn’t an event yet.

* C#

```csharp
  using Cratis.Chronicle.Events;

public record ModelingEventsAddress(string Street, string City);

// A fact that happened
  [EventType]
  public record ModelingEventsAddressChanged(ModelingEventsAddress Address);

// An intent (that's a command) or a state blob (that's a read model) — not an event
  [EventType]
  public record ModelingEventsUpdateAddress(ModelingEventsAddress Address);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

data class ModelingEventsAddress(val street: String, val city: String)

// A fact that happened
  @EventType
  data class ModelingEventsAddressChanged(val address: ModelingEventsAddress)

// An intent (that's a command) or a state blob (that's a read model) — not an event
  @EventType
  data class ModelingEventsUpdateAddress(val address: ModelingEventsAddress)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

record ModelingEventsAddress(String street, String city) {}

// A fact that happened
  @EventType
  record ModelingEventsAddressChanged(ModelingEventsAddress address) {}

// An intent (that's a command) or a state blob (that's a read model) — not an event
  @EventType
  record ModelingEventsUpdateAddress(ModelingEventsAddress address) {}
  ```

* Elixir

```elixir
  defmodule MyApp.ModelingEventsAddress do
    defstruct [:street, :city]
  end

# A fact that happened
  defmodule MyApp.Events.ModelingEventsAddressChanged do
    use Chronicle.Events.EventType, id: "modeling-events-address-changed"

defstruct [:address]
  end

# An intent (that's a command) or a state blob (that's a read model) — not an event
  defmodule MyApp.Events.ModelingEventsUpdateAddress do
    use Chronicle.Events.EventType, id: "modeling-events-update-address"

defstruct [:address]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

class ModelingEventsAddress {
      constructor(
          readonly street: string,
          readonly city: string
      ) {}
  }

// A fact that happened
  @eventType()
  class ModelingEventsAddressChanged {
      constructor(readonly address: ModelingEventsAddress) {}
  }

// An intent (that's a command) or a state blob (that's a read model) — not an event
  @eventType()
  class ModelingEventsUpdateAddress {
      constructor(readonly address: ModelingEventsAddress) {}
  }
  ```

## One event, one purpose

[Section titled “One event, one purpose”](#one-event-one-purpose)

Each event captures a single, meaningful change. Resist the “kitchen-sink” event that carries everything about an entity with most fields irrelevant on any given change. Multipurpose events force every consumer to figure out *which* change actually happened.

* C#

```csharp
  using Cratis.Chronicle.Events;

public record ModelingEventsCustomerName(string Value);
  public record ModelingEventsEmail(string Value);
  public record ModelingEventsDeactivationReason(string Value);
  public record ModelingEventsCustomerAddress(string Street, string City);

// One event trying to be everything — consumers must guess what changed
  [EventType]
  public record ModelingEventsCustomerUpdated(
      string? Name,
      ModelingEventsCustomerAddress? Address,
      ModelingEventsEmail? Email,
      bool? Deactivated);

// Distinct facts — each consumer subscribes to exactly what it cares about
  [EventType]
  public record ModelingEventsCustomerRenamed(ModelingEventsCustomerName Name);

[EventType]
  public record ModelingEventsCustomerAddressChanged(ModelingEventsCustomerAddress Address);

[EventType]
  public record ModelingEventsCustomerDeactivated(ModelingEventsDeactivationReason Reason);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

data class ModelingEventsCustomerName(val value: String)
  data class ModelingEventsEmail(val value: String)
  data class ModelingEventsDeactivationReason(val value: String)
  data class ModelingEventsCustomerAddress(val street: String, val city: String)

// One event trying to be everything — consumers must guess what changed
  @EventType
  data class ModelingEventsCustomerUpdated(
      val name: ModelingEventsCustomerName?,
      val address: ModelingEventsCustomerAddress?,
      val email: ModelingEventsEmail?,
      val deactivated: Boolean?
  )

// Distinct facts — each consumer subscribes to exactly what it cares about
  @EventType
  data class ModelingEventsCustomerRenamed(val name: ModelingEventsCustomerName)

@EventType
  data class ModelingEventsCustomerAddressChanged(val address: ModelingEventsCustomerAddress)

@EventType
  data class ModelingEventsCustomerDeactivated(val reason: ModelingEventsDeactivationReason)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

record ModelingEventsCustomerName(String value) {}
  record ModelingEventsEmail(String value) {}
  record ModelingEventsDeactivationReason(String value) {}
  record ModelingEventsCustomerAddress(String street, String city) {}

// One event trying to be everything — consumers must guess what changed
  @EventType
  record ModelingEventsCustomerUpdated(
      ModelingEventsCustomerName name,
      ModelingEventsCustomerAddress address,
      ModelingEventsEmail email,
      Boolean deactivated) {}

// Distinct facts — each consumer subscribes to exactly what it cares about
  @EventType
  record ModelingEventsCustomerRenamed(ModelingEventsCustomerName name) {}

@EventType
  record ModelingEventsCustomerAddressChanged(ModelingEventsCustomerAddress address) {}

@EventType
  record ModelingEventsCustomerDeactivated(ModelingEventsDeactivationReason reason) {}
  ```

* Elixir

```elixir
  defmodule MyApp.ModelingEventsCustomerName do
    defstruct [:value]
  end

defmodule MyApp.ModelingEventsEmail do
    defstruct [:value]
  end

defmodule MyApp.ModelingEventsDeactivationReason do
    defstruct [:value]
  end

defmodule MyApp.ModelingEventsCustomerAddress do
    defstruct [:street, :city]
  end

# One event trying to be everything — consumers must guess what changed
  defmodule MyApp.Events.ModelingEventsCustomerUpdated do
    use Chronicle.Events.EventType, id: "modeling-events-customer-updated"

defstruct [:name, :address, :email, :deactivated]
  end

# Distinct facts — each consumer subscribes to exactly what it cares about
  defmodule MyApp.Events.ModelingEventsCustomerRenamed do
    use Chronicle.Events.EventType, id: "modeling-events-customer-renamed"

defstruct [:name]
  end

defmodule MyApp.Events.ModelingEventsCustomerAddressChanged do
    use Chronicle.Events.EventType, id: "modeling-events-customer-address-changed"

defstruct [:address]
  end

defmodule MyApp.Events.ModelingEventsCustomerDeactivated do
    use Chronicle.Events.EventType, id: "modeling-events-customer-deactivated"

defstruct [:reason]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

class ModelingEventsCustomerName {
      constructor(readonly value: string) {}
  }

class ModelingEventsEmail {
      constructor(readonly value: string) {}
  }

class ModelingEventsDeactivationReason {
      constructor(readonly value: string) {}
  }

class ModelingEventsCustomerAddress {
      constructor(
          readonly street: string,
          readonly city: string
      ) {}
  }

// One event trying to be everything — consumers must guess what changed
  @eventType()
  class ModelingEventsCustomerUpdated {
      constructor(
          readonly name?: ModelingEventsCustomerName,
          readonly address?: ModelingEventsCustomerAddress,
          readonly email?: ModelingEventsEmail,
          readonly deactivated?: boolean
      ) {}
  }

// Distinct facts — each consumer subscribes to exactly what it cares about
  @eventType()
  class ModelingEventsCustomerRenamed {
      constructor(readonly name: ModelingEventsCustomerName) {}
  }

@eventType()
  class ModelingEventsCustomerAddressChanged {
      constructor(readonly address: ModelingEventsCustomerAddress) {}
  }

@eventType()
  class ModelingEventsCustomerDeactivated {
      constructor(readonly reason: ModelingEventsDeactivationReason) {}
  }
  ```

## Never nullable — if it’s optional, you need a second event

[Section titled “Never nullable — if it’s optional, you need a second event”](#never-nullable--if-its-optional-you-need-a-second-event)

This is the rule that trips up newcomers most, and it’s the most important. An event records what *was true* at the moment it happened. A nullable property means “this fact sometimes didn’t happen” — which is a contradiction. If a value is sometimes present and sometimes not, that’s **two different facts**, so model two events.

* C#

```csharp
  using Cratis.Chronicle.Events;

public record ModelingEventsOrderId(Guid Value);
  public record ModelingEventsMoney(decimal Amount, string Currency);

// Nullable smell — "sometimes there's a discount, sometimes not"
  [EventType]
  public record ModelingEventsOrderPlacedWithNullableDiscount(
      ModelingEventsOrderId Id,
      ModelingEventsMoney Total,
      ModelingEventsMoney? Discount);

// Two facts
  [EventType]
  public record ModelingEventsOrderPlaced(ModelingEventsOrderId Id, ModelingEventsMoney Total);

[EventType]
  public record ModelingEventsDiscountApplied(ModelingEventsOrderId Id, ModelingEventsMoney Amount);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

data class ModelingEventsOrderId(val value: String)
  data class ModelingEventsMoney(val amount: Double, val currency: String)

// Nullable smell — "sometimes there's a discount, sometimes not"
  @EventType
  data class ModelingEventsOrderPlacedWithNullableDiscount(
      val id: ModelingEventsOrderId,
      val total: ModelingEventsMoney,
      val discount: ModelingEventsMoney?
  )

// Two facts
  @EventType
  data class ModelingEventsOrderPlaced(val id: ModelingEventsOrderId, val total: ModelingEventsMoney)

@EventType
  data class ModelingEventsDiscountApplied(val id: ModelingEventsOrderId, val amount: ModelingEventsMoney)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

record ModelingEventsOrderId(String value) {}
  record ModelingEventsMoney(double amount, String currency) {}

// Nullable smell — "sometimes there's a discount, sometimes not"
  @EventType
  record ModelingEventsOrderPlacedWithNullableDiscount(
      ModelingEventsOrderId id,
      ModelingEventsMoney total,
      ModelingEventsMoney discount) {}

// Two facts
  @EventType
  record ModelingEventsOrderPlaced(ModelingEventsOrderId id, ModelingEventsMoney total) {}

@EventType
  record ModelingEventsDiscountApplied(ModelingEventsOrderId id, ModelingEventsMoney amount) {}
  ```

* Elixir

```elixir
  defmodule MyApp.ModelingEventsOrderId do
    defstruct [:value]
  end

defmodule MyApp.ModelingEventsMoney do
    defstruct [:amount, :currency]
  end

# Nullable smell — "sometimes there's a discount, sometimes not"
  defmodule MyApp.Events.ModelingEventsOrderPlacedWithNullableDiscount do
    use Chronicle.Events.EventType, id: "modeling-events-order-placed-with-nullable-discount"

defstruct [:id, :total, :discount]
  end

# Two facts
  defmodule MyApp.Events.ModelingEventsOrderPlaced do
    use Chronicle.Events.EventType, id: "modeling-events-order-placed"

defstruct [:id, :total]
  end

defmodule MyApp.Events.ModelingEventsDiscountApplied do
    use Chronicle.Events.EventType, id: "modeling-events-discount-applied"

defstruct [:id, :amount]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

class ModelingEventsOrderId {
      constructor(readonly value: string) {}
  }

class ModelingEventsMoney {
      constructor(
          readonly amount: number,
          readonly currency: string
      ) {}
  }

// Nullable smell — "sometimes there's a discount, sometimes not"
  @eventType()
  class ModelingEventsOrderPlacedWithNullableDiscount {
      constructor(
          readonly id: ModelingEventsOrderId,
          readonly total: ModelingEventsMoney,
          readonly discount?: ModelingEventsMoney
      ) {}
  }

// Two facts
  @eventType()
  class ModelingEventsOrderPlaced {
      constructor(
          readonly id: ModelingEventsOrderId,
          readonly total: ModelingEventsMoney
      ) {}
  }

@eventType()
  class ModelingEventsDiscountApplied {
      constructor(
          readonly id: ModelingEventsOrderId,
          readonly amount: ModelingEventsMoney
      ) {}
  }
  ```

## Capture the decision, not the field write

[Section titled “Capture the decision, not the field write”](#capture-the-decision-not-the-field-write)

The temptation coming from CRUD is to mirror table columns: a `Customer` changed, so emit `CustomerUpdated`. But the value of event sourcing is in the *meaning*. `AddressChanged` tells you a customer moved; a generic update tells you nothing. Model the business decision or transition, and the audit trail, analytics, and reactions have something precise to work from.

## Carry what was true then — and only that

[Section titled “Carry what was true then — and only that”](#carry-what-was-true-then--and-only-that)

An event holds the data that was true at the moment it occurred, captured by value. Don’t reference mutable state that might change later, and don’t enrich an event with data a consumer can derive itself. The event should be readable on its own, years from now, without joining against anything.

## The five-year test

[Section titled “The five-year test”](#the-five-year-test)

Before you commit an event type, ask: **“Will this still make sense to someone reading it in five years, with no other context?”** Clear domain naming and self-contained data are what make that a *yes*. Events are forever — they’re worth a minute of thought.

## Events change by migration, never by editing

[Section titled “Events change by migration, never by editing”](#events-change-by-migration-never-by-editing)

When an event type needs to evolve, you don’t rewrite history — you describe how to read old events as the new shape with an [event type migration](/chronicle/concepts/event-type-migrations/). Prefer *adding* a new event or field over overloading an existing event; it keeps each fact singular and clear. See the recipe: [Evolve an event’s shape](/chronicle/scenarios/evolve-an-event/).

## Where this leads

[Section titled “Where this leads”](#where-this-leads)

* [Event](/chronicle/concepts/event/) and [Event Type](/chronicle/concepts/event-type/) — the mechanics.
* [Projections, reducers, and reactors](/chronicle/concepts/observer-patterns/) — what consumes your well-modeled events.
* [When to use event sourcing](/chronicle/concepts/when-to-use-event-sourcing/) — and when modeling events isn’t worth it.

# Namespaces

Chronicle has been designed with the concept of namespaces from the ground up. Namespaces provide a way to provide segregation of data in the same event store. This can typically be used for multi-tenant scenarios were you have multiple tenants of your system and you want to provide data segregation between them.

When not specified, Chronicle will use the **Default** namespace.

> Note: A tenant is typically an organization or an organizational unit that uses a system. In cloud terminology it is often linked to Software as a Service offerings were companies can sign up to use a system. The system being the same for all these companies, or tenants, but all their data segregated from each other.

## Data Segregation

[Section titled “Data Segregation”](#data-segregation)

With Chronicle, all namespace specific data sits in its own database in the underlying data storage. This helps us avoid data leakage between namespaces, or tenants. With this you also get a better utilization of resources with mechanisms like indexing that happens on a database level.

```
One event store

Default

tenant-a

tenant-b

database: Default

database: tenant-a

database: tenant-b
```

## Database Naming

[Section titled “Database Naming”](#database-naming)

The databases are named from the event store name and the namespace. For an event store named `Ada` on MongoDB:

| Holds                  | Namespace `Default` | Namespace `tenant-a` |
| ---------------------- | ------------------- | -------------------- |
| Event store wide state | `Ada+es`            | `Ada+es`             |
| Event sequences        | `Ada+es+Default`    | `Ada+es+tenant-a`    |
| Read models            | `Ada`               | `Ada+tenant-a`       |

Note the one asymmetry: **read models of the default namespace are materialized into the bare event store name**, without a namespace suffix, while event sequences suffix every namespace including the default. Anything reading read models outside Chronicle — for instance an injected `IMongoCollection<TReadModel>` bound to a database name composed by hand — has to reproduce that rule. Composing `<eventStore>+<namespace>` unconditionally resolves `Ada+Default`, a database that does not exist, and reads then come back **empty rather than failing**.

Since the namespace becomes part of a database name, it has to be a legal one. MongoDB rejects the characters `/ \ . " $ * < > : | ?`, the space, and the null character, and limits the whole name to 63 bytes. This bites most often when the namespace is resolved from a tenant id — a display-style tenant id such as `Hive Consulting` composes a name MongoDB will not accept. Chronicle checks the composed name and throws `InvalidDatabaseName`, naming the event store, the namespace, and the offending character, rather than letting the driver fail later with a bare `Invalid namespace specified`.

# Projections, reducers, and reactors

> All three watch your events — but they do very different things. Here's how to tell them apart and choose the right one.

Projections, reducers, and reactors are all **observers**: they watch an [event sequence](/chronicle/concepts/event-sequence/) and run as events arrive. The confusion is that they look similar and are often explained on separate pages. This page puts them side by side so you can pick the right one without second-guessing.

The one-line distinction:

* **Projection** and **reducer** *build state* (a read model) — declaratively or imperatively.
* **Reactor** *causes effects* (notify, integrate, trigger a command) — it builds nothing.

```
State you can query

A side effect when something happens

Like data: map and merge events

Needs custom folding logic

What do you need?

How is it shaped?

Reactor

Projection

Reducer
```

## Side by side

[Section titled “Side by side”](#side-by-side)

|                        | Projection                                                    | Reducer                                      | Reactor                                          |
| ---------------------- | ------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------ |
| **Purpose**            | Build a read model                                            | Build a read model                           | Do a side effect                                 |
| **How**                | Declarative (`[ReadModel]` + model-bound attributes, AutoMap) | Imperative fold you write                    | A method per event type                          |
| **Produces**           | A read model instance you query                               | A value you query                            | Nothing (acts on the outside world)              |
| **Reach for it when**  | The read side is shaped like data                             | A projection can’t express the logic cleanly | You must notify, integrate, or trigger a command |
| **Must be idempotent** | Handled for you                                               | Handled for you                              | **Yes — you own this**                           |

Idempotency for projections and reducers is handled by Chronicle, but it is worth knowing what “handled” means: a rebuild always starts from a clean read model, and for a read model keyed by event source id Chronicle also refuses any write that does not move that instance’s last-handled sequence number forward, so an event redelivered after a crash changes nothing. A projection whose key deliberately collapses several event sources onto one instance — a join, a constant key, a parent hierarchy — is written out of order by design and cannot use that guard; for those Chronicle instead keeps its recovery window down to a single batch.

Building state doesn’t have to mean *materializing* it. Projections and reducers also compute state **on demand** — Chronicle replays the relevant events through them when you ask, which is how [reading a single instance](/chronicle/read-models/getting-single-instance/) serves strongly consistent results. That makes them useful beyond query views: validation rules, [aggregate roots in Arc](/arc/backend/chronicle/aggregates/defining-an-aggregate-root/), or anything else that needs current state it can trust.

## Choosing

[Section titled “Choosing”](#choosing)

1. **Do you want state you can query, or an effect in the outside world?**

* State → projection or reducer.
   * Effect → reactor.

2. **If state: can you express it as “map these event properties onto this model”?**

* Yes → [Projection](/chronicle/concepts/projection/). Start here — it’s the least code and AutoMap does most of the work.
   * No, it needs real logic (running totals, conditional accumulation) → [Reducer](/chronicle/reducers/).

3. **If effect:** use a [Reactor](/chronicle/reactors/) — and design it to be safe to run more than once, because it will be (replay, recovery, redeploy).

## The rules that keep them honest

[Section titled “The rules that keep them honest”](#the-rules-that-keep-them-honest)

* A **projection/reducer never causes side effects** — no emails, no API calls. They only build state.
* A **reactor never builds state and never writes to the event log directly** — if it must produce new events, it executes a command through the command pipeline.
* All of them are **rebuildable**: because events are the source of truth, you can replay to rebuild a read model at any time.

## Go deeper

[Section titled “Go deeper”](#go-deeper)

* [Projections](/chronicle/projections/) — the full range, including declarative and model-bound styles.
* [Reducers](/chronicle/reducers/) — when and how to fold.
* [Reactors](/chronicle/reactors/) — side effects and idempotency.
* [Read Models](/chronicle/read-models/) — what projections and reducers write to, and how consistency works.

# Observers

An observer is a part of your system that is “listening” to events. When events are appended to an [event sequence](/chronicle/concepts/event-sequence/) that the observer is observing, it will automatically be notified of the event.

Every observer decides what events they are interested in during the subscription process. This information is stored in the [event store](/chronicle/concepts/event-store/).

If the observer gets additional event types it is observing, the event store will look if there are events prior to its current offset of the new event type it is now observing. If there are, it will automatically be rewound to the beginning of the sequence and replayed.

During replay, the observer will not be active and when it reaches the end of the sequence it will become active again and observe any new events.

There are three kinds of observer, each turning events into something different — queryable state, or an action:

```
Event sequence

Projection

Read model

Reducer

Read model

Reactor

Side effect: email, API call, new event
```

## State management

[Section titled “State management”](#state-management)

One of the things you can use an observer for is to maintain application state, typically update data in a database that is used for reading. However, it is recommended to use [projections](/chronicle/concepts/projection/) for this purpose, as long as projections support your scenario. Projections are not a catch all solution, and sometimes you need to do it manually. It is also a possibility to combine manual state management with **immediate projections**.

## Reactors

[Section titled “Reactors”](#reactors)

Reactors are great for the **if this then that** type of scenarios. When an event occurs, you can react to it and perform an action. This could be any type of action, e.g. out-of-process actions like sending emails or calling an API. You could also append new events in an observer and make your observer become a pattern matcher or a state machine that responds to certain conditions and then generate more specific events for that condition.

## Reducers

[Section titled “Reducers”](#reducers)

While projections is a declarative approach and has some limitations, a reducer can help give you more capabilities. With a reducer, Chronicle manages the actual storage. Chronicle will call you on every event you are interested in for your reducer and you will get the existing state of the read model, if any, and you can then provide a new representation of state as a consequence of the event. The result will then be stored.

# Projection

A projection in Chronicle is a specialized observer. It is a declarative approach to describing events you’re interested in and how you want Chronicle to project it into something that you can display in your application or provide as data for an API. Every projection can be very specialized for the purpose it is being used in, in fact it is encouraged to create specialized projections rather than reuse a projection for multiple scenarios. The reason for this is that you then don’t run the risk of serving multiple conflicting scenarios, which could for instance impact performance and also general maintainability of your code.

```
UserRegistered

Projection (declarative)

NameChanged

OrderPlaced

Read model instance keyed by the event source
```

Chronicle projections support relationships, one-to-one and one-to-many. It also supports functions that allow you to count, add or subtract values. The identifier of the projected instance can also be configured. By default it will use the [event source identifier](/chronicle/concepts/event-source/), but you can point it to any other property or create a composite of multiple properties.

Projections support using the metadata properties of an event as well. This lets you create composite keys that could for instance leverage the `occurred` date/time value and effectively create group by scenarios. This would effectively give you an easy way to do simple histograms, with count, add and/or subtract of values in the histogram.

# Subject

The **subject** of an event is the target the event is *about* — the identity used to key compliance concerns such as PII encryption. In most systems the subject and the [`EventSourceId`](/chronicle/concepts/event-source/) are the same, but they don’t have to be.

Consider a `ShippingAddressChanged` event. The `EventSourceId` is the order identifier (that is what binds all events for that order together), but the *subject* is the customer the address is about. PII encryption keys are held per-subject, not per-event-source, so that every event that touches the same person can be decrypted with the same key regardless of which aggregate produced it.

```
Order stream — EventSourceId = orderId

subject

ShippingAddressChanged

Subject = customerId

per-subject PII encryption key
```

## Default — the `EventSourceId`

[Section titled “Default — the EventSourceId”](#default--the-eventsourceid)

When you don’t specify a subject, Chronicle uses the `EventSourceId` as the subject. This is the right default for most slices where the aggregate and the subject coincide:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;

[EventType]
  public record SubjectAuthorRegistered(string Name);

public class SubjectAuthorService(IEventStore eventStore)
  {
      public Task Register(EventSourceId authorId, string name) =>
          // Subject defaults to authorId; encryption keys for any PII on SubjectAuthorRegistered
          // are keyed by authorId.
          eventStore.EventLog.Append(authorId, new SubjectAuthorRegistered(name));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType

@EventType
  data class SubjectAuthorRegistered(val name: String)

class SubjectAuthorService(private val eventStore: IEventStore) {
      suspend fun register(authorId: String, name: String) {
          // Subject defaults to authorId, so encryption keys for any PII on
          // SubjectAuthorRegistered are keyed by authorId.
          eventStore.eventLog.append(authorId, SubjectAuthorRegistered(name))
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
  record SubjectAuthorRegistered(String name) {}

class SubjectAuthorService {
      private final IEventStore eventStore;

SubjectAuthorService(IEventStore eventStore) {
          this.eventStore = eventStore;
      }

void register(String authorId, String name) {
          // Subject defaults to authorId, so encryption keys for any PII on
          // SubjectAuthorRegistered are keyed by authorId.
          EventLogJavaBridge.append(
              eventStore.getEventLog(),
              authorId,
              new SubjectAuthorRegistered(name),
              null);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.SubjectAuthorRegistered do
    use Chronicle.Events.EventType, id: "subject-author-registered"

defstruct [:name]
  end

defmodule MyApp.SubjectAuthorService do
    alias MyApp.Events.SubjectAuthorRegistered

def register(author_id, name) do
      # Subject defaults to author_id; encryption keys for any PII on SubjectAuthorRegistered
      # are keyed by author_id.
      Chronicle.append(author_id, %SubjectAuthorRegistered{name: name})
    end
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Specifying an explicit subject

[Section titled “Specifying an explicit subject”](#specifying-an-explicit-subject)

When the event source is different from the subject, pass `Subject` explicitly. `Subject` has an implicit conversion from `EventSourceId`, so mixing the two is painless:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;

[EventType]
  public record SubjectShippingAddressChanged(string Street);

public class SubjectShippingService(IEventStore eventStore)
  {
      public Task ChangeAddress(EventSourceId orderId, Subject customerId, string street) =>
          eventStore.EventLog.Append(
              eventSourceId: orderId,
              @event: new SubjectShippingAddressChanged(street),
              subject: customerId);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.events.EventType

@EventType
  data class SubjectShippingAddressChanged(val street: String)

class SubjectShippingService(private val eventStore: IEventStore) {
      suspend fun changeAddress(orderId: String, customerId: String, street: String) {
          // The event happens to the order, but the address is the customer's data - so the
          // subject is the customer, not the event source.
          eventStore.eventLog.append(
              orderId,
              SubjectShippingAddressChanged(street),
              AppendOptions(subject = customerId)
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.AppendOptionsBuilder;
  import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
  record SubjectShippingAddressChanged(String street) {}

class SubjectShippingService {
      private final IEventStore eventStore;

SubjectShippingService(IEventStore eventStore) {
          this.eventStore = eventStore;
      }

void changeAddress(String orderId, String customerId, String street) {
          // The event happens to the order, but the address is the customer's data - so the
          // subject is the customer, not the event source.
          EventLogJavaBridge.append(
              eventStore.getEventLog(),
              orderId,
              new SubjectShippingAddressChanged(street),
              new AppendOptionsBuilder().subject(customerId).build());
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.SubjectShippingAddressChanged do
    use Chronicle.Events.EventType, id: "subject-shipping-address-changed"

defstruct [:street]
  end

defmodule MyApp.SubjectShippingService do
    alias MyApp.Events.SubjectShippingAddressChanged

def change_address(order_id, customer_id, street) do
      Chronicle.append(order_id, %SubjectShippingAddressChanged{street: street},
        subject: customer_id
      )
    end
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`Subject` also converts implicitly from `string` and `Guid`. Kotlin and Java pass a subject through `AppendOptions`. TypeScript doesn’t currently expose a `subject` append option at all.

## Implicit subject with `[Subject]`

[Section titled “Implicit subject with \[Subject\]”](#implicit-subject-with-subject)

Rather than threading `subject` through every call site, decorate the relevant property on the event type with `[Subject]`. Chronicle will read the property value automatically when no explicit subject is provided:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;

public record SubjectOrderId(Guid Value);
  public record SubjectCustomerId(Guid Value);

[EventType]
  public record SubjectShippingAddressChangedWithImplicitSubject(
      SubjectOrderId Order,
      [Subject] SubjectCustomerId Customer,
      [PII] string Street,
      [PII] string City);

public class SubjectImplicitSubjectService(IEventStore eventStore)
  {
      // Subject is derived from the Customer property — no explicit subject needed.
      public Task ChangeAddress(SubjectOrderId orderId, SubjectCustomerId customerId, string street, string city) =>
          eventStore.EventLog.Append(
              orderId.Value,
              new SubjectShippingAddressChangedWithImplicitSubject(orderId, customerId, street, city));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

An explicit `subject` argument always takes precedence over a `[Subject]` property. This declarative form is C#-only — Elixir, Kotlin, and Java pass the subject explicitly on every append (shown above), and TypeScript doesn’t support a subject at all yet.

## Compliance

[Section titled “Compliance”](#compliance)

When an event type declares `[PII]` properties, Chronicle encrypts those properties at append time using a per-subject encryption key. The key is created on first use and stored in the encryption key store. Because the key lives under the subject, every event that shares a subject is encrypted with the same key — and once that key is deleted (for example, to honor a right-to-erasure request), every PII property across every event for that subject becomes unrecoverable in one operation.

That one operation covers one event store and one namespace. A subject whose events are forwarded to another event store by a subscription holds a key in that store too, and erasing them takes one delete per event store and namespace — see [Erasing a subject](/chronicle/compliance/erasing-a-subject/).

Read more about [PII compliance](/chronicle/compliance/pii/).

# Tagging

Tags provide a flexible way to organize, categorize, and identify events and observers (reactors, reducers, projections, read models) within Chronicle. By applying the `[Tag]` or `[Tags]` attribute, you can assign one or more tags that describe the purpose, domain, or context of your artifacts.

Client coverage

Static tags on **events** or **read models** are currently C#-only. Kotlin and Java tag an **observer** with `@Tag`, supply dynamic tags at append time through `AppendOptions`, and read tags back from `EventContext` — as does Elixir for dynamic tags. TypeScript doesn’t expose a `tags` append option at all.

> **Note**: Both `[Tag]` and `[Tags]` attributes can be used interchangeably. Use whichever feels more natural, or mix them - all tags will be merged together.

## Overview

[Section titled “Overview”](#overview)

Tags are strings that can be attached to:

* **Events** - both statically (via attributes) and dynamically (when appending)
* **Reactors** - for organizing and filtering reactive behaviors
* **Reducers** - for categorizing state aggregation logic
* **Projections** - for organizing view models and read models
* **Read Models** - for categorizing data models

Tags are stored with event metadata and observer definitions, enabling powerful filtering, querying, and organizational capabilities.

## Tagging Events

[Section titled “Tagging Events”](#tagging-events)

Events can be tagged in two ways: statically using attributes, or dynamically when appending events.

### Static Event Tags

[Section titled “Static Event Tags”](#static-event-tags)

Apply the `[Tag]` or `[Tags]` attribute to your event types to assign static tags that will always be associated with that event type:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;

[EventType]
  [Tag("analytics", "user-action")]
  public record TaggingUserLoggedIn(string UserId, DateTimeOffset LoggedInAt);

// [Tags] (plural) is equivalent to [Tag] — use whichever reads more naturally
  [EventType]
  [Tags("analytics", "user-action")]
  public record TaggingUserLoggedInAlternate(string UserId, DateTimeOffset LoggedInAt);

// Mixing [Tag] and [Tags] on the same type merges all the tags
  [EventType]
  [Tag("security")]
  [Tags("audit")]
  public record TaggingUserPasswordChanged(string UserId, DateTimeOffset ChangedAt);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, tag, tags } from '@cratis/chronicle';

@eventType()
  @tag('analytics', 'user-action')
  class TaggingUserLoggedIn {
      constructor(readonly userId: string, readonly loggedInAt: Date) {}
  }

// @tags() (plural) is equivalent to @tag() — use whichever reads more naturally
  @eventType()
  @tags('analytics', 'user-action')
  class TaggingUserLoggedInAlternate {
      constructor(readonly userId: string, readonly loggedInAt: Date) {}
  }

// Mixing @tag() and @tags() on the same type merges all the tags
  @eventType()
  @tag('security')
  @tags('audit')
  class TaggingUserPasswordChanged {
      constructor(readonly userId: string, readonly changedAt: Date) {}
  }
  ```

### Dynamic Event Tags

[Section titled “Dynamic Event Tags”](#dynamic-event-tags)

When appending events, you can provide additional tags that will be merged with any static tags:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class TaggingUserLoginService(IEventLog eventLog)
  {
      public Task RecordLogin(EventSourceId eventSourceId) =>
          // The event will end up with four tags: ["analytics", "user-action", "production", "critical"]
          eventLog.Append(
              eventSourceId,
              new TaggingUserLoggedIn("user123", DateTimeOffset.UtcNow),
              tags: ["production", "critical"]);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.eventSequences.IEventLog
  import io.cratis.chronicle.events.EventType

@EventType
  data class TaggingUserLoggedIn(val userId: String)

class TaggingUserLoginService(private val eventLog: IEventLog) {
      suspend fun recordLogin(eventSourceId: String) {
          eventLog.append(
              eventSourceId,
              TaggingUserLoggedIn("user123"),
              AppendOptions(tags = listOf("production", "critical"))
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.eventSequences.IEventLog;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.AppendOptionsBuilder;
  import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
  record TaggingUserLoggedIn(String userId) {}

class TaggingUserLoginService {
      private final IEventLog eventLog;

TaggingUserLoginService(IEventLog eventLog) {
          this.eventLog = eventLog;
      }

void recordLogin(String eventSourceId) {
          EventLogJavaBridge.append(
              eventLog,
              eventSourceId,
              new TaggingUserLoggedIn("user123"),
              new AppendOptionsBuilder().tag("production").tag("critical").build());
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.TaggingUserLoggedIn do
    use Chronicle.Events.EventType, id: "tagging-user-logged-in"

defstruct [:user_id, :logged_in_at]
  end

defmodule MyApp.TaggingUserLoginService do
    alias MyApp.Events.TaggingUserLoggedIn

def record_login(event_source_id, user_id) do
      # Elixir doesn't support static tags on the event type, so this event ends up
      # with only the two dynamic tags: ["production", "critical"]
      Chronicle.append(
        event_source_id,
        %TaggingUserLoggedIn{user_id: user_id, logged_in_at: DateTime.utc_now()},
        tags: ["production", "critical"]
      )
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

// The event will end up with four tags: ['analytics', 'user-action', 'production', 'critical']
      async recordLogin(eventSourceId: string): Promise<void> {
          await this.store.eventLog.append(
              eventSourceId,
              new TaggingUserLoggedIn('user123', new Date()),
              { tags: ['production', 'critical'] });
      }
  }
  ```

In this example, the event will have four tags: `["analytics", "user-action", "production", "critical"]`.

### Tags in Event Context

[Section titled “Tags in Event Context”](#tags-in-event-context)

All tags (both static and dynamic) are available on the `EventContext` when processing events:

* C#

```csharp
  using System.Linq;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

public record TaggingUserAnalytics(int LoginCount, int CriticalLoginCount);

public class TaggingUserAnalyticsReducer : IReducerFor<TaggingUserAnalytics>
  {
      public TaggingUserAnalytics LoggedIn(TaggingUserLoggedIn @event, TaggingUserAnalytics? current, EventContext context)
      {
          var analytics = current ?? new TaggingUserAnalytics(0, 0);

// Access tags from the event context
          var isCritical = context.Tags.Any(tag => tag.Value == "critical");

return analytics with
          {
              LoginCount = analytics.LoginCount + 1,
              CriticalLoginCount = analytics.CriticalLoginCount + (isCritical ? 1 : 0)
          };
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.observation.Reducer
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class TaggingUserAnalytics(val loginCount: Int = 0, val criticalLoginCount: Int = 0)

@Reducer
  class TaggingUserAnalyticsReducer {
      fun loggedIn(
          event: TaggingUserLoggedIn,
          current: TaggingUserAnalytics?,
          context: EventContext
      ): TaggingUserAnalytics {
          val analytics = current ?: TaggingUserAnalytics()

// Tags the event was appended with are available on the context.
          val isCritical = context.tags.contains("critical")

return analytics.copy(
              loginCount = analytics.loginCount + 1,
              criticalLoginCount = analytics.criticalLoginCount + if (isCritical) 1 else 0
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.observation.Reducer;
  import io.cratis.chronicle.readModels.ReadModel;

@ReadModel
  record TaggingUserAnalytics(int loginCount, int criticalLoginCount) {
      static TaggingUserAnalytics initial() {
          return new TaggingUserAnalytics(0, 0);
      }
  }

@Reducer
  class TaggingUserAnalyticsReducer {
      TaggingUserAnalytics loggedIn(TaggingUserLoggedIn event, TaggingUserAnalytics current, EventContext context) {
          TaggingUserAnalytics analytics = current != null ? current : TaggingUserAnalytics.initial();

// Tags the event was appended with are available on the context.
          boolean isCritical = context.getTags().contains("critical");

return new TaggingUserAnalytics(
              analytics.loginCount() + 1,
              analytics.criticalLoginCount() + (isCritical ? 1 : 0));
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, reducer } from '@cratis/chronicle';

class TaggingUserAnalytics {
      loginCount = 0;
      criticalLoginCount = 0;
  }

@reducer('', undefined, TaggingUserAnalytics)
  class TaggingUserAnalyticsReducer {
      taggingUserLoggedIn(
          event: TaggingUserLoggedIn,
          current: TaggingUserAnalytics | undefined,
          context: EventContext
      ): TaggingUserAnalytics {
          const analytics = current ?? new TaggingUserAnalytics();

// Access tags from the event context
          const isCritical = context.tags.some(tag => tag.value === 'critical');

return {
              loginCount: analytics.loginCount + 1,
              criticalLoginCount: analytics.criticalLoginCount + (isCritical ? 1 : 0)
          };
      }
  }
  ```

## Tagging Observers

[Section titled “Tagging Observers”](#tagging-observers)

Observers (reactors, reducers, and projections) can be tagged to organize and categorize them:

### Single Tag

[Section titled “Single Tag”](#single-tag)

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Reactors;

[Tag("Notifications")]
  public class TaggingOrderConfirmationReactor : IReactor;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@Tag("Notifications")
  @Reactor
  class TaggingOrderConfirmationReactor
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

@Tag("Notifications")
  @Reactor
  class TaggingOrderConfirmationReactor {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { reactor, tag } from '@cratis/chronicle';

@reactor()
  @tag('Notifications')
  class TaggingOrderConfirmationReactor {}
  ```

### Multiple Tags (Single Attribute)

[Section titled “Multiple Tags (Single Attribute)”](#multiple-tags-single-attribute)

You can use either `[Tag]` or `[Tags]` (plural) for convenience:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Reactors;

[Tag("Notifications", "Customer", "Email")]
  public class TaggingCustomerNotificationReactor : IReactor;

// [Tags] (plural) is equivalent — use whichever reads more naturally
  [Tags("Notifications", "Customer", "Email")]
  public class TaggingCustomerNotificationReactorAlternate : IReactor;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@Tag("Notifications", "Customer", "Email")
  @Reactor
  class TaggingCustomerNotificationReactor
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

@Tag({"Notifications", "Customer", "Email"})
  @Reactor
  class TaggingCustomerNotificationReactor {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { reactor, tag, tags } from '@cratis/chronicle';

@reactor()
  @tag('Notifications', 'Customer', 'Email')
  class TaggingCustomerNotificationReactor {}

// @tags() (plural) is equivalent — use whichever reads more naturally
  @reactor()
  @tags('Notifications', 'Customer', 'Email')
  class TaggingCustomerNotificationReactorAlternate {}
  ```

### Multiple Tags (Multiple Attributes)

[Section titled “Multiple Tags (Multiple Attributes)”](#multiple-tags-multiple-attributes)

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Reactors;

[Tag("Integration")]
  [Tag("ExternalAPI")]
  [Tag("Inventory")]
  public class TaggingInventorySyncReactor : IReactor;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@Tag("Integration")
  @Tag("ExternalAPI")
  @Tag("Inventory")
  @Reactor
  class TaggingInventorySyncReactor
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

@Tag("Integration")
  @Tag("ExternalAPI")
  @Tag("Inventory")
  @Reactor
  class TaggingInventorySyncReactor {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { reactor, tag } from '@cratis/chronicle';

@reactor()
  @tag('Integration')
  @tag('ExternalAPI')
  @tag('Inventory')
  class TaggingInventorySyncReactor {}
  ```

### Mixed Approach

[Section titled “Mixed Approach”](#mixed-approach)

You can mix both `[Tag]` and `[Tags]` attributes - all tags will be merged:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Reactors;

[Tag("Notifications", "SMS")]
  [Tags("Customer")]
  public class TaggingSmsNotificationReactor : IReactor;

// Or mix single and multiple attributes the other way around
  [Tag("Integration")]
  [Tags("ExternalAPI", "Inventory")]
  public class TaggingInventorySyncReactorMixed : IReactor;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

// Kotlin exposes only @Tag (repeatable) - combine a multi-value use with a stacked one however reads best
  @Tag("Notifications", "SMS")
  @Tag("Customer")
  @Reactor
  class TaggingSmsNotificationReactor
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

// Java exposes only @Tag (repeatable) - combine a multi-value use with a stacked one however reads best
  @Tag({"Notifications", "SMS"})
  @Tag("Customer")
  @Reactor
  class TaggingSmsNotificationReactor {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { reactor, tag, tags } from '@cratis/chronicle';

@reactor()
  @tag('Notifications', 'SMS')
  @tags('Customer')
  class TaggingSmsNotificationReactor {}

// Or mix single and multiple attributes the other way around
  @reactor()
  @tag('Integration')
  @tags('ExternalAPI', 'Inventory')
  class TaggingInventorySyncReactorMixed {}
  ```

## Tagging Read Models

[Section titled “Tagging Read Models”](#tagging-read-models)

Read models and projections can also be tagged:

* C#

```csharp
  using Cratis.Chronicle;

[Tag("Reporting", "Analytics")]
  public record TaggingConceptsSalesReport(decimal TotalSales, int OrderCount);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { tag } from '@cratis/chronicle';

@tag('Reporting', 'Analytics')
  class TaggingConceptsSalesReport {
      constructor(readonly totalSales: number, readonly orderCount: number) {}
  }
  ```

## Best Practices

[Section titled “Best Practices”](#best-practices)

* **Use meaningful names**: Choose tag names that clearly describe the purpose or domain
* **Be consistent**: Establish tag naming conventions across your organization
* **Don’t over-tag**: Apply only relevant tags; too many can reduce their usefulness
* **Group related artifacts**: Use tags to group events and observers that serve similar purposes
* **Consider hierarchies**: Use dot notation for hierarchical tags (e.g., `"customer.registration"`, `"customer.profile"`)

## Common Tagging Patterns

[Section titled “Common Tagging Patterns”](#common-tagging-patterns)

Here are some common patterns for organizing tags:

### By Domain

[Section titled “By Domain”](#by-domain)

* C#

```csharp
  using Cratis.Chronicle;

[Tag("Sales")]
  [Tag("Inventory")]
  [Tag("Customer")]
  [Tag("Shipping")]
  public record TaggingByDomainExample;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@Tag("Sales")
  @Tag("Inventory")
  @Tag("Customer")
  @Tag("Shipping")
  @Reactor
  class TaggingByDomainExample
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

@Tag("Sales")
  @Tag("Inventory")
  @Tag("Customer")
  @Tag("Shipping")
  @Reactor
  class TaggingByDomainExample {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { tag } from '@cratis/chronicle';

@tag('Sales')
  @tag('Inventory')
  @tag('Customer')
  @tag('Shipping')
  class TaggingByDomainExample {}
  ```

### By Purpose

[Section titled “By Purpose”](#by-purpose)

* C#

```csharp
  using Cratis.Chronicle;

[Tag("Analytics")]
  [Tag("Reporting")]
  [Tag("Integration")]
  [Tag("Alerting")]
  [Tag("Monitoring")]
  [Tag("Automation")]
  public record TaggingByPurposeExample;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@Tag("Analytics")
  @Tag("Reporting")
  @Tag("Integration")
  @Tag("Alerting")
  @Tag("Monitoring")
  @Tag("Automation")
  @Reactor
  class TaggingByPurposeExample
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

@Tag("Analytics")
  @Tag("Reporting")
  @Tag("Integration")
  @Tag("Alerting")
  @Tag("Monitoring")
  @Tag("Automation")
  @Reactor
  class TaggingByPurposeExample {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { tag } from '@cratis/chronicle';

@tag('Analytics')
  @tag('Reporting')
  @tag('Integration')
  @tag('Alerting')
  @tag('Monitoring')
  @tag('Automation')
  class TaggingByPurposeExample {}
  ```

### By Integration Type

[Section titled “By Integration Type”](#by-integration-type)

* C#

```csharp
  using Cratis.Chronicle;

[Tag("Notifications")]
  [Tag("ExternalAPI")]
  [Tag("MessageQueue")]
  [Tag("FileSystem")]
  public record TaggingByIntegrationTypeExample;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@Tag("Notifications")
  @Tag("ExternalAPI")
  @Tag("MessageQueue")
  @Tag("FileSystem")
  @Reactor
  class TaggingByIntegrationTypeExample
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

@Tag("Notifications")
  @Tag("ExternalAPI")
  @Tag("MessageQueue")
  @Tag("FileSystem")
  @Reactor
  class TaggingByIntegrationTypeExample {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { tag } from '@cratis/chronicle';

@tag('Notifications')
  @tag('ExternalAPI')
  @tag('MessageQueue')
  @tag('FileSystem')
  class TaggingByIntegrationTypeExample {}
  ```

### By Communication Channel

[Section titled “By Communication Channel”](#by-communication-channel)

* C#

```csharp
  using Cratis.Chronicle;

[Tag("Email")]
  [Tag("SMS")]
  [Tag("Push")]
  [Tag("Webhook")]
  public record TaggingByCommunicationChannelExample;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@Tag("Email")
  @Tag("SMS")
  @Tag("Push")
  @Tag("Webhook")
  @Reactor
  class TaggingByCommunicationChannelExample
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

@Tag("Email")
  @Tag("SMS")
  @Tag("Push")
  @Tag("Webhook")
  @Reactor
  class TaggingByCommunicationChannelExample {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { tag } from '@cratis/chronicle';

@tag('Email')
  @tag('SMS')
  @tag('Push')
  @tag('Webhook')
  class TaggingByCommunicationChannelExample {}
  ```

### By Stakeholder

[Section titled “By Stakeholder”](#by-stakeholder)

* C#

```csharp
  using Cratis.Chronicle;

[Tag("Customer")]
  [Tag("Operations")]
  [Tag("Finance")]
  [Tag("Support")]
  [Tag("Executive")]
  public record TaggingByStakeholderExample;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@Tag("Customer")
  @Tag("Operations")
  @Tag("Finance")
  @Tag("Support")
  @Tag("Executive")
  @Reactor
  class TaggingByStakeholderExample
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

@Tag("Customer")
  @Tag("Operations")
  @Tag("Finance")
  @Tag("Support")
  @Tag("Executive")
  @Reactor
  class TaggingByStakeholderExample {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { tag } from '@cratis/chronicle';

@tag('Customer')
  @tag('Operations')
  @tag('Finance')
  @tag('Support')
  @tag('Executive')
  class TaggingByStakeholderExample {}
  ```

### By Environment or Context

[Section titled “By Environment or Context”](#by-environment-or-context)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

[EventType]
  public record TaggingDynamicTagsEventOccurred(string Data);

public class TaggingDynamicTagsService(IEventLog eventLog)
  {
      public Task RecordProductionCritical(EventSourceId eventSourceId) =>
          eventLog.Append(eventSourceId, new TaggingDynamicTagsEventOccurred("production issue"), tags: ["production", "critical"]);

public Task RecordDevelopmentTest(EventSourceId eventSourceId) =>
          eventLog.Append(eventSourceId, new TaggingDynamicTagsEventOccurred("test run"), tags: ["development", "testing"]);

public Task RecordBatchMigration(EventSourceId eventSourceId) =>
          eventLog.Append(eventSourceId, new TaggingDynamicTagsEventOccurred("batch migration"), tags: ["migration", "batch-process"]);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.eventSequences.IEventLog
  import io.cratis.chronicle.events.EventType

@EventType
  data class TaggingDynamicTagsEventOccurred(val data: String)

class TaggingDynamicTagsService(private val eventLog: IEventLog) {
      suspend fun recordProductionCritical(eventSourceId: String) =
          eventLog.append(
              eventSourceId,
              TaggingDynamicTagsEventOccurred("production issue"),
              AppendOptions(tags = listOf("production", "critical"))
          )

suspend fun recordDevelopmentTest(eventSourceId: String) =
          eventLog.append(
              eventSourceId,
              TaggingDynamicTagsEventOccurred("test run"),
              AppendOptions(tags = listOf("development", "testing"))
          )

suspend fun recordBatchMigration(eventSourceId: String) =
          eventLog.append(
              eventSourceId,
              TaggingDynamicTagsEventOccurred("batch migration"),
              AppendOptions(tags = listOf("migration", "batch-process"))
          )
  }
  ```

* Java

```java
  import io.cratis.chronicle.eventSequences.IEventLog;
  import io.cratis.chronicle.events.EventType;

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

@EventType
  record TaggingDynamicTagsEventOccurred(String data) {}

class TaggingDynamicTagsService {
      private final IEventLog eventLog;

TaggingDynamicTagsService(IEventLog eventLog) {
          this.eventLog = eventLog;
      }

void recordProductionCritical(String eventSourceId) {
          EventLogJavaBridge.append(
              eventLog,
              eventSourceId,
              new TaggingDynamicTagsEventOccurred("production issue"),
              new AppendOptionsBuilder().tag("production").tag("critical").build());
      }

void recordDevelopmentTest(String eventSourceId) {
          EventLogJavaBridge.append(
              eventLog,
              eventSourceId,
              new TaggingDynamicTagsEventOccurred("test run"),
              new AppendOptionsBuilder().tag("development").tag("testing").build());
      }

void recordBatchMigration(String eventSourceId) {
          EventLogJavaBridge.append(
              eventLog,
              eventSourceId,
              new TaggingDynamicTagsEventOccurred("batch migration"),
              new AppendOptionsBuilder().tag("migration").tag("batch-process").build());
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.TaggingDynamicPatternsEventOccurred do
    use Chronicle.Events.EventType, id: "tagging-dynamic-patterns-event-occurred"

defstruct [:data]
  end

defmodule MyApp.TaggingDynamicPatternsService do
    alias MyApp.Events.TaggingDynamicPatternsEventOccurred

def record_production_critical(event_source_id) do
      Chronicle.append(
        event_source_id,
        %TaggingDynamicPatternsEventOccurred{data: "production issue"},
        tags: ["production", "critical"]
      )
    end

def record_development_test(event_source_id) do
      Chronicle.append(
        event_source_id,
        %TaggingDynamicPatternsEventOccurred{data: "test run"},
        tags: ["development", "testing"]
      )
    end

def record_batch_migration(event_source_id) do
      Chronicle.append(
        event_source_id,
        %TaggingDynamicPatternsEventOccurred{data: "batch migration"},
        tags: ["migration", "batch-process"]
      )
    end
  end
  ```

* TypeScript

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

@eventType()
  class TaggingDynamicTagsEventOccurred {
      constructor(readonly data: string) {}
  }

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

async recordProductionCritical(eventSourceId: string): Promise<void> {
          await this.store.eventLog.append(
              eventSourceId,
              new TaggingDynamicTagsEventOccurred('production issue'),
              { tags: ['production', 'critical'] });
      }

async recordDevelopmentTest(eventSourceId: string): Promise<void> {
          await this.store.eventLog.append(
              eventSourceId,
              new TaggingDynamicTagsEventOccurred('test run'),
              { tags: ['development', 'testing'] });
      }

async recordBatchMigration(eventSourceId: string): Promise<void> {
          await this.store.eventLog.append(
              eventSourceId,
              new TaggingDynamicTagsEventOccurred('batch migration'),
              { tags: ['migration', 'batch-process'] });
      }
  }
  ```

## Using Tags

[Section titled “Using Tags”](#using-tags)

Tags stored in the event store and observer definitions can be used for:

* **Filtering and searching** for specific events or observers
* **Organizing artifacts** in administrative interfaces
* **Generating documentation** about your system
* **Managing deployments** by tag
* **Monitoring and alerting** based on tag groups
* **Controlling activation** of observers by tag
* **Analyzing event patterns** and flows
* **Creating tag-based subscriptions** or filters

Note: The specific querying and filtering capabilities depend on your Chronicle setup and tooling.

# Tagging Reactors

Tags provide a way to organize and categorize your reactors for better discoverability and management. By applying the `[Tag]` attribute to your reactor classes, you can assign one or more tags that describe the purpose or domain of the reactor.

`[Tag]` and `[Tags]` label the reactor itself. They do not filter which appended events the reactor handles. For event filtering based on appended metadata, see [Filter reducers and reactors by tag](/chronicle/events/filtering/by-tag/), [Filter reducers and reactors by event source type](/chronicle/events/filtering/by-event-source-type/), and [Filter reducers and reactors by event stream type](/chronicle/events/filtering/by-event-stream-type/).

Client coverage

Kotlin and Java tag a reactor with `@Tag`, which is repeatable and takes any number of tags. Elixir’s `use Chronicle.Reactors.Reactor` and TypeScript’s `reactor()` expose no way to attach descriptive tags to the reactor itself.

## Adding Tags

[Section titled “Adding Tags”](#adding-tags)

You can tag reactors in multiple ways:

### Single Tag

[Section titled “Single Tag”](#single-tag)

Apply a single tag to your reactor:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record TaggingReactorsOrderPlaced(string CustomerId, string OrderId);

public interface ITaggingReactorsEmailService
  {
      Task SendOrderConfirmation(string customerId, string orderId);
  }

[Tag("Notifications")]
  public class TaggingReactorsOrderConfirmationReactor(ITaggingReactorsEmailService emailService) : IReactor
  {
      public Task Placed(TaggingReactorsOrderPlaced @event, EventContext context) =>
          emailService.SendOrderConfirmation(@event.CustomerId, @event.OrderId);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@EventType
  data class TaggingReactorsOrderPlaced(val customerId: String, val orderId: String)

interface TaggingReactorsEmailService {
      suspend fun sendOrderConfirmation(customerId: String, orderId: String)
  }

@Tag("Notifications")
  @Reactor
  class TaggingReactorsOrderConfirmationReactor(private val emailService: TaggingReactorsEmailService) {
      suspend fun placed(event: TaggingReactorsOrderPlaced, context: EventContext) =
          emailService.sendOrderConfirmation(event.customerId, event.orderId)
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

@EventType
  record TaggingReactorsOrderPlaced(String customerId, String orderId) {}

interface TaggingReactorsEmailService {
      void sendOrderConfirmation(String customerId, String orderId);
  }

@Tag("Notifications")
  @Reactor
  class TaggingReactorsOrderConfirmationReactor {
      private final TaggingReactorsEmailService emailService;

TaggingReactorsOrderConfirmationReactor(TaggingReactorsEmailService emailService) {
          this.emailService = emailService;
      }

void placed(TaggingReactorsOrderPlaced event, EventContext context) {
          emailService.sendOrderConfirmation(event.customerId(), event.orderId());
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, reactor, tag } from '@cratis/chronicle';

@eventType()
  class TaggingReactorsOrderPlaced {
      constructor(readonly customerId: string, readonly orderId: string) {}
  }

interface TaggingReactorsEmailService {
      sendOrderConfirmation(customerId: string, orderId: string): Promise<void>;
  }

@reactor()
  @tag('Notifications')
  class TaggingReactorsOrderConfirmationReactor {
      constructor(private readonly emailService: TaggingReactorsEmailService) {}

async taggingReactorsOrderPlaced(event: TaggingReactorsOrderPlaced, _context: EventContext): Promise<void> {
          await this.emailService.sendOrderConfirmation(event.customerId, event.orderId);
      }
  }
  ```

### Multiple Tags (Single Attribute)

[Section titled “Multiple Tags (Single Attribute)”](#multiple-tags-single-attribute)

Use the params feature to specify multiple tags in a single attribute:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record TaggingReactorsCustomerRegistered(string Email, string Name);

public interface ITaggingReactorsWelcomeEmailService
  {
      Task SendWelcomeEmail(string email, string name);
  }

[Tag("Notifications", "Customer", "Email")]
  public class TaggingReactorsCustomerNotificationReactor(ITaggingReactorsWelcomeEmailService emailService) : IReactor
  {
      public Task Registered(TaggingReactorsCustomerRegistered @event, EventContext context) =>
          emailService.SendWelcomeEmail(@event.Email, @event.Name);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@EventType
  data class TaggingReactorsCustomerRegistered(val email: String, val name: String)

interface TaggingReactorsWelcomeEmailService {
      suspend fun sendWelcomeEmail(email: String, name: String)
  }

@Tag("Notifications", "Customer", "Email")
  @Reactor
  class TaggingReactorsCustomerNotificationReactor(private val emailService: TaggingReactorsWelcomeEmailService) {
      suspend fun registered(event: TaggingReactorsCustomerRegistered, context: EventContext) =
          emailService.sendWelcomeEmail(event.email, event.name)
  }
  ```

* Java

@EventType
  record TaggingReactorsCustomerRegistered(String email, String name) {}

interface TaggingReactorsWelcomeEmailService {
      void sendWelcomeEmail(String email, String name);
  }

@Tag({"Notifications", "Customer", "Email"})
  @Reactor
  class TaggingReactorsCustomerNotificationReactor {
      private final TaggingReactorsWelcomeEmailService emailService;

TaggingReactorsCustomerNotificationReactor(TaggingReactorsWelcomeEmailService emailService) {
          this.emailService = emailService;
      }

void registered(TaggingReactorsCustomerRegistered event, EventContext context) {
          emailService.sendWelcomeEmail(event.email(), event.name());
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, reactor, tag } from '@cratis/chronicle';

@eventType()
  class TaggingReactorsCustomerRegistered {
      constructor(readonly email: string, readonly name: string) {}
  }

interface TaggingReactorsWelcomeEmailService {
      sendWelcomeEmail(email: string, name: string): Promise<void>;
  }

@reactor()
  @tag('Notifications', 'Customer', 'Email')
  class TaggingReactorsCustomerNotificationReactor {
      constructor(private readonly emailService: TaggingReactorsWelcomeEmailService) {}

async taggingReactorsCustomerRegistered(event: TaggingReactorsCustomerRegistered, _context: EventContext): Promise<void> {
          await this.emailService.sendWelcomeEmail(event.email, event.name);
      }
  }
  ```

### Multiple Tags (Multiple Attributes)

[Section titled “Multiple Tags (Multiple Attributes)”](#multiple-tags-multiple-attributes)

Apply multiple `[Tag]` attributes:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record TaggingReactorsProductStockChanged(string ProductId, int NewQuantity);

public interface ITaggingReactorsInventoryApi
  {
      Task UpdateStock(string productId, int newQuantity);
  }

[Tag("Integration")]
  [Tag("ExternalAPI")]
  [Tag("Inventory")]
  public class TaggingReactorsInventorySyncReactor(ITaggingReactorsInventoryApi inventoryApi) : IReactor
  {
      public Task StockChanged(TaggingReactorsProductStockChanged @event, EventContext context) =>
          inventoryApi.UpdateStock(@event.ProductId, @event.NewQuantity);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@EventType
  data class TaggingReactorsProductStockChanged(val productId: String, val newQuantity: Int)

interface TaggingReactorsInventoryApi {
      suspend fun updateStock(productId: String, newQuantity: Int)
  }

@Tag("Integration")
  @Tag("ExternalAPI")
  @Tag("Inventory")
  @Reactor
  class TaggingReactorsInventorySyncReactor(private val inventoryApi: TaggingReactorsInventoryApi) {
      suspend fun stockChanged(event: TaggingReactorsProductStockChanged, context: EventContext) =
          inventoryApi.updateStock(event.productId, event.newQuantity)
  }
  ```

* Java

@EventType
  record TaggingReactorsProductStockChanged(String productId, int newQuantity) {}

interface TaggingReactorsInventoryApi {
      void updateStock(String productId, int newQuantity);
  }

@Tag("Integration")
  @Tag("ExternalAPI")
  @Tag("Inventory")
  @Reactor
  class TaggingReactorsInventorySyncReactor {
      private final TaggingReactorsInventoryApi inventoryApi;

TaggingReactorsInventorySyncReactor(TaggingReactorsInventoryApi inventoryApi) {
          this.inventoryApi = inventoryApi;
      }

void stockChanged(TaggingReactorsProductStockChanged event, EventContext context) {
          inventoryApi.updateStock(event.productId(), event.newQuantity());
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, reactor, tag } from '@cratis/chronicle';

@eventType()
  class TaggingReactorsProductStockChanged {
      constructor(readonly productId: string, readonly newQuantity: number) {}
  }

interface TaggingReactorsInventoryApi {
      updateStock(productId: string, newQuantity: number): Promise<void>;
  }

@reactor()
  @tag('Integration')
  @tag('ExternalAPI')
  @tag('Inventory')
  class TaggingReactorsInventorySyncReactor {
      constructor(private readonly inventoryApi: TaggingReactorsInventoryApi) {}

async taggingReactorsProductStockChanged(event: TaggingReactorsProductStockChanged, _context: EventContext): Promise<void> {
          await this.inventoryApi.updateStock(event.productId, event.newQuantity);
      }
  }
  ```

### Mixed Approach

[Section titled “Mixed Approach”](#mixed-approach)

Combine both approaches:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record TaggingReactorsOrderShipped(string PhoneNumber, string TrackingNumber);

public interface ITaggingReactorsSmsService
  {
      Task SendShippingNotification(string phoneNumber, string trackingNumber);
  }

[Tag("Notifications", "SMS")]
  [Tag("Customer")]
  public class TaggingReactorsSmsNotificationReactor(ITaggingReactorsSmsService smsService) : IReactor
  {
      public Task Shipped(TaggingReactorsOrderShipped @event, EventContext context) =>
          smsService.SendShippingNotification(@event.PhoneNumber, @event.TrackingNumber);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

@EventType
  data class TaggingReactorsOrderShipped(val phoneNumber: String, val trackingNumber: String)

interface TaggingReactorsSmsService {
      suspend fun sendShippingNotification(phoneNumber: String, trackingNumber: String)
  }

@Tag("Notifications", "SMS")
  @Tag("Customer")
  @Reactor
  class TaggingReactorsSmsNotificationReactor(private val smsService: TaggingReactorsSmsService) {
      suspend fun shipped(event: TaggingReactorsOrderShipped, context: EventContext) =
          smsService.sendShippingNotification(event.phoneNumber, event.trackingNumber)
  }
  ```

* Java

@EventType
  record TaggingReactorsOrderShipped(String phoneNumber, String trackingNumber) {}

interface TaggingReactorsSmsService {
      void sendShippingNotification(String phoneNumber, String trackingNumber);
  }

@Tag({"Notifications", "SMS"})
  @Tag("Customer")
  @Reactor
  class TaggingReactorsSmsNotificationReactor {
      private final TaggingReactorsSmsService smsService;

TaggingReactorsSmsNotificationReactor(TaggingReactorsSmsService smsService) {
          this.smsService = smsService;
      }

void shipped(TaggingReactorsOrderShipped event, EventContext context) {
          smsService.sendShippingNotification(event.phoneNumber(), event.trackingNumber());
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, reactor, tag } from '@cratis/chronicle';

@eventType()
  class TaggingReactorsOrderShipped {
      constructor(readonly phoneNumber: string, readonly trackingNumber: string) {}
  }

interface TaggingReactorsSmsService {
      sendShippingNotification(phoneNumber: string, trackingNumber: string): Promise<void>;
  }

@reactor()
  @tag('Notifications', 'SMS')
  @tag('Customer')
  class TaggingReactorsSmsNotificationReactor {
      constructor(private readonly smsService: TaggingReactorsSmsService) {}

async taggingReactorsOrderShipped(event: TaggingReactorsOrderShipped, _context: EventContext): Promise<void> {
          await this.smsService.sendShippingNotification(event.phoneNumber, event.trackingNumber);
      }
  }
  ```

## Best Practices

[Section titled “Best Practices”](#best-practices)

* **Use meaningful names**: Choose tag names that clearly describe the purpose or domain
* **Be consistent**: Establish tag naming conventions across your organization
* **Don’t over-tag**: Apply only relevant tags; too many can reduce their usefulness
* **Group related reactors**: Use tags to group reactors that serve similar purposes

## Common Tag Examples

[Section titled “Common Tag Examples”](#common-tag-examples)

Here are some common patterns for tagging reactors:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Reactors;

// By integration type
  [Tag("Notifications", "ExternalAPI", "MessageQueue", "FileSystem")]
  // By domain
  [Tag("Sales", "Inventory", "Customer", "Shipping")]
  // By communication channel
  [Tag("Email", "SMS", "Push", "Webhook")]
  // By purpose
  [Tag("Integration", "Alerting", "Monitoring", "Automation")]
  // By stakeholder
  [Tag("Customer", "Operations", "Finance", "Support")]
  public class TaggingReactorsCategoryExamplesReactor : IReactor;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Tag

// By integration type
  @Tag("Notifications", "ExternalAPI", "MessageQueue", "FileSystem")
  // By domain
  @Tag("Sales", "Inventory", "Customer", "Shipping")
  // By communication channel
  @Tag("Email", "SMS", "Push", "Webhook")
  // By purpose
  @Tag("Integration", "Alerting", "Monitoring", "Automation")
  // By stakeholder
  @Tag("Customer", "Operations", "Finance", "Support")
  @Reactor
  class TaggingReactorsCategoryExamplesReactor
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Tag;

// By integration type
  @Tag({"Notifications", "ExternalAPI", "MessageQueue", "FileSystem"})
  // By domain
  @Tag({"Sales", "Inventory", "Customer", "Shipping"})
  // By communication channel
  @Tag({"Email", "SMS", "Push", "Webhook"})
  // By purpose
  @Tag({"Integration", "Alerting", "Monitoring", "Automation"})
  // By stakeholder
  @Tag({"Customer", "Operations", "Finance", "Support"})
  @Reactor
  class TaggingReactorsCategoryExamplesReactor {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { reactor, tag } from '@cratis/chronicle';

@reactor()
  // By integration type
  @tag('Notifications', 'ExternalAPI', 'MessageQueue', 'FileSystem')
  // By domain
  @tag('Sales', 'Inventory', 'Customer', 'Shipping')
  // By communication channel
  @tag('Email', 'SMS', 'Push', 'Webhook')
  // By purpose
  @tag('Integration', 'Alerting', 'Monitoring', 'Automation')
  // By stakeholder
  @tag('Customer', 'Operations', 'Finance', 'Support')
  class TaggingReactorsCategoryExamplesReactor {}
  ```

## Querying by Tag

[Section titled “Querying by Tag”](#querying-by-tag)

Tags stored in the event store definition can be used for:

* Filtering and searching for specific reactors
* Organizing reactors in administrative interfaces
* Generating documentation
* Managing reactor deployments by tag
* Monitoring and alerting based on tag groups
* Controlling reactor activation by tag

Note: The specific querying capabilities depend on your Chronicle setup and tooling.

## See Also

[Section titled “See Also”](#see-also)

* [Tagging](/chronicle/concepts/tagging/) - Comprehensive guide to tagging in Chronicle
* [Reducers Tagging](/chronicle/reducers/tagging-reducers/) - Tagging reducers

# When to use event sourcing

> An honest look at why event sourcing is the Cratis default for information systems, where it pays off, and where a current-state slice can stay simpler.

Event sourcing is the Cratis default for information systems, but it is not free. The useful question is not “can this be event-sourced?” It is “which parts of this system carry meaningful facts over time, and which parts are genuinely just current-state data?” [Why Event Sourcing](/chronicle/why-event-sourcing/) makes the case for the default; this page names the boundaries.

## Where it pays off by default

[Section titled “Where it pays off by default”](#where-it-pays-off-by-default)

Event sourcing earns its keep when **history and change are part of the problem**, which is true for most business-facing information systems:

* **Audit and compliance** — you need a complete, tamper-evident record of what happened and when. The event log *is* the audit trail.
* **Process-heavy domains** — orders, claims, onboarding, logistics: things move through states and the transitions matter.
* **“How did we get here?” is a real question** — debugging, dispute resolution, or analytics that need the past, not just the present.
* **Multiple read shapes from the same facts** — you want several specialized [read models](/chronicle/read-models/) over one stream of truth.
* **Integration and reactions** — other parts of the system need to act when something happens.

## Where to be skeptical

[Section titled “Where to be skeptical”](#where-to-be-skeptical)

Be skeptical when:

* **The domain is genuinely CRUD.** A few forms over a table where the current state is the whole story and nobody will ever ask what changed — a relational or document database is simpler and you should use one.
* **There is no meaningful behavior.** If every “change” is just “overwrite this field,” you’re modeling state, not events.
* **The team has no appetite for the concepts.** Events, projections, and eventual consistency are a real learning curve. If the problem doesn’t justify it, the curve is pure cost.

## The trade-offs to weigh

[Section titled “The trade-offs to weigh”](#the-trade-offs-to-weigh)

* **Eventual consistency.** Read models are built *after* events are appended, so a read immediately after a write may not reflect it yet. This is usually fine — but it’s a shift if you expect read-after-write everywhere. See [Read Models](/chronicle/read-models/).
* **Modeling discipline.** Events are immutable facts; getting their granularity and naming right takes thought, and changing them later means [event type migrations](/chronicle/concepts/event-type-migrations/), not an `ALTER TABLE`.
* **More moving parts.** Commands, events, projections, and reactors are more concepts than “save the row” — the framework removes the boilerplate, but the mental model is larger.
* **Privacy.** Immutable history and “the right to be forgotten” need a deliberate strategy — see [Compliance](/chronicle/compliance/).

## A middle path

[Section titled “A middle path”](#a-middle-path)

You don’t have to choose globally. Event-source the core domain and the processes that define the system, and keep plain CRUD for parts that are genuinely just current-state data: reference tables, settings, or small admin surfaces. Cratis is happy alongside a relational or document store for those bits, and Arc can put the same CQRS boundary over them.

## Next

[Section titled “Next”](#next)

* Convinced it fits? Start with [Get started](/chronicle/get-started/) and the [tutorial](/chronicle/tutorial/).
* Comparing with a CRUD/EF Core model? Read [CRUD, EF Core, and Chronicle](/chronicle/coming-from-crud/).

# Configuration

Chronicle always runs as a **separate process** — the kernel — and your application talks to it as a **client** over gRPC. There is no in-process or embedded kernel to host inside your app, so on this side you’re configuring *how your application connects and behaves as a client*. (To configure the kernel itself — ports, storage backends, features — see [Hosting Configuration](/chronicle/hosting/configuration/).)

Client coverage

This whole `configuration/**` section (this page, [ChronicleOptions](/chronicle/configuration/chronicle-options/), [TLS](/chronicle/configuration/tls/), [gRPC message size](/chronicle/configuration/grpc-message-size/), [structural dependencies](/chronicle/configuration/structural-dependencies/), [camel-casing](/chronicle/configuration/camel-casing/)) is built around .NET’s `appsettings.json`/`Cratis__Chronicle__` environment-variable binding and `AddCratisChronicle`/`IServiceCollection` DI registration — a hosting model specific to .NET. Kotlin, Elixir, and TypeScript each configure a connection through their own client constructor/options object instead (see each client’s getting-started guide) rather than a layered configuration-provider system. The camel-casing page specifically addresses a PascalCase-C#-to-camelCase-JSON mismatch that doesn’t arise the same way in Kotlin (already camelCase) or Elixir (Chronicle’s own macros already convert snake\_case to camelCase automatically, confirmed in the migration builder’s `normalize_property_name`).

## How client configuration flows

[Section titled “How client configuration flows”](#how-client-configuration-flows)

Every client setting can be supplied three ways, and they layer in this order — later wins:

1. **`appsettings.json`**, under the `Cratis:Chronicle` section — the usual home for the connection string and most settings.
2. **Environment variables**, with the `Cratis__Chronicle__` prefix (.NET maps the `__` separator onto nested keys) — convenient for containers and CI.
3. **Code**, via the `configureOptions` callback on `AddCratisChronicle` — it runs *after* binding, so it overrides configuration. Structural dependencies (custom resolvers and providers) can only be set here.

A minimal `appsettings.json`:

```json
{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000",
      "EventStore": "my-store"
    }
  }
}
```

The matching registration on the host — `AddCratisChronicle` reads the section above, and the callback overrides it:

* C#

```csharp
  using Microsoft.Extensions.Hosting;

public static class ConfigurationIndexRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = Host.CreateApplicationBuilder(args);

builder.AddCratisChronicle(options => options.EventStore = "my-store");
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.ChronicleOptions
  import io.cratis.chronicle.EventStore
  import io.cratis.chronicle.connection.ChronicleConnectionString

fun registerEventStore(): EventStore {
      val options = ChronicleOptions(connectionString = ChronicleConnectionString.DEVELOPMENT)
      val client = ChronicleClient(options)
      return client.getEventStore("my-store")
  }
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingChronicleClient;

class ConfigurationIndexRegister {
      IEventStore create() {
          BlockingChronicleClient client = BlockingChronicleClient.connect(ChronicleOptions.development());
          return client.getEventStore("my-store").unwrap();
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ConfigurationIndexRegistration do
    @moduledoc false

def start_link do
      children = [
        {Chronicle.Client, event_store: "my-store"}
      ]

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

* TypeScript

```typescript
  import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';

async function runConfigurationIndexRegistrationExample(): Promise<void> {
      const client = new ChronicleClient(ChronicleOptions.fromConnectionString('chronicle://localhost:35000'));
      const eventStore = await client.getEventStore('my-store');
  }
  ```

`AddCratisChronicle` is an extension on the host builder — `IHostApplicationBuilder` for worker and console hosts, `WebApplicationBuilder` for ASP.NET Core. See the [getting-started host guides](/chronicle/get-started/) for the full setup of each.

## Topics

[Section titled “Topics”](#topics)

* [ChronicleOptions Reference](/chronicle/configuration/chronicle-options/) - Complete reference for all `ChronicleOptions`, `ChronicleClientOptions`, and `ChronicleAspNetCoreOptions` settings, including `appsettings.json` binding.
* [Connection Strings](/chronicle/connection-strings/) - The `chronicle://` connection string format, development defaults, and credentials.
* [Namespaces](/chronicle/namespaces/) - Resolve the event store namespace per request — the basis of multi-tenancy.
* [Camel Casing](/chronicle/configuration/camel-casing/) - Configure camel case naming policy for projection definitions and read model persistence.
* [gRPC Message Size](/chronicle/configuration/grpc-message-size/) - Configure maximum gRPC message sizes for large event batches.
* [Structural Dependencies](/chronicle/configuration/structural-dependencies/) - Configure artifact discovery, identity, namespace resolution, and other build-time dependencies via `ChronicleClient` constructor parameters or `IChronicleBuilder`.
* [TLS](/chronicle/configuration/tls/) - Configure client-side TLS options and certificate handling.

## Configuring the server

[Section titled “Configuring the server”](#configuring-the-server)

The kernel is configured separately from the client. See [Hosting Configuration](/chronicle/hosting/configuration/) for the `chronicle.json` file, environment variables, storage backends, and ports. To stand the kernel up locally, see [Run Chronicle locally](/chronicle/get-started/choose-hosting-model/#run-chronicle-locally).

# Camel Casing

Chronicle can apply a camel case naming policy when building projection definitions and persisting read models. This keeps property names consistent with common JSON naming conventions.

## Overview

[Section titled “Overview”](#overview)

By default, Chronicle uses property names as they appear in C# (PascalCase). Enabling camel case will:

* Govern how projection definitions are built
* Determine the property names used when projections update read models
* Keep naming consistent across projection and read model data

## Using a Direct Client

[Section titled “Using a Direct Client”](#using-a-direct-client)

For direct `ChronicleClient` usage outside of a hosted application, pass a `CamelCaseNamingPolicy` instance via the named `namingPolicy` constructor argument:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Serialization;

public static class CamelCasingDirectClient
  {
      public static ChronicleClient Create() =>
          new(options: new ChronicleOptions(), namingPolicy: new CamelCaseNamingPolicy());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Using ASP.NET Core

[Section titled “Using ASP.NET Core”](#using-aspnet-core)

When building ASP.NET Core applications, use the dependency injection extensions to configure Chronicle with camel case naming policy.

### Basic Configuration

[Section titled “Basic Configuration”](#basic-configuration)

In your `Program.cs` file, configure Chronicle with camel case naming policy using the `IChronicleBuilder` callback:

* C#

```csharp
  using Microsoft.AspNetCore.Builder;

public static class CamelCasingAspNetCoreBasicRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = WebApplication.CreateBuilder(args);

builder.AddCratisChronicle(
              configure: chronicleBuilder => chronicleBuilder.WithCamelCaseNamingPolicy());

var app = builder.Build();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### Dependency Injection Configuration

[Section titled “Dependency Injection Configuration”](#dependency-injection-configuration)

You can combine camel case naming policy with other Chronicle configuration options:

* C#

```csharp
  using Microsoft.AspNetCore.Builder;

public static class CamelCasingAspNetCoreWithOptionsRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = WebApplication.CreateBuilder(args);

builder.AddCratisChronicle(
              configureOptions: options => options.EventStore = "MyEventStore",
              configure: chronicleBuilder => chronicleBuilder.WithCamelCaseNamingPolicy());

var app = builder.Build();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Using .NET Host (Worker Services)

[Section titled “Using .NET Host (Worker Services)”](#using-net-host-worker-services)

For worker services or other non-web hosts using `IHostApplicationBuilder`:

* C#

```csharp
  using Microsoft.Extensions.Hosting;

public static class CamelCasingWorkerHostRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = Host.CreateApplicationBuilder(args);

builder.AddCratisChronicle(
              configure: chronicleBuilder => chronicleBuilder.WithCamelCaseNamingPolicy());

var host = builder.Build();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Impact on Projections

[Section titled “Impact on Projections”](#impact-on-projections)

The naming policy configuration affects how Chronicle handles projections:

### Projection Definition Building

[Section titled “Projection Definition Building”](#projection-definition-building)

When you configure camel case naming policy, Chronicle uses this policy when building projection definitions. This means property mappings within projections will use camel case property names.

### Read Models

[Section titled “Read Models”](#read-models)

The naming policy affects the read model container name, which affects the name of the collection, table, or file that data is persisted as.

When projections project to read models, the property names used will follow the configured naming policy. For example:

#### Event Definition

[Section titled “Event Definition”](#event-definition)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record CamelCasingUserRegistered(
      string FirstName,
      string LastName,
      string EmailAddress,
      DateTime RegistrationDate);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import java.time.Instant

@EventType
  data class CamelCasingUserRegistered(
      val firstName: String = "",
      val lastName: String = "",
      val emailAddress: String = "",
      val registrationDate: Instant = Instant.EPOCH
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

import java.time.Instant;

@EventType
  record CamelCasingUserRegistered(
      String firstName,
      String lastName,
      String emailAddress,
      Instant registrationDate) {
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.CamelCasingUserRegistered do
    use Chronicle.Events.EventType, id: "camel-casing-user-registered"

defstruct [:first_name, :last_name, :email_address, :registration_date]
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

#### Read Model Definition

[Section titled “Read Model Definition”](#read-model-definition)

* C#

```csharp
  public class CamelCasingUserReadModel
  {
      public string FirstName { get; set; } = string.Empty;
      public string LastName { get; set; } = string.Empty;
      public string EmailAddress { get; set; } = string.Empty;
      public DateTime RegistrationDate { get; set; }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.readModels.ReadModel
  import java.time.Instant

@ReadModel
  data class CamelCasingUserReadModel(
      val firstName: String = "",
      val lastName: String = "",
      val emailAddress: String = "",
      val registrationDate: Instant = Instant.EPOCH
  )
  ```

* Java

```java
  import io.cratis.chronicle.readModels.ReadModel;

import java.time.Instant;

@ReadModel
  class CamelCasingUserReadModel {
      public String firstName = "";
      public String lastName = "";
      public String emailAddress = "";
      public Instant registrationDate = Instant.EPOCH;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.CamelCasingUser do
    use Chronicle.ReadModels.ReadModel

defstruct first_name: nil, last_name: nil, email_address: nil, registration_date: nil
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

#### Projection with Camel Case Naming Policy

[Section titled “Projection with Camel Case Naming Policy”](#projection-with-camel-case-naming-policy)

With camel case naming policy configured, Chronicle will use camel case property names when building the projection:

* C#

```csharp
  using Cratis.Chronicle.Projections;

public class CamelCasingUserProjection : IProjectionFor<CamelCasingUserReadModel>
  {
      public void Define(IProjectionBuilderFor<CamelCasingUserReadModel> builder) => builder
          .From<CamelCasingUserRegistered>(_ => _
              .Set(m => m.FirstName).To(e => e.FirstName)
              .Set(m => m.LastName).To(e => e.LastName)
              .Set(m => m.EmailAddress).To(e => e.EmailAddress)
              .Set(m => m.RegistrationDate).To(e => e.RegistrationDate));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionFor
  import io.cratis.chronicle.projections.IProjectionBuilderFor

// Kotlin property names are already camelCase, so the projected read model properties below —
  // firstName, lastName, emailAddress, registrationDate — need no naming policy configuration to
  // come out as camelCase; that is simply how Kotlin properties are named.
  class CamelCasingUserProjection : IProjectionFor<CamelCasingUserReadModel> {
      override fun define(builder: IProjectionBuilderFor<CamelCasingUserReadModel>) {
          builder.from(CamelCasingUserRegistered::class) {
              it.set(CamelCasingUserReadModel::firstName).to { e -> e.firstName }
              it.set(CamelCasingUserReadModel::lastName).to { e -> e.lastName }
              it.set(CamelCasingUserReadModel::emailAddress).to { e -> e.emailAddress }
              it.set(CamelCasingUserReadModel::registrationDate).to { e -> e.registrationDate }
          }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionFor;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.java.ProjectionBuilderJavaBridge;

// Java field names are already camelCase, and AutoMap matches read model properties to event
  // properties of the same name — firstName, lastName, emailAddress, registrationDate — so no
  // naming policy configuration is needed to have them come out as camelCase.
  class CamelCasingUserProjection implements IProjectionFor<CamelCasingUserReadModel> {
      @Override
      public void define(IProjectionBuilderFor<CamelCasingUserReadModel> builder) {
          ProjectionBuilderJavaBridge.from(builder, CamelCasingUserRegistered.class);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Projections.CamelCasingUserProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.CamelCasingUser

from MyApp.Events.CamelCasingUserRegistered,
      set: [
        first_name: :first_name,
        last_name: :last_name,
        email_address: :email_address,
        registration_date: :registration_date
      ]
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The resulting read model data will have camel case property names: `firstName`, `lastName`, `emailAddress`, `registrationDate`.

## Important Notes

[Section titled “Important Notes”](#important-notes)

* The naming policy affects how Chronicle builds projection definitions internally.
* Property names in read models will follow the configured naming policy when data is persisted.
* This configuration is specific to Chronicle operations and does not affect general ASP.NET Core JSON serialization.
* All projections in your application will use the same naming policy once configured.

## Troubleshooting

[Section titled “Troubleshooting”](#troubleshooting)

### Projection Property Names Not Converting

[Section titled “Projection Property Names Not Converting”](#projection-property-names-not-converting)

If projection property names are not being converted to camel case:

1. Verify that `WithCamelCaseNamingPolicy()` is called on the `IChronicleBuilder` during Chronicle configuration.
2. Ensure the configuration is applied before Chronicle services are initialized.
3. Check that all projections are using the same Chronicle client instance.

### Inconsistent Property Naming

[Section titled “Inconsistent Property Naming”](#inconsistent-property-naming)

If you see inconsistent property naming in your read models:

1. Verify that Chronicle is configured with the camel case naming policy via `IChronicleBuilder.WithCamelCaseNamingPolicy()`.
2. Check if any custom property mappings are overriding the global naming policy.
3. Ensure all projection definitions are rebuilt after changing the naming policy.

# ChronicleOptions Reference

`ChronicleOptions` is the root configuration class for all Chronicle .NET clients. All properties can be set in code via the `configureOptions` callback on `AddCratisChronicle`, and most can be bound directly from `appsettings.json` under the `Cratis:Chronicle` section.

There are three options classes that form an inheritance chain, each adding settings relevant to its hosting context:

| Class                        | Used by                       | Adds                                           |
| ---------------------------- | ----------------------------- | ---------------------------------------------- |
| `ChronicleOptions`           | All clients                   | Connection, serialization, timeouts, TLS, auth |
| `ChronicleClientOptions`     | Worker services, console apps | Event store name, namespace resolver type      |
| `ChronicleAspNetCoreOptions` | ASP.NET Core apps             | HTTP header–based namespace resolution         |

## appsettings.json

[Section titled “appsettings.json”](#appsettingsjson)

All bindable settings live under `Cratis:Chronicle`:

```json
{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000",
      "EventStore": "my-store",
      "EnableEventTypeGenerationValidation": false,
      "DefaultSinkTypeId": "SQL",
      "ConnectTimeout": 5,
      "AutoDiscoverAndRegister": true,
      "MaxReceiveMessageSize": 104857600,
      "MaxSendMessageSize": 104857600,
      "ProgramIdentifier": "my-app",
      "ClaimsBasedNamespaceResolverClaimType": "tenant_id",
      "Tls": {
        "CertificatePath": "/certs/client.pfx",
        "CertificatePassword": "secret"
      },
      "Authentication": {
        "Authority": "https://login.example.com"
      }
    }
  }
}
```

## ChronicleOptions properties

[Section titled “ChronicleOptions properties”](#chronicleoptions-properties)

### EnableEventTypeGenerationValidation

[Section titled “EnableEventTypeGenerationValidation”](#enableeventtypegenerationvalidation)

Asks the Kernel to enforce strict migration chain validation when registering event types at generation 2 or higher. The value is forwarded as part of the registration request.

|         |         |
| ------- | ------- |
| Type    | `bool`  |
| Default | `false` |

> **Image restriction:** This flag is only honoured by the **development image** of the Kernel. The production image always ignores it and validates unconditionally, regardless of what the client sends. This makes it impossible to accidentally skip migration chain validation in production even if the client has this flag set to `false`.

To opt in to strict validation during development (recommended once your event schemas are stable), set the flag to `true`:

* C#

```csharp
  using Microsoft.Extensions.Hosting;

public static class ChronicleOptionsEnableValidationRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = Host.CreateApplicationBuilder(args);

builder.AddCratisChronicle(configureOptions: options =>
          {
              options.EnableEventTypeGenerationValidation = true;
          });
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

In `appsettings.json`: `"EnableEventTypeGenerationValidation": true`.

See [Generation Validation](/chronicle/migrations/validation/) for the full ruleset.

### ConnectionString

[Section titled “ConnectionString”](#connectionstring)

The gRPC endpoint for Chronicle Server.

|         |                                                                                            |
| ------- | ------------------------------------------------------------------------------------------ |
| Type    | `ChronicleConnectionString`                                                                |
| Default | Development connection string (`chronicle://localhost:35000` with default dev credentials) |

* C#

```csharp
  using Microsoft.Extensions.Hosting;

public static class ChronicleOptionsConnectionStringRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = Host.CreateApplicationBuilder(args);

builder.AddCratisChronicle(configureOptions: options =>
          {
              options.ConnectionString = "chronicle://myserver:35000";
          });
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleOptions
  import io.cratis.chronicle.connection.ChronicleConnectionString

fun optionsFromConnectionString(): ChronicleOptions =
      ChronicleOptions(connectionString = ChronicleConnectionString.parse("chronicle://myserver:35000"))
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.connection.ChronicleConnectionString;

class ConfigurationChronicleOptionsConnectionString {
      ChronicleOptions create() {
          return new ChronicleOptions(ChronicleConnectionString.Companion.parse("chronicle://myserver:35000"));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ChronicleOptionsConnectionStringRegistration do
    @moduledoc false

def start_link do
      children = [
        {Chronicle.Client, connection_string: "chronicle://myserver:35000"}
      ]

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

* TypeScript

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

function createChronicleOptionsConnectionString(): ChronicleOptions {
      return ChronicleOptions.fromConnectionString('chronicle://myserver:35000');
  }
  ```

In `appsettings.json`: `"ConnectionString": "chronicle://myserver:35000"`.

### ConnectTimeout

[Section titled “ConnectTimeout”](#connecttimeout)

Timeout in seconds when establishing a connection to Chronicle Server.

|         |       |
| ------- | ----- |
| Type    | `int` |
| Default | `5`   |

### AutoDiscoverAndRegister

[Section titled “AutoDiscoverAndRegister”](#autodiscoverandregister)

Controls whether Chronicle automatically discovers event types, projections, reactors, reducers, and other artifacts from loaded assemblies on startup.

|         |        |
| ------- | ------ |
| Type    | `bool` |
| Default | `true` |

Set to `false` when using a custom `IClientArtifactsProvider` or when you want full manual control over what gets registered.

### DefaultSinkTypeId

[Section titled “DefaultSinkTypeId”](#defaultsinktypeid)

Controls which sink type is used when registering projections and reducers with the Kernel. Chronicle supports two built-in sink types:

| Value                        | Description                                            |
| ---------------------------- | ------------------------------------------------------ |
| `WellKnownSinkTypes.MongoDB` | Stores read models in MongoDB (default)                |
| `WellKnownSinkTypes.SQL`     | Stores read models in a SQL database as JSON documents |

|         |                              |
| ------- | ---------------------------- |
| Type    | `SinkTypeId`                 |
| Default | `WellKnownSinkTypes.MongoDB` |

To use SQL as the storage backend for all read models:

* C#

```csharp
  using Microsoft.Extensions.Hosting;
  using Cratis.Chronicle.Sinks;

public static class ChronicleOptionsSqlSinkRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = Host.CreateApplicationBuilder(args);

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

* Kotlin

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

fun optionsWithSqlSink(): ChronicleOptions = ChronicleOptions(
      connectionString = ChronicleConnectionString.DEVELOPMENT,
      defaultSinkTypeId = WellKnownSinkTypes.SQL
  )
  ```

* Java

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

class ConfigurationChronicleOptionsSqlSink {
      ChronicleOptions create() {
          return new ChronicleOptions(ChronicleConnectionString.Companion.getDEVELOPMENT(), "Unknown", WellKnownSinkTypes.SQL);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ChronicleOptionsSqlSinkRegistration do
    @moduledoc false

def start_link do
      children = [
        {Chronicle.Client, default_sink_type_id: :sql}
      ]

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

* TypeScript

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

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

In `appsettings.json`:

```json
{ "Cratis": { "Chronicle": { "DefaultSinkTypeId": "SQL" } } }
```

See [Sinks](/chronicle/sinks/) for detailed guidance on storage backends.

### MaxReceiveMessageSize / MaxSendMessageSize

[Section titled “MaxReceiveMessageSize / MaxSendMessageSize”](#maxreceivemessagesize--maxsendmessagesize)

Maximum gRPC message sizes in bytes. See [gRPC Message Size](/chronicle/configuration/grpc-message-size/) for detailed guidance.

|         |                      |
| ------- | -------------------- |
| Type    | `int?`               |
| Default | `104857600` (100 MB) |

### ProgramIdentifier

[Section titled “ProgramIdentifier”](#programidentifier)

A human-readable identifier for the running application. Included in root causation metadata to identify which program appended an event.

|         |           |
| ------- | --------- |
| Type    | `string`  |
| Default | `"[N/A]"` |

### SoftwareVersion

[Section titled “SoftwareVersion”](#softwareversion)

The software version of the entry assembly, extracted from `AssemblyInformationalVersion` or `AssemblyVersion`. Included in root causation to track which build produced an event.

|         |                                             |
| ------- | ------------------------------------------- |
| Type    | `string`                                    |
| Default | Resolved from the entry assembly at startup |

### SoftwareCommit

[Section titled “SoftwareCommit”](#softwarecommit)

The commit SHA of the entry assembly, extracted from the `+commit` part of `AssemblyInformationalVersion`. Included in root causation to track which commit produced an event.

### ClaimsBasedNamespaceResolverClaimType

[Section titled “ClaimsBasedNamespaceResolverClaimType”](#claimsbasednamespaceresolverclaimtype)

The JWT claim type used by `ClaimsBasedNamespaceResolver` when namespace resolution is configured via `WithClaimsBasedNamespaceResolver`.

|         |               |
| ------- | ------------- |
| Type    | `string`      |
| Default | `"tenant_id"` |

### RegistrationRetry

[Section titled “RegistrationRetry”](#registrationretry)

How registering the client’s artifacts is retried when the Kernel does not accept them.

|         |                                              |
| ------- | -------------------------------------------- |
| Type    | `RegistrationRetryOptions`                   |
| Default | Five attempts, two seconds growing to thirty |

| Nested property | Type       | Default    | Description                                                                                              |
| --------------- | ---------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| `MaxAttempts`   | `int`      | `5`        | How many times registering all artifacts is attempted before the failure surfaces. `1` disables retrying |
| `InitialDelay`  | `TimeSpan` | `00:00:02` | Wait after the first failed attempt. Each further attempt doubles it, jittered                           |
| `MaximumDelay`  | `TimeSpan` | `00:00:30` | Upper bound for the wait between attempts                                                                |

Registration runs on the way up, so a registration that fails takes the host with it. A Kernel that is merely busy — catching a newly added read model up over a large event log, say — answers late rather than wrongly, and a host that dies on that answer comes back and asks again, adding its whole registration to the queue it was already waiting on. Retrying in place lets the client wait out a busy Kernel instead. Registration is idempotent, so a retry costs the Kernel only the comparison it already does; a Kernel that is genuinely refusing the definitions keeps failing and the host still ends up down, just after the attempts are spent rather than on the first.

In `appsettings.json`:

```json
{ "Cratis": { "Chronicle": { "RegistrationRetry": { "MaxAttempts": 10, "MaximumDelay": "00:01:00" } } } }
```

### Tls

[Section titled “Tls”](#tls)

TLS certificate settings for the gRPC connection. TLS is active when both `CertificatePath` and `CertificatePassword` are set. See [TLS](/chronicle/configuration/tls/) for full details.

|         |                                          |
| ------- | ---------------------------------------- |
| Type    | `Tls`                                    |
| Default | TLS disabled (no certificate configured) |

| Nested property       | Type      | Description                       |
| --------------------- | --------- | --------------------------------- |
| `CertificatePath`     | `string?` | Path to a PFX certificate file    |
| `CertificatePassword` | `string?` | Password for the certificate file |

### Authentication

[Section titled “Authentication”](#authentication)

OAuth/OIDC authority configuration. When `Authority` is not set, the Chronicle internal OAuth authority is used.

|         |                    |
| ------- | ------------------ |
| Type    | `Authentication`   |
| Default | Internal authority |

| Nested property | Type      | Description              |
| --------------- | --------- | ------------------------ |
| `Authority`     | `string?` | OAuth/OIDC authority URL |

## ChronicleClientOptions properties

[Section titled “ChronicleClientOptions properties”](#chronicleclientoptions-properties)

`ChronicleClientOptions` extends `ChronicleOptions` and is used by worker services, console apps, and other non-web hosts via `IHostApplicationBuilder.AddCratisChronicle`.

### EventStore

[Section titled “EventStore”](#eventstore)

The name of the event store the client connects to. Required.

|         |                        |
| ------- | ---------------------- |
| Type    | `EventStoreName`       |
| Default | *(none — must be set)* |

```json
{ "Cratis": { "Chronicle": { "EventStore": "my-store" } } }
```

### EventStoreNamespaceResolverType

[Section titled “EventStoreNamespaceResolverType”](#eventstorenamespaceresolvertype)

The `Type` of the `IEventStoreNamespaceResolver` to use for resolving the event store namespace. When `null`, defaults to `DefaultEventStoreNamespaceResolver` at runtime, which always returns the default namespace.

|         |                                               |
| ------- | --------------------------------------------- |
| Type    | `Type?`                                       |
| Default | `null` → `DefaultEventStoreNamespaceResolver` |

This is a structural dependency — it resolves a type reference and cannot be meaningfully set from `appsettings.json`. Set it in code via the `configureOptions` callback or via `IChronicleBuilder`.

## ChronicleAspNetCoreOptions properties

[Section titled “ChronicleAspNetCoreOptions properties”](#chronicleaspnetcoreoptions-properties)

`ChronicleAspNetCoreOptions` extends `ChronicleClientOptions` and is used by ASP.NET Core applications via `WebApplicationBuilder.AddCratisChronicle`. It defaults `EventStoreNamespaceResolverType` to `HttpHeaderEventStoreNamespaceResolver`.

### NamespaceHttpHeader

[Section titled “NamespaceHttpHeader”](#namespacehttpheader)

The HTTP request header used to resolve the event store namespace on a per-request basis.

|         |                        |
| ------- | ---------------------- |
| Type    | `string`               |
| Default | `"x-cratis-tenant-id"` |

```json
{ "Cratis": { "Chronicle": { "NamespaceHttpHeader": "x-my-tenant" } } }
```

# gRPC Message Size

Large event batches or queries that return many events can exceed gRPC message limits. Chronicle provides configuration options to adjust the maximum send and receive message sizes.

## Default Settings

[Section titled “Default Settings”](#default-settings)

By default, Chronicle sets both `MaxReceiveMessageSize` and `MaxSendMessageSize` to 100 MB (104,857,600 bytes). This is higher than the gRPC default of 4 MB and is suitable for most scenarios involving large event collections.

## Configuring Message Sizes

[Section titled “Configuring Message Sizes”](#configuring-message-sizes)

You can configure the message sizes when creating a `ChronicleClient` or through options:

* C#

```csharp
  public static class GrpcMessageSizeConfiguration
  {
      public static ChronicleClient Create()
      {
          var options = new ChronicleOptions
          {
              ConnectionString = "chronicle://localhost:35000",
              MaxReceiveMessageSize = 200 * 1024 * 1024, // 200 MB
              MaxSendMessageSize = 200 * 1024 * 1024      // 200 MB
          };

return new ChronicleClient(options);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Configuration via appsettings.json

[Section titled “Configuration via appsettings.json”](#configuration-via-appsettingsjson)

For ASP.NET Core applications, configure message sizes under the `Cratis:Chronicle` section of `appsettings.json`:

```json
{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000",
      "MaxReceiveMessageSize": 209715200,
      "MaxSendMessageSize": 209715200
    }
  }
}
```

## Configuration via Environment Variables

[Section titled “Configuration via Environment Variables”](#configuration-via-environment-variables)

Message sizes can also be set using environment variables. .NET maps the `__` separator onto nested configuration keys:

```bash
Cratis__Chronicle__MaxReceiveMessageSize=209715200
Cratis__Chronicle__MaxSendMessageSize=209715200
```

## Understanding the Error

[Section titled “Understanding the Error”](#understanding-the-error)

If you encounter an error like:

```env
Status(StatusCode="ResourceExhausted", Detail="Received message exceeds the maximum configured message size.")
```

This indicates that the response from the server exceeds `MaxReceiveMessageSize`. Increase this value to accommodate larger responses.

## Recommendations

[Section titled “Recommendations”](#recommendations)

* **Default (100 MB)**: Suitable for most applications with moderate event batch sizes
* **200+ MB**: Consider for applications that frequently query large event ranges or work with many events
* **Performance considerations**: Larger message sizes consume more memory. Balance your needs with available resources
* **Server configuration**: Ensure the Chronicle Server is also configured to handle the message sizes you need

## Null Values

[Section titled “Null Values”](#null-values)

Setting either property to `null` will use the gRPC default (4 MB), which is generally not recommended for Chronicle applications:

* C#

```csharp
  public static class GrpcMessageSizeNullValues
  {
      public static ChronicleOptions Create() =>
          new()
          {
              MaxReceiveMessageSize = null, // Uses gRPC default of 4 MB - not recommended
              MaxSendMessageSize = null     // Uses gRPC default of 4 MB - not recommended
          };
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

# Structural Dependencies

`ChronicleOptions` is designed to hold **runtime configuration** that can be bound from `appsettings.json` or environment variables — connection strings, timeouts, TLS settings, naming policies, and so on.

Services and providers that must be resolved at registration time (before the DI container is built) are called **structural dependencies**. These are not configuration values and cannot be meaningfully bound from `appsettings.json`. They are passed directly as constructor arguments to `ChronicleClient` or set on `IChronicleBuilder` when using the DI-hosted setup (`IHostApplicationBuilder`, `WebApplicationBuilder`).

## Structural dependencies

[Section titled “Structural dependencies”](#structural-dependencies)

| Dependency                     | Purpose                                                                                | Default                                                                     |
| ------------------------------ | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `IClientArtifactsProvider`     | Discovers event types, projections, reactors, reducers, and other artifacts at startup | `DefaultClientArtifactsProvider` (auto-discovers from loaded assemblies)    |
| `IIdentityProvider`            | Supplies the current user’s identity for event metadata                                | `BaseIdentityProvider` (empty identity)                                     |
| `ICorrelationIdAccessor`       | Provides the current correlation ID for event metadata                                 | `CorrelationIdAccessor` (generates a new ID per call)                       |
| `IEventStoreNamespaceResolver` | Resolves the event store namespace for each operation                                  | `DefaultEventStoreNamespaceResolver` (always returns the default namespace) |
| `ILoggerFactory`               | Creates loggers for the Chronicle client internals                                     | `LoggerFactory` (no-op)                                                     |

## Passing to ChronicleClient directly

[Section titled “Passing to ChronicleClient directly”](#passing-to-chronicleclient-directly)

For console applications or other non-DI scenarios, pass structural dependencies as named constructor parameters:

* C#

```csharp
  using Microsoft.Extensions.Logging;

public static class StructuralDependenciesDirectClient
  {
      public static ChronicleClient Create(ChronicleOptions options, IClientArtifactsProvider myProvider) =>
          new(
              options,
              artifactsProvider: myProvider,
              loggerFactory: LoggerFactory.Create(b => b.AddConsole()));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.ChronicleOptions
  import io.cratis.chronicle.artifacts.IArtifactActivator
  import io.cratis.chronicle.artifacts.IClientArtifacts
  import io.cratis.chronicle.connection.ChronicleConnectionString

/**
   * Unlike the .NET client, structural dependencies are not separate constructor parameters on
   * [ChronicleClient] — they are carried on [ChronicleOptions] itself, which is where every named
   * dependency below actually lives.
   */
  fun createClient(artifacts: IClientArtifacts, artifactActivator: IArtifactActivator): ChronicleClient {
      val options = ChronicleOptions(
          connectionString = ChronicleConnectionString.DEVELOPMENT,
          artifacts = artifacts,
          artifactActivator = artifactActivator
      )
      return ChronicleClient(options)
  }
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.artifacts.IArtifactActivator;
  import io.cratis.chronicle.artifacts.IClientArtifacts;
  import io.cratis.chronicle.connection.ChronicleConnectionString;
  import io.cratis.chronicle.java.BlockingChronicleClient;

// Unlike the .NET client, structural dependencies are not separate constructor parameters on the
  // client — they are carried on ChronicleOptions itself, which is where every named dependency
  // below actually lives.
  class StructuralDependenciesDirectClient {
      BlockingChronicleClient create(IClientArtifacts artifacts, IArtifactActivator artifactActivator) {
          ChronicleOptions options = new ChronicleOptions(
              ChronicleConnectionString.Companion.getDEVELOPMENT(),
              "Unknown",
              io.cratis.chronicle.sinks.WellKnownSinkTypes.MONGODB,
              true,
              artifacts,
              artifactActivator);
          return BlockingChronicleClient.connect(options);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

All parameters are optional. Any parameter you omit uses the default shown in the table above.

## Configuring with IChronicleBuilder

[Section titled “Configuring with IChronicleBuilder”](#configuring-with-ichroniclebuilder)

In DI-hosted applications (ASP.NET Core, worker services, or any `IHostApplicationBuilder`-based host), use the `configure` callback on `AddCratisChronicle` to set structural dependencies via the `IChronicleBuilder` fluent API. This callback runs at registration time, before the DI container is built.

* C#

```csharp
  using Cratis.Chronicle.Identities;
  using Microsoft.Extensions.Hosting;

public static class StructuralDependenciesChronicleBuilderRegistration
  {
      public static void Configure(string[] args, IClientArtifactsProvider myCustomProvider, IIdentityProvider myIdentityProvider)
      {
          var builder = Host.CreateApplicationBuilder(args);

builder.AddCratisChronicle(
              configureOptions: options =>                         // runtime config — bindable from appsettings.json
              {
                  options.EventStore = "my-store";
                  options.ConnectionString = "chronicle://server:35000";
              },
              configure: b => b                                    // structural dependencies
                  .WithArtifactsProvider(myCustomProvider)
                  .WithIdentityProvider(myIdentityProvider));
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The same pattern works with `WebApplicationBuilder` in ASP.NET Core:

* C#

```csharp
  using Cratis.Chronicle.Identities;
  using Microsoft.AspNetCore.Builder;

public static class StructuralDependenciesAspNetCoreBuilderRegistration
  {
      public static void Configure(string[] args, IIdentityProvider myIdentityProvider)
      {
          // ASP.NET Core — WebApplicationBuilder
          var builder = WebApplication.CreateBuilder(args);
          builder.AddCratisChronicle(
              configureOptions: options => options.EventStore = "my-store",
              configure: b => b
                  .WithIdentityProvider(myIdentityProvider));
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The two callbacks are intentionally separate:

* `configureOptions` feeds the options pipeline and can be overridden by `appsettings.json` or `IConfiguration`.
* `configure` sets structural dependencies at registration time and is not overridable by configuration.

## IChronicleBuilder fluent methods

[Section titled “IChronicleBuilder fluent methods”](#ichroniclebuilder-fluent-methods)

| Method                                                | Sets                           |
| ----------------------------------------------------- | ------------------------------ |
| `WithArtifactsProvider(IClientArtifactsProvider)`     | Custom artifact discovery      |
| `WithIdentityProvider(IIdentityProvider)`             | Custom identity resolution     |
| `WithCorrelationIdAccessor(ICorrelationIdAccessor)`   | Custom correlation ID accessor |
| `WithNamespaceResolver(IEventStoreNamespaceResolver)` | Custom namespace resolution    |

## Custom artifact discovery

[Section titled “Custom artifact discovery”](#custom-artifact-discovery)

Implement `IClientArtifactsProvider` when you need to control exactly which types Chronicle discovers. This is useful in modular applications or when using assembly scanning that differs from the default:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record StructuralDepsBookBorrowed(string BookId);

[EventType]
  public record StructuralDepsBookReturned(string BookId);

public record StructuralDepsBorrowedBook(string BookId);

public class StructuralDepsBorrowedBooksProjection : IProjectionFor<StructuralDepsBorrowedBook>
  {
      public void Define(IProjectionBuilderFor<StructuralDepsBorrowedBook> builder) => builder
          .From<StructuralDepsBookBorrowed>(_ => _.Set(m => m.BookId).To(e => e.BookId));
  }

public class StructuralDepsMyArtifactsProvider : IClientArtifactsProvider
  {
      public IEnumerable<Type> EventTypes => [typeof(StructuralDepsBookBorrowed), typeof(StructuralDepsBookReturned)];
      public IEnumerable<Type> Projections => [typeof(StructuralDepsBorrowedBooksProjection)];
      public IEnumerable<Type> ModelBoundProjections => [];
      public IEnumerable<Type> Reactors => [];
      public IEnumerable<Type> ReadModelReactors => [];
      public IEnumerable<Type> Reducers => [];
      public IEnumerable<Type> ReactorMiddlewares => [];
      public IEnumerable<Type> ComplianceForTypesProviders => [];
      public IEnumerable<Type> ComplianceForPropertiesProviders => [];
      public IEnumerable<Type> AdditionalEventInformationProviders => [];
      public IEnumerable<Type> ConstraintTypes => [];
      public IEnumerable<Type> UniqueConstraints => [];
      public IEnumerable<Type> UniqueEventTypeConstraints => [];
      public IEnumerable<Type> RemoveConstraintEventTypes => [];
      public IEnumerable<Type> EventTypeMigrators => [];
      public IEnumerable<Type> EventSeeders => [];
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.artifacts.IClientArtifacts
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionFor
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.readModels.ReadModel
  import kotlin.reflect.KClass

@EventType
  data class StructuralDepsBookBorrowed(val bookId: String = "")

@EventType
  data class StructuralDepsBookReturned(val bookId: String = "")

@ReadModel
  data class StructuralDepsBorrowedBook(val bookId: String = "")

class StructuralDepsBorrowedBooksProjection : IProjectionFor<StructuralDepsBorrowedBook> {
      override fun define(builder: IProjectionBuilderFor<StructuralDepsBorrowedBook>) {
          builder.from(StructuralDepsBookBorrowed::class) {
              it.set(StructuralDepsBorrowedBook::bookId).to { e -> e.bookId }
          }
      }
  }

class StructuralDepsMyArtifacts : IClientArtifacts {
      override val eventTypes: List<KClass<*>> = listOf(StructuralDepsBookBorrowed::class, StructuralDepsBookReturned::class)
      override val eventTypeMigrations: List<KClass<*>> = emptyList()
      override val readModels: List<KClass<*>> = listOf(StructuralDepsBorrowedBook::class)
      override val projections: List<KClass<*>> = listOf(StructuralDepsBorrowedBooksProjection::class)
      override val modelBoundProjections: List<KClass<*>> = emptyList()
      override val reactors: List<KClass<*>> = emptyList()
      override val reducers: List<KClass<*>> = emptyList()
      override val constraints: List<KClass<*>> = emptyList()
      override val eventSeeders: List<KClass<*>> = emptyList()
      override val webhooks: List<KClass<*>> = emptyList()
      override val captures: List<KClass<*>> = emptyList()
      override val reactorMiddlewares: List<KClass<*>> = emptyList()
      override val reactorArgumentResolvers: List<KClass<*>> = emptyList()
  }
  ```

* Java

```java
  import io.cratis.chronicle.artifacts.IClientArtifacts;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;
  import io.cratis.chronicle.readModels.ReadModel;
  import io.cratis.chronicle.java.ProjectionBuilderJavaBridge;

import java.util.Collections;
  import java.util.List;

import kotlin.reflect.KClass;
  import kotlin.jvm.JvmClassMappingKt;

@EventType
  record StructuralDepsBookBorrowed(String bookId) {}

@EventType
  record StructuralDepsBookReturned(String bookId) {}

@ReadModel
  class StructuralDepsBorrowedBook {
      public String bookId = "";
  }

class StructuralDepsBorrowedBooksProjection implements IProjectionFor<StructuralDepsBorrowedBook> {
      @Override
      public void define(IProjectionBuilderFor<StructuralDepsBorrowedBook> builder) {
          // AutoMap matches StructuralDepsBookBorrowed.bookId to StructuralDepsBorrowedBook.bookId by name.
          ProjectionBuilderJavaBridge.from(builder, StructuralDepsBookBorrowed.class);
      }
  }

class StructuralDepsMyArtifacts implements IClientArtifacts {
      private static KClass<?> kotlin(Class<?> type) {
          return JvmClassMappingKt.getKotlinClass(type);
      }

@Override
      public List<KClass<?>> getEventTypes() {
          return List.of(kotlin(StructuralDepsBookBorrowed.class), kotlin(StructuralDepsBookReturned.class));
      }

@Override
      public List<KClass<?>> getEventTypeMigrations() { return Collections.emptyList(); }

@Override
      public List<KClass<?>> getReadModels() { return List.of(kotlin(StructuralDepsBorrowedBook.class)); }

@Override
      public List<KClass<?>> getProjections() { return List.of(kotlin(StructuralDepsBorrowedBooksProjection.class)); }

@Override
      public List<KClass<?>> getModelBoundProjections() { return Collections.emptyList(); }

@Override
      public List<KClass<?>> getReactors() { return Collections.emptyList(); }

@Override
      public List<KClass<?>> getReducers() { return Collections.emptyList(); }

@Override
      public List<KClass<?>> getConstraints() { return Collections.emptyList(); }

@Override
      public List<KClass<?>> getEventSeeders() { return Collections.emptyList(); }

@Override
      public List<KClass<?>> getWebhooks() { return Collections.emptyList(); }

@Override
      public List<KClass<?>> getCaptures() { return Collections.emptyList(); }

@Override
      public List<KClass<?>> getReactorMiddlewares() { return Collections.emptyList(); }

@Override
      public List<KClass<?>> getReactorArgumentResolvers() { return Collections.emptyList(); }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { Constructor } from '@cratis/fundamentals';
  import { eventType, IClientArtifactsProvider, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class StructuralDepsBookBorrowed {
      constructor(readonly bookId: string) {}
  }

@eventType()
  class StructuralDepsBookReturned {
      constructor(readonly bookId: string) {}
  }

class StructuralDepsBorrowedBook {
      bookId = '';
  }

@projection()
  class StructuralDepsBorrowedBooksProjection implements IProjectionFor<StructuralDepsBorrowedBook> {
      define(builder: IProjectionBuilderFor<StructuralDepsBorrowedBook>): void {
          builder.from(StructuralDepsBookBorrowed, _ => _
              .set(m => m.bookId).to(e => e.bookId));
      }
  }

class StructuralDepsMyArtifactsProvider implements IClientArtifactsProvider {
      readonly eventTypes: Constructor[] = [StructuralDepsBookBorrowed, StructuralDepsBookReturned];
      readonly readModels: Constructor[] = [];
      readonly reactors: Constructor[] = [];
      readonly reducers: Constructor[] = [];
      readonly seeders: Constructor[] = [];
      readonly constraints: Constructor[] = [];
      readonly projections: Constructor[] = [StructuralDepsBorrowedBooksProjection];
      readonly webhooks: Constructor[] = [];
      readonly eventTypeMigrations: Constructor[] = [];
  }
  ```

- C#

```csharp
  using Microsoft.Extensions.Hosting;

public static class StructuralDepsCustomArtifactsProviderUsageRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = Host.CreateApplicationBuilder(args);

builder.AddCratisChronicle(
              configureOptions: options => options.EventStore = "my-store",
              configure: b => b.WithArtifactsProvider(new StructuralDepsMyArtifactsProvider()));
      }
  }
  ```

- Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleOptions
  import io.cratis.chronicle.connection.ChronicleConnectionString

fun optionsWithCustomArtifacts(): ChronicleOptions = ChronicleOptions(
      connectionString = ChronicleConnectionString.DEVELOPMENT,
      artifacts = StructuralDepsMyArtifacts()
  )
  ```

- Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.connection.ChronicleConnectionString;

class StructuralDepsCustomArtifactsProviderUsage {
      ChronicleOptions create() {
          return new ChronicleOptions(
              ChronicleConnectionString.Companion.getDEVELOPMENT(),
              "Unknown",
              io.cratis.chronicle.sinks.WellKnownSinkTypes.MONGODB,
              true,
              new StructuralDepsMyArtifacts());
      }
  }
  ```

- Elixir

```text
  Elixir does not support this workflow yet.
  ```

- TypeScript

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

function createStructuralDependenciesCustomArtifactsProviderOptions(): ChronicleOptions {
      return ChronicleOptions.fromConnectionString('chronicle://localhost:35000', {
          clientArtifactsProvider: new StructuralDepsMyArtifactsProvider()
      });
  }
  ```

## DefaultClientArtifactsProvider

[Section titled “DefaultClientArtifactsProvider”](#defaultclientartifactsprovider)

`DefaultClientArtifactsProvider` scans loaded assemblies for artifacts at first access (lazy initialization). You can construct it with a custom assembly provider:

* C#

```csharp
  using Cratis.Types;

public static class StructuralDepsDefaultArtifactsProvider
  {
      public static DefaultClientArtifactsProvider Create()
      {
          var assembliesProvider = new CompositeAssemblyProvider(
              ProjectReferencedAssemblies.Instance,
              PackageReferencedAssemblies.Instance);

return new DefaultClientArtifactsProvider(assembliesProvider);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.artifacts.ClientArtifacts
  import io.cratis.chronicle.artifacts.IClientArtifacts

// Scans only the given packages and everything beneath them, instead of the whole classpath.
  fun scopedArtifacts(): IClientArtifacts = ClientArtifacts("com.acme.ordering", "com.acme.shipping")

// The classpath-wide instance used when no artifacts are configured, shared across every event
  // store in the process so the classpath is scanned at most once.
  fun defaultArtifacts(): IClientArtifacts = ClientArtifacts.default
  ```

* Java

```java
  import io.cratis.chronicle.artifacts.ClientArtifacts;
  import io.cratis.chronicle.artifacts.IClientArtifacts;

class StructuralDepsDefaultArtifactsProvider {
      // Scans only the given packages and everything beneath them, instead of the whole classpath.
      ClientArtifacts create() {
          return new ClientArtifacts("com.acme.ordering", "com.acme.shipping");
      }

// The classpath-wide instance used when no artifacts are configured, shared across every
      // event store in the process so the classpath is scanned at most once.
      IClientArtifacts getDefault() {
          return ClientArtifacts.Companion.getDefault();
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { DefaultClientArtifactsProvider, TypeDiscoverer } from '@cratis/chronicle';

// TypeScript discovers artifacts by scanning files matching glob patterns rather than
  // scanning loaded assemblies - TypeDiscoverer.default is backed by ChronicleOptions'
  // discoveryPatterns.
  function createStructuralDependenciesDefaultArtifactsProvider(): DefaultClientArtifactsProvider {
      return new DefaultClientArtifactsProvider(TypeDiscoverer.default);
  }
  ```

The static `DefaultClientArtifactsProvider.Default` instance is used when no provider is supplied.

> **Note:** `DefaultClientArtifactsProvider` initializes lazily on first property access; no explicit initialization is required.

# TLS Configuration (Client)

Chronicle .NET clients communicate with Chronicle Server over TLS. The server always serves its single port over TLS — in development it generates a self-signed certificate automatically — so the client connects over TLS by default.

For server-side TLS configuration, see [TLS Configuration (Server)](/chronicle/hosting/configuration/tls/).

## appsettings.json

[Section titled “appsettings.json”](#appsettingsjson)

```json
{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000",
      "Tls": {
        "CertificatePath": "/path/to/certificate.pfx",
        "CertificatePassword": "your-password"
      }
    }
  }
}
```

## Client options

[Section titled “Client options”](#client-options)

* C#

```csharp
  public static class TlsClientOptions
  {
      public static ChronicleClient Create()
      {
          var options = new ChronicleOptions
          {
              ConnectionString = "chronicle://localhost:35000",
              Tls = new Tls
              {
                  CertificatePath = "/path/to/certificate.pfx",
                  CertificatePassword = "your-password"
              }
          };

return new ChronicleClient(options);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.TlsClientOptions do
    @moduledoc false

def start_link do
      children = [
        {Chronicle.Client,
         connection_string:
           "chronicle://localhost:35000?certificatePath=/path/to/certificate.pfx&certificatePassword=your-password"}
      ]

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

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Properties

[Section titled “Properties”](#properties)

| Property                  | Type    | Default | Description                                                                              |
| ------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------- |
| CertificatePath           | string  | null    | Path to the client certificate (PFX format) if mutual TLS is used                        |
| CertificatePassword       | string  | null    | Password for the certificate file                                                        |
| SkipCertificateValidation | boolean | true    | When `true`, the client connects over TLS but does not validate the server’s certificate |

## Certificate validation

[Section titled “Certificate validation”](#certificate-validation)

The client always connects over TLS, but by default it does **not** validate the server’s certificate — any certificate, including a self-signed one, is accepted. That default is deliberate: Chronicle Server generates a self-signed certificate on every start when none is configured, and it is never written to disk or added to a trust store, so there is nothing a client could validate it against. Skipping validation is what lets a development server and client talk to each other with no certificate setup on either side.

Once you run against a server whose certificate is verifiable, turn validation on with `skipTlsValidation=false` in the connection string:

* C#

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

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleOptions

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

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;

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

* Elixir

```elixir
  defmodule MyApp.TlsValidationEnabled do
    @moduledoc false

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

* TypeScript

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

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

You can also set it on the client’s TLS options as `SkipCertificateValidation = false`. **Either setting alone is enough** — the two combine so that whichever one asks for validation wins, and an omitted second setting can never silently turn validation back off.

To go the other way and skip explicitly:

* C#

```csharp
  public static class TlsConnectionStringSkipValidation
  {
      public static ChronicleOptions Create() =>
          ChronicleOptions.FromConnectionString("chronicle://localhost:35000?skipTlsValidation=true");
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleOptions

fun optionsSkippingTlsValidation(): ChronicleOptions =
      ChronicleOptions.fromConnectionString("chronicle://localhost:35000?skipTlsValidation=true")
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;

class TlsConnectionStringSkipValidation {
      ChronicleOptions create() {
          return ChronicleOptions.fromConnectionString("chronicle://localhost:35000?skipTlsValidation=true");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.TlsConnectionStringSkipValidation do
    @moduledoc false

def connection_string do
      Chronicle.Connections.ConnectionString.parse(
        "chronicle://localhost:35000?skipTlsValidation=true"
      )
    end
  end
  ```

* TypeScript

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

function createTlsConnectionStringSkipValidation(): ChronicleOptions {
      return ChronicleOptions.fromConnectionString('chronicle://localhost:35000?skipTlsValidation=true');
  }
  ```

Caution

The default accepts **any** server certificate, which removes protection against man-in-the-middle attacks. Set `skipTlsValidation=false` for anything reachable beyond a trusted network — and always over the public internet.

## Development vs production

[Section titled “Development vs production”](#development-vs-production)

* **Development**: the server serves TLS with an auto-generated self-signed certificate and the client skips validation by default, so a development client connects out of the box — no certificate setup is needed on either side.
* **Production**: give the server a real certificate and set `skipTlsValidation=false` so the client validates it with the standard TLS rules.

With validation enabled, the standard TLS rules apply: valid certificates are accepted without extra configuration, and a certificate that fails validation — including a self-signed one — is rejected unless you configure a matching client certificate.

## Troubleshooting

[Section titled “Troubleshooting”](#troubleshooting)

### Client connection errors

[Section titled “Client connection errors”](#client-connection-errors)

**Error**: “The remote certificate is invalid”

You only see this once you have opted into validation with `skipTlsValidation=false`.

**Solutions**:

1. Ensure the server certificate is valid, not expired, and trusted by the client.
2. If the server uses a self-signed certificate on a trusted network, drop `skipTlsValidation=false` from the connection string to fall back to the default of accepting it.
3. In development no configuration is needed — the client skips validation by default, so the server’s auto-generated certificate is accepted as-is.

# Connection Strings

Connection strings define how clients connect to the Chronicle server. They capture the host, port, authentication, and TLS options in a single, portable value.

Use the following topics to understand what the server supports and how clients configure and consume connection strings:

* [Server support](/chronicle/connection-strings/server/)
* [DotNET client usage](/chronicle/connection-strings/dotnet-client/)
* [Configuration](/chronicle/connection-strings/configuration/)

# Configuration

The .NET client reads its connection string from configuration. A typical setup binds the `Cratis:Chronicle` section of `appsettings.json` and registers Chronicle on the host with `AddCratisChronicle`.

**appsettings.json:**

```json
{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000"
    }
  }
}
```

Note

For local development, `chronicle://localhost:35000` can be used without credentials. The .NET client automatically attempts development credentials.

**Program.cs:**

* C#

```csharp
  using Microsoft.Extensions.Hosting;

public static class ConnectionStringsConfigurationRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = Host.CreateApplicationBuilder(args);

builder.AddCratisChronicle(options => options.EventStore = "my-store");
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.ChronicleOptions

// Kotlin has no appsettings.json-style configuration binding — read the connection string from
  // wherever the application keeps its configuration (here, an environment variable) and pass it
  // straight to the client.
  fun createClientFromEnvironment(): ChronicleClient {
      val connectionString = System.getenv("CHRONICLE_CONNECTION_STRING") ?: "chronicle://localhost:35000"
      return ChronicleClient(ChronicleOptions.fromConnectionString(connectionString))
  }
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.java.BlockingChronicleClient;

// Java has no appsettings.json-style configuration binding — read the connection string from
  // wherever the application keeps its configuration (here, an environment variable) and pass it
  // straight to the client.
  class ConnectionStringsConfigurationRegister {
      BlockingChronicleClient create() {
          String connectionString = System.getenv("CHRONICLE_CONNECTION_STRING");
          if (connectionString == null) {
              connectionString = "chronicle://localhost:35000";
          }
          return BlockingChronicleClient.connect(ChronicleOptions.fromConnectionString(connectionString));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ConnectionStringsConfigurationRegistration do
    @moduledoc false

def start_link do
      children = [
        {Chronicle.Client, event_store: "my-store"}
      ]

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

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`AddCratisChronicle` is an extension on the host builder — `IHostApplicationBuilder` for worker and console hosts, `WebApplicationBuilder` for ASP.NET Core. It binds the `Cratis:Chronicle` section automatically, so the connection string comes from configuration rather than code. See [Add Chronicle to a worker service](/chronicle/get-started/worker/) and [Add Chronicle to an ASP.NET Core app](/chronicle/get-started/aspnetcore/) for the full host setup.

## Environment-specific configuration

[Section titled “Environment-specific configuration”](#environment-specific-configuration)

Use per-environment configuration files to separate development and production settings:

**appsettings.Development.json:**

```json
{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000/?skipTlsValidation=true"
    }
  }
}
```

**appsettings.Production.json:**

```json
{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://clientId:clientSecret@chronicle.production.example.com:35000"
    }
  }
}
```

## Environment variables

[Section titled “Environment variables”](#environment-variables)

You can also supply the connection string via environment variables. .NET maps the `__` separator onto nested configuration keys, so `Cratis:Chronicle:ConnectionString` becomes:

```bash
export Cratis__Chronicle__ConnectionString="chronicle://clientId:clientSecret@server.example.com:35000"
```

## Related topics

[Section titled “Related topics”](#related-topics)

* [DotNET client usage](/chronicle/connection-strings/dotnet-client/)
* [ChronicleOptions reference](/chronicle/configuration/chronicle-options/)
* [TLS configuration](/chronicle/configuration/tls/)

# DotNET client usage

Chronicle uses connection strings to configure the .NET client. You can pass a connection string to `ChronicleOptions` or provide one when constructing a `ChronicleClient`.

## Development defaults

[Section titled “Development defaults”](#development-defaults)

The `ChronicleConnectionString.Development` constant provides a pre-configured development connection string. Default constructors also use this value:

* C#

```csharp
  public static class ConnectionStringsDevelopmentDefaults
  {
      public static ChronicleClient Create()
      {
          var options = new ChronicleOptions();
          return new ChronicleClient(options);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.ChronicleOptions

fun createDevelopmentClient(): ChronicleClient {
      val options = ChronicleOptions.development()
      return ChronicleClient(options)
  }
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.java.BlockingChronicleClient;

class ConnectionStringsDevelopmentDefaults {
      BlockingChronicleClient create() {
          ChronicleOptions options = ChronicleOptions.development();
          return BlockingChronicleClient.connect(options);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ConnectionStringsDevelopmentDefaults do
    @moduledoc false

def connection_string do
      Chronicle.Connections.ConnectionString.default()
    end
  end
  ```

* TypeScript

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

// ChronicleOptions.development() points at the local dev kernel on chronicle://localhost:35000
  // using the built-in development client credentials.
  function createConnectionStringsDevelopmentDefaults(): ChronicleOptions {
      return ChronicleOptions.development();
  }
  ```

This is equivalent to:

* C#

```csharp
  using Cratis.Chronicle.Connections;

public static class ConnectionStringsDevelopmentDefaultsEquivalent
  {
      public static ChronicleClient CreateFromOptions()
      {
          var options = ChronicleOptions.FromDevelopmentConnectionString();
          return new ChronicleClient(options);
      }

public static ChronicleClient CreateFromConnectionString() => new(ChronicleConnectionString.Development);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.ChronicleOptions
  import io.cratis.chronicle.connection.ChronicleConnectionString

fun createFromOptions(): ChronicleClient = ChronicleClient(ChronicleOptions.development())

fun createFromConnectionString(): ChronicleClient = ChronicleClient(ChronicleOptions(ChronicleConnectionString.DEVELOPMENT))
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.connection.ChronicleConnectionString;
  import io.cratis.chronicle.java.BlockingChronicleClient;

class ConnectionStringsDevelopmentDefaultsEquivalent {
      BlockingChronicleClient createFromOptions() {
          return BlockingChronicleClient.connect(ChronicleOptions.development());
      }

BlockingChronicleClient createFromConnectionString() {
          return BlockingChronicleClient.connect(new ChronicleOptions(ChronicleConnectionString.Companion.getDEVELOPMENT()));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ConnectionStringsDevelopmentDefaultsEquivalent do
    @moduledoc false

def connection_string do
      Chronicle.Connections.ConnectionString.parse("chronicle://localhost:35000")
    end
  end
  ```

* TypeScript

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

function createConnectionStringsDevelopmentDefaultsEquivalent(): ChronicleOptions {
      return ChronicleOptions.fromConnectionString(
          'chronicle://chronicle-dev-client:chronicle-dev-secret@localhost:35000'
      );
  }
  ```

Note

In development, you can use `chronicle://localhost:35000` without credentials. The .NET client automatically attempts the built-in development credentials (`chronicle-dev-client` / `chronicle-dev-secret`).

Use explicit configuration for production environments.

## From connection string

[Section titled “From connection string”](#from-connection-string)

* C#

```csharp
  public static class ConnectionStringsFromConnectionString
  {
      public static ChronicleClient Create()
      {
          var options = ChronicleOptions.FromConnectionString("chronicle://localhost:35000");
          return new ChronicleClient(options);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.ChronicleOptions

fun createClientFromConnectionString(): ChronicleClient {
      val options = ChronicleOptions.fromConnectionString("chronicle://localhost:35000")
      return ChronicleClient(options)
  }
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.java.BlockingChronicleClient;

class ConnectionStringsFromConnectionString {
      BlockingChronicleClient create() {
          ChronicleOptions options = ChronicleOptions.fromConnectionString("chronicle://localhost:35000");
          return BlockingChronicleClient.connect(options);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ConnectionStringsFromConnectionString do
    @moduledoc false

def start_link do
      children = [
        {Chronicle.Client, connection_string: "chronicle://localhost:35000"}
      ]

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

* TypeScript

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

function createConnectionStringsFromConnectionString(): ChronicleOptions {
      return ChronicleOptions.fromConnectionString('chronicle://myserver:35000');
  }
  ```

## Fluent builder

[Section titled “Fluent builder”](#fluent-builder)

Use `ChronicleConnectionStringBuilder` to construct a connection string programmatically:

* C#

```csharp
  using Cratis.Chronicle.Connections;

var options = ChronicleOptions.FromConnectionString(connectionString);
          return new ChronicleClient(options);
      }
  }
  ```

* Kotlin

* Java

import java.util.List;

return BlockingChronicleClient.connect(new ChronicleOptions(connectionString));
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Logging a connection string

[Section titled “Logging a connection string”](#logging-a-connection-string)

A connection string carries the client secret, the API key and the certificate password, so it must never be written to a log or an error message as it stands. `ChronicleConnectionString.Redacted` renders it with every credential replaced by `REDACTED`, while keeping the parts that make a log entry useful — scheme, host, port and the non-sensitive options:

* C#

```csharp
  using Cratis.Chronicle.Connections;

public static class ConnectionStringsRedactingForLogs
  {
      public static void LogConnectionTarget(ILogger logger)
      {
          var connectionString = new ChronicleConnectionString("chronicle://clientId:clientSecret@server.example.com:35000");

// Logs: chronicle://clientId:REDACTED@server.example.com:35000
          logger.LogInformation("Connecting to {RedactedConnectionString}", connectionString.Redacted);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`ToString()` still renders the connection string in full, credentials included. Use it to pass the value on, never to report it.

The client uses `Redacted` for its own log messages, so connecting no longer writes the client secret to the log.

## Authentication validation

[Section titled “Authentication validation”](#authentication-validation)

You cannot specify both client credentials and API key authentication in the same connection string. Doing so throws an `AmbiguousAuthenticationMode` error.

# Server support

Chronicle connection strings follow this general format:

```text
chronicle://[username:password@]host[:port][,host[:port],...][/?options]
chronicle+srv://[username:password@]host[/?options]
```

## Components

[Section titled “Components”](#components)

* **Scheme**: `chronicle://` for explicit hosts, or `chronicle+srv://` for DNS SRV record lookup
* **Authentication** (optional): `username:password@` for client credentials authentication
* **Host**: The server hostname or IP address. Multiple hosts can be given as a comma-separated list, each with an optional port
* **Port** (optional): Defaults to 35000
* **Options** (optional): Query string parameters for additional configuration

## Multiple servers and load balancing

[Section titled “Multiple servers and load balancing”](#multiple-servers-and-load-balancing)

When the connection string holds more than one host, the client picks which server to connect to using a load balancer strategy. The strategy is applied on every connect - including reconnects, so a client fails over to the next server when the one it is connected to becomes unavailable.

```text
chronicle://node1:35000,node2:35000,node3:35000
```

| Strategy            | Description                                                                                                                                                                                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `least-connections` | Default. Asks every candidate server how many clients it currently has connected and picks the one with the fewest. See below for how the probe works                                                                                                                      |
| `round-robin`       | Cycles through the servers in order, starting at a random offset so a fleet of client instances spreads across the servers. For a small fleet (two clients, two servers) the random offset can still coincide by chance - `least-connections` doesn’t have this limitation |
| `random`            | Picks a random server on every connect                                                                                                                                                                                                                                     |

Select the strategy with the `loadBalancer` query parameter, or programmatically through `ChronicleOptions.LoadBalancerStrategy` for custom implementations of `ILoadBalancerStrategy`:

```text
chronicle://node1:35000,node2:35000?loadBalancer=round-robin
```

### How least-connections picks a server

[Section titled “How least-connections picks a server”](#how-least-connections-picks-a-server)

Every Chronicle Server exposes two anonymous endpoints for this - anonymous because a client needs to ask before it has authenticated:

| Endpoint                    | Purpose                                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `GET /connections/count`    | Returns how many clients are currently connected to *that specific server* - not the cluster-wide total |
| `POST /connections/reserve` | Reserves a connection slot on that server ahead of the client actually connecting                       |

Before connecting (and on every reconnect), the client asks every candidate server for its count in parallel and picks whichever answered with the lowest number - ties are broken randomly rather than always preferring the first candidate. It then calls `POST /connections/reserve` on the server it picked, before starting the real connect handshake (TLS plus a compatibility check), and only then proceeds to connect.

The reservation exists because the gap between “decided to connect here” and “actually registered as connected” is wide enough for another client to probe in the middle of it. Without a reservation, two clients starting at the same time (a rollout, a composition bringing up several instances together) can both probe before either has registered, both see the same low count, and both pick the same server - random tie-breaking alone only turns a guaranteed collision into a coin flip, it doesn’t prevent it. The reservation is reflected in `/connections/count` immediately, so a second client probing a moment later sees the first client’s pick and routes around it. Once the real connection registers, the server clears the reservation that stood in for it, so a successful connect is only ever counted once. A reservation that never converts - the client crashes, or picks a different server after all - is not explicitly released; it simply expires on its own (30 seconds), so an abandoned connection attempt doesn’t permanently inflate a server’s reported count.

Before every probe (not just the first) the client also waits a small random delay, up to 250ms. This covers the case reservation alone doesn’t: two clients whose *probes themselves* land within microseconds of each other, before either has had a chance to reserve anything - the common case for a fleet starting together, and just as common when a fleet reconnects together (every instance was waiting on the same unavailable server and now retries at the same moment it comes back). The jitter is deliberately applied on every attempt, not only the first, because a synchronized retry needs the same protection a cold start does.

A server that doesn’t answer within 2 seconds, or that can’t be reached at all, is treated as maximally loaded rather than failing the selection - it simply won’t be picked over a server that did respond. This makes `least-connections` a safe default even while a server is restarting or briefly unreachable: the client routes around it instead of erroring out.

## DNS SRV lookup

[Section titled “DNS SRV lookup”](#dns-srv-lookup)

With the `chronicle+srv://` scheme, the client resolves the servers from DNS SRV records instead of listing them explicitly - the same mechanism MongoDB uses for `mongodb+srv://`. The client looks up `_chronicle._tcp.<host>` and uses the returned targets and ports as the server list, ordered by SRV priority and weight. The lookup happens on every connect, so servers added to or removed from DNS are picked up on reconnect without configuration changes.

```text
chronicle+srv://cluster.example.com
```

For the example above, the client queries the SRV records for `_chronicle._tcp.cluster.example.com`.

## Authentication modes

[Section titled “Authentication modes”](#authentication-modes)

Chronicle supports multiple authentication modes. The mode is determined by the credentials present in the connection string:

* **Client credentials**: Username and password supplied in the authority section. This is also what a connection string with *no* credentials falls back to — it performs the exchange with the development credentials rather than connecting anonymously
* **API key**: `apiKey` query parameter
* **None**: `auth=none` query parameter — the client presents no credentials at all

You cannot combine client credentials and API key authentication in the same connection string. `auth=none` overrides both, so credentials left behind by a shared configuration cannot quietly turn the exchange back on.

`auth=none` only works against a server running with [authentication turned off](/chronicle/hosting/configuration/authentication/#turning-authentication-off), which is meant for a Chronicle embedded alongside its own client rather than reachable over a network. Against a server that enforces authentication, every call fails as unauthenticated.

## Query parameters

[Section titled “Query parameters”](#query-parameters)

| Parameter           | Type    | Description                                                                                                            | Example                     |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `auth`              | string  | Set to `none` to connect without presenting credentials                                                                | `?auth=none`                |
| `apiKey`            | string  | API key for API key authentication                                                                                     | `?apiKey=your-api-key`      |
| `skipTlsValidation` | boolean | Connects over TLS without validating the server certificate                                                            | `?skipTlsValidation=true`   |
| `loadBalancer`      | string  | Load balancer strategy when multiple servers are configured                                                            | `?loadBalancer=round-robin` |
| `srvNameServer`     | string  | DNS name server (host\[:port], port defaults to 53) for `chronicle+srv` lookups; defaults to the system’s name servers | `?srvNameServer=10.0.0.53`  |

## TLS

[Section titled “TLS”](#tls)

The client always connects over TLS, but by default it does **not** validate the server certificate — any certificate, including a self-signed one, is accepted. Chronicle Server generates a self-signed certificate on every start when none is configured, so this default is what lets a development client connect with no certificate setup. Set `skipTlsValidation=false` to require full certificate chain validation against a server whose certificate is verifiable — do this for anything beyond a trusted network, as the default removes protection against man-in-the-middle attacks. In the .NET client this option and `Tls.SkipCertificateValidation` combine so that whichever one asks for validation wins, so either setting alone is enough and an omitted second setting can never silently turn validation back off.

See [TLS configuration (client)](/chronicle/configuration/tls/) for certificate setup.

# Constraints

Constraints define server-side rules that must be satisfied before events are committed. They run inside the Chronicle Kernel and protect data integrity across event streams and event sources.

```
satisfied

violated

Append event

Constraint checked in the kernel

Committed to the log

Append rejected
```

Use constraints to enforce rules like uniqueness across event types and event sources. Because constraints are evaluated in the kernel, they are consistent and apply to every client.

## Why constraints matter

[Section titled “Why constraints matter”](#why-constraints-matter)

* Enforce invariants regardless of client behavior
* Provide consistent validation across all event sources
* Keep integrity logic close to the event store

## Constraint types

[Section titled “Constraint types”](#constraint-types)

Chronicle supports two types of uniqueness constraints:

| Type                  | Description                                                                           |
| --------------------- | ------------------------------------------------------------------------------------- |
| **Unique property**   | Enforces that a property value is unique across all events of one or more types       |
| **Unique event type** | Enforces that only one event of a specific type can ever be appended per event source |

## Defining constraints

[Section titled “Defining constraints”](#defining-constraints)

Chronicle provides two ways to define constraints:

| Approach                                           | When to use                                                                                                                               |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Model-bound](/chronicle/constraints/model-bound/) | Declaring constraints directly on event types using attributes — no separate class needed. **Preferred for most scenarios.**              |
| [Declarative](/chronicle/constraints/declarative/) | Complex rules spanning multiple event types with different property names, or when you need a callback for constraint violation messages. |

## Topics

[Section titled “Topics”](#topics)

* [Declarative](/chronicle/constraints/declarative/)
* [Model-bound](/chronicle/constraints/model-bound/)

# Declarative constraints

The declarative API lets you define constraints in a dedicated class by implementing `IConstraint`. Chronicle discovers all `IConstraint` implementations automatically — no registration is needed.

Client coverage

Kotlin and Java have a real `IConstraint`/`IConstraintBuilder` API, but it’s narrower than C#‘s: it has no `RemovedWith` (releasing a held value), no `WithName` (custom constraint names), no dynamic message callback, and its `on(...)` can only target a single event type per unique constraint — no chaining across multiple event types. Tabs on this page that need any of those are marked as gaps for Kotlin/Java rather than silently omitted. Elixir doesn’t have a separate declarative-class style at all — see [Model-bound constraints](/chronicle/constraints/model-bound/) for its event-type-attribute equivalent, which does support name-based grouping and releasing.

Use declarative constraints when you need:

* Uniqueness spanning multiple event types with different property names
* A callback to compose dynamic violation messages
* More explicit control over constraint names

## Constraint types

[Section titled “Constraint types”](#constraint-types)

| Type                                                                       | Description                                                                     |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [Unique property](/chronicle/constraints/declarative/unique/)              | Enforce that a property value is unique across one or more event types          |
| [Unique event type](/chronicle/constraints/declarative/unique-event-type/) | Enforce that only one event of a specific type can be appended per event source |

## Defining a constraint

[Section titled “Defining a constraint”](#defining-a-constraint)

Implement `IConstraint` and call the builder in `Define`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsDeclarativeIndexProjectCreated(string Name);

[EventType]
  public record ConstraintsDeclarativeIndexProjectRemoved;

public class ConstraintsDeclarativeIndexUniqueProjectName : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(unique =>
              unique
                  .On<ConstraintsDeclarativeIndexProjectCreated>(e => e.Name)
                  .RemovedWith<ConstraintsDeclarativeIndexProjectRemoved>());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsDeclarativeIndexProjectCreated {
      constructor(readonly name: string) {}
  }

@eventType()
  class ConstraintsDeclarativeIndexProjectRemoved {
  }

@constraint()
  class ConstraintsDeclarativeIndexUniqueProjectName implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .on(ConstraintsDeclarativeIndexProjectCreated, e => e.name)
                  .removedWith(ConstraintsDeclarativeIndexProjectRemoved));
      }
  }
  ```

## Discovery

[Section titled “Discovery”](#discovery)

Chronicle scans all loaded assemblies for types that implement `IConstraint` and registers them with the Kernel automatically when the client starts. No explicit registration is required.

# Unique property constraint

Use `builder.Unique(...)` inside an `IConstraint` implementation to enforce that a property value is unique across one or more event types. The constraint fires if any tracked event would introduce a duplicate value.

Chronicle discovers all `IConstraint` implementations automatically — no registration is needed.

## Defining a constraint

[Section titled “Defining a constraint”](#defining-a-constraint)

Implement `IConstraint` and call the builder in `Define`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueProjectCreated(string Name);

[EventType]
  public record ConstraintsUniqueProjectRemoved;

public class ConstraintsUniqueProjectName : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(unique =>
              unique
                  .On<ConstraintsUniqueProjectCreated>(e => e.Name)
                  .RemovedWith<ConstraintsUniqueProjectRemoved>());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueProjectCreated {
      constructor(readonly name: string) {}
  }

@eventType()
  class ConstraintsUniqueProjectRemoved {
  }

@constraint()
  class ConstraintsUniqueProjectName implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .on(ConstraintsUniqueProjectCreated, e => e.name)
                  .removedWith(ConstraintsUniqueProjectRemoved));
      }
  }
  ```

## Uniqueness across multiple event types

[Section titled “Uniqueness across multiple event types”](#uniqueness-across-multiple-event-types)

Use multiple `.On` calls when several event types each contribute to the same logical uniqueness rule. The constraint fires if any of the tracked events would introduce a duplicate value:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueUserRegistered(string Email);

[EventType]
  public record ConstraintsUniqueUserEmailChanged(string NewEmail);

[EventType]
  public record ConstraintsUniqueUserRemoved;

public class ConstraintsUniqueEmailAcrossEvents : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(unique =>
              unique
                  .WithName("UniqueEmail")
                  .On<ConstraintsUniqueUserRegistered>(e => e.Email)
                  .On<ConstraintsUniqueUserEmailChanged>(e => e.NewEmail)
                  .RemovedWith<ConstraintsUniqueUserRemoved>());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueUserRegistered {
      constructor(readonly email: string) {}
  }

@eventType()
  class ConstraintsUniqueUserEmailChanged {
      constructor(readonly newEmail: string) {}
  }

@eventType()
  class ConstraintsUniqueUserRemoved {
  }

@constraint()
  class ConstraintsUniqueEmailAcrossEvents implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .withName('UniqueEmail')
                  .on(ConstraintsUniqueUserRegistered, e => e.email)
                  .on(ConstraintsUniqueUserEmailChanged, e => e.newEmail)
                  .removedWith(ConstraintsUniqueUserRemoved));
      }
  }
  ```

## Constraint name

[Section titled “Constraint name”](#constraint-name)

Use `.WithName(...)` to give the constraint an explicit name. When not provided, Chronicle uses the class name of the `IConstraint` implementation:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueNamedUserRegistered(string Email);

public class ConstraintsUniqueNamedEmail : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(unique =>
              unique
                  .WithName("UniqueEmail")
                  .On<ConstraintsUniqueNamedUserRegistered>(e => e.Email));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueNamedUserRegistered {
      constructor(readonly email: string) {}
  }

@constraint()
  class ConstraintsUniqueNamedEmail implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .withName('UniqueEmail')
                  .on(ConstraintsUniqueNamedUserRegistered, e => e.email));
      }
  }
  ```

## Releasing a constraint

[Section titled “Releasing a constraint”](#releasing-a-constraint)

Call `.RemovedWith<T>()` to register the event type that releases the constraint. When that event is appended, the previously held value is freed and can be claimed again:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueOrderPlaced(string Reference);

[EventType]
  public record ConstraintsUniqueOrderCancelled;

public class ConstraintsUniqueOrderReference : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(unique =>
              unique
                  .On<ConstraintsUniqueOrderPlaced>(e => e.Reference)
                  .RemovedWith<ConstraintsUniqueOrderCancelled>());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueOrderPlaced {
      constructor(readonly reference: string) {}
  }

@eventType()
  class ConstraintsUniqueOrderCancelled {
  }

@constraint()
  class ConstraintsUniqueOrderReference implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .on(ConstraintsUniqueOrderPlaced, e => e.reference)
                  .removedWith(ConstraintsUniqueOrderCancelled));
      }
  }
  ```

A lifecycle often ends in more than one way — an invitation is over when it is accepted, revoked, or expires. Call `.RemovedWith<T>()` once for each of those events and every one of them releases the value on its own; declaring a second does not replace the first:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueSeveralInvitationSent(string EmailAddress);

[EventType]
  public record ConstraintsUniqueSeveralInvitationAccepted;

[EventType]
  public record ConstraintsUniqueSeveralInvitationRevoked;

[EventType]
  public record ConstraintsUniqueSeveralInvitationExpired;

public class ConstraintsUniqueSeveralInvitedAddress : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(unique =>
              unique
                  .On<ConstraintsUniqueSeveralInvitationSent>(e => e.EmailAddress)
                  .RemovedWith<ConstraintsUniqueSeveralInvitationAccepted>()
                  .RemovedWith<ConstraintsUniqueSeveralInvitationRevoked>()
                  .RemovedWith<ConstraintsUniqueSeveralInvitationExpired>());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueSeveralInvitationSent {
      constructor(readonly emailAddress: string) {}
  }

@eventType()
  class ConstraintsUniqueSeveralInvitationAccepted {
  }

@eventType()
  class ConstraintsUniqueSeveralInvitationRevoked {
  }

@eventType()
  class ConstraintsUniqueSeveralInvitationExpired {
  }

@constraint()
  class ConstraintsUniqueSeveralInvitedAddress implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .on(ConstraintsUniqueSeveralInvitationSent, e => e.emailAddress)
                  .removedWith(ConstraintsUniqueSeveralInvitationAccepted)
                  .removedWith(ConstraintsUniqueSeveralInvitationRevoked)
                  .removedWith(ConstraintsUniqueSeveralInvitationExpired));
      }
  }
  ```

## Ignoring casing

[Section titled “Ignoring casing”](#ignoring-casing)

Call `.IgnoreCasing()` to make the uniqueness check case-insensitive:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueCasingUserRegistered(string Email);

public class ConstraintsUniqueCasingEmail : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(unique =>
              unique
                  .On<ConstraintsUniqueCasingUserRegistered>(e => e.Email)
                  .IgnoreCasing());
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.IConstraint
  import io.cratis.chronicle.constraints.IConstraintBuilder
  import io.cratis.chronicle.events.EventType

@EventType
  data class ConstraintsUniqueCasingUserRegistered(val email: String)

class ConstraintsUniqueCasingEmail : IConstraint {
      override fun define(builder: IConstraintBuilder) {
          builder.unique { unique ->
              unique
                  .on(ConstraintsUniqueCasingUserRegistered::class, ConstraintsUniqueCasingUserRegistered::email)
                  .ignoreCasing()
          }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.constraints.IConstraint;
  import io.cratis.chronicle.constraints.IConstraintBuilder;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.UniqueConstraintBuilderJavaBridge;

@EventType
  record ConstraintsUniqueCasingUserRegistered(String email) {}

class ConstraintsUniqueCasingEmail implements IConstraint {
      @Override
      public void define(IConstraintBuilder builder) {
          builder.unique(unique -> {
              UniqueConstraintBuilderJavaBridge.on(unique, ConstraintsUniqueCasingUserRegistered.class, "email")
                  .ignoreCasing();
          });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueCasingUserRegistered {
      constructor(readonly email: string) {}
  }

@constraint()
  class ConstraintsUniqueCasingEmail implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .on(ConstraintsUniqueCasingUserRegistered, e => e.email)
                  .ignoreCasing());
      }
  }
  ```

## Violation message

[Section titled “Violation message”](#violation-message)

Call `.WithMessage(...)` to provide a custom message when the constraint is violated:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueMessageProjectCreated(string Name);

public class ConstraintsUniqueMessageProjectName : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(unique =>
              unique
                  .On<ConstraintsUniqueMessageProjectCreated>(e => e.Name)
                  .WithMessage("A project with this name already exists."));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.IConstraint
  import io.cratis.chronicle.constraints.IConstraintBuilder
  import io.cratis.chronicle.events.EventType

@EventType
  data class ConstraintsUniqueMessageProjectCreated(val name: String)

class ConstraintsUniqueMessageProjectName : IConstraint {
      override fun define(builder: IConstraintBuilder) {
          builder.unique { unique ->
              unique
                  .on(ConstraintsUniqueMessageProjectCreated::class, ConstraintsUniqueMessageProjectCreated::name)
                  .withMessage("A project with this name already exists.")
          }
      }
  }
  ```

* Java

@EventType
  record ConstraintsUniqueMessageProjectCreated(String name) {}

class ConstraintsUniqueMessageProjectName implements IConstraint {
      @Override
      public void define(IConstraintBuilder builder) {
          builder.unique(unique -> {
              UniqueConstraintBuilderJavaBridge.on(unique, ConstraintsUniqueMessageProjectCreated.class, "name")
                  .withMessage("A project with this name already exists.");
          });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueMessageProjectCreated {
      constructor(readonly name: string) {}
  }

@constraint()
  class ConstraintsUniqueMessageProjectName implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .on(ConstraintsUniqueMessageProjectCreated, e => e.name)
                  .withMessage('A project with this name already exists.'));
      }
  }
  ```

Use a callback to compose the message dynamically from violation context:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueMessageCallbackProjectCreated(string Name);

public class ConstraintsUniqueMessageCallbackProjectName : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique(unique =>
              unique
                  .On<ConstraintsUniqueMessageCallbackProjectCreated>(e => e.Name)
                  .WithMessage(violation => $"A project named '{violation.Details[WellKnownConstraintDetailKeys.PropertyValue]}' already exists."));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## How constraints are enforced

[Section titled “How constraints are enforced”](#how-constraints-are-enforced)

When a constraint is registered, the Chronicle Kernel creates the indexes required to enforce it. Constraints are evaluated server-side during append, ensuring data integrity regardless of the client.

# Unique event type constraint

Use `builder.Unique<TEventType>()` inside an `IConstraint` implementation to enforce that **only one event of a specific type** can be appended per event source identifier. Use this when the event itself is a unique fact — for example, initializing a project can only happen once per project.

Chronicle discovers all `IConstraint` implementations automatically — no registration is needed.

## Defining a unique event type constraint

[Section titled “Defining a unique event type constraint”](#defining-a-unique-event-type-constraint)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueEventTypeProjectInitialized;

public class ConstraintsUniqueEventTypeProjectInitialization : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique<ConstraintsUniqueEventTypeProjectInitialized>();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.IConstraint
  import io.cratis.chronicle.constraints.IConstraintBuilder
  import io.cratis.chronicle.events.EventType

@EventType
  class ConstraintsUniqueEventTypeProjectInitialized

class ConstraintsUniqueEventTypeProjectInitialization : IConstraint {
      override fun define(builder: IConstraintBuilder) {
          builder.uniqueFor(ConstraintsUniqueEventTypeProjectInitialized::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.constraints.IConstraint;
  import io.cratis.chronicle.constraints.IConstraintBuilder;
  import io.cratis.chronicle.events.EventType;

@EventType
  class ConstraintsUniqueEventTypeProjectInitialized {
  }

class ConstraintsUniqueEventTypeProjectInitialization implements IConstraint {
      @Override
      public void define(IConstraintBuilder builder) {
          builder.uniqueFor(ConstraintsUniqueEventTypeProjectInitialized.class, "");
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueEventTypeProjectInitialized {
  }

@constraint()
  class ConstraintsUniqueEventTypeProjectInitialization implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.uniqueFor(ConstraintsUniqueEventTypeProjectInitialized);
      }
  }
  ```

## Violation message

[Section titled “Violation message”](#violation-message)

Provide a static message string:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueEventTypeMessageProjectInitialized;

public class ConstraintsUniqueEventTypeMessageProjectInitialization : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique<ConstraintsUniqueEventTypeMessageProjectInitialized>(
              message: "A project can only be initialized once.");
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.IConstraint
  import io.cratis.chronicle.constraints.IConstraintBuilder
  import io.cratis.chronicle.events.EventType

@EventType
  class ConstraintsUniqueEventTypeMessageProjectInitialized

class ConstraintsUniqueEventTypeMessageProjectInitialization : IConstraint {
      override fun define(builder: IConstraintBuilder) {
          builder.uniqueFor(
              ConstraintsUniqueEventTypeMessageProjectInitialized::class,
              message = "A project can only be initialized once."
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.constraints.IConstraint;
  import io.cratis.chronicle.constraints.IConstraintBuilder;
  import io.cratis.chronicle.events.EventType;

@EventType
  class ConstraintsUniqueEventTypeMessageProjectInitialized {
  }

class ConstraintsUniqueEventTypeMessageProjectInitialization implements IConstraint {
      @Override
      public void define(IConstraintBuilder builder) {
          builder.uniqueFor(ConstraintsUniqueEventTypeMessageProjectInitialized.class, "A project can only be initialized once.");
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueEventTypeMessageProjectInitialized {
  }

@constraint()
  class ConstraintsUniqueEventTypeMessageProjectInitialization implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.uniqueFor(ConstraintsUniqueEventTypeMessageProjectInitialized, 'A project can only be initialized once.');
      }
  }
  ```

Or use a callback to compose the message dynamically from violation context:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueEventTypeCallbackProjectInitialized;

public class ConstraintsUniqueEventTypeCallbackProjectInitialization : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique<ConstraintsUniqueEventTypeCallbackProjectInitialized>(
              messageCallback: violation => $"Constraint '{violation.ConstraintName}' was violated - the project has already been initialized.");
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Constraint name

[Section titled “Constraint name”](#constraint-name)

An optional name can be provided to identify the constraint. When not provided, Chronicle uses the event type name as the default constraint name:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueEventTypeNamedProjectInitialized;

public class ConstraintsUniqueEventTypeNamedProjectInitialization : IConstraint
  {
      public void Define(IConstraintBuilder builder) =>
          builder.Unique<ConstraintsUniqueEventTypeNamedProjectInitialized>(
              name: "UniqueProjectInitialization",
              message: "A project can only be initialized once.");
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueEventTypeNamedProjectInitialized {
  }

@constraint()
  class ConstraintsUniqueEventTypeNamedProjectInitialization implements IConstraint {
      define(builder: IConstraintBuilder): void {
          builder.uniqueFor(
              ConstraintsUniqueEventTypeNamedProjectInitialized,
              'A project can only be initialized once.',
              'UniqueProjectInitialization');
      }
  }
  ```

## Releasing a constraint

[Section titled “Releasing a constraint”](#releasing-a-constraint)

Left alone the constraint says “at most one, ever”. Most lifecycles repeat — a shift is worked and ended, a loan is taken and returned, a subscription is activated and cancelled — and for those, “ever” refuses the second legitimate cycle and there is nothing the caller can do about it.

Call `.RemovedWith<T>()` to name the event that ends a cycle. A covered event then violates the constraint only when it comes **after** the most recent removal event on that event source, so the next cycle is free to start:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueEventTypeShiftStarted(string Location);

[EventType]
  public record ConstraintsUniqueEventTypeShiftEnded;

public class ConstraintsUniqueEventTypeOneOpenShift : IConstraint
  {
      // At most one open shift per employee. Ending the shift releases the constraint,
      // so the next shift is allowed - without it the constraint could only say
      // "at most one, ever", and the employee's second shift would be refused forever.
      public void Define(IConstraintBuilder builder) =>
          builder
              .Unique<ConstraintsUniqueEventTypeShiftStarted>()
              .RemovedWith<ConstraintsUniqueEventTypeShiftEnded>();
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueEventTypeShiftStarted {
      constructor(readonly location: string) {}
  }

@eventType()
  class ConstraintsUniqueEventTypeShiftEnded {
  }

@constraint()
  class ConstraintsUniqueEventTypeOneOpenShift implements IConstraint {
      // At most one open shift per employee. Ending the shift releases the constraint,
      // so the next shift is allowed - without it the constraint could only say
      // "at most one, ever", and the employee's second shift would be refused forever.
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .on(ConstraintsUniqueEventTypeShiftStarted)
                  .removedWith(ConstraintsUniqueEventTypeShiftEnded));
      }
  }
  ```

The removal applies to the constraint declared immediately before it, and it is per event source — one employee ending their shift opens their own next cycle and nobody else’s.

A cycle can end in more than one way, so chain `.RemovedWith<T>()` once for each event that ends it. Every one of them releases the constraint on its own, and the cycle ends at whichever was appended most recently:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsUniqueEventTypeSeveralLoanCheckedOut(string Title);

[EventType]
  public record ConstraintsUniqueEventTypeSeveralLoanReturned;

[EventType]
  public record ConstraintsUniqueEventTypeSeveralLoanWrittenOff;

public class ConstraintsUniqueEventTypeSeveralOneOpenLoan : IConstraint
  {
      // A loan is open until it is returned or written off. Both end the cycle, so the
      // borrower can take the next loan whichever way the previous one finished.
      public void Define(IConstraintBuilder builder) =>
          builder
              .Unique<ConstraintsUniqueEventTypeSeveralLoanCheckedOut>()
              .RemovedWith<ConstraintsUniqueEventTypeSeveralLoanReturned>()
              .RemovedWith<ConstraintsUniqueEventTypeSeveralLoanWrittenOff>();
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder } from '@cratis/chronicle';

@eventType()
  class ConstraintsUniqueEventTypeSeveralLoanCheckedOut {
      constructor(readonly title: string) {}
  }

@eventType()
  class ConstraintsUniqueEventTypeSeveralLoanReturned {
  }

@eventType()
  class ConstraintsUniqueEventTypeSeveralLoanWrittenOff {
  }

@constraint()
  class ConstraintsUniqueEventTypeSeveralOneOpenLoan implements IConstraint {
      // A loan is open until it is returned or written off. Both end the cycle, so the
      // borrower can take the next loan whichever way the previous one finished.
      define(builder: IConstraintBuilder): void {
          builder.unique(unique =>
              unique
                  .on(ConstraintsUniqueEventTypeSeveralLoanCheckedOut)
                  .removedWith(ConstraintsUniqueEventTypeSeveralLoanReturned)
                  .removedWith(ConstraintsUniqueEventTypeSeveralLoanWrittenOff));
      }
  }
  ```

Declaring several event types under one name makes them a single constraint, and the removal events declared across those declarations all apply to it.

The [model-bound form](/chronicle/constraints/model-bound/unique-event-type/) expresses the same thing with `[RemoveConstraint]` on the event that ends the cycle.

## Mutually exclusive event types

[Section titled “Mutually exclusive event types”](#mutually-exclusive-event-types)

Declare several event types under the **same constraint name** and they become one constraint: at most one event drawn from that set is allowed per event source. Use it when an event source has more than one terminal outcome and the outcomes exclude each other — cancelled *or* completed, merged *or* erased, approved *or* permanently rejected.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsPersonAliasedTo(Guid Target);

[EventType]
  public record ConstraintsPersonErased;

public class ConstraintsPersonTerminalOutcome : IConstraint
  {
      // Both declarations share one constraint name, so they become a single constraint:
      // at most one event drawn from { ConstraintsPersonAliasedTo, ConstraintsPersonErased }
      // per person. A person merged away can no longer be erased, and neither event can
      // occur twice.
      public void Define(IConstraintBuilder builder)
      {
          builder.Unique<ConstraintsPersonAliasedTo>(
              name: "PersonTerminal",
              message: "This person already has a terminal outcome.");

builder.Unique<ConstraintsPersonErased>(
              name: "PersonTerminal",
              message: "This person already has a terminal outcome.");
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { constraint, eventType, IConstraint, IConstraintBuilder, Guid } from '@cratis/chronicle';

@eventType()
  class ConstraintsPersonAliasedTo {
      constructor(readonly target: Guid) {}
  }

@eventType()
  class ConstraintsPersonErased {
  }

@constraint()
  class ConstraintsPersonTerminalOutcome implements IConstraint {
      // Both declarations share one constraint name, so they become a single constraint:
      // at most one event drawn from { ConstraintsPersonAliasedTo, ConstraintsPersonErased }
      // per person. A person merged away can no longer be erased, and neither event can
      // occur twice.
      define(builder: IConstraintBuilder): void {
          builder.uniqueFor(ConstraintsPersonAliasedTo, 'This person already has a terminal outcome.', 'PersonTerminal');
          builder.uniqueFor(ConstraintsPersonErased, 'This person already has a terminal outcome.', 'PersonTerminal');
      }
  }
  ```

Each event type still cannot occur twice — that is the single-type case of the same rule. What sharing the name adds is that the *first* of them to be appended blocks all of the others.

Because this is enforced at append time it holds under concurrency, which a validator reading prior state cannot guarantee: that check and the append are not atomic, so two competing commands can both observe “no terminal event yet” and both succeed.

## How constraints are enforced

[Section titled “How constraints are enforced”](#how-constraints-are-enforced)

# Model-bound constraints

Model-bound constraints let you declare uniqueness rules directly on event types using attributes. No separate constraint class is needed — adorn the event type or its properties with attributes, and Chronicle registers the constraints automatically when the client starts.

Note

Elixir has a real equivalent: `unique(fields, opts)`, `unique_event_type(opts)`, and `remove_constraint(name)` macros declared directly on the event type module — it supports custom constraint names and grouping by name, but not a custom violation message. Kotlin, Java, and TypeScript have no attribute/macro-based constraint declaration at all — only the [declarative](/chronicle/constraints/declarative/) `IConstraint` class style, and even that is narrower than C#‘s (see its own coverage note).

Use model-bound constraints when:

* The uniqueness rule applies to a single event type
* You want constraint metadata co-located with the event type it protects
* You want the simplest possible syntax

## Constraint types

[Section titled “Constraint types”](#constraint-types)

| Type                                                                       | Description                                                                     |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [Unique property](/chronicle/constraints/model-bound/unique/)              | Enforce that a property value is unique across one or more event types          |
| [Unique event type](/chronicle/constraints/model-bound/unique-event-type/) | Enforce that only one event of a specific type can be appended per event source |

## Discovery

[Section titled “Discovery”](#discovery)

Chronicle scans all loaded assemblies for types adorned with `[Unique]` and `[RemoveConstraint]` and registers the constraints with the Kernel automatically when the client starts. No explicit registration is required.

# Unique property constraint

Adorn a property with `[Unique]` to enforce that the **value of that property is unique** across every event of this type in the event store.

Chronicle discovers `[Unique]`-adorned properties automatically and registers the constraints with the Kernel when the client starts.

## Defining a unique property constraint

[Section titled “Defining a unique property constraint”](#defining-a-unique-property-constraint)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsModelBoundUniqueProjectCreated([property: Unique] string Name, string Description);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.Unique
  import io.cratis.chronicle.events.EventType

@EventType
  data class ConstraintsModelBoundUniqueProjectCreated(@Unique val name: String, val description: String)
  ```

* Java

```java
  import io.cratis.chronicle.constraints.Unique;
  import io.cratis.chronicle.events.EventType;

@EventType
  record ConstraintsModelBoundUniqueProjectCreated(@Unique String name, String description) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstraintsModelBoundUniqueProjectCreated do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-project-created"

defstruct [:name, :description]

unique(:name)
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Strongly-typed properties

[Section titled “Strongly-typed properties”](#strongly-typed-properties)

`[Unique]` works on `ConceptAs<T>` properties — the idiomatic way to model a domain value in Cratis. Chronicle treats the concept as the underlying primitive it wraps (`string`, `Guid`, and so on), so a uniqueness rule on a strongly-typed `EmailAddress` or `OrganizationNumber` behaves exactly like one on the raw primitive, and registers and enforces identically through the [declarative](/chronicle/constraints/declarative/unique/) form too:

* C#

```csharp
  using Cratis.Concepts;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

public record ConstraintsModelBoundUniqueEmailAddress(string Value) : ConceptAs<string>(Value);

[EventType]
  public record ConstraintsModelBoundUniqueAuthorRegistered([property: Unique(name: "UniqueAuthorEmail")] ConstraintsModelBoundUniqueEmailAddress Email);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.concepts.ConceptAs
  import io.cratis.chronicle.constraints.Unique
  import io.cratis.chronicle.events.EventType

data class ConstraintsModelBoundUniqueEmailAddress(override val value: String) : ConceptAs<String>

@EventType
  data class ConstraintsModelBoundUniqueAuthorRegistered(
      @Unique(id = "UniqueAuthorEmail") val email: ConstraintsModelBoundUniqueEmailAddress
  )
  ```

* Java

```java
  import io.cratis.chronicle.concepts.ConceptAs;
  import io.cratis.chronicle.constraints.Unique;
  import io.cratis.chronicle.events.EventType;

record ConstraintsModelBoundUniqueEmailAddress(String value) implements ConceptAs<String> {
      @Override
      public String getValue() {
          return value;
      }
  }

@EventType
  record ConstraintsModelBoundUniqueAuthorRegistered(
      @Unique(id = "UniqueAuthorEmail") ConstraintsModelBoundUniqueEmailAddress email) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Grouping constraints across event types

[Section titled “Grouping constraints across event types”](#grouping-constraints-across-event-types)

When multiple event types share the same constraint `name`, Chronicle groups them into a single constraint. A value introduced by any of the participating events is checked against all others:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsModelBoundUniqueUserRegistered([property: Unique(name: "UniqueEmail")] string Email, string DisplayName);

[EventType]
  public record ConstraintsModelBoundUniqueUserEmailChanged([property: Unique(name: "UniqueEmail")] string NewEmail);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.Unique
  import io.cratis.chronicle.events.EventType

@EventType
  data class ConstraintsModelBoundUniqueUserRegistered(
      @Unique(id = "UniqueEmail") val email: String,
      val displayName: String
  )

@EventType
  data class ConstraintsModelBoundUniqueUserEmailChanged(@Unique(id = "UniqueEmail") val newEmail: String)
  ```

* Java

```java
  import io.cratis.chronicle.constraints.Unique;
  import io.cratis.chronicle.events.EventType;

@EventType
  record ConstraintsModelBoundUniqueUserRegistered(@Unique(id = "UniqueEmail") String email, String displayName) {}

@EventType
  record ConstraintsModelBoundUniqueUserEmailChanged(@Unique(id = "UniqueEmail") String newEmail) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstraintsModelBoundUniqueUserRegistered do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-user-registered"

defstruct [:email, :display_name]

unique(:email, name: "UniqueEmail")
  end

defmodule MyApp.Events.ConstraintsModelBoundUniqueUserEmailChanged do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-user-email-changed"

defstruct [:new_email]

unique(:new_email, name: "UniqueEmail")
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Both events now participate in the same `UniqueEmail` constraint, so neither `UserRegistered` nor `UserEmailChanged` can introduce an email address that already exists.

## Violation message

[Section titled “Violation message”](#violation-message)

The `message` parameter is optional. Chronicle produces a default violation message when one is not supplied. A custom violation message is currently C#-only — none of the other clients’ constraint declarations (model-bound or declarative) support one:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  public record ConstraintsModelBoundUniqueMessageProjectCreated([property: Unique(message: "A project with this name already exists.")] string Name, string Description);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.Unique
  import io.cratis.chronicle.events.EventType

@EventType
  data class ConstraintsModelBoundUniqueMessageProjectCreated(
      @Unique(message = "A project with this name already exists.") val name: String,
      val description: String
  )
  ```

* Java

```java
  import io.cratis.chronicle.constraints.Unique;
  import io.cratis.chronicle.events.EventType;

@EventType
  record ConstraintsModelBoundUniqueMessageProjectCreated(
      @Unique(message = "A project with this name already exists.") String name, String description) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstraintsModelBoundUniqueMessageProjectCreated do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-message-project-created"

defstruct [:name, :description]

unique(:name, message: "A project with this name already exists.")
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Releasing a constraint

[Section titled “Releasing a constraint”](#releasing-a-constraint)

Apply `[RemoveConstraint]` to the event type that signals a domain object has been removed. When this event is appended, Chronicle releases the named constraint and its previously held values can be claimed again:

* C#

```csharp
  using Cratis.Concepts;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

public record ConstraintsModelBoundUniqueUserId(Guid Value) : ConceptAs<Guid>(Value);

[EventType]
  [RemoveConstraint("UniqueEmail")]
  public record ConstraintsModelBoundUniqueUserRemoved(ConstraintsModelBoundUniqueUserId UserId);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.RemoveConstraint
  import io.cratis.chronicle.events.EventType

@EventType
  @RemoveConstraint("UniqueEmail")
  data class ConstraintsModelBoundUniqueUserRemoved(val userId: String)
  ```

* Java

```java
  import io.cratis.chronicle.constraints.RemoveConstraint;
  import io.cratis.chronicle.events.EventType;

@EventType
  @RemoveConstraint("UniqueEmail")
  record ConstraintsModelBoundUniqueUserRemoved(String userId) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstraintsModelBoundUniqueUserRemoved do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-user-removed"

defstruct [:user_id]

remove_constraint("UniqueEmail")
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The constraint name must exactly match the name used in the `[Unique]` attribute that established it.

An event type can release more than one constraint by stacking multiple attributes:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  [RemoveConstraint("UniqueEmail")]
  [RemoveConstraint("UniqueUsername")]
  public record ConstraintsModelBoundUniqueMultiRemoveUserRemoved(ConstraintsModelBoundUniqueUserId UserId);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.RemoveConstraint
  import io.cratis.chronicle.events.EventType

@EventType
  @RemoveConstraint("UniqueEmail")
  @RemoveConstraint("UniqueUsername")
  data class ConstraintsModelBoundUniqueMultiRemoveUserRemoved(val userId: String)
  ```

* Java

```java
  import io.cratis.chronicle.constraints.RemoveConstraint;
  import io.cratis.chronicle.events.EventType;

@EventType
  @RemoveConstraint("UniqueEmail")
  @RemoveConstraint("UniqueUsername")
  record ConstraintsModelBoundUniqueMultiRemoveUserRemoved(String userId) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstraintsModelBoundUniqueMultiRemoveUserRemoved do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-multi-remove-user-removed"

defstruct [:user_id]

remove_constraint("UniqueEmail")
    remove_constraint("UniqueUsername")
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The reverse also holds: more than one event type can release the same constraint. Name it from each event that ends the lifecycle and every one of them frees the held values:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  [RemoveConstraint("UniqueInvitedEmail")]
  public record ConstraintsModelBoundUniqueSeveralInvitationAccepted;

[EventType]
  [RemoveConstraint("UniqueInvitedEmail")]
  public record ConstraintsModelBoundUniqueSeveralInvitationRevoked;

[EventType]
  [RemoveConstraint("UniqueInvitedEmail")]
  public record ConstraintsModelBoundUniqueSeveralInvitationExpired;
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstraintsModelBoundUniqueSeveralInvitationAccepted do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-several-invitation-accepted"

defstruct []

remove_constraint("UniqueInvitedEmail")
  end

defmodule MyApp.Events.ConstraintsModelBoundUniqueSeveralInvitationRevoked do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-several-invitation-revoked"

defstruct []

remove_constraint("UniqueInvitedEmail")
  end

defmodule MyApp.Events.ConstraintsModelBoundUniqueSeveralInvitationExpired do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-several-invitation-expired"

defstruct []

remove_constraint("UniqueInvitedEmail")
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## How constraints are enforced

[Section titled “How constraints are enforced”](#how-constraints-are-enforced)

The Chronicle Kernel reads the `[Unique]` and `[RemoveConstraint]` attributes when the client connects and creates the indexes it needs. Every subsequent append is checked against those indexes server-side, so no constraint logic runs in client code.

# Unique event type constraint

Adorn the event type class with `[Unique]` to enforce that **only one event of this type** can be appended per event source. Use this when the event itself is a unique fact — for example, registering a user can only happen once.

Chronicle discovers `[Unique]`-adorned types automatically and registers the constraints with the Kernel when the client starts.

## Defining a unique event type constraint

[Section titled “Defining a unique event type constraint”](#defining-a-unique-event-type-constraint)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  [Unique]
  public record ConstraintsModelBoundUniqueEventTypeUserRegistered(string Email, string DisplayName);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.Unique
  import io.cratis.chronicle.events.EventType

@EventType
  @Unique
  data class ConstraintsModelBoundUniqueEventTypeUserRegistered(val email: String, val displayName: String)
  ```

* Java

```java
  import io.cratis.chronicle.constraints.Unique;
  import io.cratis.chronicle.events.EventType;

@EventType
  @Unique
  record ConstraintsModelBoundUniqueEventTypeUserRegistered(String email, String displayName) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstraintsModelBoundUniqueEventTypeUserRegistered do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-event-type-user-registered"

defstruct [:email, :display_name]

unique_event_type()
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Constraint name and violation message

[Section titled “Constraint name and violation message”](#constraint-name-and-violation-message)

An optional constraint name and violation message can be provided:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

[EventType]
  [Unique(name: "UniqueUser", message: "A user with this identity has already been registered.")]
  public record ConstraintsModelBoundUniqueEventTypeNamedUserRegistered(string Email, string DisplayName);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.Unique
  import io.cratis.chronicle.events.EventType

@EventType
  @Unique(id = "UniqueUser", message = "A user with this identity has already been registered.")
  data class ConstraintsModelBoundUniqueEventTypeNamedUserRegistered(val email: String, val displayName: String)
  ```

* Java

```java
  import io.cratis.chronicle.constraints.Unique;
  import io.cratis.chronicle.events.EventType;

@EventType
  @Unique(id = "UniqueUser", message = "A user with this identity has already been registered.")
  record ConstraintsModelBoundUniqueEventTypeNamedUserRegistered(String email, String displayName) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstraintsModelBoundUniqueEventTypeNamedUserRegistered do
    use Chronicle.Events.EventType,
      id: "constraints-model-bound-unique-event-type-named-user-registered"

defstruct [:email, :display_name]

# Elixir supports a custom constraint name, but not a custom violation message.
    unique_event_type(name: "UniqueUser")
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The `message` parameter is optional. Chronicle produces a default violation message when one is not supplied.

## Releasing a constraint

[Section titled “Releasing a constraint”](#releasing-a-constraint)

Apply `[RemoveConstraint]` to the event type that signals a domain object has been removed. When this event is appended, Chronicle releases the constraint, and the event source can accept a new event of this type:

* C#

```csharp
  using Cratis.Concepts;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Constraints;

public record ConstraintsModelBoundUniqueEventTypeUserId(Guid Value) : ConceptAs<Guid>(Value);

[EventType]
  [RemoveConstraint("UniqueUser")]
  public record ConstraintsModelBoundUniqueEventTypeUserRemoved(ConstraintsModelBoundUniqueEventTypeUserId UserId);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.constraints.RemoveConstraint
  import io.cratis.chronicle.events.EventType

@EventType
  @RemoveConstraint("UniqueUser")
  data class ConstraintsModelBoundUniqueEventTypeUserRemoved(val userId: String)
  ```

* Java

```java
  import io.cratis.chronicle.constraints.RemoveConstraint;
  import io.cratis.chronicle.events.EventType;

@EventType
  @RemoveConstraint("UniqueUser")
  record ConstraintsModelBoundUniqueEventTypeUserRemoved(String userId) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstraintsModelBoundUniqueEventTypeUserRemoved do
    use Chronicle.Events.EventType, id: "constraints-model-bound-unique-event-type-user-removed"

defstruct [:user_id]

remove_constraint("UniqueUser")
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The constraint name must exactly match the name provided to the `[Unique]` attribute. When no name was provided to `[Unique]`, Chronicle uses the event type name as the default constraint name.

More than one event type can name the same constraint. Each of them releases it on its own, which is how a cycle that can end in more than one way is expressed with attributes.

## How constraints are enforced

[Section titled “How constraints are enforced”](#how-constraints-are-enforced)

# Contributing

| Topic                                                           | Description                                                                 |
| --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Integration Tests](/chronicle/contributing/integration-tests/) | How to run and work with integration tests.                                 |
| [PrimeUI License](/chronicle/contributing/primeui-license/)     | Supplying the PrimeReact/PrimeUI license key when working on the Workbench. |
| [Building a Client](/chronicle/building-a-client/)              | Starting a brand-new Chronicle client from scratch.                         |
| [Clients](/chronicle/contributing/clients/)                     | Contributing to the clients.                                                |
| [Kernel](/chronicle/contributing/kernel/)                       | Contributing to the Kernel.                                                 |

# Contributing to Clients

> Starting a brand-new client from scratch? [Building a Chronicle Client](/chronicle/building-a-client/) is the onboarding story — starting points, the idiomatic-client layering, authentication, clustering, and the real history of the TypeScript, Elixir, and Kotlin clients. This page and the rest of this section are the deep reference for how Chronicle’s own clients are built and maintained.

Below are the core principles for building public facing APIs exposed in our clients:

* APIs should be lovable
* Provide sane defaults but make them flexible, extensible and overridable
* Consistency is king
* It should be easy to do things right, hard to do things wrong
* Never expose more than is needed

## Shared documentation snippets

[Section titled “Shared documentation snippets”](#shared-documentation-snippets)

Chronicle’s shared public documentation is language agnostic. It uses unified language tabs for examples that apply across clients. The shared Chronicle page owns the explanation and where the tab group appears, but each client repo owns its own code snippet.

This keeps the published docs readable while keeping client-specific APIs close to the code that can verify them.

### Ownership

[Section titled “Ownership”](#ownership)

Place snippets in `Documentation/client-snippets/**` in the repo that owns the client:

* C#: `Chronicle/Documentation/client-snippets`
* Kotlin: `Chronicle.Kotlin/Documentation/client-snippets`
* Java: `Chronicle.Kotlin/Documentation/client-snippets-java`
* Elixir: `Chronicle.Elixir/Documentation/client-snippets`
* TypeScript: `Chronicle.TypeScript/Documentation/client-snippets`

Snippet files can be `.md` or `.mdx`. Prefer `.md` for ordinary fenced code snippets; use `.mdx` only when the snippet file itself needs MDX syntax.

Do not create a public client-specific Chronicle section just to hold equivalent snippets. The snippet folders are source-only and are expanded into the shared pages by the documentation site sync.

Do not add new raw `csharp`, `cs`, `java`, `kotlin`, `elixir`, `typescript`, or `ts` fenced examples to shared Chronicle docs for client SDK behavior. Use `<ChronicleClientTabs />` instead. The Documentation repo runs `npm run chronicle-client-docs:check`, which fails on missing snippets and on any increase in direct client-language fences in shared Chronicle docs.

### Add a shared example

[Section titled “Add a shared example”](#add-a-shared-example)

Shared Chronicle pages reference those snippets with a placeholder:

```mdx
<ChronicleClientTabs snippet="events/appending/example" />
```

The snippet id is extensionless. Add the same id under each participating client repo:

```text
Chronicle/Documentation/client-snippets/events/appending/example.md
Chronicle.Kotlin/Documentation/client-snippets-java/events/appending/example.md
Chronicle.Kotlin/Documentation/client-snippets/events/appending/example.md
Chronicle.Elixir/Documentation/client-snippets/events/appending/example.md
Chronicle.TypeScript/Documentation/client-snippets/events/appending/example.md
```

Use one fenced code block in each snippet file unless the language needs more than one block. The fenced language must match the owning client, for example `csharp`, `java`, `kotlin`, `elixir`, or `typescript`.

`<ChronicleClientTabs />` has no `clients` property. Chronicle’s shared docs never declare which clients apply to an example — the sync discovers that itself: it checks every registered client’s snippet root for a file at that id and renders a tab only for the clients where one exists. When only some clients expose a concept, simply don’t add a snippet file for the others; there is nothing to configure on the placeholder.

When a shared workflow should be visible for a client but that client does not support it yet, keep the tab visible with an explicit unsupported snippet instead of omitting the client:

````md
```text
This Chronicle client does not support this workflow yet.
Track the client SDK issue before using this API from this language.
```
````

The default synchronized tab key is `chronicle-client`, so choosing TypeScript in one tab group selects TypeScript in the other tab groups on that page. Use a custom `syncKey` only when tab groups should not follow each other.

### Where “client X doesn’t support this” belongs

[Section titled “Where “client X doesn’t support this” belongs”](#where-client-x-doesnt-support-this-belongs)

That unsupported snippet is the **only** place to state that a client does not support a workflow. Do not write it as prose on a shared page — no “this is currently C#-only”, no “Kotlin and Java don’t have an equivalent yet”.

A shared page cannot know when a client gains a capability. It lives in a different repo, on a different release cadence, with no CI that fails when the claim stops being true — so the claim silently rots, and the first person to notice is a reader who believes it. An unsupported snippet, by contrast, sits in the client repo next to the code, and the person adding the capability is already editing that folder.

The rule is about **claims of absence**, not about describing differences. It is fine for a shared page to say that a client expresses the same capability through a different shape, as long as it does not assert that some client cannot do something:

* ❌ “Kotlin, Java, and Elixir don’t currently support targeting a non-default event sequence at all.”
* ✅ “TypeScript reaches the same result through the decorator’s event-sequence parameter rather than a separate attribute.”

When a client does not support a workflow at all, leave the shared prose alone and let the tab carry it.

### Validation and CI

[Section titled “Validation and CI”](#validation-and-ci)

Each client repo must also keep `Documentation/validate-client-snippets.py` wired into its `Client Snippet Verification` workflow. That workflow compiles the snippets against the client source when either `Documentation/client-snippets/**` or `Source/**` changes, so a client API change cannot silently leave the shared Chronicle docs stale.

Run the validator in each repo whose snippets changed:

```bash
python3 Documentation/validate-client-snippets.py
```

Then run the documentation site build from the Documentation repo:

```bash
cd web
npm run build
```

External client repos also need a documentation sync workflow that triggers the `build-docs` workflow in the `Cratis/Documentation` repo after snippet changes land on `main`.

### Client-specific pages

[Section titled “Client-specific pages”](#client-specific-pages)

Use snippets for examples that belong inside shared Chronicle pages. Use client-specific pages only when the content is genuinely different for that client, such as installation, connection setup, runtime integration, language-specific APIs, framework integration, decorators or annotations, package behavior, generated APIs, or troubleshooting.

Chronicle concepts and feature workflows belong in the shared Chronicle docs. Do not add client-specific concept or guide trees for events, reactors, reducers, read models, projections, constraints, seeding, transactions, migrations, or compliance when the same explanation applies across clients.

Client-specific pages still live in the owning client repo’s `Documentation/**` folder:

* .NET pages render under `/chronicle/clients/dotnet/` from `Chronicle/Documentation/clients/dotnet/**`
* Kotlin pages render under `/chronicle/clients/kotlin/`
* Elixir pages render under `/chronicle/clients/elixir/`
* TypeScript pages render under `/chronicle/clients/typescript/`

The documentation site imports those pages into the Chronicle navigation under **Client SDKs**. The `Documentation/client-snippets/**` folders are skipped and never become public pages.

If a client-specific page later becomes generally useful across clients, move the explanation into the shared Chronicle docs and use `<ChronicleClientTabs />` for the code.

`npm run chronicle-client-docs:check` audits public client docs for shared-topic overlap using `Documentation/web/chronicle-client-docs.yml`. That count is a ratchet: it can go down as duplicated client pages are consolidated into shared docs, but it must not increase.

If an old client URL must remain as a pointer to the shared docs, mark it as a bridge page:

```yaml
---
sharedTopicBridge: true
---
```

Bridge pages should only explain where the canonical shared topic lives and where to find client-specific setup or reference details.

### Add another Chronicle client

[Section titled “Add another Chronicle client”](#add-another-chronicle-client)

To add another client language later:

1. Add the client repo to the Documentation repo checkout/submodule setup.
2. Add it to `Documentation/web/chronicle-client-docs.yml`.
3. Add `Documentation/client-snippets/**` to the client repo when it participates in shared tabs. A new client only shows up in a tab group once it has a matching snippet file — no other wiring makes it opt-in or required.
4. Add `Documentation/validate-client-snippets.py` that compiles snippets against that client.
5. Add a `Client Snippet Verification` workflow in the client repo.
6. Add the documentation sync workflow that triggers the Documentation repo after `Documentation/**` changes land on `main`.
7. Add the new language’s snippet files for the shared Chronicle pages that should include it.
8. Run the affected snippet validators, `npm run chronicle-client-docs:check`, and `npm run build` in `Documentation/web`.

### Migration audit

[Section titled “Migration audit”](#migration-audit)

The current docs have migrated shared client examples behind `<ChronicleClientTabs />`. The Documentation repo keeps a direct-fence baseline in `web/scripts/chronicle-client-docs-baseline.json`; the normal audit allows direct-fence counts to decrease but fails if they increase.

The aggregate client-doc check also reports public client pages that still look like shared Chronicle topic pages. Treat those counts as migration debt: move the shared explanation into Chronicle docs, replace code with synchronized tabs, then lower the manifest baseline.

Use strict mode to see the remaining migration work:

```bash
cd Documentation/web
npm run audit:chronicle-client-docs:strict
```

When migrating a page, replace each client SDK example with `<ChronicleClientTabs snippet="..." />`, add matching snippets in the participating client repos, run each affected client snippet validator, then refresh the baseline after the direct-fence count decreases.

## Topics

[Section titled “Topics”](#topics)

| Topic                                                               | Description                                                |
| ------------------------------------------------------------------- | ---------------------------------------------------------- |
| [Client Types](/chronicle/contributing/clients/client-types/)       | The different client types and relationships between them. |
| [.NET](/chronicle/contributing/clients/dotnet/)                     | The .NET Client.                                           |
| [API](/chronicle/contributing/clients/api/)                         | The REST API Client.                                       |
| [Internalization](/chronicle/contributing/clients/internalization/) | The process of internalization.                            |

# API

The REST API client is exposed in the Kernel when packaged as a Docker container, hidden behind a feature flag that is default set to true. Its main use case is for the Workbench to work.

In addition to this, the Workbench can also be embedded into a client project, it will also then embed the API.

## Internal constructors

[Section titled “Internal constructors”](#internal-constructors)

When we package assemblies using runtime-only strategy, we perform an [internalization](/chronicle/contributing/clients/internalization/) of types from assemblies that should not be exposed at compile-time. Some of these types, such as gRPC service contracts are typically things we would like to use as dependencies on constructors of the controllers.

The problem with this is that we can’t have public constructors with dependencies to these types that are runtime-only.

To make this work, the constructors are internal as a consequence.

## Custom Controller Activation

[Section titled “Custom Controller Activation”](#custom-controller-activation)

The default activation of controllers is not capable of resolving controllers with internal constructors. In the `API` client project you’ll therefore find a type called `CustomControllerActivator` that is capable of resolving these.

# Client Types

Chronicle provides several types of clients, each designed for specific scenarios and use cases. All client implementations are found in `./Source/Clients` at the root of the Chronicle repository. Client types include standard clients, test clients, and REST APIs.

## Project Dependencies

[Section titled “Project Dependencies”](#project-dependencies)

The various client projects have the following dependency hierarchy:

```
XUnit.Integration

XUnit

ClientIntegration

AspNetCore

DotNET

Orleans

Connections

Infrastructure

Contracts

Api
```

## Common Building Blocks

[Section titled “Common Building Blocks”](#common-building-blocks)

All clients share a set of foundational building blocks, used either directly or indirectly:

### Connections

[Section titled “Connections”](#connections)

The `Connections` project provides abstractions for managing connections to the Chronicle **Kernel** and maintaining their lifecycle. It also defines the `ChronicleConnectionString` type.

### Contracts

[Section titled “Contracts”](#contracts)

All **gRPC** protobuf data and service definitions are created in a code-first manner using the [protobuf-net.Grpc](https://github.com/protobuf-net/protobuf-net.Grpc) package. These definitions are referred to as [contracts](/chronicle/contributing/kernel/contracts/).

### Infrastructure

[Section titled “Infrastructure”](#infrastructure)

The `Infrastructure` project, located at `./Source/Infrastructure`, contains shared infrastructure components used by both the **Kernel** and the clients. It is not part of the `Clients` folder.

## .NET

[Section titled “.NET”](#net)

Most clients are built on top of the common .NET client, which serves as the idiomatic C# entry point to the **Kernel** API surface. It relies on the [gRPC contracts](/chronicle/contributing/kernel/contracts/) for communication. The goal is to provide a C#-friendly API that is intuitive and easy to use. For more details, see [the .NET client documentation](/chronicle/contributing/clients/dotnet/).

## Client Integration

[Section titled “Client Integration”](#client-integration)

The `Integration/Client` project hosts the shared .NET integration specifications and can run them against either an in-process kernel or an out-of-process Chronicle container.

## ASP.NET Core

[Section titled “ASP.NET Core”](#aspnet-core)

The ASP.NET Core client enables seamless integration with Chronicle in ASP.NET Core applications. It provides extension methods for `WebApplicationBuilder` to simplify configuration and setup.

## XUnit

[Section titled “XUnit”](#xunit)

For unit-level testing, the XUnit project provides helpers that allow you to write tests without depending on infrastructure.

## XUnit.Integration

[Section titled “XUnit.Integration”](#xunitintegration)

The `XUnit.Integration` project focuses on full-stack testing with all infrastructure in place. It provides test setup for both in-process and out-of-process scenarios.

## Orleans

[Section titled “Orleans”](#orleans)

The `Orleans` project enables deeper integration with Microsoft Orleans, allowing you to leverage Orleans features alongside Chronicle. For example, it provides an `AggregateRoot` implementation as a Grain, turning aggregates into actors.

## API

[Section titled “API”](#api)

The `API` project contains all REST endpoints used by the Workbench. For more information, see the [API documentation](/chronicle/contributing/clients/api/).

# .NET Client

The .NET client serves as the foundation for most Chronicle clients. Its design philosophy is to offer a streamlined API for quick onboarding, while also empowering developers with full control and extensibility. Out of the box, the client provides sensible defaults to help you get started rapidly, but every default is fully overridable to suit advanced scenarios.

For example, you can instantiate a `ChronicleClient` with just the server `URI` and immediately begin working. You may use the built-in discovery method to automatically discover all artifacts, or selectively discover only those you need. If you require custom behavior, you can override the discovery mechanism entirely by implementing your own `IClientArtifactsProvider`.

This approach ensures an easy entry point for new users, while also supporting advanced customization for those who need it.

## Packaging

[Section titled “Packaging”](#packaging)

The .NET client uses runtime-only packaging to hide internal implementation details. It includes the [contracts](/chronicle/contributing/kernel/contracts/) and the `Connection` project as runtime-only assemblies, ensuring they’re not exposed in IntelliSense or available for direct compilation by consumers. See [internalization](/chronicle/contributing/clients/internalization/) for details on how this works.

## Using statements

[Section titled “Using statements”](#using-statements)

* Common usings are provided in `GlobalUsings.cs` files, don’t add any using statements already in this file.
* Include using statements not covered by any `GlobalUsing.cs` definitions.
* Don’t add any `System` using statements.

## Language

[Section titled “Language”](#language)

* C# does not allow for multiple inheritance.

# Internalization

Clients must present a single, clear, and idiomatic API surface. Any dependencies required to implement this API should remain hidden from consumers. This prevents confusion caused by exposing internal concepts or types that may exist in multiple namespaces or packages for different purposes. When tools like IDEs auto-import namespaces, exposing these internals can lead to ambiguous references and a degraded developer experience.

Furthermore, some APIs are not intended for public consumption or long-term support. Exposing these would require us to maintain and version them alongside the official client APIs, which is undesirable.

Typical examples of APIs we internalize include [contracts](/chronicle/contributing/kernel/contracts/) and any Kernel APIs bundled with the full .NET InProcess client.

## Runtime-only packaging

[Section titled “Runtime-only packaging”](#runtime-only-packaging)

To prevent exposing APIs that are not intended for public use, we package our assemblies using a runtime-only strategy. This approach separates compile-time dependencies (what developers see in IntelliSense) from runtime dependencies (what’s available at execution time).

The core idea is to:

* **Package SDK assemblies under `lib/`** as compile-time references
* **Ship Server, Contracts, Services, and other kernel assemblies as runtime-only assets** in the `runtimes/` folder

This means:

* IntelliSense/autocomplete shows only SDK types
* `using Cratis.Chronicle.Projections;` binds to SDK’s IProjection interface
* Even if consumers manually type internal server type names, they won’t compile (no compile-time reference to those DLLs)
* Server/contracts can contain identical namespaces and types—they simply aren’t part of compilation

The following diagram illustrates the packaging structure:

```
NuGet Package

Compiles against

Runs with

runtimes/ (Runtime-only)

Cratis.Chronicle.Connections.dll

Cratis.Chronicle.Contracts.dll

Cratis.Chronicle.Contracts.Implementations.dll

Cratis.Chronicle.Core.dll

Cratis.Chronicle.Services.dll

Cratis.Chronicle.Storage*.dll

Other kernel assemblies...

lib/ (Compile-time)

Cratis.Chronicle.dll (SDK API)

Cratis.Chronicle.InProcess.dll (InProcess API)

Consumer Application
```

## Configuring runtime-only packaging

[Section titled “Configuring runtime-only packaging”](#configuring-runtime-only-packaging)

Runtime-only packaging is handled **automatically** by the shared `Source/Clients/Directory.Build.props`. The only thing you need to do in your `.csproj` is mark the dependency with `<PrivateAssets>all</PrivateAssets>`.

### Convention

[Section titled “Convention”](#convention)

Any `ProjectReference` with `<PrivateAssets>all</PrivateAssets>` is treated as a runtime-only dependency. When at least one such reference exists in a library project, the build infrastructure automatically:

1. Places the **main assembly** in `ref/{tfm}/` — this is the only assembly visible to consumers at compile time and in IntelliSense.
2. Places each **private reference assembly** (DLL + PDB) in `lib/{tfm}/` — available at runtime but hidden from consumers.

`IncludeBuildOutput` is set to `true` by the shared props file so the main assembly is also placed in `lib/` for runtime. Projects that need a different value (e.g. Roslyn analyzers) can override it locally.

### Example: marking a dependency as private

[Section titled “Example: marking a dependency as private”](#example-marking-a-dependency-as-private)

```xml
<ItemGroup>
    <ProjectReference Include="../../Kernel/Contracts/Contracts.csproj">
        <PrivateAssets>all</PrivateAssets>
    </ProjectReference>
</ItemGroup>
```

That single annotation is all that is needed. The `ref/lib` split, `<None>` items, and NuGet packaging are generated automatically — no manual `<None Include="..." Pack="true" PackagePath="..." />` entries required.

### Non-ProjectReference private assemblies

[Section titled “Non-ProjectReference private assemblies”](#non-projectreference-private-assemblies)

Some assemblies are generated at build time and are not represented by a `ProjectReference`. For these, add a `<PrivatePackageAssembly>` item with the assembly name (without file extension):

```xml
<ItemGroup>
    <PrivatePackageAssembly Include="Cratis.Chronicle.Contracts.Implementations" />
</ItemGroup>
```

These assemblies are packaged in `lib/{tfm}/` alongside the private project-reference assemblies.

### How it works

[Section titled “How it works”](#how-it-works)

The `_SetupPrivateRefPackaging` MSBuild target in `Source/Clients/Directory.Build.props` is registered via `TargetsForTfmSpecificContentInPackage`, which is the official NuGet SDK extension point for adding per-TFM content to packages. During `dotnet pack`, NuGet’s `_WalkEachTargetPerFramework` invokes this target once per target framework in an inner build where `$(TargetFramework)` is set.

The target:

1. Filters `ProjectReference` items for those with `PrivateAssets=all`.
2. Invokes `GetTargetPath` on each to resolve the output assembly name.
3. Adds the main assembly to `ref/{tfm}/` and all private assemblies to `lib/{tfm}/` as `TfmSpecificPackageFile` items.

The target only fires for library projects (`OutputType != Exe`) that have at least one private `ProjectReference`.

## Grpc Client Factory

[Section titled “Grpc Client Factory”](#grpc-client-factory)

To efficiently reuse the core connection logic while internalizing implementation details, we take a specialized approach to generating and consuming gRPC clients.

When kernel assemblies are packaged as runtime-only, types such as `ChronicleConnection` from the `Connections` project are not available at compile-time, making it impossible to reference them in generated gRPC client code. To address this, we generate the required client types at build time and include them in the .NET client assembly.

This process involves two key steps:

* **Build-time client generation:** The `GrpcClients` project uses `System.Reflection.Emit` and gRPC tooling to generate a dedicated assembly containing all required client implementations. These types are pre-generated and ready for use, eliminating the need for runtime code generation.
* **Custom ClientFactory:** We override the default `ClientFactory` to discover and instantiate these pre-generated client types. Instead of attempting to create new clients dynamically (which would fail due to missing compile-time references), the factory locates and uses the generated implementations.

The resulting workflow for the .NET client is as follows:

```
Generate gRPC Clients

Build SDK

Package with Runtime Assemblies
```

By generating clients ahead of time and customizing the factory, we ensure that all necessary gRPC clients are available and discoverable, even without compile-time access to internal types. This approach maintains a clean public API, leverages shared connection logic, and avoids runtime errors related to inaccessible types.

## Projects with access to internals

[Section titled “Projects with access to internals”](#projects-with-access-to-internals)

When a project depends on a packaged assembly and requires access to its internalized types—such as the `AspNetCore` project, we must explicitly grant visibility to those internals. This is achieved by adding an `<InternalsVisibleTo>` entry for the consuming assembly.

For example, in the `DotNET.csproj` file, you will find an `<ItemGroup>` containing one or more such entries:

```xml
<ItemGroup>
    <InternalsVisibleTo Include="Cratis.Chronicle.AspNetCore" />
</ItemGroup>
```

This configuration ensures that `AspNetCore` can access internal members of the SDK assembly, while those internals remain hidden from all other consumers.

## Internals Verifier

[Section titled “Internals Verifier”](#internals-verifier)

When a public API inadvertently exposes a type from an assembly that should be runtime-only, consumers may attempt to use these types in their code, leading to compilation errors. This is a common source of accidental leaks—such as a public property, method, or constructor referencing an internal type—which can compromise the intended encapsulation.

To prevent this, we use the `InternalsVerifier` as a post-build tool. It scans assemblies for any public members that reference types originating from assemblies marked for runtime-only packaging. If such a violation is detected, the build fails immediately, ensuring that no internal implementation details are exposed to consumers.

Typical violations include public properties or constructors that use runtime-only types, which are easy to overlook during development. The `InternalsVerifier` enforces this boundary automatically, maintaining a clean and intentional API surface.

# Protobuf Extraction from C# Contracts

This document explains how to extract `.proto` files from C# gRPC service definitions using the ProtoGenerator tool.

## Overview

[Section titled “Overview”](#overview)

Chronicle uses a code-first approach for gRPC service definitions in C#. To support clients in other languages (TypeScript, Python, Go, etc.), we extract the service definitions to standard Protocol Buffer (`.proto`) files using the ProtoGenerator tool.

## ProtoGenerator Tool

[Section titled “ProtoGenerator Tool”](#protogenerator-tool)

**Location:** `Source/Tools/ProtoGenerator`

A .NET console application that generates `.proto` files from the Chronicle C# gRPC contracts.

### How It Works

[Section titled “How It Works”](#how-it-works)

1. Loads the `Cratis.Chronicle.Contracts.dll` assembly
2. Finds all interfaces decorated with `[Service]` attribute
3. Uses `protobuf-net.Grpc.Reflection` to generate proto files
4. Groups services by namespace to handle multiple packages
5. Outputs separate `.proto` files for each service namespace

### Usage

[Section titled “Usage”](#usage)

```bash
dotnet run --project Source/Tools/ProtoGenerator/ProtoGenerator.csproj -- \
  <path-to-contracts-dll> \
  <output-directory>
```

### Example

[Section titled “Example”](#example)

```bash
dotnet run --project Source/Tools/ProtoGenerator/ProtoGenerator.csproj -- \
  Source/Kernel/Contracts/bin/Release/net10.0/Cratis.Chronicle.Contracts.dll \
  Source/Kernel/Protobuf
```

## Generating Proto Files Locally

[Section titled “Generating Proto Files Locally”](#generating-proto-files-locally)

```bash
# Build the Contracts assembly
cd Source/Kernel/Contracts
dotnet build -c Release

# Generate proto files
cd ../../..
dotnet run --project Source/Tools/ProtoGenerator/ProtoGenerator.csproj -- \
  Source/Kernel/Contracts/bin/Release/net10.0/Cratis.Chronicle.Contracts.dll \
  Source/Kernel/Protobuf
```

## Generated Proto Files

[Section titled “Generated Proto Files”](#generated-proto-files)

**Output location:** `Source/Kernel/Protobuf/*.proto`

The tool generates the following proto files:

* `clients.proto` - Client connection services
* `cratis_chronicle_contracts.proto` - Event stores and namespaces
* `events.proto` - Event type services
* `events_constraints.proto` - Event constraint services
* `eventsequences.proto` - Event sequence services
* `host.proto` - Host/server information
* `identities.proto` - Identity services
* `jobs.proto` - Job management
* `observation.proto` - Observer services
* `observation_reactors.proto` - Reactor services
* `observation_reducers.proto` - Reducer services
* `projections.proto` - Projection services
* `readmodels.proto` - Read model services
* `recommendations.proto` - Recommendation services
* `seeding.proto` - Event seeding services

## Using Proto Files for Other Clients

[Section titled “Using Proto Files for Other Clients”](#using-proto-files-for-other-clients)

Once the proto files are generated, they can be used to generate client code in any language that supports gRPC:

### Python Example

[Section titled “Python Example”](#python-example)

```bash
python -m grpc_tools.protoc \
  -I Source/Kernel/Protobuf \
  --python_out=. \
  --grpc_python_out=. \
  Source/Kernel/Protobuf/*.proto
```

### Go Example

[Section titled “Go Example”](#go-example)

```bash
protoc \
  -I Source/Kernel/Protobuf \
  --go_out=. \
  --go-grpc_out=. \
  Source/Kernel/Protobuf/*.proto
```

### TypeScript Example

[Section titled “TypeScript Example”](#typescript-example)

See [TypeScript gRPC Package](/chronicle/contributing/clients/typescript-grpc-package/) for details on the TypeScript client generation.

## Maintenance

[Section titled “Maintenance”](#maintenance)

When adding new gRPC services to the C# Contracts:

1. Decorate service interfaces with `[Service]` attribute
2. Decorate service methods with `[Operation]` attribute
3. Run the ProtoGenerator to regenerate proto files
4. Regenerate client code for all supported languages
5. Commit the updated proto files to the repository

## Dependencies

[Section titled “Dependencies”](#dependencies)

The ProtoGenerator tool uses:

* `protobuf-net.Grpc.Reflection` - For extracting proto definitions from C# attributes
* `.NET 10` - Runtime for the tool

## Proto File Format

[Section titled “Proto File Format”](#proto-file-format)

The generated proto files follow the Protocol Buffers version 3 syntax and include:

* Service definitions with RPC methods
* Message types for requests and responses
* Import statements for dependencies (including `protobuf-net/bcl.proto` for .NET-specific types like Guid, DateTime, etc.)

# TypeScript gRPC Package Generation

This document explains the TypeScript gRPC package generation and publishing setup for Chronicle.

## Overview

[Section titled “Overview”](#overview)

The Chronicle TypeScript gRPC package (`@cratis/chronicle.contracts`) provides strongly-typed TypeScript bindings for Chronicle’s gRPC services. The package generation process consists of two main steps:

1. **Generate .proto files** from C# gRPC service definitions (see [Protobuf Extraction](/chronicle/contributing/clients/protobuf-extraction/))
2. **Generate TypeScript code** from proto files and publish the npm package

## Components

[Section titled “Components”](#components)

### 1. TypeScript Package (`Source/Clients/TypeScript`)

[Section titled “1. TypeScript Package (Source/Clients/TypeScript)”](#1-typescript-package-sourceclientstypescript)

An npm package that provides strongly-typed TypeScript bindings for the Chronicle gRPC services.

**Structure:**

* `package.json` - Package configuration with @cratis/chronicle.contracts as the package name
* `tsconfig.json` - TypeScript compiler configuration
* `rollup.config.mjs` - Rollup bundler configuration for ESM and CJS builds
* `index.ts` - Main entry point that exports all generated services
* `ChronicleConnection.ts` - Connection manager for Chronicle services
* `ChronicleServices.ts` - Interface for all available services
* `generated/` - Directory containing TypeScript files generated from proto definitions
* `README.md` - Package documentation

**How it works:**

* Uses `ts-proto` to generate TypeScript files from proto definitions
* Generates proto `int64`/`uint64` fields as TypeScript `bigint` (`forceLong=bigint`)
* Generates strongly-typed clients with full IDE support and IntelliSense
* Provides `ChronicleConnection` class for easy connection management
* Provides `ChronicleConnectionString` class for connection string parsing
* Implements OAuth 2.0 client credentials flow for authentication
* Exports all service clients and types
* Builds both ESM and CJS versions using Rollup

**Key classes:**

* `ChronicleConnection` - Main connection manager with service access
* `ChronicleConnectionString` - Connection string parser supporting `chronicle://` URI scheme
* `ChronicleServices` - Interface defining all available services
* `TokenProvider` - OAuth token management (client credentials and API key)

### 2. GitHub Workflows

[Section titled “2. GitHub Workflows”](#2-github-workflows)

#### Build Workflow (`.github/workflows/typescript-build.yml`)

[Section titled “Build Workflow (.github/workflows/typescript-build.yml)”](#build-workflow-githubworkflowstypescript-buildyml)

Validates the TypeScript package on every PR and push to main.

**Triggers:**

* Push to main branch
* Pull requests to any branch
* Changes to TypeScript client, Contracts, Protobuf, or ProtoGenerator

**Steps:**

1. Setup .NET 10 and Node.js 23
2. Install protoc (Protocol Buffer Compiler)
3. Build the Contracts assembly
4. Run ProtoGenerator to generate .proto files
5. Install TypeScript dependencies
6. Generate TypeScript files from proto definitions using ts-proto
7. Build TypeScript package

#### Publish Workflow (`.github/workflows/publish.yml`)

[Section titled “Publish Workflow (.github/workflows/publish.yml)”](#publish-workflow-githubworkflowspublishyml)

Publishes the TypeScript package to NPM alongside .NET packages during releases.

**Triggers:**

* Release published

**Steps:**

1. Setup .NET 10 and Node.js 23
2. Install protoc
3. Build the Contracts assembly
4. Run ProtoGenerator to generate .proto files
5. Install TypeScript dependencies
6. Generate TypeScript files using ts-proto
7. Build TypeScript package
8. Publish to NPM
9. Commit and push updated proto and TypeScript files back to repository

**Required Secrets:**

* `NPM_TOKEN` - NPM authentication token for publishing

## Usage

[Section titled “Usage”](#usage)

### Prerequisites

[Section titled “Prerequisites”](#prerequisites)

Proto files must be generated first. See [Protobuf Extraction](/chronicle/contributing/clients/protobuf-extraction/) for details on generating proto files from C# contracts.

### Building TypeScript Package Locally

[Section titled “Building TypeScript Package Locally”](#building-typescript-package-locally)

```bash
cd Source/Clients/TypeScript
yarn install
yarn build
```

### Using the Published Package

[Section titled “Using the Published Package”](#using-the-published-package)

Install the package:

```bash
npm install @cratis/chronicle.contracts
# or
yarn add @cratis/chronicle.contracts
```

Use the generated service definitions from your gRPC transport code:

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventStoresDefinition } from '@cratis/chronicle.contracts';

const eventStoresService = EventStoresDefinition.fullName;
  const eventStoresMethods = Object.keys(EventStoresDefinition.methods);

console.log(`Generated service ${eventStoresService} exposes: ${eventStoresMethods.join(', ')}`);
  ```

The package also includes generated request and response message helpers:

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EnsureEventStoreRequest, EnsureNamespaceRequest, AllNamespacesRequest } from '@cratis/chronicle.contracts';

console.log(eventStore, namespace, namespaces);
  ```

### Service Definitions

[Section titled “Service Definitions”](#service-definitions)

Service definitions expose the protobuf service name and generated method definitions:

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { NamespacesDefinition } from '@cratis/chronicle.contracts';

const allNamespacesMethod = NamespacesDefinition.methods.allNamespaces;

console.log(`${NamespacesDefinition.fullName}.${allNamespacesMethod.name}`);
  ```

### Typed Clients

[Section titled “Typed Clients”](#typed-clients)

When a gRPC transport creates clients from the generated definitions, use the generated client interfaces for type safety:

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventStoresClient, NamespacesClient } from '@cratis/chronicle.contracts';

async function readAvailableNamespaces(eventStores: EventStoresClient, namespaces: NamespacesClient): Promise<string[]> {
      await eventStores.ensureEventStore({ Name: 'shopping' });

// Queries stream results so they can also be observed; one-shot callers take the first result.
      for await (const result of namespaces.allNamespaces({ EventStore: 'shopping' })) {
          return result.Data;
      }

return [];
  }
  ```

## Publishing a New Version

[Section titled “Publishing a New Version”](#publishing-a-new-version)

The TypeScript package is automatically published to NPM when a new GitHub release is created. The publish workflow will:

1. Generate fresh proto files from C# contracts
2. Generate TypeScript code from proto files
3. Build the TypeScript package
4. Publish to NPM with the release version tag
5. Commit updated proto and TypeScript files back to the repository

## Generated Files

[Section titled “Generated Files”](#generated-files)

**Proto files:** `Source/Kernel/Protobuf/*.proto`

See [Protobuf Extraction](/chronicle/contributing/clients/protobuf-extraction/) for the complete list of generated proto files.

**TypeScript files:** `Source/Clients/TypeScript/generated/*.ts`

The TypeScript generation creates:

* Service client interfaces and implementations
* Request and response message types
* Enum definitions
* Type definitions for all Chronicle concepts

## Maintenance

[Section titled “Maintenance”](#maintenance)

When adding new gRPC services to the C# Contracts:

1. Ensure services are decorated with `[Service]` attribute
2. Ensure methods are decorated with `[Operation]` attribute
3. Regenerate proto files (see [Protobuf Extraction](/chronicle/contributing/clients/protobuf-extraction/))
4. Run the TypeScript generation to create new TypeScript clients
5. The TypeScript package will automatically include the new services with full type safety
6. Publish a new version of the npm package by creating a GitHub release

## Package Structure

[Section titled “Package Structure”](#package-structure)

The published npm package includes:

* **ESM build** (`dist/esm/`) - ES modules for modern bundlers
* **CJS build** (`dist/cjs/`) - CommonJS for Node.js compatibility
* **Type definitions** (`dist/types/`) - TypeScript .d.ts files for IntelliSense
* **Source maps** - For debugging support
* **README.md** - Package documentation

## Dependencies

[Section titled “Dependencies”](#dependencies)

The TypeScript package has the following runtime dependencies:

* `@grpc/grpc-js` - gRPC client for Node.js
* `@grpc/proto-loader` - Protocol buffer loading (for metadata)

Development dependencies include:

* `ts-proto` - TypeScript code generation from proto files
* `typescript` - TypeScript compiler
* `rollup` - Module bundler for builds
* Various Rollup plugins for TypeScript and module resolution

# The Value Contract

Every Chronicle client — C#, TypeScript, Kotlin, Java, Elixir — writes and reads the same values over the same wire. The kernel does not adapt to the client that happens to be calling it, so the client is what has to agree.

This page is that agreement. It is deliberately short: the contract is small, and the reason it is written down is that until now it was not, which is how a client comes to diverge from it without anyone noticing.

## What has to agree

[Section titled “What has to agree”](#what-has-to-agree)

Only what crosses the wire. That is a much smaller set than what a client library contains — dependency injection, task scheduling, reactive plumbing and type discovery are host concerns that never leave the process, and no two clients should be expected to solve them the same way.

### Values

[Section titled “Values”](#values)

| Value                      | Form on the wire                          | Example                                            |
| -------------------------- | ----------------------------------------- | -------------------------------------------------- |
| Guid / UUID                | canonical string                          | `4db8c897-b236-43a7-9d16-ea95a0742e03`             |
| Date, no time              | ISO-8601 `yyyy-MM-dd`                     | `2026-08-06`                                       |
| Time, no date              | `HH:mm`, `HH:mm:ss` or `HH:mm:ss.fffffff` | `14:30:00`                                         |
| Duration                   | `[-][d.]hh:mm:ss[.fffffff]`               | `1.02:30:00`                                       |
| Point, LineString, Polygon | GeoJSON                                   | `{ "type": "Point", "coordinates": [10.7, 59.9] }` |

The duration form is .NET’s, not ISO-8601. That is a deliberate choice the other clients inherit rather than a leak — every client has to parse and emit it, whatever its own language would prefer.

### Concepts

[Section titled “Concepts”](#concepts)

A concept — a strongly-typed wrapper over a primitive — serializes as **the primitive it wraps**, with no envelope. `CustomerId("4db8c897-…")` is written as the string, not as `{ "value": "4db8c897-…" }`.

This is what makes a concept free at the boundary: adding one to a domain model does not change a single byte of what the kernel stores or what another client reads.

Whether a language expresses concepts through a generic base class (C#), an inline value class (Kotlin), or a plain wrapper is a matter for that language. The serialized form is not.

### Derived types

[Section titled “Derived types”](#derived-types)

When a property is declared as a base type and holds a derived one, the concrete type is named by a `_derivedTypeId` property carrying that type’s declared identifier.

Both stacks that implement it today agree on the name — `DerivedTypeJsonConverter.DerivedTypeIdProperty` in .NET and `JsonSerializer.DerivedTypeIdProperty` in TypeScript are both `"_derivedTypeId"`. A client adding derived-type support uses that name.

> `_t` is **not** this. It is MongoDB’s own discriminator, written by the kernel’s storage layer, and no client ever sees it. The two are easy to confuse and mean different things.

### Event type schemas

[Section titled “Event type schemas”](#event-type-schemas)

An event type is registered with a JSON Schema describing its properties. Two things about it are contract rather than convenience:

* **Property names are verbatim.** The kernel matches a schema property to a payload key by exact name first, then case-insensitively. A client that renames properties on the way out — camel-casing them, say — must apply the same naming to both the schema and the payload, or the two stop agreeing.
* **A schema with no properties is not the same as no schema.** The converter falls back to raw conversion when a schema declares nothing, so an empty schema does not corrupt reads — but the event type registers with no properties, and every tool that reads the registry shows it as empty. Registering `{}` is a bug, not a degraded mode.

## What deliberately does not have to agree

[Section titled “What deliberately does not have to agree”](#what-deliberately-does-not-have-to-agree)

* **How a client discovers artifacts.** Attribute scanning, annotation processing, explicit registration — all fine. The kernel sees the result, not the mechanism.
* **How a client models identity, options, logging, or lifetime.** Idiomatic beats uniform.
* **Whether a client implements a capability at all.** A client may lag; see [Contributing to Clients](/chronicle/contributing/clients/) for how an unsupported capability is stated so the claim cannot rot.

## Why there is no per-language Fundamentals package

[Section titled “Why there is no per-language Fundamentals package”](#why-there-is-no-per-language-fundamentals-package)

Chronicle’s `Cratis.Fundamentals` exists for .NET, and `@cratis/fundamentals` for TypeScript. There is no Kotlin or Elixir equivalent, and that is a decision rather than an omission.

The two that exist are not the same library in two languages. The .NET one carries nineteen areas, most of them host concerns; the TypeScript one carries about six, and they are exactly the ones on this page. The TypeScript package is not a port — it is this contract, expressed once for a stack that also needed it.

A third would be justified by a second consumer in that language. Today `Chronicle.Kotlin` is the only Kotlin consumer and there is no Arc for the JVM, so a shared package would have one caller, one release cadence to keep in step, and no second implementation to keep honest. Kotlin’s inline value classes already give it concepts more cheaply than a library could.

The rule: **extract when a second consumer appears in that language, not before.** Until then a client keeps its own implementation, internal to itself, and conforms to this page.

That is only safe if conformance is checked rather than assumed, which is what this page exists to make possible — and what a conformance suite, run by each client against a real kernel, would make automatic.

# Running Integration Tests

Integration tests run from the `Integration/Client` project and can execute in either in-process or out-of-process mode. They require Docker to be running on your machine and a short manual wait between consecutive runs so Docker has time to tear down and release the fixed MongoDB port.

When you provide no runtime arguments, the suite defaults to:

* mode: `outofprocess`
* database: `mongodb`

## Prerequisites

[Section titled “Prerequisites”](#prerequisites)

* Docker running locally
* .NET SDK (version matches `global.json`)
* Built binaries — run `dotnet build` from the repository root before running tests for the first time, or after any source change

## Test Suites

[Section titled “Test Suites”](#test-suites)

| Suite                | Project              | Description                                                                                                                                                 |
| -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client               | `Integration/Client` | Runs the shared .NET integration specifications in either `inprocess` or `outofprocess` mode, with runtime storage selected through command-line arguments. |
| API (out-of-process) | `Integration/Api`    | Runs a full Chronicle server via Docker and tests the HTTP/gRPC client against it.                                                                          |

## Running the Tests

[Section titled “Running the Tests”](#running-the-tests)

### From the command line

[Section titled “From the command line”](#from-the-command-line)

Run all tests in a suite with the convenience scripts at the root of each project:

```bash
# Release build (CI default)
cd Integration/Client
./run.sh

# Debug build (faster iteration locally)
./run-debug.sh
```

Or invoke `dotnet test` directly from the repository root:

```bash
dotnet test Integration/Client/Client.csproj \
    --logger "console;verbosity=normal" \
    --configuration Release \
    --framework net10.0 \
    -- inprocess mongodb
```

### Runtime and database configurations (CLI)

[Section titled “Runtime and database configurations (CLI)”](#runtime-and-database-configurations-cli)

The first positional argument after `--` is the mode, and the second is the database:

```bash
dotnet test Integration/Client/Client.csproj -- outofprocess mongodb
dotnet test Integration/Client/Client.csproj -- outofprocess postgresql
dotnet test Integration/Client/Client.csproj -- outofprocess mssql
dotnet test Integration/Client/Client.csproj -- outofprocess sqlite
dotnet test Integration/Client/Client.csproj -- inprocess mongodb
```

Named arguments are also supported:

```bash
dotnet test Integration/Client/Client.csproj -- --mode=outofprocess --database=postgresql
dotnet test Integration/Client/Client.csproj -- --mode=inprocess --db=mongodb
```

Alternatively, configure via environment variables or `--environment` flags:

```bash
dotnet test Integration/Client/Client.csproj --environment CHRONICLE_RUNTIME_MODE=inprocess
CHRONICLE_RUNTIME_MODE=inprocess dotnet test Integration/Client/Client.csproj
```

For PostgreSQL and MsSql, set connection details before running tests. The values below are examples only — replace credentials and hosts with values from your local environment:

```bash
export CHRONICLE_POSTGRESQL_CONNECTION_DETAILS="Host=localhost;Port=5432;Database=chronicle;Username=postgres;Password=postgres"
export CHRONICLE_MSSQL_CONNECTION_DETAILS="Server=localhost,1433;Database=chronicle;User Id=sa;Password=Your_password123;TrustServerCertificate=true"
```

For SQLite, you can optionally set:

```bash
export CHRONICLE_SQLITE_CONNECTION_DETAILS="Data Source=/tmp/chronicle.db"
```

### Running a single test

[Section titled “Running a single test”](#running-a-single-test)

Use `--filter` with the fully qualified type name or a substring of it:

```bash
dotnet test Integration/Client/Client.csproj \
    --filter "FullyQualifiedName~for_EventSequence.when_appending.an_event" \
    --no-build \
    -- outofprocess mongodb
```

### From VS Code

[Section titled “From VS Code”](#from-vs-code)

You can run the same configurations from VS Code by creating a dedicated test launch configuration in `.vscode/launch.json`:

```json
{
  "name": ".NET Test (Client integration - outofprocess mongodb)",
  "type": "coreclr",
  "request": "launch",
  "program": "dotnet",
  "args": [
    "test",
    "${workspaceFolder}/Integration/Client/Client.csproj",
    "--framework",
    "net10.0",
    "--configuration",
    "Debug",
    "--",
    "outofprocess",
    "mongodb"
  ],
  "cwd": "${workspaceFolder}",
  "console": "integratedTerminal"
}
```

For in-process mode, change the last two arguments to `"inprocess"` and `"mongodb"`.

For database changes in out-of-process mode, set the second argument to `"postgresql"`, `"mssql"`, or `"sqlite"`.

## Important: Wait Between Consecutive Runs

[Section titled “Important: Wait Between Consecutive Runs”](#important-wait-between-consecutive-runs)

The MongoDB container binds to a fixed host port (`27018`). After a test run ends, Docker’s Ryuk reaper removes the container, but the port is not immediately available. If you start a second run before the port is released, the Docker startup will hang until it times out.

**Always wait a few seconds between runs** when re-running tests manually. In CI, each run starts a fresh agent so this is not a concern.

## Test Backups

[Section titled “Test Backups”](#test-backups)

Each test collection automatically takes a MongoDB backup at the end of a run when the backup feature is enabled. Backups are useful for inspecting the state left by a failing test.

### Enabling backups

[Section titled “Enabling backups”](#enabling-backups)

Set the `CHRONICLE_BACKUP_ENABLED` environment variable to `true` before running tests:

```bash
CHRONICLE_BACKUP_ENABLED=true dotnet test Integration/Client/Client.csproj \
    --environment CHRONICLE_RUNTIME_MODE=inprocess \
    --environment CHRONICLE_STORAGE_PROVIDER=mongodb
```

### Where backups are stored

[Section titled “Where backups are stored”](#where-backups-are-stored)

Backups are written to a `backups/` directory that sits alongside the compiled test binary. For a Debug build targeting `net10.0`, that path is:

```bash
Integration/Client/bin/Debug/net10.0/backups/
```

The directory is created automatically during fixture initialization — you do not need to create it yourself.

### Backup file naming

[Section titled “Backup file naming”](#backup-file-naming)

Each backup file is a gzip-compressed MongoDB archive dump with the following naming pattern:

```bash
{prefix}-yyyyMMdd-HHmmss.tgz
```

The prefix corresponds to the xUnit collection name registered for the test suite. When no prefix is set the timestamp is used alone:

```bash
20260412-143025.tgz
```

### Inspecting a backup

[Section titled “Inspecting a backup”](#inspecting-a-backup)

Restore a backup to a local `mongod` instance to inspect the data:

```bash
mongorestore --gzip --archive=backups/20260412-143025.tgz
```

# Kernel

| Topic                                                  | Description                               |
| ------------------------------------------------------ | ----------------------------------------- |
| [Contracts](/chronicle/contributing/kernel/contracts/) | What are contracts - the Kernel protocol. |
| [Services](/chronicle/contributing/kernel/services/)   | Working with services.                    |

# Contracts

The Contracts project contains all gRPC definitions for data and services, representing the complete protocol of the **Kernel**. Contracts are defined as C# types: data is represented using classes, and services as interfaces.

We use [protobuf-net.Grpc](https://github.com/protobuf-net/protobuf-net.Grpc) to enable a *code-first* approach to defining protobuf contracts.

The implementation of these contracts resides in the **Kernel**. For more details, see the [services documentation](/chronicle/contributing/kernel/services/).

## Attributes

[Section titled “Attributes”](#attributes)

[protobuf-net.Grpc](https://github.com/protobuf-net/protobuf-net.Grpc) supports defining contracts using annotations from `System.ServiceModel` as well as those from `Protobuf` and `Protobuf.Grpc`. We use the latter.

For data types, decorate the class with `[ProtoContract]` and each property with `[ProtoMember(<id>)]`, where **id** is a sequential number indicating the field’s position in the contract.

Example:

* C#

```csharp
  using ProtoBuf;
  using ProtoBuf.Grpc;

[ProtoContract]
  public class ContributingKernelAppendRequest
  {
      [ProtoMember(1)]
      public string EventStore { get; set; } = string.Empty;

[ProtoMember(2)]
      public string Namespace { get; set; } = string.Empty;

[ProtoMember(3)]
      public string EventSequenceId { get; set; } = string.Empty;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Always add new properties at the end, without reordering existing ones.

For service contracts, use the `[Service]` and `[Operation]` attributes.

Example:

* C#

```csharp
  using ProtoBuf.Grpc;
  using ProtoBuf.Grpc.Configuration;

[Service]
  public interface IContributingKernelEventSequences
  {
      /// <summary>
      /// Append an event to an event sequence.
      /// </summary>
      /// <param name="request">The <see cref="ContributingKernelAppendRequest"/>.</param>
      /// <param name="context">gRPC call context.</param>
      /// <returns>The response.</returns>
      [Operation]
      Task<ContributingKernelAppendResponse> Append(ContributingKernelAppendRequest request, CallContext context = default);
  }

public class ContributingKernelAppendResponse
  {
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Streaming APIs

[Section titled “Streaming APIs”](#streaming-apis)

Some APIs require streaming data from client to server, server to client, or both. We use the `System.Reactive` type `IObservable<>` for streaming, as it is intuitive, consistent with our implementation, and provides expressive power through the fluent interfaces of `System.Reactive`.

Example:

* C#

```csharp
  using ProtoBuf;
  using ProtoBuf.Grpc;
  using ProtoBuf.Grpc.Configuration;

[ProtoContract]
  public class ContributingKernelReactorMessage
  {
      [ProtoMember(1)]
      public string Content { get; set; } = string.Empty;
  }

[ProtoContract]
  public class ContributingKernelEventsToObserve
  {
      [ProtoMember(1)]
      public string EventType { get; set; } = string.Empty;
  }

[Service]
  public interface IContributingKernelReactors
  {
      [Operation]
      IObservable<ContributingKernelEventsToObserve> Observe(IObservable<ContributingKernelReactorMessage> messages, CallContext context = default);
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## SerializableDateTimeOffset

[Section titled “SerializableDateTimeOffset”](#serializabledatetimeoffset)

Protobuf does not natively support `DateTimeOffset`, so we provide `SerializableDateTimeOffset` in the `Contracts.Primitives` namespace. This type serializes a `DateTimeOffset` as an ISO 8601 string (round-trip format `"O"`, e.g. `"2024-01-15T12:30:00.0000000+02:00"`), which is protobuf-compatible.

`SerializableDateTimeOffset` provides implicit conversion operators to and from `DateTimeOffset`, making it transparent to use in your code.

**Always use `SerializableDateTimeOffset` instead of `DateTimeOffset` in contract definitions.**

Example:

* C#

```csharp
  using ProtoBuf;
  using Cratis.Chronicle.Contracts.Primitives;

[ProtoContract]
  public class ContributingKernelUser
  {
      [ProtoMember(1)]
      public string Username { get; set; } = string.Empty;

[ProtoMember(2)]
      public SerializableDateTimeOffset CreatedAt { get; set; } = new();

[ProtoMember(3)]
      public SerializableDateTimeOffset? LastModifiedAt { get; set; }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The implicit conversions allow natural usage:

* C#

```csharp
  public static class ContributingKernelDateTimeOffsetUsage
  {
      public static void Run()
      {
          var user = new ContributingKernelUser
          {
              Username = "john",
              CreatedAt = DateTimeOffset.UtcNow  // Implicit conversion from DateTimeOffset
          };

DateTimeOffset created = user.CreatedAt;  // Implicit conversion to DateTimeOffset
          Console.WriteLine(created);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## OneOf

[Section titled “OneOf”](#oneof)

When you need a contract property that can hold one of several different types (a discriminated union), use the `OneOf<T0, T1, ...>` generic types from the `Contracts.Primitives` namespace. These support 2, 3, or 4 type parameters.

Each `OneOf` instance stores the value in one of its `Value0`, `Value1`, etc. properties, with the others set to `null`. The `Value` property returns whichever value is set, or throws `NoValueSetForOneOf` if none are set.

Example with a service returning either a result or an error:

* C#

```csharp
  using ProtoBuf;
  using ProtoBuf.Grpc;
  using ProtoBuf.Grpc.Configuration;
  using Cratis.Chronicle.Contracts.Primitives;

[ProtoContract]
  public class ContributingKernelGetJobRequest
  {
      [ProtoMember(1)]
      public string JobId { get; set; } = string.Empty;
  }

[ProtoContract]
  public class ContributingKernelJob
  {
      [ProtoMember(1)]
      public string Id { get; set; } = string.Empty;
  }

[ProtoContract]
  public class ContributingKernelJobError
  {
      [ProtoMember(1)]
      public string Message { get; set; } = string.Empty;
  }

[Service]
  public interface IContributingKernelJobs
  {
      [Operation]
      Task<OneOf<ContributingKernelJob, ContributingKernelJobError>> GetJob(ContributingKernelGetJobRequest request, CallContext context = default);
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Example with a message containing different content types:

* C#

```csharp
  using ProtoBuf;
  using Cratis.Chronicle.Contracts.Primitives;

[ProtoContract]
  public class ContributingKernelRegisterReactor
  {
      [ProtoMember(1)]
      public string ReactorId { get; set; } = string.Empty;
  }

[ProtoContract]
  public class ContributingKernelReactorResult
  {
      [ProtoMember(1)]
      public bool Success { get; set; }
  }

[ProtoContract]
  public class ContributingKernelReactorOneOfMessage
  {
      [ProtoMember(1)]
      public OneOf<ContributingKernelRegisterReactor, ContributingKernelReactorResult> Content { get; set; } = new();
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Usage on the client side:

* C#

```csharp
  public static class ContributingKernelOneOfUsage
  {
      public static async Task Run(IContributingKernelJobs jobsService, ContributingKernelGetJobRequest request)
      {
          var result = await jobsService.GetJob(request);

if (result.Value0 is not null)
          {
              // Handle Job
              var job = result.Value0;
              Console.WriteLine($"Job: {job.Id}");
          }
          else if (result.Value1 is not null)
          {
              // Handle JobError
              var error = result.Value1;
              Console.WriteLine($"Error: {error.Message}");
          }

// Or use the Value property to get whichever is set
          object value = result.Value;
          Console.WriteLine(value);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

# Version Patch System

Chronicle includes a version-based patch system to handle breaking changes during upgrades. Patches are automatically discovered and applied during server startup, ensuring the system state is migrated correctly between versions.

## Overview

[Section titled “Overview”](#overview)

The patch system:

* **Automatically discovers** patches using reflection (`IInstancesOf<ICanApplyPatch>`)
* **Applies patches in order** based on semantic version
* **Tracks applied patches** to prevent re-execution
* **Supports rollback** through `Down()` methods for safe downgrades
* **Runs at startup** before other Chronicle services initialize

## Key Concepts

[Section titled “Key Concepts”](#key-concepts)

### SemanticVersion

[Section titled “SemanticVersion”](#semanticversion)

Patches are tied to semantic versions (e.g., `1.5.0`, `2.0.0-beta.1`). The system compares the current system version with patch versions to determine which patches to apply.

### Patch Lifecycle

[Section titled “Patch Lifecycle”](#patch-lifecycle)

1. **Discovery**: On startup, all `ICanApplyPatch` implementations are discovered
2. **Filtering**: Only patches with versions newer than the current system version are selected
3. **Ordering**: Selected patches are sorted in ascending version order
4. **Application**: Each patch’s `Up()` method is called sequentially
5. **Tracking**: Successfully applied patches are recorded in storage
6. **Version Update**: System version is updated to the latest applied patch version

### Storage

[Section titled “Storage”](#storage)

Patches are tracked in MongoDB:

* **Collection**: `patches` (in system database)
* **Version**: Stored separately as the current system version
* **State**: PatchManager grain maintains state of all applied patches

## Writing a Patch

[Section titled “Writing a Patch”](#writing-a-patch)

### Basic Structure

[Section titled “Basic Structure”](#basic-structure)

Create a patch by implementing `ICanApplyPatch`:

* C#

```csharp
  public class PatchesBasicPatch(IStorage storage, ILogger<PatchesBasicPatch> logger) : ICanApplyPatch
  {
      public SemanticVersion Version => new(1, 5, 0);

public async Task Up()
      {
          logger.LogInformation("Applying PatchesBasicPatch");

var eventStore = storage.GetEventStore(EventStoreName.System);
          var reactors = await eventStore.Reactors.GetAll();
          logger.LogInformation("Found {Count} reactors", reactors.Count());
      }

public Task Down()
      {
          logger.LogInformation("Rolling back PatchesBasicPatch");
          return Task.CompletedTask;
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### Patch Naming Conventions

[Section titled “Patch Naming Conventions”](#patch-naming-conventions)

* **Folder structure**: Organize patches by version in `Source/Kernel/Core/Patches/{version}/`
* **File naming**: Use descriptive names (e.g., `RenameReactors.cs`, `MigrateEventSchema.cs`)
* **Class naming**: Match the file name (the `Name` property is auto-derived from the type name)

### Dependencies

[Section titled “Dependencies”](#dependencies)

Patches can inject any services registered in the DI container:

* C#

```csharp
  public class PatchesComplexPatch(
      IStorage storage,
      IEventTypes eventTypes,
      ILogger<PatchesComplexPatch> logger) : ICanApplyPatch
  {
      public SemanticVersion Version => new(2, 0, 0);

public async Task Up()
      {
          if (await storage.HasEventStore(EventStoreName.System))
          {
              await eventTypes.DiscoverAndRegister(EventStoreName.System);
              logger.LogInformation("Discovered and registered event types");
          }
      }

public Task Down() => Task.CompletedTask;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Best Practices

[Section titled “Best Practices”](#best-practices)

### 1. Semantic Logging

[Section titled “1. Semantic Logging”](#1-semantic-logging)

Use proper semantic logging with `LoggerMessage` attributes:

* C#

```csharp
  internal static partial class PatchesLoggingPatchLogMessages
  {
      [LoggerMessage(LogLevel.Information, "Starting PatchesLoggingPatch migration")]
      internal static partial void StartingMigration(this ILogger<PatchesLoggingPatch> logger);

[LoggerMessage(LogLevel.Information, "Migrated {Count} items")]
      internal static partial void MigratedItems(this ILogger<PatchesLoggingPatch> logger, int count);
  }

public class PatchesLoggingPatch(IStorage storage, ILogger<PatchesLoggingPatch> logger) : ICanApplyPatch
  {
      public SemanticVersion Version => new(1, 6, 0);

public async Task Up()
      {
          logger.StartingMigration();

var count = (await storage.GetEventStores()).Count();
          logger.MigratedItems(count);
      }

public Task Down() => Task.CompletedTask;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### 2. Implement Down() for Safety

[Section titled “2. Implement Down() for Safety”](#2-implement-down-for-safety)

Always implement `Down()` to support rollback scenarios:

* C#

```csharp
  public class PatchesRollbackPatch(ILogger<PatchesRollbackPatch> logger) : ICanApplyPatch
  {
      public SemanticVersion Version => new(1, 7, 0);

public Task Up() => Task.CompletedTask;

public Task Down()
      {
          // Reverse the changes made in Up()
          // This allows safe rollback if needed
          logger.LogInformation("Rolling back PatchesRollbackPatch");
          return Task.CompletedTask;
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### 3. Handle Idempotency

[Section titled “3. Handle Idempotency”](#3-handle-idempotency)

Patches should be idempotent where possible. The system prevents re-execution, but defensive coding helps:

* C#

```csharp
  public class PatchesIdempotentPatch(IStorage storage, ILogger<PatchesIdempotentPatch> logger) : ICanApplyPatch
  {
      public SemanticVersion Version => new(1, 8, 0);

public async Task Up()
      {
          var eventStore = storage.GetEventStore(EventStoreName.System);
          var reactors = await eventStore.Reactors.GetAll();

// Filter to only process items that need migration
          var reactorsToMigrate = reactors
              .Where(r => r.Identifier.Value.Contains("OldPattern"))
              .ToList();

if (reactorsToMigrate.Count == 0)
          {
              logger.LogInformation("Nothing to migrate");
              return;
          }

// Proceed with migration
      }

public Task Down() => Task.CompletedTask;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### 4. Test Thoroughly

[Section titled “4. Test Thoroughly”](#4-test-thoroughly)

Write comprehensive specs for your patches:

* C#

```csharp
  using Cratis.Specifications;
  using NSubstitute;
  using Xunit;

public class when_rolling_back_the_patch : Specification
  {
      readonly ILogger<PatchesRollbackPatch> _logger = Substitute.For<ILogger<PatchesRollbackPatch>>();
      PatchesRollbackPatch _patch = default!;

void Establish() => _patch = new PatchesRollbackPatch(_logger);

Task Because() => _patch.Down();

[Fact] void should_complete_without_throwing() => true.ShouldBeTrue();
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Runtime Behavior

[Section titled “Runtime Behavior”](#runtime-behavior)

### Startup Sequence

[Section titled “Startup Sequence”](#startup-sequence)

1. **Server Initialization**: Chronicle server starts
2. **Patch Discovery**: `PatchManager` grain discovers all `ICanApplyPatch` implementations
3. **Version Check**: Current system version is retrieved from storage
4. **Patch Selection**: Patches newer than current version are selected
5. **Sequential Application**: Patches are applied in ascending version order
6. **Version Update**: System version is updated to latest applied patch
7. **Normal Startup**: Chronicle continues with normal initialization

### Error Handling

[Section titled “Error Handling”](#error-handling)

If a patch fails:

* The exception is logged and re-thrown
* Startup is halted to prevent running with inconsistent state
* Manual intervention is required to fix the issue
* The patch can be fixed and server restarted

### Version Comparison

[Section titled “Version Comparison”](#version-comparison)

Patches are applied based on version comparison:

* **Current: 1.0.0, Patch: 1.5.0** → Patch IS applied
* **Current: 2.0.0, Patch: 1.5.0** → Patch is NOT applied
* **Current: 1.5.0, Patch: 1.5.0** → Patch is NOT applied (equal versions)
* **Current: null, Patch: 1.0.0** → Patch IS applied (treats null as 0.0.0)

## Example: RenameReactors Patch

[Section titled “Example: RenameReactors Patch”](#example-renamereactors-patch)

The `RenameReactors` patch (version 15.3.0) demonstrates a real-world migration:

* C#

```csharp
  internal static partial class RenameReactorsLogMessages
  {
      [LoggerMessage(LogLevel.Information, "Starting patch to rename reactors")]
      internal static partial void StartingPatch(this ILogger<RenameReactors> logger);

[LoggerMessage(LogLevel.Information, "Found {Count} reactors to rename")]
      internal static partial void FoundReactorsToRename(this ILogger<RenameReactors> logger, int count);

[LoggerMessage(LogLevel.Information, "Renaming reactor from {CurrentId} to {NewId}")]
      internal static partial void RenamingReactor(this ILogger<RenameReactors> logger, string currentId, string newId);

[LoggerMessage(LogLevel.Information, "Patch completed")]
      internal static partial void PatchCompleted(this ILogger<RenameReactors> logger);

[LoggerMessage(LogLevel.Information, "Starting rollback")]
      internal static partial void StartingRollback(this ILogger<RenameReactors> logger);

[LoggerMessage(LogLevel.Information, "Rollback completed")]
      internal static partial void RollbackCompleted(this ILogger<RenameReactors> logger);
  }

public class RenameReactors(IStorage storage, ILogger<RenameReactors> logger) : ICanApplyPatch
  {
      public SemanticVersion Version => new(15, 3, 0);

public async Task Up()
      {
          logger.StartingPatch();

var systemEventStore = storage.GetEventStore(EventStoreName.System);
          var reactors = await systemEventStore.Reactors.GetAll();

var reactorsToRename = reactors
              .Where(r => r.Identifier.Value.Contains("Grains", StringComparison.OrdinalIgnoreCase))
              .ToList();

logger.FoundReactorsToRename(reactorsToRename.Count);

foreach (var reactor in reactorsToRename)
          {
              var currentId = reactor.Identifier;
              var newIdValue = currentId.Value.Replace("Grains", string.Empty, StringComparison.OrdinalIgnoreCase);

logger.RenamingReactor(currentId.Value, newIdValue);
              await systemEventStore.Reactors.Rename(currentId, newIdValue);
          }

logger.PatchCompleted();
      }

public Task Down()
      {
          logger.StartingRollback();
          logger.RollbackCompleted();
          return Task.CompletedTask;
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Troubleshooting

[Section titled “Troubleshooting”](#troubleshooting)

### Patch Not Running

[Section titled “Patch Not Running”](#patch-not-running)

1. **Check version**: Ensure patch version is greater than current system version
2. **Check registration**: Verify patch implements `ICanApplyPatch` and is in correct namespace
3. **Check logs**: Look for patch discovery and application logs at startup

### Patch Failing

[Section titled “Patch Failing”](#patch-failing)

1. **Review exception**: Check startup logs for detailed error information
2. **Test locally**: Run patch specs to verify logic
3. **Check storage**: Ensure storage connections are working
4. **Verify state**: Check if system is in expected state before migration

### Need to Re-run Patch

[Section titled “Need to Re-run Patch”](#need-to-re-run-patch)

If you need to re-run a patch (e.g., during development):

1. Remove patch record from `patches` collection in MongoDB
2. Optionally reset system version if needed
3. Restart server

**Warning**: Only do this in development environments. Production systems should use new patch versions.

## Migration from Older Versions

[Section titled “Migration from Older Versions”](#migration-from-older-versions)

When upgrading Chronicle from versions without the patch system:

1. System version defaults to `0.0.0` (or `SemanticVersion.NotSet`)
2. All patches will be discovered and applied in order
3. After successful application, system version is set to latest patch version
4. Future upgrades will only apply newer patches

## Summary

[Section titled “Summary”](#summary)

The patch system provides a robust, automated way to handle breaking changes during Chronicle upgrades. By following the conventions and best practices outlined here, you can write safe, testable patches that keep Chronicle systems properly migrated across versions.

# Services

All gRPC service implementations for our [contracts](/chronicle/contributing/kernel/contracts/) reside in the `Services` project.

These services are owned by the `Kernel` and must remain internal. Every service implementation should be marked as `internal`, since integration testing can host the client and kernel in the same process. This is required by our [internalization](/chronicle/contributing/clients/internalization/) process for client assemblies.

Service implementations are built on top of the Grains exposed by the Kernel.

# PrimeUI License

The Workbench frontend is built on [Cratis Components](https://github.com/Cratis/Components), which in turn builds on PrimeReact. From version 11, PrimeReact is PrimeTek’s commercially licensed **PrimeUI** rather than the MIT-licensed library version 10 was. It verifies a license key when its provider mounts, and without one it logs a warning and renders an *“Invalid PrimeUI License”* banner over the application — in development and production alike, whatever the styling configuration.

Cratis is open source and qualifies for the free **Community** tier. The terms and the eligibility rules are at [primeui.dev/licenses/community](https://primeui.dev/licenses/community).

## Contributing without a key

[Section titled “Contributing without a key”](#contributing-without-a-key)

**You do not need a license key to contribute.** Everything builds, every spec runs, and the Workbench is fully usable — the banner is the only difference. Pull requests from forks build without one, because GitHub does not expose repository secrets to fork builds.

The banner is deliberately not suppressed. Hiding it would make a licensing problem invisible rather than absent, and an unlicensed build is exactly the thing a contributor should be able to see at a glance.

## Supplying a key

[Section titled “Supplying a key”](#supplying-a-key)

The key is read from the environment as `PRIMEUI_LICENSE`. It is configuration, not source: it differs between machines and builds, and it must never be committed.

Vite reads the **process environment** as well as `.env` files, so either of these works:

```bash
# A shell profile - one export serves every Cratis application on the machine
export PRIMEUI_LICENSE=your-key-here
```

```bash
# Or per-repository, in Source/Workbench/.env (git-ignored; see .env.example)
PRIMEUI_LICENSE=your-key-here
```

The variable keeps PrimeTek’s own name rather than a Chronicle-specific one, so a single value covers this repository, Studio, and any other Cratis application you have checked out. `Source/Workbench/.frontend` exposes both the `CHRONICLE_` and `PRIMEUI_` prefixes to the bundle for exactly this reason.

Restart the dev server after setting it — Vite reads the environment at startup.

## How it reaches the application

[Section titled “How it reaches the application”](#how-it-reaches-the-application)

| Piece                                                                                                                       | Role                                                        |
| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [`vite.config.ts`](https://github.com/Cratis/Chronicle/blob/main/Source/Workbench/.frontend/vite.config.ts)                 | Exposes the `PRIMEUI_` prefix alongside `CHRONICLE_`        |
| [`primeUiLicense.ts`](https://github.com/Cratis/Chronicle/blob/main/Source/Workbench/.frontend/primeUiLicense.ts)           | The single accessor; resolves an empty value to `undefined` |
| [`index.tsx`](https://github.com/Cratis/Chronicle/blob/main/Source/Workbench/.frontend/index.tsx)                           | Passes it to `CratisComponentsProvider`                     |
| [`.storybook/preview.tsx`](https://github.com/Cratis/Chronicle/blob/main/Source/Workbench/.frontend/.storybook/preview.tsx) | The same, so Storybook renders unbannered too               |
| [`vite-env.d.ts`](https://github.com/Cratis/Chronicle/blob/main/Source/Workbench/.frontend/vite-env.d.ts)                   | Types it, so it is discoverable rather than a magic string  |

## Continuous integration

[Section titled “Continuous integration”](#continuous-integration)

Both the pull-request build and the release build pass the key from a repository secret, also named `PRIMEUI_LICENSE`. Because the environment variable and the secret share a name, no per-workflow translation is involved:

```yaml
env:
    PRIMEUI_LICENSE: ${{ secrets.PRIMEUI_LICENSE }}
```

It is set in [`workbench-build.yml`](https://github.com/Cratis/Chronicle/blob/main/.github/workflows/workbench-build.yml) and [`publish.yml`](https://github.com/Cratis/Chronicle/blob/main/.github/workflows/publish.yml). A fork’s pull request builds with it unset, which is a supported outcome rather than a failure.

# Dynamic Consistency Boundary

A Dynamic Consistency Boundary (DCB) defines the minimal set of information that must be consistent to make a decision. The boundary is determined at runtime by the data a command actually uses, rather than by a fixed aggregate or transactional scope. This keeps decisions correct while allowing the rest of the system to remain eventually consistent and independently evolving.

## Core idea

[Section titled “Core idea”](#core-idea)

* Consistency is scoped to the facts used to decide a change.
* The boundary can cross multiple event streams and read models.
* Events can still be appended independently once the decision is made.

## How it works in practice

[Section titled “How it works in practice”](#how-it-works-in-practice)

1. Load the facts needed to decide.
2. Derive a boundary that represents those facts.
3. Enforce consistency for that boundary only.
4. Append new events and let read models catch up.

```
Command

Load decision facts

Derive consistency boundary

Validate and decide

Append events

Project read models
```

## Why it matters

[Section titled “Why it matters”](#why-it-matters)

A fixed aggregate boundary often forces unrelated data into a single consistency scope. DCB keeps correctness while avoiding unnecessary coupling. It improves throughput, reduces contention, and keeps models aligned with actual decision rules.

## References

[Section titled “References”](#references)

* <https://dcb.events>
* <https://www.eventsourcing.dev/best-practices/dynamic-consistency-boundaries>

# Dynamic Consistency Boundary in Chronicle

Chronicle was designed to support decision-scoped consistency long before DCB was named. You can append events independently, project read models from disparate streams, and still enforce consistency for the specific facts used to decide.

## Mapping DCB to Chronicle

[Section titled “Mapping DCB to Chronicle”](#mapping-dcb-to-chronicle)

* Decision facts are read from projections or other read models.
* Constraints validate that the decision is still valid when appending events.
* Concurrency scopes let you define which streams or partitions must be checked together.
* Projections update read models asynchronously after the append.

```
Client command

Read models

Decide and build constraints

Append events

Event store

Projections

Concurrency scopes
```

## Constraints and concurrency scopes

[Section titled “Constraints and concurrency scopes”](#constraints-and-concurrency-scopes)

Constraints are the primary way to express decision correctness. They are evaluated at append time, so the decision is validated against the most recent events. Concurrency scopes complement this by defining which streams must be checked together to keep the decision consistent without forcing a single aggregate boundary.

## Metadata tags

[Section titled “Metadata tags”](#metadata-tags)

Chronicle uses formalized metadata tags to scope concurrency control. These tags are indexed and used by Chronicle when evaluating concurrency scopes:

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

For more details, see [Formalized metadata tags for concurrency](/chronicle/events/concurrency/#formalized-metadata-tags-for-concurrency).

You can also attach [custom tags](/chronicle/events/appending-with-tags/#custom-tags) to events when appending for categorization and filtering purposes.

## Aggregate roots

[Section titled “Aggregate roots”](#aggregate-roots)

If you prefer an aggregate root style, Chronicle supports it through Cratis.Arc. See aggregate roots support.

## Arc command validation flow

[Section titled “Arc command validation flow”](#arc-command-validation-flow)

When using Arc, command validation runs before decision evaluation. See Arc validation for details.

```
Client command

Arc command validation

Read models

Decide and build constraints

Append events

Event store

Projections

Concurrency scopes
```

## Practical flow

[Section titled “Practical flow”](#practical-flow)

1. Read the projections needed to decide.
2. Build constraints that capture the decision rule.
3. Choose concurrency scopes that match the decision boundary.
4. Append events and let projections update.

## Next steps

[Section titled “Next steps”](#next-steps)

* [Constraints](/chronicle/constraints/)
* [Appending events](/chronicle/events/appending/)
* [Appending with tags](/chronicle/events/appending-with-tags/)
* [Concurrency scopes](/chronicle/events/concurrency/)
* [Projections](/chronicle/projections/)

## Related resources

[Section titled “Related resources”](#related-resources)

* <https://github.com/bwaidelich/dcb-example-courses>

# Event Seeding

Event seeding is a Chronicle Server capability that lets you provide a predefined set of events when the event store connects. It is useful when you need your deployment to include baseline data that the system depends on, or when you want developers to start from a known state with ready-to-use test data.

## Why seed events

[Section titled “Why seed events”](#why-seed-events)

* Ensure required domain data exists the first time a system starts in a new environment.
* Bootstrap development and testing with realistic data after clearing the event store.
* Provide a repeatable, versioned starting point for demos and CI environments.

## When to use it

[Section titled “When to use it”](#when-to-use-it)

Use event seeding when you need deterministic, append-only data to be part of the system from the beginning. Chronicle tracks seeded events so it is safe to start applications multiple times without duplicating data.

## Next steps

[Section titled “Next steps”](#next-steps)

* [Seeding with C Sharp](/chronicle/event-seeding/seeding-with-csharp/)
* [Seeding with Kotlin](/chronicle/clients/kotlin/guides/seeding/)
* [Seeding with Elixir](/chronicle/clients/elixir/seeding/)
* [Seeding with TypeScript](/chronicle/clients/typescript/seeding/)

# Seeding with C Sharp

This page shows how to seed events using the Chronicle .NET client. Seeding is sent to the Chronicle Server when the event store connects, and the server applies it once per namespace.

## Define events

[Section titled “Define events”](#define-events)

Use `record` types for event definitions in examples:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record EvtSeedingUserRegistered(string Email, string DisplayName);

[EventType]
  public record EvtSeedingEmailVerified(string Email);

[EventType]
  public record EvtSeedingProfileUpdated(string DisplayName);

[EventType]
  public record EvtSeedingOrderPlaced(string UserId, decimal Amount);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class EvtSeedingUserRegistered(val email: String, val displayName: String)

@EventType
  data class EvtSeedingEmailVerified(val email: String)

@EventType
  data class EvtSeedingProfileUpdated(val displayName: String)

@EventType
  data class EvtSeedingOrderPlaced(val userId: String, val amount: Double)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record EvtSeedingUserRegistered(String email, String displayName) {}

@EventType
  record EvtSeedingEmailVerified(String email) {}

@EventType
  record EvtSeedingProfileUpdated(String displayName) {}

@EventType
  record EvtSeedingOrderPlaced(String userId, double amount) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EvtSeedingUserRegistered do
    use Chronicle.Events.EventType, id: "evt-seeding-user-registered"

defstruct [:email, :display_name]
  end

defmodule MyApp.Events.EvtSeedingEmailVerified do
    use Chronicle.Events.EventType, id: "evt-seeding-email-verified"

defstruct [:email]
  end

defmodule MyApp.Events.EvtSeedingProfileUpdated do
    use Chronicle.Events.EventType, id: "evt-seeding-profile-updated"

defstruct [:display_name]
  end

defmodule MyApp.Events.EvtSeedingOrderPlaced do
    use Chronicle.Events.EventType, id: "evt-seeding-order-placed"

defstruct [:user_id, :amount]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class EvtSeedingUserRegistered {
      constructor(readonly email: string, readonly displayName: string) {}
  }

@eventType()
  class EvtSeedingEmailVerified {
      constructor(readonly email: string) {}
  }

@eventType()
  class EvtSeedingProfileUpdated {
      constructor(readonly displayName: string) {}
  }

@eventType()
  class EvtSeedingOrderPlaced {
      constructor(readonly userId: string, readonly amount: number) {}
  }
  ```

## Implement a seeder

[Section titled “Implement a seeder”](#implement-a-seeder)

Implement `ICanSeedEvents` and use `IEventSeedingBuilder` to define events to append:

* C#

```csharp
  using Cratis.Chronicle.Seeding;

public sealed class EvtSeedingUserSeeding : ICanSeedEvents
  {
      public void Seed(IEventSeedingBuilder builder)
      {
          builder
              .For<EvtSeedingUserRegistered>("user-123", [
                  new("john@example.com", "John")
              ])
              .ForEventSource("user-456", [
                  new EvtSeedingUserRegistered("jane@example.com", "Jane"),
                  new EvtSeedingEmailVerified("jane@example.com")
              ]);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.seeding.ICanSeedEvents
  import io.cratis.chronicle.seeding.IEventSeedingBuilder
  import io.cratis.chronicle.seeding.Seeder

@Seeder
  class EvtSeedingUserSeeding : ICanSeedEvents {
      override fun seed(builder: IEventSeedingBuilder) {
          builder
              .forEventType(
                  EvtSeedingUserRegistered::class,
                  "user-123",
                  listOf(EvtSeedingUserRegistered("john@example.com", "John"))
              )
              .forEventSource(
                  "user-456",
                  listOf(
                      EvtSeedingUserRegistered("jane@example.com", "Jane"),
                      EvtSeedingEmailVerified("jane@example.com")
                  )
              )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.seeding.ICanSeedEvents;
  import io.cratis.chronicle.seeding.IEventSeedingBuilder;
  import io.cratis.chronicle.seeding.Seeder;

import io.cratis.chronicle.java.EventSeedingBuilderJavaBridge;

import java.util.List;

@Seeder
  class EvtSeedingUserSeeding implements ICanSeedEvents {
      @Override
      public void seed(IEventSeedingBuilder builder) {
          EventSeedingBuilderJavaBridge.forEventType(
              builder,
              EvtSeedingUserRegistered.class,
              "user-123",
              List.of(new EvtSeedingUserRegistered("john@example.com", "John")));

builder.forEventSource(
              "user-456",
              List.of(
                  new EvtSeedingUserRegistered("jane@example.com", "Jane"),
                  new EvtSeedingEmailVerified("jane@example.com")));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EvtSeedingSeederUserRegistered do
    use Chronicle.Events.EventType, id: "evt-seeding-seeder-user-registered"

defstruct [:email, :display_name]
  end

defmodule MyApp.Events.EvtSeedingSeederEmailVerified do
    use Chronicle.Events.EventType, id: "evt-seeding-seeder-email-verified"

defstruct [:email]
  end

defmodule MyApp.Seeders.EvtSeedingUserSeeding do
    use Chronicle.Seeding.Seeder

alias MyApp.Events.{EvtSeedingSeederEmailVerified, EvtSeedingSeederUserRegistered}

@impl true
    def seed(builder) do
      builder
      |> Chronicle.Seeding.for(EvtSeedingSeederUserRegistered, "user-123", [
        %EvtSeedingSeederUserRegistered{email: "john@example.com", display_name: "John"}
      ])
      |> Chronicle.Seeding.for_event_source("user-456", [
        %EvtSeedingSeederUserRegistered{email: "jane@example.com", display_name: "Jane"},
        %EvtSeedingSeederEmailVerified{email: "jane@example.com"}
      ])
    end
  end
  ```

* TypeScript

```typescript
  import { ICanSeedEvents, IEventSeedingBuilder, seeder } from '@cratis/chronicle';

@seeder()
  class EvtSeedingUserSeeding implements ICanSeedEvents {
      seed(builder: IEventSeedingBuilder): void {
          builder
              .for('user-123', [new EvtSeedingUserRegistered('john@example.com', 'John')])
              .forEventSource('user-456', [
                  new EvtSeedingUserRegistered('jane@example.com', 'Jane'),
                  new EvtSeedingEmailVerified('jane@example.com')
              ]);
      }
  }
  ```

## Seed multiple events of the same type

[Section titled “Seed multiple events of the same type”](#seed-multiple-events-of-the-same-type)

* C#

```csharp
  using Cratis.Chronicle.Seeding;

public sealed class EvtSeedingMultipleSameTypeSeeding : ICanSeedEvents
  {
      public void Seed(IEventSeedingBuilder builder)
      {
          builder.For<EvtSeedingUserRegistered>("user-123", [
              new("john@example.com", "John"),
              new("jane@example.com", "Jane")
          ]);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.seeding.ICanSeedEvents
  import io.cratis.chronicle.seeding.IEventSeedingBuilder
  import io.cratis.chronicle.seeding.Seeder

@Seeder
  class EvtSeedingMultipleSameTypeSeeding : ICanSeedEvents {
      override fun seed(builder: IEventSeedingBuilder) {
          builder.forEventType(
              EvtSeedingUserRegistered::class,
              "user-123",
              listOf(
                  EvtSeedingUserRegistered("john@example.com", "John"),
                  EvtSeedingUserRegistered("jane@example.com", "Jane")
              )
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.seeding.ICanSeedEvents;
  import io.cratis.chronicle.seeding.IEventSeedingBuilder;
  import io.cratis.chronicle.seeding.Seeder;

import io.cratis.chronicle.java.EventSeedingBuilderJavaBridge;

import java.util.List;

@Seeder
  class EvtSeedingMultipleSameTypeSeeding implements ICanSeedEvents {
      @Override
      public void seed(IEventSeedingBuilder builder) {
          EventSeedingBuilderJavaBridge.forEventType(
              builder,
              EvtSeedingUserRegistered.class,
              "user-123",
              List.of(
                  new EvtSeedingUserRegistered("john@example.com", "John"),
                  new EvtSeedingUserRegistered("jane@example.com", "Jane")));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EvtSeedingMultiSameTypeUserRegistered do
    use Chronicle.Events.EventType, id: "evt-seeding-multi-same-type-user-registered"

defstruct [:email, :display_name]
  end

defmodule MyApp.Seeders.EvtSeedingMultipleSameTypeSeeding do
    use Chronicle.Seeding.Seeder

alias MyApp.Events.EvtSeedingMultiSameTypeUserRegistered

@impl true
    def seed(builder) do
      Chronicle.Seeding.for(builder, EvtSeedingMultiSameTypeUserRegistered, "user-123", [
        %EvtSeedingMultiSameTypeUserRegistered{email: "john@example.com", display_name: "John"},
        %EvtSeedingMultiSameTypeUserRegistered{email: "jane@example.com", display_name: "Jane"}
      ])
    end
  end
  ```

* TypeScript

```typescript
  import { ICanSeedEvents, IEventSeedingBuilder, seeder } from '@cratis/chronicle';

@seeder()
  class EvtSeedingMultipleSameTypeSeeding implements ICanSeedEvents {
      seed(builder: IEventSeedingBuilder): void {
          builder.for('user-123', [
              new EvtSeedingUserRegistered('john@example.com', 'John'),
              new EvtSeedingUserRegistered('jane@example.com', 'Jane')
          ]);
      }
  }
  ```

## Seed mixed event types

[Section titled “Seed mixed event types”](#seed-mixed-event-types)

* C#

```csharp
  using Cratis.Chronicle.Seeding;

public sealed class EvtSeedingMixedTypesSeeding : ICanSeedEvents
  {
      public void Seed(IEventSeedingBuilder builder)
      {
          builder.ForEventSource("user-123", [
              new EvtSeedingUserRegistered("john@example.com", "John"),
              new EvtSeedingEmailVerified("john@example.com"),
              new EvtSeedingProfileUpdated("John Doe")
          ]);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.seeding.ICanSeedEvents
  import io.cratis.chronicle.seeding.IEventSeedingBuilder
  import io.cratis.chronicle.seeding.Seeder

@Seeder
  class EvtSeedingMixedTypesSeeding : ICanSeedEvents {
      override fun seed(builder: IEventSeedingBuilder) {
          builder.forEventSource(
              "user-123",
              listOf(
                  EvtSeedingUserRegistered("john@example.com", "John"),
                  EvtSeedingEmailVerified("john@example.com"),
                  EvtSeedingProfileUpdated("John Doe")
              )
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.seeding.ICanSeedEvents;
  import io.cratis.chronicle.seeding.IEventSeedingBuilder;
  import io.cratis.chronicle.seeding.Seeder;

import java.util.List;

@Seeder
  class EvtSeedingMixedTypesSeeding implements ICanSeedEvents {
      @Override
      public void seed(IEventSeedingBuilder builder) {
          builder.forEventSource(
              "user-123",
              List.of(
                  new EvtSeedingUserRegistered("john@example.com", "John"),
                  new EvtSeedingEmailVerified("john@example.com"),
                  new EvtSeedingProfileUpdated("John Doe")));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EvtSeedingMixedTypesUserRegistered do
    use Chronicle.Events.EventType, id: "evt-seeding-mixed-types-user-registered"

defstruct [:email, :display_name]
  end

defmodule MyApp.Events.EvtSeedingMixedTypesEmailVerified do
    use Chronicle.Events.EventType, id: "evt-seeding-mixed-types-email-verified"

defstruct [:email]
  end

defmodule MyApp.Events.EvtSeedingMixedTypesProfileUpdated do
    use Chronicle.Events.EventType, id: "evt-seeding-mixed-types-profile-updated"

defstruct [:display_name]
  end

defmodule MyApp.Seeders.EvtSeedingMixedTypesSeeding do
    use Chronicle.Seeding.Seeder

alias MyApp.Events.{
      EvtSeedingMixedTypesEmailVerified,
      EvtSeedingMixedTypesProfileUpdated,
      EvtSeedingMixedTypesUserRegistered
    }

@impl true
    def seed(builder) do
      Chronicle.Seeding.for_event_source(builder, "user-123", [
        %EvtSeedingMixedTypesUserRegistered{email: "john@example.com", display_name: "John"},
        %EvtSeedingMixedTypesEmailVerified{email: "john@example.com"},
        %EvtSeedingMixedTypesProfileUpdated{display_name: "John Doe"}
      ])
    end
  end
  ```

* TypeScript

```typescript
  import { ICanSeedEvents, IEventSeedingBuilder, seeder } from '@cratis/chronicle';

@seeder()
  class EvtSeedingMixedTypesSeeding implements ICanSeedEvents {
      seed(builder: IEventSeedingBuilder): void {
          builder.forEventSource('user-123', [
              new EvtSeedingUserRegistered('john@example.com', 'John'),
              new EvtSeedingEmailVerified('john@example.com'),
              new EvtSeedingProfileUpdated('John Doe')
          ]);
      }
  }
  ```

## Development-only seeding

[Section titled “Development-only seeding”](#development-only-seeding)

If seed data should only run in development, use conditional compilation or runtime configuration:

* C#

```csharp
  using Cratis.Chronicle.Seeding;

#if DEBUG
  public sealed class EvtSeedingDevelopmentSeeding : ICanSeedEvents
  {
      public void Seed(IEventSeedingBuilder builder)
      {
          builder.For<EvtSeedingUserRegistered>("dev-user-1", [
              new("dev@example.com", "Dev User")
          ]);
      }
  }
  #endif
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.seeding.ICanSeedEvents
  import io.cratis.chronicle.seeding.IEventSeedingBuilder
  import io.cratis.chronicle.seeding.Seeder

// Kotlin has no equivalent of C#'s #if DEBUG - gate seed data with a runtime check instead,
  // such as an environment variable or an application profile flag.
  @Seeder
  class EvtSeedingDevelopmentSeeding : ICanSeedEvents {
      override fun seed(builder: IEventSeedingBuilder) {
          if (System.getenv("APP_ENVIRONMENT") != "Development") return

builder.forEventType(
              EvtSeedingUserRegistered::class,
              "dev-user-1",
              listOf(EvtSeedingUserRegistered("dev@example.com", "Dev User"))
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.seeding.ICanSeedEvents;
  import io.cratis.chronicle.seeding.IEventSeedingBuilder;
  import io.cratis.chronicle.seeding.Seeder;

import io.cratis.chronicle.java.EventSeedingBuilderJavaBridge;

import java.util.List;

// Java has no equivalent of C#'s #if DEBUG - gate seed data with a runtime check instead,
  // such as an environment variable or an application profile flag.
  @Seeder
  class EvtSeedingDevelopmentSeeding implements ICanSeedEvents {
      @Override
      public void seed(IEventSeedingBuilder builder) {
          if (!"Development".equals(System.getenv("APP_ENVIRONMENT"))) {
              return;
          }

EventSeedingBuilderJavaBridge.forEventType(
              builder,
              EvtSeedingUserRegistered.class,
              "dev-user-1",
              List.of(new EvtSeedingUserRegistered("dev@example.com", "Dev User")));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EvtSeedingDevUserRegistered do
    use Chronicle.Events.EventType, id: "evt-seeding-dev-user-registered"

defstruct [:email, :display_name]
  end

defmodule MyApp.Seeders.EvtSeedingDevelopmentSeeding do
    use Chronicle.Seeding.Seeder

alias MyApp.Events.EvtSeedingDevUserRegistered

@impl true
    def seed(builder) do
      Chronicle.Seeding.for(builder, EvtSeedingDevUserRegistered, "dev-user-1", [
        %EvtSeedingDevUserRegistered{email: "dev@example.com", display_name: "Dev User"}
      ])
    end
  end

defmodule MyApp.EvtSeedingApplication do
    use Application

# Chronicle doesn't distinguish between development and production seed
    # data — decide when to seed based on build configuration or runtime
    # settings, resolved once at compile time here via Mix.env/0.
    @dev_seeders (if Mix.env() == :dev do
                    [MyApp.Seeders.EvtSeedingDevelopmentSeeding]
                  else
                    []
                  end)

@impl true
    def start(_type, _args) do
      children = [
        {Chronicle.Client,
         connection_string: "chronicle://localhost:35000",
         event_store: "my-store",
         seeders: @dev_seeders}
      ]

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

* TypeScript

```typescript
  import { ICanSeedEvents, IEventSeedingBuilder, seeder } from '@cratis/chronicle';

// Only include this seeder's file in your development build/discovery patterns -
  // TypeScript has no build-time equivalent of C#'s #if DEBUG, so keep it out of what
  // ChronicleOptions.discoveryPatterns picks up for production.
  @seeder()
  class EvtSeedingDevelopmentSeeding implements ICanSeedEvents {
      seed(builder: IEventSeedingBuilder): void {
          builder.for('dev-user-1', [new EvtSeedingUserRegistered('dev@example.com', 'Dev User')]);
      }
  }
  ```

Chronicle does not distinguish between development and production seed data. Decide when to seed based on build configuration or runtime settings.

## Organize seeders by feature

[Section titled “Organize seeders by feature”](#organize-seeders-by-feature)

For larger solutions, split seeders by domain or feature:

* C#

```csharp
  using Cratis.Chronicle.Seeding;

public sealed class EvtSeedingUserFeatureSeeding : ICanSeedEvents
  {
      public void Seed(IEventSeedingBuilder builder)
      {
          builder.For<EvtSeedingUserRegistered>("test-user-1", [
              new("test1@example.com", "Test User 1")
          ]);
      }
  }

public sealed class EvtSeedingOrderFeatureSeeding : ICanSeedEvents
  {
      public void Seed(IEventSeedingBuilder builder)
      {
          builder.For<EvtSeedingOrderPlaced>("test-order-1", [
              new("test-user-1", 100.00m)
          ]);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.seeding.ICanSeedEvents
  import io.cratis.chronicle.seeding.IEventSeedingBuilder
  import io.cratis.chronicle.seeding.Seeder

@Seeder
  class EvtSeedingUserFeatureSeeding : ICanSeedEvents {
      override fun seed(builder: IEventSeedingBuilder) {
          builder.forEventType(
              EvtSeedingUserRegistered::class,
              "test-user-1",
              listOf(EvtSeedingUserRegistered("test1@example.com", "Test User 1"))
          )
      }
  }

@Seeder
  class EvtSeedingOrderFeatureSeeding : ICanSeedEvents {
      override fun seed(builder: IEventSeedingBuilder) {
          builder.forEventType(
              EvtSeedingOrderPlaced::class,
              "test-order-1",
              listOf(EvtSeedingOrderPlaced("test-user-1", 100.00))
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.seeding.ICanSeedEvents;
  import io.cratis.chronicle.seeding.IEventSeedingBuilder;
  import io.cratis.chronicle.seeding.Seeder;

import io.cratis.chronicle.java.EventSeedingBuilderJavaBridge;

import java.util.List;

@Seeder
  class EvtSeedingUserFeatureSeeding implements ICanSeedEvents {
      @Override
      public void seed(IEventSeedingBuilder builder) {
          EventSeedingBuilderJavaBridge.forEventType(
              builder,
              EvtSeedingUserRegistered.class,
              "test-user-1",
              List.of(new EvtSeedingUserRegistered("test1@example.com", "Test User 1")));
      }
  }

@Seeder
  class EvtSeedingOrderFeatureSeeding implements ICanSeedEvents {
      @Override
      public void seed(IEventSeedingBuilder builder) {
          EventSeedingBuilderJavaBridge.forEventType(
              builder,
              EvtSeedingOrderPlaced.class,
              "test-order-1",
              List.of(new EvtSeedingOrderPlaced("test-user-1", 100.00)));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EvtSeedingFeatureUserRegistered do
    use Chronicle.Events.EventType, id: "evt-seeding-feature-user-registered"

defstruct [:email, :display_name]
  end

defmodule MyApp.Events.EvtSeedingFeatureOrderPlaced do
    use Chronicle.Events.EventType, id: "evt-seeding-feature-order-placed"

defstruct [:user_id, :amount]
  end

defmodule MyApp.Seeders.EvtSeedingUserFeatureSeeding do
    use Chronicle.Seeding.Seeder

alias MyApp.Events.EvtSeedingFeatureUserRegistered

@impl true
    def seed(builder) do
      Chronicle.Seeding.for(builder, EvtSeedingFeatureUserRegistered, "test-user-1", [
        %EvtSeedingFeatureUserRegistered{email: "test1@example.com", display_name: "Test User 1"}
      ])
    end
  end

defmodule MyApp.Seeders.EvtSeedingOrderFeatureSeeding do
    use Chronicle.Seeding.Seeder

alias MyApp.Events.EvtSeedingFeatureOrderPlaced

@impl true
    def seed(builder) do
      Chronicle.Seeding.for(builder, EvtSeedingFeatureOrderPlaced, "test-order-1", [
        %EvtSeedingFeatureOrderPlaced{user_id: "test-user-1", amount: 100.00}
      ])
    end
  end
  ```

* TypeScript

```typescript
  import { ICanSeedEvents, IEventSeedingBuilder, seeder } from '@cratis/chronicle';

@seeder()
  class EvtSeedingUserFeatureSeeding implements ICanSeedEvents {
      seed(builder: IEventSeedingBuilder): void {
          builder.for('test-user-1', [new EvtSeedingUserRegistered('test1@example.com', 'Test User 1')]);
      }
  }

@seeder()
  class EvtSeedingOrderFeatureSeeding implements ICanSeedEvents {
      seed(builder: IEventSeedingBuilder): void {
          builder.for('test-order-1', [new EvtSeedingOrderPlaced('test-user-1', 100.0)]);
      }
  }
  ```

## Namespace-scoped seed data

[Section titled “Namespace-scoped seed data”](#namespace-scoped-seed-data)

By default, seed data applies to all namespaces in the event store. To target a specific namespace, use `ForNamespace` to get a scoped builder:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Seeding;

[EventType]
  public record EvtSeedingProductCreated(string Name, decimal Price);

[EventType]
  public record EvtSeedingOrganizationCreated(string Name);

[EventType]
  public record EvtSeedingBillingSetUp(string BillingEmail);

public sealed class EvtSeedingTenantSeeding : ICanSeedEvents
  {
      public void Seed(IEventSeedingBuilder builder)
      {
          // Global seed data — applied to every namespace
          builder.For<EvtSeedingProductCreated>("product-1", [
              new("Laptop", 1299.00m)
          ]);

// Namespace-scoped seed data — applied only to the "acme" namespace
          builder.ForNamespace("acme")
              .For<EvtSeedingUserRegistered>("user-1", [
                  new("admin@acme.com", "Acme Admin")
              ]);

// A second namespace with different seed data
          builder.ForNamespace("contoso")
              .For<EvtSeedingUserRegistered>("user-1", [
                  new("admin@contoso.com", "Contoso Admin")
              ])
              .ForEventSource("org-1", [
                  new EvtSeedingOrganizationCreated("Contoso"),
                  new EvtSeedingBillingSetUp("contoso@billing.com")
              ]);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.seeding.ICanSeedEvents
  import io.cratis.chronicle.seeding.IEventSeedingBuilder
  import io.cratis.chronicle.seeding.Seeder

@EventType
  data class EvtSeedingProductCreated(val name: String, val price: Double)

@EventType
  data class EvtSeedingOrganizationCreated(val name: String)

@EventType
  data class EvtSeedingBillingSetUp(val billingEmail: String)

@Seeder
  class EvtSeedingTenantSeeding : ICanSeedEvents {
      override fun seed(builder: IEventSeedingBuilder) {
          // Global seed data - applied to every namespace
          builder.forEventType(
              EvtSeedingProductCreated::class,
              "product-1",
              listOf(EvtSeedingProductCreated("Laptop", 1299.00))
          )

// Namespace-scoped seed data - applied only to the "acme" namespace
          builder.forNamespace("acme")
              .forEventType(
                  EvtSeedingUserRegistered::class,
                  "user-1",
                  listOf(EvtSeedingUserRegistered("admin@acme.com", "Acme Admin"))
              )

// A second namespace with different seed data
          builder.forNamespace("contoso")
              .forEventType(
                  EvtSeedingUserRegistered::class,
                  "user-1",
                  listOf(EvtSeedingUserRegistered("admin@contoso.com", "Contoso Admin"))
              )
              .forEventSource(
                  "org-1",
                  listOf(
                      EvtSeedingOrganizationCreated("Contoso"),
                      EvtSeedingBillingSetUp("contoso@billing.com")
                  )
              )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.seeding.ICanSeedEvents;
  import io.cratis.chronicle.seeding.IEventSeedingBuilder;
  import io.cratis.chronicle.seeding.IEventSeedingScopeBuilder;
  import io.cratis.chronicle.seeding.Seeder;

import io.cratis.chronicle.java.EventSeedingBuilderJavaBridge;
  import io.cratis.chronicle.java.EventSeedingScopeBuilderJavaBridge;

import java.util.List;

@EventType
  record EvtSeedingProductCreated(String name, double price) {}

@EventType
  record EvtSeedingOrganizationCreated(String name) {}

@EventType
  record EvtSeedingBillingSetUp(String billingEmail) {}

@Seeder
  class EvtSeedingTenantSeeding implements ICanSeedEvents {
      @Override
      public void seed(IEventSeedingBuilder builder) {
          // Global seed data - applied to every namespace
          EventSeedingBuilderJavaBridge.forEventType(
              builder,
              EvtSeedingProductCreated.class,
              "product-1",
              List.of(new EvtSeedingProductCreated("Laptop", 1299.00)));

// Namespace-scoped seed data - applied only to the "acme" namespace
          IEventSeedingScopeBuilder acme = builder.forNamespace("acme");
          EventSeedingScopeBuilderJavaBridge.forEventType(
              acme,
              EvtSeedingUserRegistered.class,
              "user-1",
              List.of(new EvtSeedingUserRegistered("admin@acme.com", "Acme Admin")));

// A second namespace with different seed data
          IEventSeedingScopeBuilder contoso = builder.forNamespace("contoso");
          EventSeedingScopeBuilderJavaBridge.forEventType(
              contoso,
              EvtSeedingUserRegistered.class,
              "user-1",
              List.of(new EvtSeedingUserRegistered("admin@contoso.com", "Contoso Admin")));
          contoso.forEventSource(
              "org-1",
              List.of(
                  new EvtSeedingOrganizationCreated("Contoso"),
                  new EvtSeedingBillingSetUp("contoso@billing.com")));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EvtSeedingNsProductCreated do
    use Chronicle.Events.EventType, id: "evt-seeding-ns-product-created"

defstruct [:name, :price]
  end

defmodule MyApp.Events.EvtSeedingNsUserRegistered do
    use Chronicle.Events.EventType, id: "evt-seeding-ns-user-registered"

defstruct [:email, :display_name]
  end

defmodule MyApp.Events.EvtSeedingNsOrganizationCreated do
    use Chronicle.Events.EventType, id: "evt-seeding-ns-organization-created"

defstruct [:name]
  end

defmodule MyApp.Events.EvtSeedingNsBillingSetUp do
    use Chronicle.Events.EventType, id: "evt-seeding-ns-billing-set-up"

defstruct [:billing_email]
  end

defmodule MyApp.Seeders.EvtSeedingTenantSeeding do
    use Chronicle.Seeding.Seeder

alias MyApp.Events.{
      EvtSeedingNsBillingSetUp,
      EvtSeedingNsOrganizationCreated,
      EvtSeedingNsProductCreated,
      EvtSeedingNsUserRegistered
    }

@impl true
    def seed(builder) do
      builder
      # Global seed data — applied to every namespace
      |> Chronicle.Seeding.for(EvtSeedingNsProductCreated, "product-1", [
        %EvtSeedingNsProductCreated{name: "Laptop", price: 1299.00}
      ])
      # Namespace-scoped seed data — applied only to the "acme" namespace
      |> Chronicle.Seeding.for_namespace("acme", fn scoped ->
        Chronicle.Seeding.for(scoped, EvtSeedingNsUserRegistered, "user-1", [
          %EvtSeedingNsUserRegistered{email: "admin@acme.com", display_name: "Acme Admin"}
        ])
      end)
      # A second namespace with different seed data
      |> Chronicle.Seeding.for_namespace("contoso", fn scoped ->
        scoped
        |> Chronicle.Seeding.for(EvtSeedingNsUserRegistered, "user-1", [
          %EvtSeedingNsUserRegistered{email: "admin@contoso.com", display_name: "Contoso Admin"}
        ])
        |> Chronicle.Seeding.for_event_source("org-1", [
          %EvtSeedingNsOrganizationCreated{name: "Contoso"},
          %EvtSeedingNsBillingSetUp{billing_email: "contoso@billing.com"}
        ])
      end)
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, ICanSeedEvents, IEventSeedingBuilder, seeder } from '@cratis/chronicle';

@eventType()
  class EvtSeedingProductCreated {
      constructor(readonly name: string, readonly price: number) {}
  }

@eventType()
  class EvtSeedingOrganizationCreated {
      constructor(readonly name: string) {}
  }

@eventType()
  class EvtSeedingBillingSetUp {
      constructor(readonly billingEmail: string) {}
  }

@seeder()
  class EvtSeedingTenantSeeding implements ICanSeedEvents {
      seed(builder: IEventSeedingBuilder): void {
          // Global seed data — applied to every namespace
          builder.for('product-1', [new EvtSeedingProductCreated('Laptop', 1299.0)]);

// Namespace-scoped seed data — applied only to the "acme" namespace
          builder.forNamespace('acme')
              .for('user-1', [new EvtSeedingUserRegistered('admin@acme.com', 'Acme Admin')]);

// A second namespace with different seed data
          builder.forNamespace('contoso')
              .for('user-1', [new EvtSeedingUserRegistered('admin@contoso.com', 'Contoso Admin')])
              .forEventSource('org-1', [
                  new EvtSeedingOrganizationCreated('Contoso'),
                  new EvtSeedingBillingSetUp('contoso@billing.com')
              ]);
      }
  }
  ```

The scoped builder supports the same `For<TEvent>` and `ForEventSource` methods as the global builder. Each namespace receives only its own scoped events in addition to any global events.

## Register corrected seed definitions without reconnecting

[Section titled “Register corrected seed definitions without reconnecting”](#register-corrected-seed-definitions-without-reconnecting)

When registration fails, Chronicle retains the attempted entries in the event store’s default `Seeding` buffer. That makes retrying an unchanged idempotent batch safe after a transient failure. If the definitions themselves were wrong, create an independent empty buffer so the corrected set is not combined with the retained set:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Seeding;

public static class EvtSeedingCorrection
  {
      public static async Task Register(IEventStore eventStore)
      {
          var correctedSeeding = eventStore.CreateEventSeeding();
          correctedSeeding.For<EvtSeedingUserRegistered>("user-123", [
              new("john@example.com", "John Doe")
          ]);

await correctedSeeding.Register();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

async function registerEvtSeedingCorrection(eventStore: IEventStore): Promise<void> {
      eventStore.seeding.for('user-123', [new EvtSeedingUserRegistered('john@example.com', 'John Doe')]);

await eventStore.seeding.register();
  }
  ```

The new buffer uses the event store’s existing connection, event types, serializer, and client configuration. A failure from its `Register()` call still propagates normally.

## How it runs

[Section titled “How it runs”](#how-it-runs)

* Seeders are automatically discovered at application startup.
* Seed batches are sent to the Chronicle Server when the event store connects.
* Every entry is applied once per namespace, and seeding is idempotent across restarts: entries that have already been appended are skipped on the next run.
* An entry that your seeder yields twice is two events, not one. Two events of the same type, on the same event source, carrying the same payload are two facts, and both are appended.
* Events are appended in batches of 100. A batch is validated as a whole before anything is written, so a single entry that violates a constraint means none of its batch is appended. The server reports the rejection at `Error` with the violations, leaves those entries unseeded, and fails registration. The remote client surfaces that failure through its normal transport error. Retry the unchanged buffer for a transient failure; after correcting the definitions, restart the process or use `CreateEventSeeding()` to offer a fresh set.

## Best practices

[Section titled “Best practices”](#best-practices)

* Keep seed data minimal and deterministic.
* Use clear event source IDs to make debugging easier.
* Group seeders by scenario so you can remove or adjust them easily.
* Use build flags or runtime settings to prevent seeding in production.
* Use `ForNamespace` when seed data is tenant-specific or environment-specific to avoid polluting other namespaces.

# Events

Events are immutable facts that describe what happened in your system. Chronicle identifies events by their event type rather than the .NET CLR type, which makes the CLR type a convenient vessel for expressing intent and structure.

```
[EventType] record

Append

Event sequence (immutable, ordered)

Observers (projections · reducers · reactors)
```

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record EventsIndexEmployeeRegistered(string FirstName, string LastName);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class EventsIndexTypeEmployeeRegistered(val firstName: String = "", val lastName: String = "")
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record EventsIndexTypeEmployeeRegistered(String firstName, String lastName) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EventsIndexTypeEmployeeRegistered do
    use Chronicle.Events.EventType, id: "events-index-type-employee-registered"

defstruct [:first_name, :last_name]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class EventsIndexEmployeeRegistered {
      constructor(
          readonly firstName: string,
          readonly lastName: string
      ) {}
  }
  ```

## Event Sequences and the Event Log

[Section titled “Event Sequences and the Event Log”](#event-sequences-and-the-event-log)

Events live in event sequences, which are ordered, append-only streams. Each event receives a monotonically increasing sequence number that makes it possible to replay events, resume processing, and reason about how far consumers have progressed.

Chronicle includes a specialized event sequence called the event log. It is the default sequence used throughout the system and is exposed through the `IEventLog` API.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class EventsIndexEmployeesService(IEventLog eventLog)
  {
      public Task RegisterEmployee(EventSourceId employeeId, string firstName, string lastName) =>
          eventLog.Append(employeeId, new EventsIndexEmployeeRegistered(firstName, lastName));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType

@EventType
  data class EventsIndexLogEmployeeRegistered(val firstName: String = "", val lastName: String = "")

/**
   * The event log is the default event sequence, exposed through [IEventStore.eventLog].
   */
  suspend fun registerEmployee(store: IEventStore, employeeId: String, firstName: String, lastName: String) =
      store.eventLog.append(employeeId, EventsIndexLogEmployeeRegistered(firstName, lastName))
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.AppendResult;

import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
  record EventsIndexLogEmployeeRegistered(String firstName, String lastName) {}

class EventsIndexEventLog {
      // The event log is the default event sequence, exposed through EventStore.getEventLog().
      AppendResult registerEmployee(EventStore store, String employeeId, String firstName, String lastName) {
          return EventLogJavaBridge.append(store.getEventLog(), employeeId, new EventsIndexLogEmployeeRegistered(firstName, lastName), null);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EventsIndexEmployeeRegistered do
    use Chronicle.Events.EventType, id: "events-index-employee-registered"

defstruct [:first_name, :last_name]
  end

defmodule MyApp.EventsIndexEmployeesService do
    alias MyApp.Events.EventsIndexEmployeeRegistered

def register_employee(employee_id, first_name, last_name) do
      Chronicle.append(employee_id, %EventsIndexEmployeeRegistered{
        first_name: first_name,
        last_name: last_name
      })
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async registerEmployee(employeeId: string, firstName: string, lastName: string): Promise<void> {
          await this.store.eventLog.append(employeeId, new EventsIndexEmployeeRegistered(firstName, lastName));
      }
  }
  ```

## Working with Events

[Section titled “Working with Events”](#working-with-events)

Use these topics to append, read, and manage events:

* [Appending](/chronicle/events/appending/)
* [Appending with tags](/chronicle/events/appending-with-tags/)
* [Filtering reducers and reactors](/chronicle/events/filtering/)
* [Appending many](/chronicle/events/appending-many/)
* [Observing appends](/chronicle/events/observing-appends/)
* [Getting events](/chronicle/events/getting-events/)
* [Getting state](/chronicle/events/getting-state/)
* [Concurrency](/chronicle/events/concurrency/)
* [Cross-cutting properties](/chronicle/events/cross-cutting-properties/)
* [Revision](/chronicle/events/revision/)
* [Redaction](/chronicle/events/redaction/)

# Appending

Appending adds a single event to an event sequence. The event log is the default sequence, but you can also append to any custom sequence your system defines.

Note

With Cratis Arc and the Chronicle extension, you can append events as state changes coming out of a command using a more functional approach. See [Arc Chronicle commands](/arc/backend/chronicle/commands/).

## How it works

[Section titled “How it works”](#how-it-works)

When you append an event, Chronicle:

* Validates the event content against its registered JSON schema
* Applies any [cross-cutting properties](/chronicle/events/cross-cutting-properties/)
* Associates the event with its event source
* Assigns the next sequence number
* Persists the event and metadata atomically
* Updates the sequence state

The append returns an operation result you can use to detect schema errors, concurrency violations, constraint violations, and other append-time problems. This makes it safe to retry or revise without duplicating events.

## AppendResult

[Section titled “AppendResult”](#appendresult)

Appending returns an `AppendResult` that describes whether the operation succeeded and includes details about what went wrong when it fails. It can surface schema validation errors, concurrency violations, constraint violations, and other append-time problems. See [Concurrency](/chronicle/events/concurrency/) and [Constraints](/chronicle/constraints/) for more on these cases.

## Schema validation

[Section titled “Schema validation”](#schema-validation)

Chronicle validates every event’s content against its registered JSON schema before persisting it. If the content does not conform to the schema — for example, a required property is missing or has the wrong type — the append fails and the errors appear in `AppendResult.Errors`.

* C#

```csharp
  var result = await eventLog.Append(eventSourceId, new OrderPlaced(customerId, total));

if (result.HasErrors)
  {
      foreach (var error in result.Errors)
      {
          Console.WriteLine($"Schema error: {error}");
      }
  }
  ```

* Kotlin

```kotlin
  val result = store.eventLog.append(eventSourceId, OrderPlaced(customerId, total))

if (!result.isSuccess) {
      result.errors.forEach { error ->
          println("Schema error: $error")
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.BlockingEventStore;

@EventType
  record SchemaValidatedOrderPlaced(String customerId, double total) {}

class SchemaValidationExample {
      void append(IEventStore store, String eventSourceId, String customerId, double total) {
          var result = new BlockingEventStore(store).getEventLog().append(
              eventSourceId,
              new SchemaValidatedOrderPlaced(customerId, total));

if (!result.isSuccess()) {
              result.getErrors().forEach(error ->
                  System.out.println("Schema error: " + error));
          }
      }
  }
  ```

* Elixir

```elixir
  case Chronicle.append(event_source_id, %MyApp.Events.OrderPlaced{
         customer_id: customer_id,
         total: total
       }) do
    :ok ->
      :ok

{:error, {:append_errors, errors}} ->
      Enum.each(errors, &IO.puts("Schema error: #{inspect(&1)}"))
  end
  ```

* TypeScript

```typescript
  const result = await store.eventLog.append(
      eventSourceId,
      new OrderPlaced(customerId, total)
  );

if (!result.isSuccess) {
      for (const error of result.errors) {
          console.log(`Schema error: ${error.message}`);
      }
  }
  ```

Schema validation runs before any other checks, so a schema error is returned immediately without touching the event sequence.

## Specifying when an event occurred

[Section titled “Specifying when an event occurred”](#specifying-when-an-event-occurred)

By default, Chronicle assigns the current server time as the event’s `Occurred` timestamp when it persists the event. Some clients expose an explicit timestamp override for import and replay scenarios.

* C#

```csharp
  var result = await eventLog.Append(
      eventSourceId,
      new OrderPlaced(customerId, total),
      occurred: DateTimeOffset.Parse("2024-01-15T10:30:00Z")
  );
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.events.EventType
  import java.time.Instant

@EventType
  data class OccurredOrderPlaced(val customerId: String = "", val total: Double = 0.0)

/**
   * Appends an event with an explicit [AppendOptions.occurred] timestamp, bypassing the kernel's
   * default of assigning the current server time. Use this only when importing or replaying
   * historical events.
   */
  suspend fun placeHistoricalOrder(store: IEventStore, eventSourceId: String, customerId: String, total: Double) =
      store.eventLog.append(
          eventSourceId,
          OccurredOrderPlaced(customerId, total),
          AppendOptions(occurred = Instant.parse("2024-01-15T10:30:00Z"))
      )
  ```

* Java

import java.time.Instant;

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

@EventType
  record OccurredOrderPlaced(String customerId, double total) {}

class EventsAppendingOccurred {
      // Appends an event with an explicit occurred timestamp, bypassing the kernel's default of
      // assigning the current server time. Use this only when importing or replaying historical events.
      AppendResult placeHistoricalOrder(EventStore store, String eventSourceId, String customerId, double total) {
          AppendOptions options = new AppendOptionsBuilder()
              .occurred(Instant.parse("2024-01-15T10:30:00Z"))
              .build();

return EventLogJavaBridge.append(store.getEventLog(), eventSourceId, new OccurredOrderPlaced(customerId, total), options);
      }
  }
  ```

* Elixir

```elixir
  {:ok, occurred, 0} = DateTime.from_iso8601("2024-01-15T10:30:00Z")

:ok =
    Chronicle.append(
      event_source_id,
      %MyApp.Events.OrderPlaced{customer_id: customer_id, total: total},
      occurred: occurred
    )
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Caution

Specifying `occurred` bypasses the automatic server timestamp. Use this only for importing historical events or replaying data from an external system. Incorrect timestamps can break projections and reactors that rely on event ordering by time.

## When to use

[Section titled “When to use”](#when-to-use)

Appending is lightweight and intended for single domain decisions that produce one event. When your decision spans multiple event sources, use concurrency scopes to enforce the boundary while keeping sequences independent. See [Concurrency](/chronicle/events/concurrency/) for details.

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record OrderPlaced(string CustomerId, decimal Total);

public class CheckoutService(IEventLog eventLog)
  {
      public async Task PlaceOrder(OrderId orderId, string customerId, decimal total)
      {
          var result = await eventLog.Append(
              orderId,
              new OrderPlaced(customerId, total)
          );

if (!result.IsSuccess)
          {
              // Decide whether to retry or surface a conflict to the caller.
          }
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType

@EventType
  data class OrderPlaced(
      val customerId: String,
      val total: Double
  )

class CheckoutService(private val store: IEventStore) {
      suspend fun placeOrder(orderId: String, customerId: String, total: Double) {
          val result = store.eventLog.append(
              orderId,
              OrderPlaced(customerId, total)
          )

if (!result.isSuccess) {
              // Decide whether to retry or surface a conflict to the caller.
          }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.BlockingEventStore;

@EventType
  record OrderPlaced(String customerId, double total) {}

class CheckoutService {
      private final BlockingEventStore store;

CheckoutService(IEventStore store) {
          this.store = new BlockingEventStore(store);
      }

void placeOrder(String orderId, String customerId, double total) {
          var result = store.getEventLog().append(orderId, new OrderPlaced(customerId, total));

if (!result.isSuccess()) {
              // Decide whether to retry or surface a conflict to the caller.
          }
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.OrderPlaced do
    use Chronicle.Events.EventType, id: "order-placed"

defstruct [:customer_id, :total]
  end

defmodule MyApp.CheckoutService do
    def place_order(order_id, customer_id, total) do
      case Chronicle.append(order_id, %MyApp.Events.OrderPlaced{
             customer_id: customer_id,
             total: total
           }) do
        :ok ->
          :ok

{:error, _reason} = error ->
          # Decide whether to retry or surface a conflict to the caller.
          error
      end
    end
  end
  ```

* TypeScript

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

@eventType()
  class OrderPlaced {
      constructor(
          readonly customerId: string,
          readonly total: number
      ) {}
  }

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

async placeOrder(orderId: string, customerId: string, total: number): Promise<void> {
          const result = await this.store.eventLog.append(
              orderId,
              new OrderPlaced(customerId, total)
          );

if (!result.isSuccess) {
              // Decide whether to retry or surface a conflict to the caller.
          }
      }
  }
  ```

# Appending many

Appending many events in a single call is useful for batch workflows such as imports, migrations, or multi-step business operations.

Note

With Cratis Arc and the Chronicle extension, you can append events as state changes coming out of a command using a more functional approach. See `Arc.Chronicle.Commands`.

Batch appends preserve ordering and reduce per-event overhead compared to appending each event individually.

AppendMany is transactional all the way to storage. Either all events in the batch are committed, or none are. Chronicle assigns sequence numbers in order, persists the events and metadata atomically, and updates the sequence state once the batch succeeds.

## How it works

[Section titled “How it works”](#how-it-works)

* Each item in the batch pairs an event with the event source it belongs to.
* The batch is validated as a unit and written atomically.
* Sequence numbers are assigned in the order provided.
* The event sequence state is updated once the batch commits.

## When to use

[Section titled “When to use”](#when-to-use)

Use this approach when you already have a set of events that should be appended together. Each event can still target different event sources, and you can include concurrency scopes to validate the boundary across streams. See [Concurrency](/chronicle/events/concurrency/) for details.

## Example

[Section titled “Example”](#example)

* C#

```csharp
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Events;

public readonly record struct AccountId(string Value)
  {
      public static implicit operator EventSourceId(AccountId id) => new(id.Value);
  }

[EventType]
  public record MoneyWithdrawn(decimal Amount);

[EventType]
  public record MoneyDeposited(decimal Amount);

public class TransferService(IEventLog eventLog)
  {
      public Task<AppendManyResult> Transfer(AccountId fromAccount, AccountId toAccount, decimal amount)
      {
          var events = new[]
          {
              new EventForEventSourceId(fromAccount, new MoneyWithdrawn(amount)),
              new EventForEventSourceId(toAccount, new MoneyDeposited(amount))
          };

return eventLog.AppendMany(events);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.eventSequences.AppendResult
  import io.cratis.chronicle.eventSequences.EventForEventSourceId
  import io.cratis.chronicle.eventSequences.IEventLog
  import io.cratis.chronicle.events.EventType

@EventType
  data class MoneyWithdrawn(val amount: Double)

@EventType
  data class MoneyDeposited(val amount: Double)

class Transfers(private val eventLog: IEventLog) {
      /**
       * Moves money between two accounts as one atomic append - each event targets its own account,
       * and either both are committed or neither of them is.
       */
      suspend fun transfer(fromAccount: String, toAccount: String, amount: Double): List<AppendResult> =
          eventLog.appendMany(
              listOf(
                  EventForEventSourceId(fromAccount, MoneyWithdrawn(amount)),
                  EventForEventSourceId(toAccount, MoneyDeposited(amount))
              )
          )
  }
  ```

* Java

import io.cratis.chronicle.java.EventSequenceJavaBridge;

import java.util.List;

@EventType
  record TransferMoneyWithdrawn(double amount) {}

@EventType
  record TransferMoneyDeposited(double amount) {}

class EventsAppendingManyTransfer {
      // Moves money between two accounts as one atomic append — each event targets its own account,
      // and either both are committed or neither of them is.
      List<AppendResult> transfer(EventStore store, String fromAccount, String toAccount, double amount) {
          return EventSequenceJavaBridge.appendMany(
              store.getEventLog(),
              List.of(
                  new EventForEventSourceId(fromAccount, new TransferMoneyWithdrawn(amount)),
                  new EventForEventSourceId(toAccount, new TransferMoneyDeposited(amount))));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.TransferMoneyWithdrawn do
    use Chronicle.Events.EventType, id: "transfer-money-withdrawn-v1"

defstruct [:amount]
  end

defmodule MyApp.Events.TransferMoneyDeposited do
    use Chronicle.Events.EventType, id: "transfer-money-deposited-v1"

defstruct [:amount]
  end

defmodule MyApp.TransferService do
    alias Chronicle.EventSequences.{EventForEventSourceId, EventLog}
    alias MyApp.Events.{TransferMoneyDeposited, TransferMoneyWithdrawn}

# Appends both events atomically in a single append-many, each carrying
    # its own target event source id.
    def transfer(from_account, to_account, amount) do
      events = [
        %EventForEventSourceId{
          event_source_id: from_account,
          event: %TransferMoneyWithdrawn{amount: amount}
        },
        %EventForEventSourceId{
          event_source_id: to_account,
          event: %TransferMoneyDeposited{amount: amount}
        }
      ]

EventLog.append_many_for_event_sources(events)
    end
  end
  ```

* TypeScript

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

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

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

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

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

const results = await this.store.eventLog.appendMany(events);

if (results.some(_ => !_.isSuccess)) {
              // Decide whether to retry or surface a conflict to the caller.
          }
      }
  }
  ```

# Appending with Tags

Chronicle lets you associate tags with appended events. Tags are stored as event metadata and can be used for categorization, filtering, and concurrency scoping.

## Built-in metadata tags

[Section titled “Built-in metadata tags”](#built-in-metadata-tags)

Chronicle maintains built-in metadata tags for event identity and stream routing:

* `EventSourceType`
* `EventSourceId`
* `EventStreamType`
* `EventStreamId`

You can add custom tags in addition to these built-in tags. For the full list and behavior, see [Event Metadata Tags](/chronicle/concepts/event-metadata-tags/).

## Custom tags

[Section titled “Custom tags”](#custom-tags)

Custom tags are simple strings that you provide when appending. They are merged with any static tags defined on the event type.

## Append with tags

[Section titled “Append with tags”](#append-with-tags)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record TaggedOrderPlaced(string CustomerId, decimal Total);

public class TaggedCheckoutService(IEventLog eventLog)
  {
      public Task<AppendResult> PlaceOrder(OrderId orderId, string customerId, decimal total)
      {
          return eventLog.Append(
              orderId,
              new TaggedOrderPlaced(customerId, total),
              tags: ["checkout", "priority"]);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.eventSequences.AppendResult
  import io.cratis.chronicle.events.EventType

@EventType
  data class TaggedOrderPlaced(val customerId: String, val total: Double)

class TaggedCheckoutService(private val eventStore: IEventStore) {
      suspend fun placeOrder(orderId: String, customerId: String, total: Double): AppendResult =
          eventStore.eventLog.append(
              orderId,
              TaggedOrderPlaced(customerId, total),
              AppendOptions(tags = listOf("checkout", "priority"))
          )
  }
  ```

* Java

@EventType
  record TaggedOrderPlaced(String customerId, double total) {}

class TaggedCheckoutService {
      private final BlockingEventStore eventStore;

TaggedCheckoutService(IEventStore eventStore) {
          this.eventStore = new BlockingEventStore(eventStore);
      }

void placeOrder(String orderId, String customerId, double total) {
          var options = new AppendOptionsBuilder().tag("checkout").tag("priority").build();
          eventStore.getEventLog().append(orderId, new TaggedOrderPlaced(customerId, total), options);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.TaggedOrderPlaced do
    defstruct [:customer_id, :total]
  end

defmodule MyApp.TaggedCheckoutService do
    alias MyApp.Events.TaggedOrderPlaced

def place_order(order_id, customer_id, total) do
      Chronicle.append(
        order_id,
        %TaggedOrderPlaced{customer_id: customer_id, total: total},
        tags: ["checkout", "priority"]
      )
    end
  end
  ```

* TypeScript

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

@eventType()
  class TaggedOrderPlaced {
      constructor(readonly customerId: string, readonly total: number) {}
  }

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

async placeOrder(orderId: string, customerId: string, total: number): Promise<void> {
          await this.store.eventLog.append(
              orderId,
              new TaggedOrderPlaced(customerId, total),
              { tags: ['checkout', 'priority'] });
      }
  }
  ```

## AppendMany with tags

[Section titled “AppendMany with tags”](#appendmany-with-tags)

`AppendMany` applies the provided tags to each event in the batch.

* C#

```csharp
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Events;

public readonly record struct TaggedAccountId(string Value)
  {
      public static implicit operator EventSourceId(TaggedAccountId id) => new(id.Value);
  }

[EventType]
  public record TaggedMoneyWithdrawn(decimal Amount);

[EventType]
  public record TaggedMoneyDeposited(decimal Amount);

public class TaggedTransferService(IEventLog eventLog)
  {
      public Task<AppendManyResult> Transfer(TaggedAccountId fromAccount, TaggedAccountId toAccount, decimal amount)
      {
          var events = new[]
          {
              new EventForEventSourceId(fromAccount, new TaggedMoneyWithdrawn(amount)),
              new EventForEventSourceId(toAccount, new TaggedMoneyDeposited(amount))
          };

return eventLog.AppendMany(events, tags: ["transfer", "audit"]);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.AppendResult
  import io.cratis.chronicle.eventSequences.EventForEventSourceId
  import io.cratis.chronicle.events.EventType

@EventType
  data class TaggedMoneyWithdrawn(val amount: Double)

@EventType
  data class TaggedMoneyDeposited(val amount: Double)

class TaggedTransferService(private val eventStore: IEventStore) {
      suspend fun transfer(fromAccount: String, toAccount: String, amount: Double): List<AppendResult> {
          val events = listOf(
              EventForEventSourceId(fromAccount, TaggedMoneyWithdrawn(amount), tags = listOf("transfer", "audit")),
              EventForEventSourceId(toAccount, TaggedMoneyDeposited(amount), tags = listOf("transfer", "audit"))
          )

return eventStore.eventLog.appendMany(events)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.eventSequences.AppendResult;
  import io.cratis.chronicle.eventSequences.EventForEventSourceId;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.BlockingEventStore;

import java.util.List;

@EventType
  record TaggedMoneyWithdrawn(double amount) {}

@EventType
  record TaggedMoneyDeposited(double amount) {}

class TaggedTransferService {
      private final BlockingEventStore eventStore;

TaggedTransferService(IEventStore eventStore) {
          this.eventStore = new BlockingEventStore(eventStore);
      }

List<AppendResult> transfer(String fromAccount, String toAccount, double amount) {
          var events = List.of(
              new EventForEventSourceId(fromAccount, new TaggedMoneyWithdrawn(amount), null, null, null, List.of("transfer", "audit")),
              new EventForEventSourceId(toAccount, new TaggedMoneyDeposited(amount), null, null, null, List.of("transfer", "audit")));

return eventStore.getEventLog().appendMany(events);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.TaggedMoneyWithdrawn do
    defstruct [:amount]
  end

defmodule MyApp.Events.TaggedWithdrawalFeeCharged do
    defstruct [:amount]
  end

defmodule MyApp.TaggedWithdrawalService do
    alias MyApp.Events.TaggedMoneyWithdrawn
    alias MyApp.Events.TaggedWithdrawalFeeCharged

def withdraw(account_id, amount, fee) do
      Chronicle.append_many(
        account_id,
        [
          %TaggedMoneyWithdrawn{amount: amount},
          %TaggedWithdrawalFeeCharged{amount: fee}
        ],
        tags: ["withdrawal", "audit"]
      )
    end
  end
  ```

* TypeScript

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

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

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

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

async transfer(fromAccountId: string, toAccountId: string, amount: number): Promise<void> {
          const events: EventForEventSourceId[] = [
              { eventSourceId: fromAccountId, event: new TaggedMoneyWithdrawn(amount) },
              { eventSourceId: toAccountId, event: new TaggedMoneyDeposited(amount) }
          ];

await this.store.eventLog.appendMany(events, { tags: ['transfer', 'audit'] });
      }
  }
  ```

# Concurrency

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

## Understanding ConcurrencyScope

[Section titled “Understanding ConcurrencyScope”](#understanding-concurrencyscope)

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

### Formalized Metadata Tags for Concurrency

[Section titled “Formalized Metadata Tags for Concurrency”](#formalized-metadata-tags-for-concurrency)

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

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

### Simple Concurrency Scope

[Section titled “Simple Concurrency Scope”](#simple-concurrency-scope)

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

* C#

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

[EventType]
  public record ConcurrencyAccountOpened(string AccountName);

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

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

* Kotlin

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

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

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

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

* Java

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

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

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

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

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

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

* Elixir

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

defstruct [:account_name]
  end

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

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

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

* TypeScript

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

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

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

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

### Using ConcurrencyScopeBuilder

[Section titled “Using ConcurrencyScopeBuilder”](#using-concurrencyscopebuilder)

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

* C#

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

[EventType]
  public record ConcurrencyMoneyDeposited(decimal Amount);

[EventType]
  public record ConcurrencyMoneyWithdrawn(decimal Amount);

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

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

* Kotlin

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

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

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

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

* Java

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

@EventType
  record ConcurrencyMoneyDeposited(double amount) {}

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

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

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

* Elixir

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

defstruct [:amount]
  end

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

defstruct [:amount]
  end

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

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

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

* TypeScript

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

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

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

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

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

## Scoping by Event Metadata Tags

[Section titled “Scoping by Event Metadata Tags”](#scoping-by-event-metadata-tags)

### EventSourceType and EventStreamType

[Section titled “EventSourceType and EventStreamType”](#eventsourcetype-and-eventstreamtype)

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

* C#

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

[EventType]
  public record ConcurrencyAccountSettingsUpdated(string Settings);

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

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

* Kotlin

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

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

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

* Java

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

@EventType
  record ConcurrencyAccountSettingsUpdated(String settings) {}

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

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

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

* Elixir

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

defstruct [:settings]
  end

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

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

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

* TypeScript

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

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

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

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

### EventStreamId

[Section titled “EventStreamId”](#eventstreamid)

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

* C#

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

[EventType]
  public record ConcurrencyMonthlyReportGenerated(string Month);

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

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

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

* Kotlin

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

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

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

* Java

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

@EventType
  record ConcurrencyMonthlyReportGenerated(String month) {}

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

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

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

* Elixir

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

defstruct [:month]
  end

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

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

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

* TypeScript

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

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

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

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

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

### Event Types

[Section titled “Event Types”](#event-types)

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

* C#

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

[EventType]
  public record ConcurrencyPaymentProcessed(decimal Amount);

[EventType]
  public record ConcurrencyPaymentFailed(decimal Amount);

[EventType]
  public record ConcurrencyPaymentRefunded(decimal Amount);

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

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

* Kotlin

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

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

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

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

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

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

* Java

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

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

@EventType
  record ConcurrencyPaymentProcessed(double amount) {}

@EventType
  record ConcurrencyPaymentFailed(double amount) {}

@EventType
  record ConcurrencyPaymentRefunded(double amount) {}

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

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

* Elixir

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

defstruct [:amount]
  end

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

defstruct [:amount]
  end

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

defstruct [:amount]
  end

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

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

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

* TypeScript

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

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

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

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

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

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

## AppendMany with Concurrency Scopes

[Section titled “AppendMany with Concurrency Scopes”](#appendmany-with-concurrency-scopes)

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

* C#

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

[EventType]
  public record ConcurrencyMoneyWithdrawnForTransfer(decimal Amount);

[EventType]
  public record ConcurrencyMoneyDepositedForTransfer(decimal Amount);

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

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

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

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

* Kotlin

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

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

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

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

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

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

* Java

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

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

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

@EventType
  record ConcurrencyMoneyWithdrawnForTransfer(double amount) {}

@EventType
  record ConcurrencyMoneyDepositedForTransfer(double amount) {}

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

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

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

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

* Elixir

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

defstruct [:amount]
  end

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

defstruct [:amount]
  end

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

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

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

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

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

* TypeScript

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

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

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

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

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

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

## Event Source Operations with Concurrency

[Section titled “Event Source Operations with Concurrency”](#event-source-operations-with-concurrency)

You can also use concurrency scopes with event source operations:

* C#

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

[EventType]
  public record ConcurrencyAccountValidated;

[EventType]
  public record ConcurrencyAccountProcessed;

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

* Kotlin

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

@EventType
  class ConcurrencyAccountValidated

@EventType
  class ConcurrencyAccountProcessed

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

* Java

import java.util.List;

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

@EventType
  record ConcurrencyAccountValidated() {}

@EventType
  record ConcurrencyAccountProcessed() {}

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

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

return EventSequenceOperationsJavaBridge.perform(operations);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Handling Concurrency Violations

[Section titled “Handling Concurrency Violations”](#handling-concurrency-violations)

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

* C#

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

[EventType]
  public record ConcurrencySafeAccountOpened(string AccountName);

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

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

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

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

* Kotlin

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

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

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

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

return result.isSuccess
  }
  ```

* Java

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

@EventType
  record ConcurrencySafeAccountOpened(String accountName) {}

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

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

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

return result.isSuccess();
      }
  }
  ```

* Elixir

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

defstruct [:account_name]
  end

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

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

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

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

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

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Concurrency Strategies

[Section titled “Concurrency Strategies”](#concurrency-strategies)

Chronicle provides built-in concurrency strategies:

### Optimistic Concurrency Strategy

[Section titled “Optimistic Concurrency Strategy”](#optimistic-concurrency-strategy)

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

* C#

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

[EventType]
  public record ConcurrencyAccountNameChanged(string NewName);

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

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

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

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

defstruct [:new_name]
  end

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

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

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

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

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

## The First Append Into a Scope Is Not Checked by Default

[Section titled “The First Append Into a Scope Is Not Checked by Default”](#the-first-append-into-a-scope-is-not-checked-by-default)

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

```
yes

yes

no, the default

yes

Append with a concurrency scope

Does any event match the scope's narrowing?

Expected tail resolved

Has anything matching been appended since?

Appended

Concurrency violation

First-append check turned on?

Check skipped, logged at debug

Does anything match it now?
```

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

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

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

### Checking It — Opt In

[Section titled “Checking It — Opt In”](#checking-it--opt-in)

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

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

* C#

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

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

[EventType]
  public record ConcurrencyFirstAppendPartitionOpened(string Name);

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

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

return result.IsSuccess;
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

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

This rejects appends that succeed with it off

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

The default is scheduled to change

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

### Expressing “This Must Not Exist Yet”

[Section titled “Expressing “This Must Not Exist Yet””](#expressing-this-must-not-exist-yet)

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

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

### Telling a Skipped Check From a Passing One

[Section titled “Telling a Skipped Check From a Passing One”](#telling-a-skipped-check-from-a-passing-one)

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

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

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

### Mixed-Version Deployments

[Section titled “Mixed-Version Deployments”](#mixed-version-deployments)

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

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

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

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

## Best Practices

[Section titled “Best Practices”](#best-practices)

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

# Cross-cutting properties

You can add properties to all events that are appended without requiring each event type to define the fields. This is useful for metadata such as correlation identifiers, tenant identifiers, or system-generated values that should not be set by domain code.

To provide cross-cutting properties, implement `ICanProvideAdditionalEventInformation`:

* C#

```csharp
  using System.Text.Json.Nodes;
  using Cratis.Chronicle.Events;

public class CrossCuttingAdditionalEventInformationProvider : ICanProvideAdditionalEventInformation
  {
      public Task ProvideFor(JsonObject @event)
      {
          @event.Add("something", Guid.NewGuid());
          @event.Add("someTime", DateTimeOffset.UtcNow);
          return Task.CompletedTask;
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Chronicle will discover providers automatically and apply the additional properties during event append.

# Event Source Id

An event source identifier (`EventSourceId`) is the key that groups related events together within an event sequence. Every event you append must carry an event source identifier — it is how Chronicle knows which instance of an entity the event belongs to.

## How the server works

[Section titled “How the server works”](#how-the-server-works)

Internally, Chronicle represents all event source identifiers as plain strings. This keeps the server and storage layer simple and schema-independent: the server does not need to know whether your identifier is a `Guid`, an integer, or a domain concept. Any type you use on the client side is serialized to its string representation before it reaches the server.

## The `EventSourceId` type

[Section titled “The EventSourceId type”](#the-eventsourceid-type)

The `EventSourceId` record is the primary type used throughout the Chronicle API. It wraps a `string` value and provides implicit conversions from both `string` and `Guid`, so you can pass either directly wherever an `EventSourceId` is expected.

* C#

```csharp
  using Cratis.Chronicle.Events;

public static class EventSourceIdConversionExamples
  {
      public static void FromGuid()
      {
          // From a Guid — common for aggregate-style identifiers
          EventSourceId id = Guid.NewGuid();
      }

public static void FromString()
      {
          // From a string — useful for natural keys
          EventSourceId id = "order-42";
      }

public static void Generated()
      {
          // Generate a new random identifier
          EventSourceId id = EventSourceId.New();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The `Unspecified` sentinel value signals the absence of a meaningful identifier and corresponds to an empty string. Use it when an identifier is structurally required but contextually irrelevant.

## The generic `EventSourceId<T>`

[Section titled “The generic EventSourceId\<T>”](#the-generic-eventsourceidt)

The generic `EventSourceId<T>` type lets you carry a strongly-typed value through the client-side API while remaining wire-compatible with the plain `EventSourceId` that the server expects.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

// A strongly-typed domain concept
  public record EventSourceIdCustomerId(Guid Value) : EventSourceId<Guid>(Value)
  {
      public static EventSourceIdCustomerId New() => new(Guid.NewGuid());
  }

[EventType]
  public record EventSourceIdOrderPlaced(EventSourceIdCustomerId CustomerId, decimal Total);

public class EventSourceIdOrderService(IEventLog eventLog)
  {
      public Task PlaceOrder(decimal total)
      {
          var customerId = EventSourceIdCustomerId.New();

// The typed identifier converts implicitly to EventSourceId — no manual conversion needed
          return eventLog.Append(customerId, new EventSourceIdOrderPlaced(customerId, total));
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Because `EventSourceId<T>` carries an implicit conversion to `EventSourceId`, you can pass a typed identifier anywhere the untyped form is expected — including directly to `IEventLog.Append` — without any manual conversion. The typed form is most useful when you want the identifier to carry its concrete type through multiple layers so that callers always see the domain concept rather than a plain string.

## Frontend proxy generation

[Section titled “Frontend proxy generation”](#frontend-proxy-generation)

When you use `EventSourceId<T>` in a command or query parameter, the Arc ProxyGenerator reads the underlying type `T` and emits a TypeScript proxy that reflects the concrete type rather than a plain string. This gives you a fully typed frontend experience that matches the domain model on the server.

See `Arc.Chronicle.ProxyGeneration` for details on how proxy generation works and how to configure it.

# Filter observers by appended event metadata

Chronicle can filter reducers and reactors before they handle an appended event. You do this by putting filter attributes on the observer and appending matching metadata with the event.

## How filters correlate to append operations

[Section titled “How filters correlate to append operations”](#how-filters-correlate-to-append-operations)

| Append metadata    | Observer attribute           | Matches when                                            |
| ------------------ | ---------------------------- | ------------------------------------------------------- |
| `tags:`            | `[FilterEventsByTag("...")]` | Any appended or static event tag matches any filter tag |
| `eventSourceType:` | `[EventSourceType("...")]`   | The appended event source type matches exactly          |
| `eventStreamType:` | `[EventStreamType("...")]`   | The appended event stream type matches exactly          |

## Important distinctions

[Section titled “Important distinctions”](#important-distinctions)

* `[Tag]` and `[Tags]` on a reactor, reducer, or projection **label the observer itself**. They do not filter incoming events.
* `[FilterEventsByTag]`, `[EventSourceType]`, and `[EventStreamType]` on a reducer or reactor **filter which appended events are dispatched**.
* If you combine filter types, Chronicle applies them together. The event must satisfy every configured filter category.
* Multiple `[FilterEventsByTag]` attributes are additive. An event is dispatched when it matches any configured filter tag.

## Scope

[Section titled “Scope”](#scope)

Reducers and reactors use these filters during subscription. Projections still describe what they observe through event types, joins, and event sequence selection.

## Guides

[Section titled “Guides”](#guides)

* [Filter reducers and reactors by tag](/chronicle/events/filtering/by-tag/)
* [Filter reducers and reactors by event source type](/chronicle/events/filtering/by-event-source-type/)
* [Filter reducers and reactors by event stream type](/chronicle/events/filtering/by-event-stream-type/)

# Filter reducers and reactors by event source type

Use `[EventSourceType]` on a reducer or reactor when it should only handle events appended with a specific event source type.

## How the match works

[Section titled “How the match works”](#how-the-match-works)

Chronicle compares the observer attribute to the `eventSourceType:` value used when appending the event. If the values do not match, the reducer or reactor is skipped.

## Filter a reactor by event source type

[Section titled “Filter a reactor by event source type”](#filter-a-reactor-by-event-source-type)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record FilterBySourceTypeCustomerRegistered(string EmailAddress);

public class FilterBySourceTypeCustomerRegistrationService(IEventLog eventLog)
  {
      public Task Register(string emailAddress) =>
          eventLog.Append(
              EventSourceId.New(),
              new FilterBySourceTypeCustomerRegistered(emailAddress),
              eventSourceType: "customer");
  }

[EventSourceType("customer")]
  public class FilterBySourceTypeCustomerWelcomeReactor : IReactor
  {
      public Task Registered(FilterBySourceTypeCustomerRegistered @event, EventContext context) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.observation.EventSourceType
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class FilterBySourceTypeCustomerRegistered(val emailAddress: String = "")

suspend fun registerByEventSourceType(store: IEventStore, eventSourceId: String, emailAddress: String) =
      store.eventLog.append(
          eventSourceId,
          FilterBySourceTypeCustomerRegistered(emailAddress),
          AppendOptions(eventSourceType = "customer")
      )

@EventSourceType("customer")
  @Reactor
  class FilterBySourceTypeCustomerWelcomeReactor {
      fun customerRegistered(event: FilterBySourceTypeCustomerRegistered, context: EventContext) {
          // Only invoked for events appended with eventSourceType: "customer"
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.AppendOptions;
  import io.cratis.chronicle.eventSequences.AppendResult;
  import io.cratis.chronicle.observation.EventSourceType;
  import io.cratis.chronicle.observation.Reactor;

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

@EventType
  record FilterBySourceTypeCustomerRegistered(String emailAddress) {}

@EventSourceType("customer")
  @Reactor
  class FilterBySourceTypeCustomerWelcomeReactor {
      public void customerRegistered(FilterBySourceTypeCustomerRegistered event, EventContext context) {
          // Only invoked for events appended with eventSourceType: "customer"
      }
  }

class EventsFilteringByEventSourceTypeReactor {
      AppendResult register(EventStore store, String eventSourceId, String emailAddress) {
          AppendOptions options = new AppendOptionsBuilder().eventSourceType("customer").build();
          return EventLogJavaBridge.append(store.getEventLog(), eventSourceId, new FilterBySourceTypeCustomerRegistered(emailAddress), options);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The reactor is only invoked for events appended with `eventSourceType: "customer"`.

## Filter a reducer by event source type

[Section titled “Filter a reducer by event source type”](#filter-a-reducer-by-event-source-type)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reducers;

[EventType]
  public record FilterBySourceTypeInvoiceIssued(decimal Amount);

public record FilterBySourceTypeCustomerInvoiceTotal(decimal Amount);

[EventSourceType("customer")]
  public class FilterBySourceTypeCustomerInvoiceTotalReducer : IReducerFor<FilterBySourceTypeCustomerInvoiceTotal>
  {
      public FilterBySourceTypeCustomerInvoiceTotal Issued(FilterBySourceTypeInvoiceIssued @event, FilterBySourceTypeCustomerInvoiceTotal? current, EventContext context) =>
          new((current?.Amount ?? 0m) + @event.Amount);
  }

public class FilterBySourceTypeInvoicingService(IEventLog eventLog)
  {
      public Task IssueCustomerInvoice(decimal amount) =>
          eventLog.Append(
              EventSourceId.New(),
              new FilterBySourceTypeInvoiceIssued(amount),
              eventSourceType: "customer");
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.observation.EventSourceType
  import io.cratis.chronicle.observation.Reducer

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

data class FilterBySourceTypeCustomerInvoiceTotal(val amount: Double = 0.0)

@EventSourceType("customer")
  @Reducer
  class FilterBySourceTypeCustomerInvoiceTotalReducer {
      fun invoiceIssued(event: FilterBySourceTypeInvoiceIssued, current: FilterBySourceTypeCustomerInvoiceTotal?): FilterBySourceTypeCustomerInvoiceTotal =
          FilterBySourceTypeCustomerInvoiceTotal((current?.amount ?: 0.0) + event.amount)
  }

suspend fun issueCustomerInvoice(store: IEventStore, eventSourceId: String, amount: Double) =
      store.eventLog.append(eventSourceId, FilterBySourceTypeInvoiceIssued(amount), AppendOptions(eventSourceType = "customer"))
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.AppendOptions;
  import io.cratis.chronicle.eventSequences.AppendResult;
  import io.cratis.chronicle.observation.EventSourceType;
  import io.cratis.chronicle.observation.Reducer;

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

@EventType
  record FilterBySourceTypeInvoiceIssued(double amount) {}

record FilterBySourceTypeCustomerInvoiceTotal(double amount) {}

@EventSourceType("customer")
  @Reducer
  class FilterBySourceTypeCustomerInvoiceTotalReducer {
      public FilterBySourceTypeCustomerInvoiceTotal invoiceIssued(FilterBySourceTypeInvoiceIssued event, FilterBySourceTypeCustomerInvoiceTotal current) {
          double currentAmount = current != null ? current.amount() : 0.0;
          return new FilterBySourceTypeCustomerInvoiceTotal(currentAmount + event.amount());
      }
  }

class EventsFilteringByEventSourceTypeReducer {
      AppendResult issueCustomerInvoice(EventStore store, String eventSourceId, double amount) {
          AppendOptions options = new AppendOptionsBuilder().eventSourceType("customer").build();
          return EventLogJavaBridge.append(store.getEventLog(), eventSourceId, new FilterBySourceTypeInvoiceIssued(amount), options);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

If you append the same event with `eventSourceType: "supplier"`, this reducer does not receive it.

## Combine with other filters

[Section titled “Combine with other filters”](#combine-with-other-filters)

You can combine `[EventSourceType]` with `[FilterEventsByTag]` or `[EventStreamType]`. When you do, Chronicle requires all configured filter categories to match.

# Filter reducers and reactors by event stream type

Use `[EventStreamType]` on a reducer or reactor when it should only handle events appended to a specific stream type.

## How the match works

[Section titled “How the match works”](#how-the-match-works)

Chronicle compares the observer attribute to the `eventStreamType:` value used when appending the event. If the values do not match, the reducer or reactor is skipped.

## Filter a reactor by event stream type

[Section titled “Filter a reactor by event stream type”](#filter-a-reactor-by-event-stream-type)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record FilterByStreamTypePaymentCaptured(decimal Amount);

public class FilterByStreamTypePaymentsService(IEventLog eventLog)
  {
      public Task Capture(decimal amount) =>
          eventLog.Append(
              EventSourceId.New(),
              new FilterByStreamTypePaymentCaptured(amount),
              eventStreamType: "payments");
  }

[EventStreamType("payments")]
  public class FilterByStreamTypePaymentNotificationsReactor : IReactor
  {
      public Task Captured(FilterByStreamTypePaymentCaptured @event, EventContext context) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.observation.EventStreamType
  import io.cratis.chronicle.observation.Reactor

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

suspend fun capture(store: IEventStore, eventSourceId: String, amount: Double) =
      store.eventLog.append(eventSourceId, FilterByStreamTypePaymentCaptured(amount), AppendOptions(eventStreamType = "payments"))

@EventStreamType("payments")
  @Reactor
  class FilterByStreamTypePaymentNotificationsReactor {
      fun paymentCaptured(event: FilterByStreamTypePaymentCaptured, context: EventContext) {
          // Only handles events appended to the "payments" stream type
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.AppendOptions;
  import io.cratis.chronicle.eventSequences.AppendResult;
  import io.cratis.chronicle.observation.EventStreamType;
  import io.cratis.chronicle.observation.Reactor;

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

@EventType
  record FilterByStreamTypePaymentCaptured(double amount) {}

@EventStreamType("payments")
  @Reactor
  class FilterByStreamTypePaymentNotificationsReactor {
      public void paymentCaptured(FilterByStreamTypePaymentCaptured event, EventContext context) {
          // Only handles events appended to the "payments" stream type
      }
  }

class EventsFilteringByEventStreamTypeReactor {
      AppendResult capture(EventStore store, String eventSourceId, double amount) {
          AppendOptions options = new AppendOptionsBuilder().eventStreamType("payments").build();
          return EventLogJavaBridge.append(store.getEventLog(), eventSourceId, new FilterByStreamTypePaymentCaptured(amount), options);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The reactor only handles events appended to the `payments` stream type.

## Filter a reducer by event stream type

[Section titled “Filter a reducer by event stream type”](#filter-a-reducer-by-event-stream-type)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reducers;

[EventType]
  public record FilterByStreamTypeShipmentSent(decimal ShippingCost);

public record FilterByStreamTypeShippingTotals(decimal ShippingCost);

[EventStreamType("shipping")]
  public class FilterByStreamTypeShippingTotalsReducer : IReducerFor<FilterByStreamTypeShippingTotals>
  {
      public FilterByStreamTypeShippingTotals Sent(FilterByStreamTypeShipmentSent @event, FilterByStreamTypeShippingTotals? current, EventContext context) =>
          new((current?.ShippingCost ?? 0m) + @event.ShippingCost);
  }

public class FilterByStreamTypeShippingService(IEventLog eventLog)
  {
      public Task Send(decimal shippingCost) =>
          eventLog.Append(
              EventSourceId.New(),
              new FilterByStreamTypeShipmentSent(shippingCost),
              eventStreamType: "shipping");
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.observation.EventStreamType
  import io.cratis.chronicle.observation.Reducer

@EventType
  data class FilterByStreamTypeShipmentSent(val shippingCost: Double = 0.0)

data class FilterByStreamTypeShippingTotals(val shippingCost: Double = 0.0)

@EventStreamType("shipping")
  @Reducer
  class FilterByStreamTypeShippingTotalsReducer {
      fun shipmentSent(event: FilterByStreamTypeShipmentSent, current: FilterByStreamTypeShippingTotals?): FilterByStreamTypeShippingTotals =
          FilterByStreamTypeShippingTotals((current?.shippingCost ?: 0.0) + event.shippingCost)
  }

suspend fun send(store: IEventStore, eventSourceId: String, shippingCost: Double) =
      store.eventLog.append(eventSourceId, FilterByStreamTypeShipmentSent(shippingCost), AppendOptions(eventStreamType = "shipping"))
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.AppendOptions;
  import io.cratis.chronicle.eventSequences.AppendResult;
  import io.cratis.chronicle.observation.EventStreamType;
  import io.cratis.chronicle.observation.Reducer;

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

@EventType
  record FilterByStreamTypeShipmentSent(double shippingCost) {}

record FilterByStreamTypeShippingTotals(double shippingCost) {}

@EventStreamType("shipping")
  @Reducer
  class FilterByStreamTypeShippingTotalsReducer {
      public FilterByStreamTypeShippingTotals shipmentSent(FilterByStreamTypeShipmentSent event, FilterByStreamTypeShippingTotals current) {
          double currentCost = current != null ? current.shippingCost() : 0.0;
          return new FilterByStreamTypeShippingTotals(currentCost + event.shippingCost());
      }
  }

class EventsFilteringByEventStreamTypeReducer {
      AppendResult send(EventStore store, String eventSourceId, double shippingCost) {
          AppendOptions options = new AppendOptionsBuilder().eventStreamType("shipping").build();
          return EventLogJavaBridge.append(store.getEventLog(), eventSourceId, new FilterByStreamTypeShipmentSent(shippingCost), options);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

If the same event is appended with another stream type, such as `eventStreamType: "returns"`, this reducer does not receive it.

## When to choose stream type filtering

[Section titled “When to choose stream type filtering”](#when-to-choose-stream-type-filtering)

Use stream type filtering when the same event source can produce distinct processing flows and you want a reducer or reactor to observe only one of those flows.

# Filter reducers and reactors by tag

Use `[FilterEventsByTag]` when a reducer or reactor should only handle events that carry specific tags.

## What counts as a matching tag

[Section titled “What counts as a matching tag”](#what-counts-as-a-matching-tag)

Chronicle compares the filter tag against the tags on the appended event. Those tags can come from:

* `[Tag]` or `[Tags]` on the event type
* The `tags:` argument when you append the event

`[Tag]` and `[Tags]` on the reducer or reactor do not filter anything. They only label the observer itself.

## Filter a reactor by tag

[Section titled “Filter a reactor by tag”](#filter-a-reactor-by-tag)

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  [Tag("customer-lifecycle")]
  public record FilterByTagCustomerRegistered(string EmailAddress);

public class FilterByTagCustomerRegistrationService(IEventLog eventLog)
  {
      public Task Register(string emailAddress) =>
          eventLog.Append(
              EventSourceId.New(),
              new FilterByTagCustomerRegistered(emailAddress),
              tags: ["vip", "onboarding"]);
  }

[FilterEventsByTag("vip")]
  public class FilterByTagVipWelcomeReactor : IReactor
  {
      public Task Registered(FilterByTagCustomerRegistered @event, EventContext context) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.observation.FilterEventsByTag
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class FilterByTagCustomerRegistered(val emailAddress: String = "")

suspend fun registerByTag(store: IEventStore, eventSourceId: String, emailAddress: String) =
      store.eventLog.append(
          eventSourceId,
          FilterByTagCustomerRegistered(emailAddress),
          AppendOptions(tags = listOf("vip", "onboarding"))
      )

@FilterEventsByTag("vip")
  @Reactor
  class FilterByTagVipWelcomeReactor {
      fun customerRegistered(event: FilterByTagCustomerRegistered, context: EventContext) {
          // Only receives events appended with the "vip" tag
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.AppendOptions;
  import io.cratis.chronicle.eventSequences.AppendResult;
  import io.cratis.chronicle.observation.FilterEventsByTag;
  import io.cratis.chronicle.observation.Reactor;

import java.util.List;

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

@EventType
  record FilterByTagCustomerRegistered(String emailAddress) {}

@FilterEventsByTag("vip")
  @Reactor
  class FilterByTagVipWelcomeReactor {
      public void customerRegistered(FilterByTagCustomerRegistered event, EventContext context) {
          // Only receives events appended with the "vip" tag
      }
  }

class EventsFilteringByTagReactor {
      AppendResult register(EventStore store, String eventSourceId, String emailAddress) {
          AppendOptions options = new AppendOptionsBuilder().tags(List.of("vip", "onboarding")).build();
          return EventLogJavaBridge.append(store.getEventLog(), eventSourceId, new FilterByTagCustomerRegistered(emailAddress), options);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, filterEventsByTag, IEventStore, reactor, tag } from '@cratis/chronicle';

@eventType()
  @tag('customer-lifecycle')
  class FilterByTagCustomerRegistered {
      constructor(readonly emailAddress: string) {}
  }

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

async register(eventSourceId: string, emailAddress: string): Promise<void> {
          await this.store.eventLog.append(
              eventSourceId,
              new FilterByTagCustomerRegistered(emailAddress),
              { tags: ['vip', 'onboarding'] });
      }
  }

@reactor()
  @filterEventsByTag('vip')
  class FilterByTagVipWelcomeReactor {
      async filterByTagCustomerRegistered(_event: FilterByTagCustomerRegistered, _context: EventContext): Promise<void> {}
  }
  ```

The reactor receives the event because the append call added the `vip` tag.

## Filter a reducer by tag

[Section titled “Filter a reducer by tag”](#filter-a-reducer-by-tag)

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reducers;

[EventType]
  public record FilterByTagOrderPlaced(decimal TotalAmount);

public record FilterByTagPriorityOrderTotals(decimal TotalAmount);

[FilterEventsByTag("priority")]
  public class FilterByTagPriorityOrderTotalsReducer : IReducerFor<FilterByTagPriorityOrderTotals>
  {
      public FilterByTagPriorityOrderTotals Placed(FilterByTagOrderPlaced @event, FilterByTagPriorityOrderTotals? current, EventContext context) =>
          new((current?.TotalAmount ?? 0m) + @event.TotalAmount);
  }

public class FilterByTagCheckoutService(IEventLog eventLog)
  {
      public Task PlacePriorityOrder(decimal totalAmount) =>
          eventLog.Append(
              EventSourceId.New(),
              new FilterByTagOrderPlaced(totalAmount),
              tags: ["priority"]);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.observation.FilterEventsByTag
  import io.cratis.chronicle.observation.Reducer

@EventType
  data class FilterByTagOrderPlaced(val totalAmount: Double = 0.0)

data class FilterByTagPriorityOrderTotals(val totalAmount: Double = 0.0)

@FilterEventsByTag("priority")
  @Reducer
  class FilterByTagPriorityOrderTotalsReducer {
      fun orderPlaced(event: FilterByTagOrderPlaced, current: FilterByTagPriorityOrderTotals?): FilterByTagPriorityOrderTotals =
          FilterByTagPriorityOrderTotals((current?.totalAmount ?: 0.0) + event.totalAmount)
  }

suspend fun placePriorityOrder(store: IEventStore, eventSourceId: String, totalAmount: Double) =
      store.eventLog.append(eventSourceId, FilterByTagOrderPlaced(totalAmount), AppendOptions(tags = listOf("priority")))
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.AppendOptions;
  import io.cratis.chronicle.eventSequences.AppendResult;
  import io.cratis.chronicle.observation.FilterEventsByTag;
  import io.cratis.chronicle.observation.Reducer;

import java.util.List;

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

@EventType
  record FilterByTagOrderPlaced(double totalAmount) {}

record FilterByTagPriorityOrderTotals(double totalAmount) {}

@FilterEventsByTag("priority")
  @Reducer
  class FilterByTagPriorityOrderTotalsReducer {
      public FilterByTagPriorityOrderTotals orderPlaced(FilterByTagOrderPlaced event, FilterByTagPriorityOrderTotals current) {
          double currentTotal = current != null ? current.totalAmount() : 0.0;
          return new FilterByTagPriorityOrderTotals(currentTotal + event.totalAmount());
      }
  }

class EventsFilteringByTagReducer {
      AppendResult placePriorityOrder(EventStore store, String eventSourceId, double totalAmount) {
          AppendOptions options = new AppendOptionsBuilder().tags(List.of("priority")).build();
          return EventLogJavaBridge.append(store.getEventLog(), eventSourceId, new FilterByTagOrderPlaced(totalAmount), options);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, filterEventsByTag, IEventStore, reducer } from '@cratis/chronicle';

@eventType()
  class FilterByTagOrderPlaced {
      constructor(readonly totalAmount: number) {}
  }

class FilterByTagPriorityOrderTotals {
      totalAmount = 0;
  }

@reducer('', undefined, FilterByTagPriorityOrderTotals)
  @filterEventsByTag('priority')
  class FilterByTagPriorityOrderTotalsReducer {
      filterByTagOrderPlaced(
          event: FilterByTagOrderPlaced,
          current: FilterByTagPriorityOrderTotals | undefined
      ): FilterByTagPriorityOrderTotals {
          return { totalAmount: (current?.totalAmount ?? 0) + event.totalAmount };
      }
  }

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

async placePriorityOrder(eventSourceId: string, totalAmount: number): Promise<void> {
          await this.store.eventLog.append(
              eventSourceId,
              new FilterByTagOrderPlaced(totalAmount),
              { tags: ['priority'] });
      }
  }
  ```

The reducer only updates when the appended event carries the `priority` tag.

## Use multiple filter tags

[Section titled “Use multiple filter tags”](#use-multiple-filter-tags)

Multiple `[FilterEventsByTag]` attributes widen the match:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record FilterByTagMultiCustomerRegistered(string EmailAddress);

[FilterEventsByTag("vip")]
  [FilterEventsByTag("priority")]
  public class FilterByTagMultiPriorityNotificationsReactor : IReactor
  {
      public Task Registered(FilterByTagMultiCustomerRegistered @event) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.FilterEventsByTag
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class FilterByTagMultiCustomerRegistered(val emailAddress: String = "")

@FilterEventsByTag("vip")
  @FilterEventsByTag("priority")
  @Reactor
  class FilterByTagMultiPriorityNotificationsReactor {
      fun customerRegistered(event: FilterByTagMultiCustomerRegistered) {
          // Dispatched when the appended event carries either the "vip" or "priority" tag
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.FilterEventsByTag;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record FilterByTagMultiCustomerRegistered(String emailAddress) {}

@FilterEventsByTag("vip")
  @FilterEventsByTag("priority")
  @Reactor
  class FilterByTagMultiPriorityNotificationsReactor {
      public void customerRegistered(FilterByTagMultiCustomerRegistered event) {
          // Dispatched when the appended event carries either the "vip" or "priority" tag
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, filterEventsByTag, reactor } from '@cratis/chronicle';

@eventType()
  class FilterByTagMultiCustomerRegistered {
      constructor(readonly emailAddress: string) {}
  }

@reactor()
  @filterEventsByTag('vip')
  @filterEventsByTag('priority')
  class FilterByTagMultiPriorityNotificationsReactor {
      async filterByTagMultiCustomerRegistered(_event: FilterByTagMultiCustomerRegistered): Promise<void> {}
  }
  ```

Chronicle dispatches the event if it has either `vip` or `priority`.

# Getting events

Event sequences support multiple ways of reading events depending on your needs. The `IEventSequence` APIs (and the specialized `IEventLog`) cover common patterns such as:

* Reading events from a sequence in order
* Reading events for a specific event source
* Reading a range of events based on sequence numbers
* Reading a fixed number of events from the tail

Use the client APIs to select the pattern that best matches your scenario, such as replaying state, building read models, or auditing changes.

## Examples

[Section titled “Examples”](#examples)

### Read events for a single event source

[Section titled “Read events for a single event source”](#read-events-for-a-single-event-source)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using System.Collections.Immutable;

[EventType]
  public record GettingEventsOrderPlaced(string OrderId, decimal Total);

[EventType]
  public record GettingEventsOrderCancelled(string OrderId, string Reason);

public class GettingEventsOrderHistoryReader(IEventLog eventLog)
  {
      public async Task<IImmutableList<AppendedEvent>> GetOrderEvents(EventSourceId orderId)
      {
          // Filters the timeline to only the order events you care about.
          var eventTypes = new[]
          {
              typeof(GettingEventsOrderPlaced).GetEventType(),
              typeof(GettingEventsOrderCancelled).GetEventType()
          };

return await eventLog.GetForEventSourceIdAndEventTypes(orderId, eventTypes);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType

@EventType
  data class EventsForSourceAccountOpened(val accountId: String = "", val ownerName: String = "")

suspend fun getAccountOpenedEvents(store: IEventStore, accountId: String) =
      store.eventLog.getForEventSourceIdAndEventTypes(accountId, listOf(EventsForSourceAccountOpened::class))
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.AppendedEvent;

import java.util.List;

import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
  record EventsForSourceAccountOpened(String accountId, String ownerName) {}

class EventsGettingEventsForEventSource {
      List<AppendedEvent> getAccountOpenedEvents(EventStore store, String accountId) {
          return EventLogJavaBridge.getForEventSourceIdAndEventTypes(
              store.getEventLog(), accountId, List.of(EventsForSourceAccountOpened.class));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.GettingEventsOrderPlaced do
    use Chronicle.Events.EventType, id: "getting-events-order-placed"

defstruct [:order_id, :total]
  end

defmodule MyApp.Events.GettingEventsOrderCancelled do
    use Chronicle.Events.EventType, id: "getting-events-order-cancelled"

defstruct [:order_id, :reason]
  end

defmodule MyApp.GettingEventsOrderHistoryReader do
    alias Chronicle.EventSequences.EventLog
    alias MyApp.Events.{GettingEventsOrderCancelled, GettingEventsOrderPlaced}

def get_order_events(order_id) do
      # Filters the timeline to only the order events you care about.
      EventLog.get_for_event_source(order_id,
        event_types: [GettingEventsOrderPlaced, GettingEventsOrderCancelled]
      )
    end
  end
  ```

* TypeScript

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

@eventType()
  class GettingEventsOrderPlaced {
      constructor(readonly orderId: string = '', readonly total: number = 0) {}
  }

@eventType()
  class GettingEventsOrderCancelled {
      constructor(readonly orderId: string = '', readonly reason: string = '') {}
  }

async function getOrderEvents(store: IEventStore, orderId: string): Promise<void> {
      // Filters the timeline to only the order events you care about.
      const events = await store.eventLog.getForEventSourceIdAndEventTypes(
          orderId,
          [GettingEventsOrderPlaced, GettingEventsOrderCancelled]);

for (const event of events) {
          console.log(`${event.eventType.id.value} at sequence ${event.context.sequenceNumber}`);
      }
  }
  ```

Kotlin, Java, and TypeScript don’t currently expose a way to read raw events back for an event source — their public event sequence APIs only support appending and checking for existence.

### Read from a checkpoint

[Section titled “Read from a checkpoint”](#read-from-a-checkpoint)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using System.Collections.Immutable;

public class GettingEventsReplayEvents(IEventLog eventLog)
  {
      public async Task<IImmutableList<AppendedEvent>> ReadFrom(EventSequenceNumber sequenceNumber)
      {
          // Replays from a known checkpoint to rebuild projections or read models.
          return await eventLog.GetFromSequenceNumber(sequenceNumber);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.AppendedEvent
  import io.cratis.chronicle.eventSequences.EventSequenceNumber

/**
   * Replays every event from a known checkpoint onwards, across all event sources - useful for
   * rebuilding projections or read models from a saved position.
   */
  suspend fun readFrom(store: IEventStore, sequenceNumber: Long): List<AppendedEvent> =
      store.eventLog.getFromSequenceNumber(EventSequenceNumber(sequenceNumber))
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.eventSequences.AppendedEvent;

import java.util.List;

import io.cratis.chronicle.java.EventLogJavaBridge;

class EventsGettingEventsFromCheckpoint {
      // Replays every event from a known checkpoint onwards, across all event sources.
      List<AppendedEvent> readFrom(EventStore store, long sequenceNumber) {
          return EventLogJavaBridge.getFromSequenceNumber(store.getEventLog(), sequenceNumber, null, null);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.GettingEventsReplayEvents do
    alias Chronicle.EventSequences.EventLog

def read_from(sequence_number) do
      # Replays from a known checkpoint to rebuild projections or read models.
      EventLog.get_from_sequence_number(sequence_number)
    end
  end
  ```

* TypeScript

```typescript
  import { EventSequenceNumber, IEventStore } from '@cratis/chronicle';

async function readFrom(store: IEventStore, sequenceNumber: EventSequenceNumber): Promise<void> {
      // Replays from a known checkpoint to rebuild projections or read models.
      const events = await store.eventLog.getFromSequenceNumber(sequenceNumber);

for (const event of events) {
          console.log(`${event.eventType.id.value} at sequence ${event.context.sequenceNumber}`);
      }
  }
  ```

This is currently a C#-only capability — no other client exposes a way to resume reading from an arbitrary sequence number.

### Read the last events in a sequence

[Section titled “Read the last events in a sequence”](#read-the-last-events-in-a-sequence)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using System.Collections.Immutable;
  using System.Linq;

public class GettingEventsTailReader(IEventLog eventLog)
  {
      public async Task<IImmutableList<AppendedEvent>> ReadLast(int count)
      {
          // Reads from the computed start and trims in memory to the requested count.
          var tail = await eventLog.GetTailSequenceNumber();
          var start = tail.IsActualValue && tail.Value >= (ulong)count
              ? tail - (count - 1)
              : EventSequenceNumber.First;

var events = await eventLog.GetFromSequenceNumber(start);
          return events.TakeLast(count).ToImmutableList();
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.AppendedEvent
  import io.cratis.chronicle.eventSequences.EventSequenceNumber

/**
   * Reads from a computed start position and trims in memory to the requested count.
   */
  suspend fun readLast(store: IEventStore, count: Int): List<AppendedEvent> {
      val tail = store.eventLog.getTailSequenceNumber()
      val start = if (tail.isActualValue && tail.value >= count - 1) {
          EventSequenceNumber(tail.value - (count - 1))
      } else {
          EventSequenceNumber.first
      }

val events = store.eventLog.getFromSequenceNumber(start)
      return events.takeLast(count)
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.eventSequences.AppendedEvent;

import java.util.List;

import io.cratis.chronicle.java.EventLogJavaBridge;

class EventsGettingEventsTail {
      // Reads from a computed start position and trims in memory to the requested count.
      // The tail sequence number bridge returns -1 when the sequence is unavailable (empty).
      List<AppendedEvent> readLast(EventStore store, int count) {
          long tail = EventLogJavaBridge.getTailSequenceNumber(store.getEventLog(), null);
          long start = tail >= 0 && tail >= count - 1 ? tail - (count - 1) : 0;

List<AppendedEvent> events = EventLogJavaBridge.getFromSequenceNumber(store.getEventLog(), start, null, null);
          return events.size() > count ? events.subList(events.size() - count, events.size()) : events;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.GettingEventsTailReader do
    alias Chronicle.EventSequences.EventLog

def read_last(count) do
      # Reads from the computed start and trims in memory to the requested count.
      with {:ok, tail} <- EventLog.get_tail_sequence_number() do
        start = if tail >= count, do: tail - (count - 1), else: 0

with {:ok, events} <- EventLog.get_from_sequence_number(start) do
          {:ok, Enum.take(events, -count)}
        end
      end
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

async function reportSequencePosition(store: IEventStore): Promise<void> {
      // The tail is the most recently appended event; unset (EventSequenceNumber.unset)
      // when the sequence is empty.
      const tail = await store.eventLog.getTailSequenceNumber();

// getNextSequenceNumber is one past the tail, or EventSequenceNumber.first when
      // empty - the sequence number the next appended event will receive.
      const next = await store.eventLog.getNextSequenceNumber();

console.log(`Tail: ${tail.value}, next append will be at: ${next.value}`);
  }
  ```

Reading the tail this way also relies on resuming from a sequence number, so it’s currently C#-only too. Kotlin, Java, and TypeScript can still get the tail sequence *number* (see [Getting state](/chronicle/events/getting-state/)), just not the events at it.

# Getting state

Event sequence state provides information about how far a sequence has progressed. The most common state value is the tail sequence number, which represents the latest event appended to the sequence. Use the `IEventSequence` APIs, such as `GetTailSequenceNumber` and related state calls, to capture the current position.

Use sequence state for scenarios such as:

* Tracking progress for consumers and observers
* Capturing a point in time for read model time travel
* Avoiding duplicate processing when resuming work

For point-in-time reads of read models, capture the sequence position from the event sequence state and use it alongside the read model APIs described in the read models guides.

Related reading:

* [Getting a Collection of Instances](/chronicle/read-models/getting-collection-instances/)

## Examples

[Section titled “Examples”](#examples)

### Capture the tail for a checkpoint

[Section titled “Capture the tail for a checkpoint”](#capture-the-tail-for-a-checkpoint)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class GettingStateCheckpointStore(IEventLog eventLog)
  {
      public async Task<EventSequenceNumber> CaptureTail()
      {
          // Persists the current tail so processing can resume later.
          return await eventLog.GetTailSequenceNumber();
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore

suspend fun getAccountTailSequenceNumber(store: IEventStore, accountId: String): Long {
      val tail = store.eventLog.getTailSequenceNumber(accountId)
      println("Tail sequence number for $accountId: ${tail.value}")
      return tail.value
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;

import io.cratis.chronicle.java.EventLogJavaBridge;

class EventsGettingStateTail {
      long getAccountTailSequenceNumber(EventStore store, String accountId) {
          long tail = EventLogJavaBridge.getTailSequenceNumber(store.getEventLog(), accountId);
          System.out.println("Tail sequence number for " + accountId + ": " + tail);
          return tail;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.GettingStateCheckpointStore do
    def capture_tail do
      # Persists the current tail so processing can resume later.
      Chronicle.get_tail_sequence_number()
    end
  end
  ```

* TypeScript

```typescript
  import { EventSequenceNumber, IEventStore } from '@cratis/chronicle';

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

async captureTail(): Promise<EventSequenceNumber> {
          // Persists the current tail so processing can resume later.
          return await this.store.eventLog.getTailSequenceNumber();
      }
  }
  ```

Kotlin and Java don’t currently expose a way to read the tail sequence number at all — their public event sequence APIs only support appending and checking for existence.

### Capture the tail for a specific event source and event types

[Section titled “Capture the tail for a specific event source and event types”](#capture-the-tail-for-a-specific-event-source-and-event-types)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

[EventType]
  public record GettingStateInventoryAdjusted(string Sku, int Delta);

[EventType]
  public record GettingStateInventoryReserved(string Sku, int Quantity);

public class GettingStateInventoryCheckpoint(IEventLog eventLog)
  {
      public async Task<EventSequenceNumber> CaptureFor(EventSourceId inventoryId)
      {
          // Scopes the tail to a specific stream of inventory events.
          var eventTypes = new[]
          {
              typeof(GettingStateInventoryAdjusted).GetEventType(),
              typeof(GettingStateInventoryReserved).GetEventType()
          };

return await eventLog.GetTailSequenceNumber(
              eventSourceId: inventoryId,
              filterEventTypes: eventTypes
          );
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.EventSequenceNumber

/**
   * Scopes the tail sequence number to a specific event source, rather than the whole event log.
   */
  suspend fun captureFor(store: IEventStore, inventoryId: String): EventSequenceNumber =
      store.eventLog.getTailSequenceNumber(eventSourceId = inventoryId)
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;

import io.cratis.chronicle.java.EventLogJavaBridge;

class EventsGettingStateTailForEventSource {
      // Scopes the tail sequence number to a specific event source, rather than the whole event log.
      long captureFor(EventStore store, String inventoryId) {
          return EventLogJavaBridge.getTailSequenceNumber(store.getEventLog(), inventoryId);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

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

@eventType()
  class GettingStateInventoryAdjusted {
      constructor(readonly sku: string, readonly delta: number) {}
  }

@eventType()
  class GettingStateInventoryReserved {
      constructor(readonly sku: string, readonly quantity: number) {}
  }

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

// Scopes the tail to a specific stream of inventory events.
      captureFor(inventoryId: string): Promise<EventSequenceNumber> {
          return this.eventLog.getTailSequenceNumber(
              inventoryId,
              undefined,
              undefined,
              undefined,
              [GettingStateInventoryAdjusted, GettingStateInventoryReserved]
          );
      }
  }
  ```

This scoped form (filtering by event source and event types) is currently C#-only. Elixir and TypeScript can capture the *overall* tail (see above), but neither exposes a way to scope it to specific event types.

### Check whether an observer is caught up

[Section titled “Check whether an observer is caught up”](#check-whether-an-observer-is-caught-up)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class GettingStateObserverProgress(IEventSequence eventSequence)
  {
      public async Task<EventSequenceNumber> GetRelevantTail(Type observerType)
      {
          // Uses the observer's event type filters to compute the relevant tail.
          return await eventSequence.GetTailSequenceNumberForObserver(observerType);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.eventSequences.EventSequenceNumber
  import io.cratis.chronicle.eventSequences.IEventSequence
  import kotlin.reflect.KClass

/**
   * Computes the tail sequence number relevant to a specific observer, based on the event types
   * it handles.
   */
  suspend fun getRelevantTail(eventSequence: IEventSequence, observerType: KClass<*>): EventSequenceNumber =
      eventSequence.getTailSequenceNumberForObserver(observerType)
  ```

* Java

```java
  import io.cratis.chronicle.eventSequences.IEventLog;
  import io.cratis.chronicle.java.EventLogJavaBridge;

class TailForObserverExample {
      /**
       * Computes the tail sequence number relevant to a specific observer, based on the event types
       * it handles.
       */
      static long getRelevantTail(IEventLog eventLog, Class<?> observerType) {
          return EventLogJavaBridge.getTailSequenceNumberForObserver(eventLog, observerType);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.GettingStateObserverProgressSomethingHappened do
    use Chronicle.Events.EventType, id: "getting-state-observer-progress-something-happened"

defstruct []
  end

defmodule MyApp.Reactors.GettingStateObserverProgressReactor do
    use Chronicle.Reactors.Reactor

alias MyApp.Events.GettingStateObserverProgressSomethingHappened

@handles GettingStateObserverProgressSomethingHappened

@impl true
    def handle(%GettingStateObserverProgressSomethingHappened{}, _context), do: :ok
  end

defmodule MyApp.GettingStateObserverProgress do
    alias Chronicle.EventSequences.EventLog
    alias MyApp.Reactors.GettingStateObserverProgressReactor

def get_relevant_tail do
      # Uses the reactor's @handles event types to compute the relevant tail.
      EventLog.get_tail_sequence_number_for_observer(GettingStateObserverProgressReactor)
    end
  end
  ```

* TypeScript

```typescript
  import { Constructor } from '@cratis/fundamentals';
  import { EventSequenceNumber, IEventSequence } from '@cratis/chronicle';

class GettingStateObserverProgress {
      constructor(private readonly eventSequence: IEventSequence) {}

// Uses the observer's event type filters to compute the relevant tail.
      getRelevantTail(observerType: Constructor): Promise<EventSequenceNumber> {
          return this.eventSequence.getTailSequenceNumberForObserver(observerType);
      }
  }
  ```

Computing the relevant tail for a specific observer is currently a C#-only capability.

# Observing Append Operations

`IEventSequence` exposes an `AppendOperations` observable that emits after every `Append` or `AppendMany` call on that sequence. Any code can subscribe to this observable to react to appended events in real time — without polling the event log.

## AppendOperations

[Section titled “AppendOperations”](#appendoperations)

* C#

```csharp
  using Cratis.Chronicle.EventSequences;

public interface IObservingAppendsEventSequence
  {
      IObservable<IEnumerable<AppendedEventWithResult>> AppendOperations { get; }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.eventSequences.AppendedEventWithResult
  import kotlinx.coroutines.flow.SharedFlow

/**
   * The shape of [io.cratis.chronicle.eventSequences.IEventSequence.appendOperations] - a hot
   * [SharedFlow] that emits after every [io.cratis.chronicle.eventSequences.IEventSequence.append]
   * or [io.cratis.chronicle.eventSequences.IEventSequence.appendMany] call made through that instance.
   */
  interface EventSequenceAppendOperationsShape {
      val appendOperations: SharedFlow<List<AppendedEventWithResult>>
  }
  ```

* Java

```java
  import io.cratis.chronicle.eventSequences.AppendedEventWithResult;
  import io.cratis.chronicle.eventSequences.IEventLog;

import java.util.List;
  import java.util.function.Consumer;

import kotlinx.coroutines.Job;

// The shape of the Java bridge for observing append operations: EventLogJavaBridge.watchAppendOperations
  // subscribes a callback that receives a list of AppendedEventWithResult after every append or
  // appendMany call made through the event log, returning the Job backing the subscription.
  interface EventSequenceAppendOperationsShape {
      Job watchAppendOperations(IEventLog eventLog, Consumer<List<AppendedEventWithResult>> callback);
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { AppendedEventWithResult } from '@cratis/chronicle';

// eventLog.appendOperations is an AsyncIterable<AppendedEventWithResult[]> - a hot,
  // multicast stream: iterating it yields every batch of events appended through this
  // specific event log instance from the moment you start iterating (never for
  // transactional appends, and never replayed for a late subscriber).
  type ObservingAppendsShape = AsyncIterable<AppendedEventWithResult[]>;
  ```

The observable emits a collection of `AppendedEventWithResult` after each operation:

* A single-event `Append` emits a collection containing one element.
* A batch `AppendMany` emits the full batch as one collection.

Each `AppendedEventWithResult` pairs the appended event with its result:

| Member          | Type            | Description                                                              |
| --------------- | --------------- | ------------------------------------------------------------------------ |
| `Event`         | `AppendedEvent` | The appended event, including context and deserialized content           |
| `Event.Content` | `object`        | The deserialized event object                                            |
| `Event.Context` | `EventContext`  | Metadata: event source, sequence number, correlation ID, causation chain |
| `Result`        | `AppendResult`  | Success flag, sequence number, violations, and errors                    |

Subscribers receive the notification after the operation has completed, whether it succeeded or failed. This observable does not fire for transactional appends through `ITransactionalEventSequence`.

## Subscribing

[Section titled “Subscribing”](#subscribing)

Inject `IEventSequence` (or `IEventLog`) and subscribe to `AppendOperations`:

* C#

```csharp
  using Cratis.Chronicle.EventSequences;

public class ObservingAppendsMonitor(IEventLog eventLog) : IDisposable
  {
      readonly IDisposable _subscription = eventLog.AppendOperations.Subscribe(OnAppended);

static void OnAppended(IEnumerable<AppendedEventWithResult> operations)
      {
          foreach (var item in operations)
          {
              Console.WriteLine($"Event {item.Event.Content.GetType().Name} appended: success={item.Result.IsSuccess}");
          }
      }

public void Dispose() => _subscription.Dispose();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.eventSequences.IEventLog
  import kotlinx.coroutines.CoroutineScope
  import kotlinx.coroutines.launch

/**
   * Collects append operations for as long as [scope] is active, logging each appended event's
   * outcome.
   */
  class AppendMonitor(eventLog: IEventLog, scope: CoroutineScope) {
      init {
          scope.launch {
              eventLog.appendOperations.collect { operations ->
                  operations.forEach { println("Event ${it.event::class.simpleName} appended: success=${it.result.isSuccess}") }
              }
          }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.eventSequences.IEventLog;

import io.cratis.chronicle.java.EventLogJavaBridge;
  import kotlinx.coroutines.Job;

class EventsObservingAppendsSubscribing {
      // Subscribes to append operations for the lifetime of the returned Job; cancel it to stop.
      Job subscribe(IEventLog eventLog) {
          return EventLogJavaBridge.watchAppendOperations(eventLog, operations ->
              operations.forEach(operation ->
                  System.out.println("Event " + operation.getEvent().getClass().getSimpleName() +
                      " appended: success=" + operation.getResult().isSuccess())));
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IEventLog } from '@cratis/chronicle';

async function monitorAppends(eventLog: IEventLog): Promise<void> {
      for await (const operations of eventLog.appendOperations) {
          for (const item of operations) {
              console.log(`Event ${item.event.eventType.id.value} appended: success=${item.result.isSuccess}`);
          }
      }
  }
  ```

Always dispose the subscription when you no longer need it to avoid resource leaks.

## Integration Testing

[Section titled “Integration Testing”](#integration-testing)

The most common use of `AppendOperations` in application code is through the `IEventAppendCollection` helper provided by `Cratis.Chronicle.XUnit.Integration`. It subscribes internally and provides a ready-to-assert collection of `AppendedEventWithResult` entries. See `Chronicle.Testing.EventAppendCollection` for full details.

## Waiting for Observer Completion After Append

[Section titled “Waiting for Observer Completion After Append”](#waiting-for-observer-completion-after-append)

When you need to wait until observers affected by an append operation have completed, use `WaitForCompletion()` from the `Cratis.Chronicle.Observation` namespace.

If any affected observer fails while catching up, the returned result includes failed partitions.

Waiting only means something when there are observers behind the connection. The in-process testing surfaces (`EventScenario` and `EventStoreForTesting`) run the event sequence without a silo, so an append there never reaches a projection, reducer, or reactor. Rather than report that everything completed, `WaitForCompletion()` throws `CannotWaitForObserverCompletion` on an append result that carries no observer surface — assert on the scenario’s own surface, or move the check to an out-of-process integration spec where observers genuinely run.

### Append

[Section titled “Append”](#append)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Observation;

[EventType]
  public record ObservingAppendsSomeEvent(string Data);

public class ObservingAppendsCompletionWaiter(IEventLog eventLog)
  {
      public async Task AppendAndWait(EventSourceId eventSourceId)
      {
          var appendResult = await eventLog.Append(eventSourceId, new ObservingAppendsSomeEvent("example"));
          var completion = await appendResult.WaitForCompletion();

if (!completion.IsSuccess)
          {
              foreach (var failedPartition in completion.FailedPartitions)
              {
                  Console.WriteLine($"Observer {failedPartition.ObserverId} failed partition {failedPartition.Partition}");
              }
          }
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ObservingAppendsSomeEvent do
    use Chronicle.Events.EventType, id: "observing-appends-some-event"

defstruct [:data]
  end

defmodule MyApp.ObservingAppendsCompletionWaiter do
    alias Chronicle.EventSequences.EventLog
    alias MyApp.Events.ObservingAppendsSomeEvent

def append_and_wait(event_source_id) do
      case EventLog.append_and_wait_for_completion(event_source_id, %ObservingAppendsSomeEvent{
             data: "example"
           }) do
        {:ok, %{success: true}} ->
          :ok

{:ok, %{success: false, failed_partitions: failed_partitions}} ->
          Enum.each(failed_partitions, fn failed_partition ->
            IO.puts("Observer failed partition: #{inspect(failed_partition)}")
          end)

{:error, reason} ->
          {:error, reason}
      end
    end
  end
  ```

* TypeScript

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

@eventType()
  class ObservingAppendsSomeEvent {
      constructor(readonly data: string = '') {}
  }

async function appendAndWait(eventLog: IEventLog, eventSourceId: string): Promise<void> {
      const appendResult = await eventLog.append(eventSourceId, new ObservingAppendsSomeEvent('example'));
      const completion = await appendResult.waitForCompletion();

if (!completion.isSuccess) {
          for (const failedPartition of completion.failedPartitions) {
              console.log(`Observer ${failedPartition.observerId} failed partition ${failedPartition.partition}`);
          }
      }
  }
  ```

### AppendMany

[Section titled “AppendMany”](#appendmany)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Observation;

[EventType]
  public record ObservingAppendsFirstEvent(string Data);

[EventType]
  public record ObservingAppendsSecondEvent(string Data);

public class ObservingAppendsBatchCompletionWaiter(IEventLog eventLog)
  {
      public async Task AppendManyAndWait(EventSourceId eventSourceId)
      {
          var appendManyResult = await eventLog.AppendMany(eventSourceId, new object[]
          {
              new ObservingAppendsFirstEvent("first"),
              new ObservingAppendsSecondEvent("second")
          });

var completion = await appendManyResult.WaitForCompletion();
          if (!completion.IsSuccess)
          {
              // Inspect failed partitions from affected observers
          }
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

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

@eventType()
  class ObservingAppendsFirstEvent {
      constructor(readonly data: string = '') {}
  }

@eventType()
  class ObservingAppendsSecondEvent {
      constructor(readonly data: string = '') {}
  }

async function appendManyAndWait(eventLog: IEventLog, eventSourceId: string): Promise<void> {
      const appendManyResults = await eventLog.appendMany(eventSourceId, [
          new ObservingAppendsFirstEvent('first'),
          new ObservingAppendsSecondEvent('second')
      ]);

for (const appendResult of appendManyResults) {
          const completion = await appendResult.waitForCompletion();
          if (!completion.isSuccess) {
              // Inspect completion.failedPartitions from affected observers.
          }
      }
  }
  ```

# Event Redaction

Redaction removes the meaningful content of a previously appended event when you need to erase data — for example, to comply with a right-to-erasure request. Rather than deleting the event entirely, Chronicle replaces the event’s payload with a redaction marker that preserves the sequence number, original event type, and the full audit context of both the original event and the redaction action itself.

## Why redaction keeps the event slot

[Section titled “Why redaction keeps the event slot”](#why-redaction-keeps-the-event-slot)

Events are immutable, and their sequence numbers are permanent identifiers. Observers, projections, and reducers may have already processed an event and advanced their positions based on those sequence numbers. Removing the slot entirely would corrupt every downstream position. Redaction instead replaces the content in-place, changes the event type to the internal `EventRedacted` type, and stores the reason and the original context alongside it.

This means:

* Observers that replay the event see only the redaction marker, not the original data.
* Positions and sequence numbers remain stable and consistent.
* An auditor can still determine that an event existed at that position and who requested its removal.

## When to use redaction

[Section titled “When to use redaction”](#when-to-use-redaction)

Redact an event when:

* A regulation or legal request (e.g. GDPR right to erasure) requires that personal data be removed.
* An event was appended in error and contains sensitive information that must not be retained.
* You need to wipe all events associated with a specific event source (e.g. a user account deletion).

Do not use redaction as a way to undo domain decisions. If a correction is being made in the domain — for example, a cancellation, reversal, or override — model that as a new event instead.

## Redacting a single event

[Section titled “Redacting a single event”](#redacting-a-single-event)

To redact one specific event by its sequence number, call `Redact` on the event sequence and provide a reason:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class RedactionUnknownReasonService(IEventLog eventLog)
  {
      public Task Redact(EventSequenceNumber sequenceNumber) =>
          eventLog.Redact(sequenceNumber, RedactionReason.Unknown);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.EventSequenceNumber
  import io.cratis.chronicle.eventSequences.RedactionReason

/**
   * Redacts a single event by sequence number without stating a specific reason.
   */
  suspend fun redactUnknown(store: IEventStore, sequenceNumber: Long) =
      store.eventLog.redact(EventSequenceNumber(sequenceNumber), RedactionReason.unknown)
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;

import io.cratis.chronicle.java.EventLogJavaBridge;

class EventsRedactionBySequenceNumberUnknown {
      // Redacts a single event by sequence number without stating a specific reason. "Unknown" is
      // the same value RedactionReason.unknown carries on the wire.
      void redact(EventStore store, long sequenceNumber) {
          EventLogJavaBridge.redact(store.getEventLog(), sequenceNumber, "Unknown");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.RedactionUnknownReasonService do
    alias Chronicle.EventSequences.EventLog

def redact(sequence_number) do
      EventLog.redact(sequence_number, "Unknown")
    end
  end
  ```

* TypeScript

```typescript
  import { EventSequenceNumber, IEventLog } from '@cratis/chronicle';

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

// The TypeScript client always requires an explicit reason - there is no
      // "unknown reason" default overload.
      redact(sequenceNumber: EventSequenceNumber): Promise<void> {
          return this.eventLog.redact(sequenceNumber, 'Unknown');
      }
  }
  ```

Always provide a meaningful reason when possible:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class RedactionWithReasonService(IEventLog eventLog)
  {
      public Task Redact(EventSequenceNumber sequenceNumber) =>
          eventLog.Redact(sequenceNumber, new RedactionReason("GDPR erasure request"));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.EventSequenceNumber
  import io.cratis.chronicle.eventSequences.RedactionReason

/**
   * Redacts a single event by sequence number with a meaningful reason.
   */
  suspend fun redactWithReason(store: IEventStore, sequenceNumber: Long) =
      store.eventLog.redact(EventSequenceNumber(sequenceNumber), RedactionReason("GDPR erasure request"))
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;

import io.cratis.chronicle.java.EventLogJavaBridge;

class EventsRedactionBySequenceNumberWithReason {
      // Redacts a single event by sequence number with a meaningful reason.
      void redact(EventStore store, long sequenceNumber) {
          EventLogJavaBridge.redact(store.getEventLog(), sequenceNumber, "GDPR erasure request");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.RedactionWithReasonService do
    alias Chronicle.EventSequences.EventLog

def redact(sequence_number) do
      EventLog.redact(sequence_number, "GDPR erasure request")
    end
  end
  ```

* TypeScript

```typescript
  import { EventSequenceNumber, IEventLog } from '@cratis/chronicle';

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

redact(sequenceNumber: EventSequenceNumber): Promise<void> {
          return this.eventLog.redact(sequenceNumber, 'GDPR erasure request');
      }
  }
  ```

## Redacting all events for an event source

[Section titled “Redacting all events for an event source”](#redacting-all-events-for-an-event-source)

To redact every event associated with a particular event source — for example, to erase all data for a specific user — pass the event source identifier and a reason:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class RedactionByEventSourceService(IEventLog eventLog)
  {
      public Task RedactAccount(EventSourceId eventSourceId) =>
          eventLog.Redact(eventSourceId, new RedactionReason("Account deletion requested"));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.RedactionReason

/**
   * Redacts every event associated with a particular event source - for example, to erase all
   * data for a specific user.
   */
  suspend fun redactAccount(store: IEventStore, eventSourceId: String) =
      store.eventLog.redactForEventSource(eventSourceId, RedactionReason("Account deletion requested"))
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;

import java.util.List;

import io.cratis.chronicle.java.EventLogJavaBridge;

class EventsRedactionByEventSource {
      // Redacts every event associated with a particular event source.
      void redactAccount(EventStore store, String eventSourceId) {
          EventLogJavaBridge.redactForEventSource(store.getEventLog(), eventSourceId, "Account deletion requested", List.of());
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.RedactionByEventSourceService do
    alias Chronicle.EventSequences.EventLog

def redact_account(event_source_id) do
      EventLog.redact_for_event_source(event_source_id, "Account deletion requested")
    end
  end
  ```

* TypeScript

```typescript
  import { IEventLog } from '@cratis/chronicle';

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

redactAccount(eventSourceId: string): Promise<void> {
          return this.eventLog.redactForEventSource(eventSourceId, 'Account deletion requested');
      }
  }
  ```

If you only want to redact a specific type of event rather than all events for the event source, provide the event types:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

[EventType]
  public record RedactionPersonalDetailsRecorded(string Name, string SocialSecurityNumber);

[EventType]
  public record RedactionAddressChanged(string Street, string City);

public class RedactionByEventSourceAndTypesService(IEventLog eventLog)
  {
      public Task RedactPersonalData(EventSourceId eventSourceId) =>
          eventLog.Redact(
              eventSourceId,
              new RedactionReason("PII erasure"),
              typeof(RedactionPersonalDetailsRecorded),
              typeof(RedactionAddressChanged));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.RedactionReason

@EventType
  data class RedactionPersonalDetailsRecorded(val name: String = "", val socialSecurityNumber: String = "")

@EventType
  data class RedactionAddressChanged(val street: String = "", val city: String = "")

/**
   * Redacts only the given event types for an event source, leaving every other event type intact.
   */
  suspend fun redactPersonalData(store: IEventStore, eventSourceId: String) =
      store.eventLog.redactForEventSource(
          eventSourceId,
          RedactionReason("PII erasure"),
          listOf(RedactionPersonalDetailsRecorded::class, RedactionAddressChanged::class)
      )
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventType;

import java.util.List;

import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
  record RedactionPersonalDetailsRecorded(String name, String socialSecurityNumber) {}

@EventType
  record RedactionAddressChanged(String street, String city) {}

class EventsRedactionByEventSourceAndTypes {
      // Redacts only the given event types for an event source, leaving every other event type intact.
      void redactPersonalData(EventStore store, String eventSourceId) {
          EventLogJavaBridge.redactForEventSource(
              store.getEventLog(),
              eventSourceId,
              "PII erasure",
              List.of(RedactionPersonalDetailsRecorded.class, RedactionAddressChanged.class));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.RedactionPersonalDetailsRecorded do
    use Chronicle.Events.EventType, id: "redaction-personal-details-recorded"

defstruct [:name, :social_security_number]
  end

defmodule MyApp.Events.RedactionAddressChanged do
    use Chronicle.Events.EventType, id: "redaction-address-changed"

defstruct [:street, :city]
  end

defmodule MyApp.RedactionByEventSourceAndTypesService do
    alias Chronicle.EventSequences.EventLog
    alias MyApp.Events.{RedactionAddressChanged, RedactionPersonalDetailsRecorded}

def redact_personal_data(event_source_id) do
      EventLog.redact_for_event_source(event_source_id, "PII erasure", [
        RedactionPersonalDetailsRecorded,
        RedactionAddressChanged
      ])
    end
  end
  ```

* TypeScript

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

@eventType()
  class RedactionPersonalDetailsRecorded {
      constructor(readonly name: string = '', readonly socialSecurityNumber: string = '') {}
  }

@eventType()
  class RedactionAddressChanged {
      constructor(readonly street: string = '', readonly city: string = '') {}
  }

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

redactPersonalData(eventSourceId: string): Promise<void> {
          return this.eventLog.redactForEventSource(
              eventSourceId,
              'PII erasure',
              [RedactionPersonalDetailsRecorded, RedactionAddressChanged]);
      }
  }
  ```

## How it works

[Section titled “How it works”](#how-it-works)

Redaction is modelled as a system event in the system event sequence. When you call `Redact`, Chronicle appends an `EventRedactionRequested` (for a single event) or an `EventsRedactedForEventSource` (for an event source) system event to the internal system sequence. A built-in reactor observes these system events and performs the actual in-place replacement in the target event sequence.

The replacement stores an `EventRedacted` content record inside the event document that captures:

* The reason for the redaction.
* The original event type, so auditors know what kind of event was removed.
* The `Occurred`, `CorrelationId`, `Causation`, and `CausedBy` of the **original** event, preserving its full provenance.

The event’s own context fields are then updated to reflect the time and identity of the redaction action, giving a complete two-sided audit record.

## Observing redacted events in Reactors and Reducers

[Section titled “Observing redacted events in Reactors and Reducers”](#observing-redacted-events-in-reactors-and-reducers)

When an event is redacted, the `EventRedacted` event is dispatched to any observer that was subscribed to the original event type and also includes `EventRedacted` in its subscription. This lets Reactors and Reducers react to the removal of data — for example, to clean up read models or trigger downstream notifications.

### Why subscribe to `EventRedacted`?

[Section titled “Why subscribe to EventRedacted?”](#why-subscribe-to-eventredacted)

* **Read model cleanup**: If a Reducer builds state from an event that is later redacted, subscribing to `EventRedacted` lets you remove or anonymise that state in reaction.
* **Audit and notifications**: A Reactor can notify external systems or write a compliance log entry whenever sensitive data is erased.
* **Cross-aggregate side effects**: If redacting one event should trigger cancellations or clean-up in other parts of the system, a Reactor can coordinate that work.

### Subscribing in a Reactor

[Section titled “Subscribing in a Reactor”](#subscribing-in-a-reactor)

Add a handler method that accepts `EventRedacted` alongside the event type(s) you already handle. The Kernel will only dispatch `EventRedacted` to your Reactor when the redacted event belongs to a type that your Reactor is also subscribed to.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record RedactionPersonRegistered(string Name);

public class RedactionPersonReactor : IReactor
  {
      public Task Registered(RedactionPersonRegistered @event, EventContext context)
      {
          // Handle the original event
          return Task.CompletedTask;
      }

public Task Redacted(EventRedacted @event, EventContext context)
      {
          // Called only when a RedactionPersonRegistered event (a type this reactor handles) is redacted.
          // @event.OriginalEventType is typeof(RedactionPersonRegistered).
          // Use this to undo any side effects produced by the original event.
          return Task.CompletedTask;
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The `EventRedacted` record is defined in `Cratis.Chronicle.Events` and carries:

| Property            | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `Reason`            | The `RedactionReason` provided at the time of redaction. |
| `OriginalEventType` | The CLR `Type` of the event that was redacted.           |
| `Occurred`          | When the original event occurred.                        |
| `CorrelationId`     | The correlation identifier of the original event.        |
| `Causation`         | The full causation chain of the original event.          |
| `CausedBy`          | The identity chain that caused the original event.       |

### Subscribing in a Reducer

[Section titled “Subscribing in a Reducer”](#subscribing-in-a-reducer)

The same approach applies to Reducers. Include `EventRedacted` handling inside the `IReducerFor<TReadModel>` implementation to update the read model when a source event is erased.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reducers;

[EventType]
  public record RedactionReducerPersonRegistered(string Name);

public record RedactionPersonReadModel(string Name);

public class RedactionPersonReadModelReducer : IReducerFor<RedactionPersonReadModel>
  {
      public RedactionPersonReadModel Registered(RedactionReducerPersonRegistered @event, RedactionPersonReadModel? current, EventContext context) =>
          (current ?? new RedactionPersonReadModel(string.Empty)) with
          {
              Name = @event.Name
          };

public RedactionPersonReadModel? Redacted(EventRedacted @event, RedactionPersonReadModel? current, EventContext context) =>
          // Return null to remove the read model, or return a sanitised version
          null;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### Filtering guarantee

[Section titled “Filtering guarantee”](#filtering-guarantee)

The `EventRedacted` event is delivered to an observer **only if** the observer was already subscribed to the original event type. An observer that subscribes to `[PersonRegistered, EventRedacted]` will **not** receive an `EventRedacted` notification when an unrelated event type (e.g. `OrderPlaced`) is redacted.

The Workbench lets you redact events without writing any code:

1. Open the **Event Log** view for the event store and namespace you want to manage.
2. Select the event you want to redact.
3. Click the **Redact** button in the event detail panel.
4. In the dialog that appears, enter the reason for the redaction.
5. Click **OK** to confirm.

Chronicle immediately replaces the event’s content with the redaction marker. The event slot remains visible in the sequence but no longer contains the original data.

# Event Revision

Event revision lets you correct the content of a previously appended event when you discover it contained incorrect data. Rather than modifying the immutable event log, revision records a new version of the event’s content alongside the original, preserving the full audit trail while making the corrected data available to all consumers.

## Why revision instead of deletion

[Section titled “Why revision instead of deletion”](#why-revision-instead-of-deletion)

Events are immutable by design. Deleting or modifying an event would break the audit trail and could leave projections, reactors and reducers in an inconsistent state. Revision solves this by storing a corrected payload for the event while keeping the original intact. All observers that read or replay the event see the revised content.

## When to use revision

[Section titled “When to use revision”](#when-to-use-revision)

Use revision when:

* A field was recorded with incorrect data due to a bug or data entry error.
* Regulatory or business requirements demand a correction to a specific event’s content.
* You need to fix data without triggering a full rewind of observers.

Do not use revision as a substitute for appending new domain events. If something genuinely happened in the domain — for example a correction being made by a user — model that as a new event instead.

## Revising events from the Workbench

[Section titled “Revising events from the Workbench”](#revising-events-from-the-workbench)

The Workbench provides a UI for revising events in the event log:

1. Open the **Event Log** view for the event store and namespace you want to manage.
2. Select the event you want to correct.
3. Click the **Revise** button in the event detail panel.
4. In the dialog that appears, change the values you want to correct.
5. Click **OK** to submit the revision.

The corrected content is stored alongside the original event. All subsequent reads of that event return the revised content. The original payload remains accessible in the full event history.

## What gets stored

[Section titled “What gets stored”](#what-gets-stored)

When you revise an event, Chronicle stores:

* The sequence number of the original event.
* The event type of the revised content (which must be the same type or a compatible type).
* The full JSON payload of the corrected event.
* The causation and identity of whoever submitted the revision.

Revisions are ordered, so if you revise the same event more than once, the latest revision is the one consumers see.

# Overriding how a type appears in the schema

Chronicle generates a JSON schema for every event and read model, and that schema is what the kernel stores against the event type and uses to materialize values back out. Most types map on their own — primitives directly, and `ConceptAs<T>` types as their underlying primitive.

A type that serializes to something other than its shape needs to say so, or the generated schema describes the CLR structure while the stored JSON holds whatever the converter wrote. Annotate the type with `JsonSchemaType` to declare what it is really represented as:

* C#

```csharp
  using System.Text.Json;
  using System.Text.Json.Serialization;
  using Cratis.Chronicle.Schemas;

[JsonSchemaType(typeof(string))]
  [JsonConverter(typeof(PostalCodeJsonConverter))]
  public class PostalCode(string value)
  {
      public string Value { get; } = value;
  }

public class PostalCodeJsonConverter : JsonConverter<PostalCode>
  {
      public override PostalCode Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
          new(reader.GetString()!);

public override void Write(Utf8JsonWriter writer, PostalCode value, JsonSerializerOptions options) =>
          writer.WriteStringValue(value.Value);
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The schema then describes a string, matching what the converter actually writes.

Two things are preserved through the override:

* **Compliance metadata.** A type marked `[PII]` keeps its compliance metadata after the redirect, so it is still encrypted per subject.
* **Nullability.** A nullable use of the type is still marked nullable in the schema.

An explicit `JsonSchemaType` always wins over what Chronicle would otherwise infer, including the `ConceptAs<T>` handling.

Client coverage

`JsonSchemaType` is currently C#-only.

# Transactions and Unit of Work

A unit of work groups event appends in the client and commits them as one append batch. Use it when one logical operation must produce multiple events and the operation should have one commit point, one correlation id, and one success or failure outcome.

The transaction is still an event append operation. Chronicle validates constraints and concurrency when the unit of work commits, then persists the accepted events atomically for each committed batch.

## When to Use a Unit of Work

[Section titled “When to Use a Unit of Work”](#when-to-use-a-unit-of-work)

Use a unit of work when:

* One command or workflow emits more than one event.
* The events should share the same correlation id.
* The operation should not send partial appends before the workflow is ready.
* The appends should be committed or rejected together.

Do not use a unit of work to hide modeling problems. If two facts can happen independently, append them independently. If one fact depends on another, model that invariant with constraints, concurrency, or the command decision that creates the events.

## Commit Transactional Appends

[Section titled “Commit Transactional Appends”](#commit-transactional-appends)

Create a unit of work, append through the transactional event sequence, and commit when every event has been staged.

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Execution;

public static class TransactionalOrderWorkflow
  {
      public static async Task CommitOrder(IEventStore store)
      {
          var unitOfWork = store.UnitOfWorkManager.Begin(CorrelationId.New());

try
          {
              await store.EventLog.Transactional.Append(
                  "order-123",
                  new TransactionalOrderPlaced("order-123", 99.95m));

await store.EventLog.Transactional.Append(
                  "inventory-widget",
                  new TransactionalInventoryReserved("widget", 1));

await unitOfWork.Commit();
          }
          catch
          {
              await unitOfWork.Rollback();
              throw;
          }
      }
  }

public record TransactionalOrderPlaced(string OrderId, decimal TotalAmount);
  public record TransactionalInventoryReserved(string Sku, int Quantity);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore

data class TransactionalOrderPlaced(val orderId: String, val totalAmount: Double)
  data class TransactionalInventoryReserved(val sku: String, val quantity: Int)

suspend fun commitOrder(store: IEventStore) {
      val unitOfWork = store.unitOfWorkManager.begin()

try {
          store.eventLog.transactional.append(
              "order-123",
              TransactionalOrderPlaced("order-123", 99.95)
          )

store.eventLog.transactional.append(
              "inventory-widget",
              TransactionalInventoryReserved("widget", 1)
          )

unitOfWork.commit()
      } catch (exception: Exception) {
          unitOfWork.rollback()
          throw exception
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingEventStore;

record TransactionalOrderPlaced(String orderId, double totalAmount) {}
  record TransactionalInventoryReserved(String sku, int quantity) {}

class TransactionalOrderWorkflow {
      void commitOrder(IEventStore store) {
          var eventStore = new BlockingEventStore(store);

// Rolls back on the way out unless it was committed, so a throw needs no catch.
          try (var unitOfWork = eventStore.beginUnitOfWork()) {
              eventStore.getTransactional().append(
                  "order-123",
                  new TransactionalOrderPlaced("order-123", 99.95));

eventStore.getTransactional().append(
                  "inventory-widget",
                  new TransactionalInventoryReserved("widget", 1));

unitOfWork.commit();
          }
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.TransactionalOrderPlaced do
    use Chronicle.Events.EventType, id: "TransactionalOrderPlaced"

defstruct [:order_id, :total_amount]
  end

defmodule MyApp.Events.TransactionalInventoryReserved do
    use Chronicle.Events.EventType, id: "TransactionalInventoryReserved"

defstruct [:sku, :quantity]
  end

defmodule MyApp.TransactionalOrderWorkflow do
    alias Chronicle.Transactions.UnitOfWork
    alias MyApp.Events.{TransactionalInventoryReserved, TransactionalOrderPlaced}

def commit_order do
      unit_of_work = UnitOfWork.begin()

try do
        :ok =
          Chronicle.append("order-123", %TransactionalOrderPlaced{
            order_id: "order-123",
            total_amount: 99.95
          })

:ok =
          Chronicle.append("inventory-widget", %TransactionalInventoryReserved{
            sku: "widget",
            quantity: 1
          })

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

* TypeScript

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

@eventType()
  class TransactionalOrderPlaced {
      constructor(readonly orderId: string, readonly totalAmount: number) {}
  }

@eventType()
  class TransactionalInventoryReserved {
      constructor(readonly sku: string, readonly quantity: number) {}
  }

async function commitOrder(store: IEventStore): Promise<void> {
      const unitOfWork = store.unitOfWorkManager.begin();

try {
          await store.eventLog.transactional.append(
              'order-123',
              new TransactionalOrderPlaced('order-123', 99.95)
          );

await store.eventLog.transactional.append(
              'inventory-widget',
              new TransactionalInventoryReserved('widget', 1)
          );

await unitOfWork.commit();
      } catch (error) {
          await unitOfWork.rollback();
          throw error;
      }
  }
  ```

## Commit an ordered batch with exact concurrency

[Section titled “Commit an ordered batch with exact concurrency”](#commit-an-ordered-batch-with-exact-concurrency)

When a decision reads several streams, capture the exact revision it used and stage the resulting events with that scope. `AddEvents` materializes the events and scopes immediately, preserves cross-stream order, and still waits for the unit of work to commit before sending anything to Chronicle.

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.EventSequences.Concurrency;
  using Cratis.Execution;

public static class TransactionalTransferWorkflow
  {
      public static async Task<bool> TryCommitTransfer(
          IEventStore store,
          EventSequenceNumber expectedAuthorizationRevision)
      {
          using var unitOfWork = store.UnitOfWorkManager.Begin(CorrelationId.New());
          EventSourceId authorizationScopeLabel = "authorization-history";
          var authorizationScope = new ConcurrencyScope(
              expectedAuthorizationRevision,
              EventStreamType: "authorization");

unitOfWork.AddEvents(
              EventSequenceId.Log,
              [
                  new EventForEventSourceId(
                      "account-from",
                      new TransferDebited(100m)),
                  new EventForEventSourceId(
                      "account-to",
                      new TransferCredited(100m))
              ],
              [new(authorizationScopeLabel, authorizationScope)]);

await unitOfWork.Commit();
          return unitOfWork.IsSuccess;
      }
  }

[EventType]
  public record TransferDebited(decimal Amount);

[EventType]
  public record TransferCredited(decimal Amount);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

A concurrency-scope key can be an independent label when the scope does not narrow by event-source ID. It does not need to match either event target, so one decision-wide stream-, type-, or event-type-scoped revision can protect the entire ordered batch. If a scope does narrow by event-source ID, its key must be that event-source ID.

Every event target and scope label must contain a non-whitespace value; blank labels cannot survive transport and are rejected during enrollment.

Chronicle resolves the configured concurrency strategy for an event target that has no supplied scope or carries `ConcurrencyScope.NotSet`. An independent non-target label has no event target from which to resolve a strategy, so Chronicle rejects `NotSet` and incomplete scopes for those labels. Give an independent label a concrete exact scope or `ConcurrencyScope.None`.

`AddEvents` snapshots the event list, scope collection, and every scope’s nested event-type filter before it binds or stages anything in the unit of work. When ordered enrollment first participates in a unit of work, Chronicle also snapshots effective scopes from preceding `AddEvent` calls; later `AddEvent` scopes are snapshotted as they are enrolled. Later mutations to caller-owned collections therefore cannot change the eventual commit, and a lazy collection failure is reported during enrollment.

Dispose the unit of work even when enrollment validation fails, and inspect `IsSuccess` after commit. A completed `Commit` can still report a constraint or concurrency rejection rather than a successful append.

Consecutive `AddEvent` calls keep their existing source-grouped order. Each `AddEvents` call creates an exact-order segment between those legacy segments. Commit flattens the segments in enrollment-call order and sends all of them through one atomic append.

Legacy-only `AddEvent` calls retain their historical event-sequence behavior. Once `AddEvents` participates, every event in the unit of work must name the same event sequence; a mismatch is rejected before the ordered batch is staged.

## Roll Back

[Section titled “Roll Back”](#roll-back)

Rollback discards the events staged in the unit of work. Nothing is sent to Chronicle for those staged events.

## Related Topics

[Section titled “Related Topics”](#related-topics)

* [Appending events](/chronicle/events/appending/)
* [Appending many events](/chronicle/events/appending-many/)
* [Optimistic concurrency](/chronicle/events/concurrency/)
* [Constraints](/chronicle/constraints/)

# External Services

External Services are named, per–event store configurations that describe **how to connect to something outside Chronicle** — an HTTP API or a database. Instead of scattering URLs, connection strings, and secrets across features (such as [captures](/chronicle/captures/)), you configure a connection once as an External Service and reference it by name.

## Why External Services

[Section titled “Why External Services”](#why-external-services)

* **One place for connection details.** Base URLs, hosts, credentials, and provider options live on the service, not inside the feature that uses it.
* **Secrets stay out of declarations.** A [capture](/chronicle/captures/) API source references `api <Name>` — the URL and authentication come from the referenced External Service, so no secrets live in capture text.
* **Extensible.** The endpoint model is open — new endpoint types can be added without changing existing ones.

## Endpoint types

[Section titled “Endpoint types”](#endpoint-types)

Every External Service has one endpoint of a specific type:

| Type           | What it configures                                                   | Forms                                    |
| -------------- | -------------------------------------------------------------------- | ---------------------------------------- |
| **HTTP**       | Base URL, authorization (None / Basic / Bearer / OAuth), and headers | An HTTP client target                    |
| **MSSQL**      | Host, port, database, username, password, and options                | A Microsoft SQL Server connection string |
| **PostgreSQL** | Host, port, database, username, password, and options                | A PostgreSQL connection string           |

Database endpoints know how to **form their own connection string** from their configuration. Each database provider has its own formatter (`IFormDatabaseConnectionString`), discovered by convention — adding a new provider is a matter of implementing that interface for a new endpoint type.

### Connection string formation

[Section titled “Connection string formation”](#connection-string-formation)

For a database endpoint, the connection string is built from the configured fields:

* **MSSQL** → `Server=<host>[,<port>];Database=<db>;User Id=<user>;Password=<pw>;<options...>`
* **PostgreSQL** → `Host=<host>;[Port=<port>;]Database=<db>;Username=<user>;Password=<pw>;<options...>`

When the port is left unspecified (`0`), the provider default is used and the port is omitted from the connection string.

## Configuring External Services

[Section titled “Configuring External Services”](#configuring-external-services)

External Services are configured per event store. In the **Workbench**, open an event store and go to **General → External Services** to add, view, and remove services. Choose the endpoint type and fill in the type-specific form:

* **HTTP** — base URL, an authorization type, the matching credential fields, and optional headers.
* **MSSQL / PostgreSQL** — host, port, database, username, and password.

Secrets (passwords, tokens, client secrets) are write-only from the Workbench — they are never returned by the read model that lists services.

External Services can also be registered programmatically — see [Registering External Services from code](/chronicle/clients/dotnet/external-services/) in the .NET client docs.

## Using External Services from captures

[Section titled “Using External Services from captures”](#using-external-services-from-captures)

A [capture](/chronicle/captures/) API source references an External Service by name. The capture only declares *what* to poll (the route and interval); *where* and *how to authenticate* come from the External Service:

```cdl
capture Customers
  source api
    api CustomersApi   # references the "CustomersApi" External Service
    route /customers
    poll 5m
  key customerId
  ...
```

See [Capture Declaration Language](/chronicle/captures/capture-declaration-language/) for the full capture syntax.

# Get started

> Start the Chronicle kernel, choose a client SDK, and see the same event-sourcing loop across C#, Kotlin, Java, Elixir, and TypeScript.

The fastest way to understand Chronicle is to watch one fact travel through it. Chronicle stores the fact as an event, projections fold it into read models, and reactors respond to it. That loop is the same no matter which client SDK you use.

This page is the shared Chronicle starting point. It explains the common model and shows the same examples in every supported client. Use the client-specific setup guides for package installation, project scaffolding, host integration, and runtime idioms.

Never done event sourcing?

You don’t need any event-sourcing background to follow the loop below. If you’d rather understand the *why* before the *how*, read [Why Event Sourcing](/chronicle/why-event-sourcing/) first, then come back. Either order is fine.

## Pick a client

[Section titled “Pick a client”](#pick-a-client)

Start with the client that matches the application you are building. The setup guide owns the language-specific details; the rest of this page owns the Chronicle concepts.

| Client     | Setup guide                                                         |
| ---------- | ------------------------------------------------------------------- |
| .NET       | [.NET client](/chronicle/clients/dotnet/getting-started/)           |
| Kotlin     | [Kotlin client](/chronicle/clients/kotlin/get-started/)             |
| Java       | [Kotlin/JVM client](/chronicle/clients/kotlin/get-started/)         |
| Elixir     | [Elixir client](/chronicle/clients/elixir/get-started/)             |
| TypeScript | [TypeScript client](/chronicle/clients/typescript/getting-started/) |

Java uses the JVM client

Java examples are owned by the Kotlin/JVM client repo. Use the JVM setup guide, then choose the Java tab when reading shared examples.

## Start Chronicle

[Section titled “Start Chronicle”](#start-chronicle)

Chronicle application code connects to a running Chronicle kernel. For local development, the fastest path is the development image:

```shell
docker run -d -p 27017:27017 -p 35000:35000 cratis/chronicle:latest-development
```

The kernel listens on `chronicle://localhost:35000`, the workbench runs on `https://localhost:35000` — the same, single TLS-secured port — and the bundled MongoDB stores materialized read models. If you need Docker Compose, Aspire, a separate database, or production-style hosting, use [Choose an application host model](/chronicle/get-started/choose-hosting-model/).

## The Chronicle loop

[Section titled “The Chronicle loop”](#the-chronicle-loop)

One event-sourced interaction has three parts:

```
Append a fact

Event log

Projection

Read model

Reactor

Side effect
```

In [event modeling](/event-modeling/) notation, the tiny example below is:

```
UI/A: DemoC/RM: DemoStream: Demo
TestEvent

message: string
TestProjection
TestReactor
```

Each client has its own syntax, but the Chronicle shape is the same: create a client, choose an event store, and append a fact to the event log.

* C#

Program.cs

```csharp
  using var client = new ChronicleClient();
  var eventStore = await client.GetEventStore("ChronicleConsole");

await eventStore.EventLog.Append("some-event-source", new TestEvent("Hello world!"));
  ```

* Kotlin

Main.kt

```kotlin
  val client = ChronicleClient(ChronicleOptions.development())
  val eventStore = client.getEventStore("ChronicleConsole")

eventStore.eventLog.append("some-event-source", TestEvent("Hello world!"))
  ```

* Java

Main.java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.java.BlockingChronicleClient;

class Main {
      void run() {
          var client = BlockingChronicleClient.connect(ChronicleOptions.development());
          var eventStore = client.getEventStore("ChronicleConsole");

eventStore.getEventLog().append("some-event-source", new TestEvent("Hello world!"));
      }
  }
  ```

* Elixir

application.ex

```elixir
  children = [
    {Chronicle.Client,
     connection_string: "chronicle://localhost:35000",
     event_store: "chronicle-console",
     otp_app: :my_app}
  ]

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

Append the event

```elixir
  :ok =
    Chronicle.append("some-event-source", %MyApp.Events.TestEvent{
      message: "Hello world!"
    })
  ```

* TypeScript

index.ts

```typescript
  import 'reflect-metadata';
  import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';

const client = new ChronicleClient(ChronicleOptions.development());
  const eventStore = await client.getEventStore('ChronicleConsole');

await eventStore.eventLog.append('some-event-source', new TestEvent('Hello world!'));
  ```

Reading top to bottom: the client connects to the kernel, asks for an **event store** by name, and **appends** a `TestEvent` to its event log. That append is the only operation that changes the event store. Everything else reacts to the recorded fact.

The event itself is just a record marked as a fact:

* C#

The event - an immutable fact

```csharp
  [EventType]
  public record TestEvent(string Message);
  ```

* Kotlin

The event - an immutable fact

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class TestEvent(val message: String)
  ```

* Java

The event - an immutable fact

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record TestEvent(String message) {}
  ```

* Elixir

The event - an immutable fact

```elixir
  defmodule MyApp.Events.TestEvent do
    use Chronicle.Events.EventType, id: "test-event-v1"

defstruct [:message]
  end
  ```

* TypeScript

The event - an immutable fact

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class TestEvent {
      constructor(readonly message: string) {}
  }
  ```

A **projection** folds that event into a read model: state you can query, rebuild, and store in a sink:

* C#

The projection - builds queryable state

```csharp
  [FromEvent<TestEvent>]
  public record TestProjection(
      string Message,
      [SetFromContext<TestEvent>(nameof(EventContext.EventSourceId))] string EventSource);
  ```

* Kotlin

The projection - builds queryable state

```kotlin
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  @FromEvent(TestEvent::class)
  data class TestProjection(
      val message: String = ""
  )
  ```

* Java

The projection - builds queryable state

```java
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;

@ReadModel
  @FromEvent(eventType = TestEvent.class)
  record TestProjection(String message) {
      TestProjection() {
          this("");
      }
  }
  ```

* Elixir

The projection - builds queryable state

```elixir
  defmodule MyApp.ReadModels.TestProjection do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.TestEvent

defstruct [:id, :message]

from TestEvent,
      set: [
        id: :event_source_id,
        message: :message
      ]
  end
  ```

* TypeScript

The projection - builds queryable state

```typescript
  import { fromEvent, readModel } from '@cratis/chronicle';

@readModel()
  @fromEvent(TestEvent)
  class TestProjection {
      message = '';
  }
  ```

A **reactor** does something when the event arrives:

* C#

The reactor - does something when it happens

```csharp
  public class TestReactor : IReactor
  {
      public Task React(TestEvent @event)
      {
          Console.WriteLine($"Received event with message: {@event.Message}");
          return Task.CompletedTask;
      }
  }
  ```

* Kotlin

The reactor - does something when it happens

```kotlin
  import io.cratis.chronicle.observation.Reactor

@Reactor
  class TestReactor {
      fun react(event: TestEvent) {
          println("Received event with message: ${event.message}")
      }
  }
  ```

* Java

The reactor - does something when it happens

```java
  import io.cratis.chronicle.observation.Reactor;

@Reactor
  class TestReactor {
      void react(TestEvent event) {
          System.out.println("Received event with message: " + event.message());
      }
  }
  ```

* Elixir

The reactor - does something when it happens

```elixir
  defmodule MyApp.Reactors.TestReactor do
    use Chronicle.Reactors.Reactor

alias MyApp.Events.TestEvent

@handles TestEvent

@impl true
    def handle(%TestEvent{} = event, _context) do
      IO.puts("Received event with message: #{event.message}")
      :ok
    end
  end
  ```

* TypeScript

The reactor - does something when it happens

```typescript
  import { reactor } from '@cratis/chronicle';

@reactor()
  class TestReactor {
      async testEvent(event: TestEvent): Promise<void> {
          console.log(`Received event with message: ${event.message}`);
      }
  }
  ```

Discovery and registration are client-specific. Some hosts discover annotated artifacts; others register modules, classes, or functions explicitly. The invariant is the same: events are facts, projections derive read models, and reactors observe events to produce side effects.

That's the whole model

Append a fact → a projection builds state from it → a reactor acts on it. **Append → project → react.** Every Chronicle application, however large, repeats that loop.

## Inspect it in the workbench

[Section titled “Inspect it in the workbench”](#inspect-it-in-the-workbench)

The development image includes the **Chronicle workbench** — a web UI for inspecting event stores. Open <https://localhost:35000> and log in with the development credentials: username `Admin`, password `ChangeMeNow!`. In development the port uses a self-signed certificate, so accept your browser’s certificate warning the first time.

After you run one of the client setup guides or the example flow above, choose the event store your client used and open **Sequences**. The `TestEvent` is permanent and ordered in the event log. Append more events and watch the sequence grow. That log is the source of truth your projections and reactors read from.

## Where to go next

[Section titled “Where to go next”](#where-to-go-next)

* **Pick your client** — start with [.NET](/chronicle/clients/dotnet/getting-started/), [Kotlin/JVM](/chronicle/clients/kotlin/get-started/), [Elixir](/chronicle/clients/elixir/get-started/), or [TypeScript](/chronicle/clients/typescript/getting-started/).
* **Build something real, step by step** — the [tutorial](/chronicle/tutorial/) builds a small library system one concept at a time.
* **Run Chronicle your way** — [choose an application host model and run the kernel](/chronicle/get-started/choose-hosting-model/).
* **Understand the model** — [Why Event Sourcing](/chronicle/why-event-sourcing/) makes the case, and the [Concepts](/chronicle/concepts/) section defines every term you just met.

# Add Chronicle to an ASP.NET Core app

> Wire Chronicle into an ASP.NET Core web application — the DI container registers and discovers everything, and a minimal API endpoint appends events directly.

When your app is a web API, Chronicle fits the way you already build: it plugs into the `WebApplicationBuilder`, registers itself in the dependency-injection container, and lets your endpoints append events by taking `IEventLog` as a dependency. There’s almost no glue — a couple of calls in `Program.cs` and your routes can start recording facts.

We’ll build a small library domain and expose an endpoint that borrows a book. If you’re not building a web app — a background processor or scheduled host — the [Worker Service guide](/chronicle/get-started/worker/) covers that host instead, and the [console guide](/chronicle/get-started/console/) shows the bare-bones version with no container at all.

## Before you start

[Section titled “Before you start”](#before-you-start)

Have the Chronicle kernel running locally. [Run Chronicle locally](/chronicle/get-started/choose-hosting-model/#run-chronicle-locally) brings it up with a single `docker run` and lists the prerequisites (.NET 8+, Docker); this guide assumes it’s listening on `chronicle://localhost:35000`.

You can also find the [complete ASP.NET Core quickstart sample](https://github.com/Cratis/Samples/tree/main/Chronicle/Quickstart/AspNetCore) on GitHub.

## Set up the project

[Section titled “Set up the project”](#set-up-the-project)

Create a folder for your project, then a .NET web project inside it:

```shell
dotnet new web
```

Add a reference to the [Chronicle ASP.NET Core package](https://www.nuget.org/packages/Cratis.Chronicle.AspNetCore) (it brings in the base [Chronicle package](https://www.nuget.org/packages/Cratis.Chronicle) for you):

```shell
dotnet add package Cratis.Chronicle.AspNetCore
```

## Register Chronicle on the host

[Section titled “Register Chronicle on the host”](#register-chronicle-on-the-host)

ASP.NET Core builds your app through the `WebApplicationBuilder`, which already has a dependency-injection container. Chronicle hooks straight into it — two calls in `Program.cs` are the entire integration:

* C#

```csharp
  using Microsoft.AspNetCore.Builder;

public static class AspNetCoreRegistration
  {
      public static void ConfigureApp(string[] args)
      {
          var builder = WebApplication.CreateBuilder(args)
              .AddCratisChronicle(options => options.EventStore = "Quickstart");

var app = builder.Build();
          app.UseCratisChronicle();
      }
  }
  ```

* Kotlin

````kotlin
  /**
   * The `cratis-chronicle-spring-boot-starter` on the classpath is the entire integration - there
   * is no `AddCratisChronicle`/`UseCratisChronicle` to call. Autoconfiguration connects to the
   * kernel, discovers every event type, read model, reducer, reactor and constraint in this
   * application's packages, and registers them before the first request is served. The entry point
   * itself needs nothing Chronicle-specific - only Spring Boot's own `@SpringBootApplication` class
   * and `runApplication<...>(*args)`. Point it at an event store with one setting in
   * application.yml:
   *
   * ```yaml
   * cratis:
   *   chronicle:
   *     event-store: Quickstart
   * ```
   */
  object AspNetCoreRegistration
  ````

* Java

```java
  /**
   * The {@code cratis-chronicle-spring-boot-starter} on the classpath is the entire integration -
   * there is no {@code AddCratisChronicle}/{@code UseCratisChronicle} to call. Autoconfiguration
   * connects to the kernel, discovers every event type, read model, reducer, reactor and
   * constraint in this application's packages, and registers them before the first request is
   * served. The entry point itself needs nothing Chronicle-specific - only Spring Boot's own
   * {@code @SpringBootApplication} class and {@code SpringApplication.run(...)}. Point it at an
   * event store with one setting in application.yml:
   *
   * <pre>
   * cratis:
   *   chronicle:
   *     event-store: Quickstart
   * </pre>
   */
  class AspNetCoreRegistration {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`AddCratisChronicle` registers Chronicle’s services and names the event store to use; `UseCratisChronicle` hooks it into the request pipeline. Unlike the bare-bones [console](/chronicle/get-started/console/) version, all discovery and registration of your artifacts happens automatically — the container finds your reactors, reducers, and projections for you.

```
AddCratisChronicle

UseCratisChronicle

IEventLog.Append

WebApplicationBuilder

DI container (auto-discovers artifacts)

app

request pipeline

minimal API / controller

event store
```

## Define some events

[Section titled “Define some events”](#define-some-events)

Everything in Chronicle starts with a fact. You model facts as `record` types marked with `[EventType]` — records because an event, once it happened, never changes. The attribute is how Chronicle discovers the type; it takes no name, the type name *is* the identity.

Here are the facts of a small library — a book arrives, gets borrowed, and comes back:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record GetStartedBookAdded(string Title, string Isbn);

[EventType]
  public record GetStartedBookBorrowed(string MemberName);

[EventType]
  public record GetStartedBookReturned;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class GetStartedBookAdded(val title: String, val isbn: String)

@EventType
  data class GetStartedBookBorrowed(val memberName: String)

@EventType
  class GetStartedBookReturned
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record GetStartedBookAdded(String title, String isbn) {}

@EventType
  record GetStartedBookBorrowed(String memberName) {}

@EventType
  record GetStartedBookReturned() {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.GetStartedBookAdded do
    use Chronicle.Events.EventType, id: "get-started-book-added"

defstruct [:title, :isbn]
  end

defmodule MyApp.Events.GetStartedBookBorrowed do
    use Chronicle.Events.EventType, id: "get-started-book-borrowed"

defstruct [:member_name]
  end

defmodule MyApp.Events.GetStartedBookReturned do
    use Chronicle.Events.EventType, id: "get-started-book-returned"

defstruct []
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class GetStartedBookAdded {
      constructor(
          readonly title: string,
          readonly isbn: string
      ) {}
  }

@eventType()
  class GetStartedBookBorrowed {
      constructor(readonly memberName: string) {}
  }

@eventType()
  class GetStartedBookReturned {
  }
  ```

`BookReturned` carries no data at all — that it *happened*, on a particular book’s stream, is the whole story. Not every fact needs a payload.

## Append them

[Section titled “Append them”](#append-them)

You record a fact by **appending** it to an [event sequence](/chronicle/concepts/event-sequence/). Chronicle gives you one by default — the **event log**, the main sequence you’ll use, much like the `main` branch of a Git repository. Reach it through the event store:

* C#

```csharp
  using Cratis.Chronicle;

public class GetStartedBookService(IEventStore eventStore)
  {
      public async Task<Guid> AddBook()
      {
          var eventLog = eventStore.EventLog;

var bookId = Guid.NewGuid();
          await eventLog.Append(bookId, new GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"));

return bookId;
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import java.util.UUID

class GetStartedBookService(private val eventStore: IEventStore) {
      suspend fun addBook(): String {
          val eventLog = eventStore.eventLog

val bookId = UUID.randomUUID().toString()
          eventLog.append(bookId, GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"))

return bookId
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingEventStore;
  import java.util.UUID;

class GetStartedBookService {
      private final BlockingEventStore eventStore;

GetStartedBookService(IEventStore eventStore) {
          this.eventStore = new BlockingEventStore(eventStore);
      }

String addBook() {
          var bookId = UUID.randomUUID().toString();

eventStore.getEventLog().append(
              bookId,
              new GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"));

return bookId;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.BookService do
    alias MyApp.Events.GetStartedBookAdded

def add_book do
      book_id = Base.encode16(:crypto.strong_rand_bytes(8), case: :lower)

:ok =
        Chronicle.append(book_id, %GetStartedBookAdded{
          title: "The Pragmatic Programmer",
          isbn: "978-0135957059"
        })

book_id
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async addBook(bookId: string): Promise<void> {
          const eventLog = this.store.eventLog;

await eventLog.append(bookId, new GetStartedBookAdded('The Pragmatic Programmer', '978-0135957059'));
      }
  }
  ```

That first argument is the [event source id](/chronicle/concepts/event-source/) — the identity of the thing this fact is about, like a primary key. Every event you append against `bookId` becomes part of *that book’s* stream of history.

Tip

We use a raw generated id here to keep the quickstart short. In C#, real code would wrap it in a strongly-typed `BookId` so the compiler can’t confuse a book’s id with a member’s — the [tutorial](/chronicle/tutorial/) shows exactly that. Kotlin, Elixir, and TypeScript event source ids are plain strings; those clients don’t currently have an equivalent typed-id wrapper.

Run your app, then open the [workbench](https://localhost:35000), pick your event store, and select **Sequences** — your `BookAdded` is sitting there at sequence number `0`, permanent and in order.

Note

If you are using the Development or Development-slim image, log in with username **Admin** and password **ChangeMeNow!**. See [Workbench — Development](/chronicle/workbench/development/) for details.

![Chronicle Workbench showing events](/_astro/workbench.CcnUH1d2_Z1CPEDn.webp)

## Turn events into a read model

[Section titled “Turn events into a read model”](#turn-events-into-a-read-model)

Events are the **write** side — the source of truth. To *read* current state you don’t query the log directly; you let Chronicle fold the events into a **read model** for you. The declarative way to do that is a [projection](/chronicle/concepts/projection/): you declare the shape you want and which events feed each field, and Chronicle keeps it in sync — no update code, ever.

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<GetStartedBookAdded>]
  public record GetStartedBook(
      [Key]
      Guid Id,

string Title,

string Isbn,

[SetValue<GetStartedBookAdded>(false)]
      [SetValue<GetStartedBookBorrowed>(true)]
      [SetValue<GetStartedBookReturned>(false)]
      bool OnLoan,

[SetFrom<GetStartedBookBorrowed>(nameof(GetStartedBookBorrowed.MemberName))]
      string? BorrowedBy);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.GetStartedBook do
    use Chronicle.ReadModels.ReadModel

defstruct id: nil, title: nil, isbn: nil, on_loan: false, borrowed_by: nil

from MyApp.Events.GetStartedBookAdded,
      set: [id: :event_source_id, title: :title, isbn: :isbn, on_loan: false]

from MyApp.Events.GetStartedBookBorrowed,
      set: [on_loan: true, borrowed_by: :member_name]

from MyApp.Events.GetStartedBookReturned,
      set: [on_loan: false]
  end
  ```

* TypeScript

```typescript
  import { fromEvent, Guid, readModel, setFrom, setValue } from '@cratis/chronicle';

@readModel()
  @fromEvent(GetStartedBookAdded)
  class GetStartedBook {
      id: Guid = Guid.empty;

@setFrom(GetStartedBookAdded, 'title')
      title = '';

@setFrom(GetStartedBookAdded, 'isbn')
      isbn = '';

@setValue(GetStartedBookAdded, false)
      @setValue(GetStartedBookBorrowed, true)
      @setValue(GetStartedBookReturned, false)
      onLoan = false;

@setFrom(GetStartedBookBorrowed, 'memberName')
      borrowedBy: string | null = null;
  }
  ```

Read the attributes as a sentence: a book comes into the view from `BookAdded`; `OnLoan` is `false` when it’s added, `true` when borrowed, `false` again when returned; `BorrowedBy` is whoever borrowed it. You’re *declaring* how facts map onto the view — Chronicle replays the events in order and applies the mapping.

Note

The class-level `[FromEvent<BookAdded>]` maps event properties onto read model properties **by naming convention** — `BookAdded.Title` flows into `Title` and `BookAdded.Isbn` into `Isbn` without a single per-property attribute. You only reach for `[SetFrom<T>]` when the names differ, the way `BookBorrowed.MemberName` feeds `BorrowedBy` here. Setting a literal value per event type (like `OnLoan` here) isn’t currently supported in Kotlin or Java’s model-bound projections — only event-property mappings are.

One view rarely answers every question. The librarian’s next one is “what’s out on loan right now?” — and rather than filtering `Book`, you declare a second, purpose-built read model whose very *existence* tracks the loan:

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<GetStartedBookBorrowed>]
  [RemovedWith<GetStartedBookReturned>]
  public record GetStartedBorrowedBook(
      [Key]
      Guid Id,

string MemberName);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWith
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  @FromEvent(GetStartedBookBorrowed::class)
  @RemovedWith(GetStartedBookReturned::class)
  data class GetStartedBorrowedBook(
      val id: String = "",
      val memberName: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWith;
  import io.cratis.chronicle.readModels.ReadModel;

@ReadModel
  @FromEvent(eventType = GetStartedBookBorrowed.class)
  @RemovedWith(eventType = GetStartedBookReturned.class)
  class GetStartedBorrowedBook {
      private String id = "";
      private String memberName = "";

public GetStartedBorrowedBook() {}

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getMemberName() { return memberName; }
      public void setMemberName(String memberName) { this.memberName = memberName; }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.GetStartedBorrowedBook do
    use Chronicle.ReadModels.ReadModel

defstruct id: nil, member_name: nil

from MyApp.Events.GetStartedBookBorrowed,
      set: [id: :event_source_id, member_name: :member_name]

removed_with MyApp.Events.GetStartedBookReturned, []
  end
  ```

* TypeScript

```typescript
  import { fromEvent, Guid, readModel, removedWith, setFrom } from '@cratis/chronicle';

@readModel()
  @fromEvent(GetStartedBookBorrowed)
  @removedWith(GetStartedBookReturned)
  class GetStartedBorrowedBook {
      id: Guid = Guid.empty;

@setFrom(GetStartedBookBorrowed, 'memberName')
      memberName = '';
  }
  ```

The moment a `BookBorrowed` lands, a `BorrowedBook` instance appears — keyed by the book’s id, its `MemberName` mapped by the same naming convention. When the matching `BookReturned` arrives, `[RemovedWith<BookReturned>]` removes the instance from the view again. The collection always holds exactly the books that are out *right now* — no flag to maintain, no filter to remember, no cleanup job. Kotlin and Java don’t currently have an equivalent to `[RemovedWith<T>]`.

## Query the read models

[Section titled “Query the read models”](#query-the-read-models)

The most direct way to look at a read model is to ask Chronicle itself. `IReadModels` — reached through `eventStore.ReadModels` — hands you every instance of a read model, one call per view:

* C#

```csharp
  using Cratis.Chronicle;

public class GetStartedBookQueryService(IEventStore eventStore)
  {
      public async Task<(IEnumerable<GetStartedBook> Books, IEnumerable<GetStartedBorrowedBook> BorrowedBooks)> QueryBooks()
      {
          var books = await eventStore.ReadModels.GetInstances<GetStartedBook>();
          var borrowedBooks = await eventStore.ReadModels.GetInstances<GetStartedBorrowedBook>();

return (books, borrowedBooks);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.BookQueryService do
    alias MyApp.ReadModels.GetStartedBook
    alias MyApp.ReadModels.GetStartedBorrowedBook

def query_books do
      {:ok, books} = Chronicle.all(GetStartedBook)
      {:ok, borrowed_books} = Chronicle.all(GetStartedBorrowedBook)

{books, borrowed_books}
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async queryBooks(): Promise<{ books: GetStartedBook[]; borrowedBooks: GetStartedBorrowedBook[] }> {
          const books = await this.store.readModels.getInstances(GetStartedBook);
          const borrowedBooks = await this.store.readModels.getInstances(GetStartedBorrowedBook);

return { books, borrowedBooks };
      }
  }
  ```

These results are **strongly consistent**: Chronicle replays the read model’s events on demand, so what comes back reflects every event appended up to that instant — including the one you appended a moment ago. That replay is also the cost: every call processes *all* the events feeding the read model, which is perfect for a quickstart but not necessarily what you’d put on a hot path in production. You can cap the work by passing an event count — `GetInstances<Book>(eventCount: 1_000)` — but a capped replay can stop before the newest events and hand you incomplete results. [Getting a collection of instances](/chronicle/read-models/getting-collection-instances/) covers the details. Kotlin and Java currently only support fetching a single instance by key (`getInstanceByKey`) — fetching every instance of a read model isn’t available yet.

By default Chronicle also **materializes** every projection into the **sink** storage configured for the event store — MongoDB unless you change it — under a database named after the event store and a collection named after the read model. Materialization happens in the background as events arrive, so it’s **eventually consistent**: a freshly appended event may take a moment to show up. In exchange, a query costs nothing but a database fetch. The `Materialized` API reads those stored instances back, a page at a time. Kotlin and Java don’t currently have a materialized/paging query API at all; Elixir’s equivalent pages by page number rather than skip/take:

* C#

```csharp
  using Cratis.Chronicle;

public class GetStartedBookPagingService(IEventStore eventStore)
  {
      public async Task<IEnumerable<GetStartedBook>> GetPage() =>
          await eventStore.ReadModels.Materialized.GetInstances<GetStartedBook>(skip: 0, take: 20);
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.BookPagingService do
    alias MyApp.ReadModels.GetStartedBook

def get_page do
      {:ok, result} = Chronicle.ReadModels.query(GetStartedBook, page: 1, page_size: 20)
      result.instances
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

getPage(): Promise<GetStartedBook[]> {
          return this.store.readModels.materialized.getInstances(GetStartedBook, 0, 20);
      }
  }
  ```

`skip` and `take` are plain paging (they default to `0` and `50`), so you can window through a large collection without ever loading all of it — [Materialized read models](/chronicle/read-models/materialized-pagination/) shows the paging and observing patterns.

Neither call filters, though: `GetInstances` returns everything (you’d filter with LINQ in memory), and `Materialized` only pages. When you need to filter efficiently — “which books are on loan?” — query the [sink](/chronicle/sinks/)’s database directly with its native tools. Our sink is MongoDB, so the `Book` read model is an ordinary collection and the driver does what it does best:

* C#

```csharp
  using MongoDB.Driver;

public class GetStartedBooks(IMongoCollection<GetStartedBook> collection)
  {
      public IEnumerable<GetStartedBook> OnLoan() => collection.Find(b => b.OnLoan).ToList();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class GetStartedBook(val title: String = "", val onLoan: Boolean = false)

/**
   * Kotlin has no raw MongoCollection to query directly - reads go through the read model service
   * instead, which returns already-deserialized instances to filter in memory.
   */
  class GetStartedBooks(private val store: IEventStore) {
      suspend fun onLoan(): List<GetStartedBook> =
          store.readModels.getInstances(GetStartedBook::class).filter { it.onLoan }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;
  import java.util.stream.Collectors;

@ReadModel
  record GetStartedBook(String title, boolean onLoan) {}

// Java has no raw MongoCollection to query directly - reads go through the read model service
  // instead, which returns already-deserialized instances to filter in memory.
  class GetStartedBooks {
      private final IEventStore store;

GetStartedBooks(IEventStore store) {
          this.store = store;
      }

List<GetStartedBook> onLoan() {
          return ReadModelsJavaBridge.getInstances(store.getReadModels(), GetStartedBook.class).stream()
              .filter(GetStartedBook::onLoan)
              .collect(Collectors.toList());
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Append a `BookBorrowed` against the same `bookId`, query again, and `OnLoan` is `true` with `BorrowedBy` set — and a `BorrowedBook` now sits in its collection. Append a `BookReturned` and both flip back: the flag clears, the `BorrowedBook` disappears. You never wrote an `UPDATE`. The trade-offs between the on-demand and materialized paths are laid out in [read model consistency](/chronicle/read-models/consistency/).

## React when something happens

[Section titled “React when something happens”](#react-when-something-happens)

Projections build *state*. When you need to *do something* the moment a fact lands — notify someone, call another system — you write a **reactor**. `IReactor` is a marker; you just add a method whose first parameter is the event you care about, and Chronicle routes matching events to it:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

public class GetStartedBookReturnedNotifier : IReactor
  {
      public Task Returned(GetStartedBookReturned @event, EventContext context)
      {
          // context.EventSourceId is the BookId this happened to
          Console.WriteLine($"Book {context.EventSourceId} was returned — notify the next member in line.");
          return Task.CompletedTask;
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.observation.Reactor

@Reactor
  class GetStartedBookReturnedNotifier {
      fun returned(event: GetStartedBookReturned, context: EventContext) {
          // context.eventSourceId is the bookId this happened to
          println("Book ${context.eventSourceId} was returned — notify the next member in line.")
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.observation.Reactor;

@Reactor
  class GetStartedBookReturnedNotifier {
      void returned(GetStartedBookReturned event, EventContext context) {
          // context.getEventSourceId() is the bookId this happened to
          System.out.println("Book " + context.getEventSourceId() + " was returned — notify the next member in line.");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Reactors.GetStartedBookReturnedNotifier do
    use Chronicle.Reactors.Reactor

alias MyApp.Events.GetStartedBookReturned

@handles GetStartedBookReturned

@impl true
    def handle(%GetStartedBookReturned{}, %{event_source_id: book_id}) do
      # book_id is the id this happened to
      IO.puts("Book #{book_id} was returned — notify the next member in line.")
      :ok
    end
  end
  ```

* TypeScript

```typescript
  import { EventContext, reactor } from '@cratis/chronicle';

@reactor()
  class GetStartedBookReturnedNotifier {
      // Method name must be the exact camelCase of the event's class name -
      // Chronicle discovers handlers by name, not by parameter type.
      async getStartedBookReturned(event: GetStartedBookReturned, context: EventContext): Promise<void> {
          // context.eventSourceId is the bookId this happened to
          console.log(`Book ${context.eventSourceId} was returned — notify the next member in line.`);
      }
  }
  ```

No registration, no wiring — drop the class in and every `BookReturned` flows to it. Reactors must be idempotent, because the same event may be delivered more than once (during a replay or a recovery). In a real app you’d inject a notification service here — the [tutorial](/chronicle/tutorial/) and the [Reactors](/chronicle/reactors/) guide show that, along with how reactors get their dependencies under a host.

That’s the whole loop — **append → project → react**. The [tutorial](/chronicle/tutorial/) builds exactly this library one concept at a time and explains each as you go; the [Projections](/chronicle/projections/), [Reducers](/chronicle/reducers/), and [Reactors](/chronicle/reactors/) guides go deeper on each piece.

## Append from an endpoint

[Section titled “Append from an endpoint”](#append-from-an-endpoint)

In a web app you usually append events from a route handler rather than inline. Take `IEventLog` as a dependency and append — the container injects it:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Microsoft.AspNetCore.Builder;
  using Microsoft.AspNetCore.Mvc;

public static class AspNetCoreBookEndpoint
  {
      public static void MapEndpoints(WebApplication app)
      {
          app.MapPost("/api/books/{bookId}/borrow", async (
              [FromServices] IEventLog eventLog,
              [FromRoute] Guid bookId,
              [FromQuery] string memberName) =>
                  await eventLog.Append(bookId, new GetStartedBookBorrowed(memberName)));
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore

/**
   * Kotlin has no ASP.NET Core minimal-API route builder to show here - the handler is a plain
   * suspend function taking the values a web framework would already have extracted from the
   * request (a path variable and a query parameter), and appends the event directly. Spring MVC
   * handlers are synchronous, so bridge with runBlocking there; on WebFlux, or anywhere that
   * already supports suspend functions, call this directly instead.
   */
  class AspNetCoreBookEndpoint(private val eventStore: IEventStore) {
      suspend fun borrow(bookId: String, memberName: String) =
          eventStore.eventLog.append(bookId, GetStartedBookBorrowed(memberName))
  }
  ```

* Java

```java
  import io.cratis.chronicle.java.BlockingEventStore;

// Java has no ASP.NET Core minimal-API route builder to show here - the handler is a plain
  // method taking the values a web framework would already have extracted from the request (a
  // path variable and a query parameter), and appends the event directly through the blocking
  // event store facade a Spring MVC handler can call without any coroutine bridging.
  class AspNetCoreBookEndpoint {
      private final BlockingEventStore eventStore;

AspNetCoreBookEndpoint(BlockingEventStore eventStore) {
          this.eventStore = eventStore;
      }

void borrow(String bookId, String memberName) {
          eventStore.getEventLog().append(bookId, new GetStartedBookBorrowed(memberName));
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The `bookId` from the route is the [event source](/chronicle/concepts/event-source/) — the book this fact is about — and `memberName` is the event’s payload. That one `Append` is all it takes; the projections pick it up from there — `Book` flips to on loan and a `BorrowedBook` instance appears — along with any reactors.

## Register your artifacts

[Section titled “Register your artifacts”](#register-your-artifacts)

Chronicle creates its discovered artifacts — reactors, reducers, projections — through the container, so they need to be registered as services. For a handful, register them explicitly:

* C#

```csharp
  using Microsoft.AspNetCore.Builder;
  using Microsoft.Extensions.DependencyInjection;

public static class AspNetCoreExplicitRegistration
  {
      public static void ConfigureServices(WebApplicationBuilder builder)
      {
          builder.Services.AddTransient<GetStartedBookReturnedNotifier>();
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import kotlinx.coroutines.runBlocking

/**
   * Autodiscovery already finds every `@Reactor` in a scanned package - this is only needed when a
   * reactor is constructed with something Spring cannot inject on its own, or when
   * `cratis.chronicle.auto-discover-and-register` is turned off and every artifact is registered
   * by hand. In a Spring Boot application this factory function is exposed as an `@Bean` inside an
   * `@Configuration` class, so the constructed instance is also available for injection elsewhere.
   */
  fun registerBookReturnedNotifier(eventStore: IEventStore): GetStartedBookReturnedNotifier {
      val notifier = GetStartedBookReturnedNotifier()
      runBlocking { eventStore.reactors.register(notifier) }
      return notifier
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReactorsServiceJavaBridge;

// Autodiscovery already finds every @Reactor in a scanned package - this is only needed when a
  // reactor is constructed with something Spring cannot inject on its own, or when
  // cratis.chronicle.auto-discover-and-register is turned off and every artifact is registered by
  // hand. In a Spring Boot application this factory method is exposed as an @Bean inside an
  // @Configuration class, so the constructed instance is also available for injection elsewhere.
  class AspNetCoreExplicitRegistration {
      GetStartedBookReturnedNotifier bookReturnedNotifier(IEventStore eventStore) {
          GetStartedBookReturnedNotifier notifier = new GetStartedBookReturnedNotifier();
          ReactorsServiceJavaBridge.register(eventStore.getReactors(), notifier);
          return notifier;
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

As the solution grows this gets tedious, so Cratis Fundamentals can do it by convention:

* C#

```csharp
  using Cratis.DependencyInjection;
  using Microsoft.AspNetCore.Builder;
  using Microsoft.Extensions.DependencyInjection;

public static class AspNetCoreConventionRegistration
  {
      public static void ConfigureServices(WebApplicationBuilder builder)
      {
          builder.Services
              .AddBindingsByConvention()
              .AddSelfBindings();
      }
  }
  ```

* Kotlin

```kotlin
  /**
   * Spring's own convention is `@ComponentScan`: every class carrying a recognized stereotype in
   * the scanned packages becomes a registered bean automatically - the same mechanism that finds
   * Chronicle artifacts. `@SpringBootApplication` already implies scanning its own package and
   * below, so this is only needed to widen the scan to another package explicitly, by adding
   * `@ComponentScan("io.cratis.chronicle.samples.getstarted")` to an `@Configuration` class.
   */
  object AspNetCoreConventionRegistration
  ```

* Java

```java
  // Spring's own convention is @ComponentScan: every class carrying a recognized stereotype in the
  // scanned packages becomes a registered bean automatically - the same mechanism that finds
  // Chronicle artifacts. @SpringBootApplication already implies scanning its own package and
  // below, so this is only needed to widen the scan to another package explicitly, by adding
  // @ComponentScan("io.cratis.chronicle.samples.getstarted") to an @Configuration class.
  class AspNetCoreConventionRegistration {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`AddBindingsByConvention` registers any service that implements an interface of the same name prefixed with `I` (`IFoo` → `Foo`); `AddSelfBindings` registers concrete classes as themselves, so you can depend on them directly without registering each one.

## Configure the MongoDB client

[Section titled “Configure the MongoDB client”](#configure-the-mongodb-client)

The `Books` query reads documents Chronicle wrote, so the MongoDB driver needs to match how Chronicle stores them — register these conventions once at startup:

## MongoDB

[Section titled “MongoDB”](#mongodb)

When leveraging the Reducer and Projection capabilities of Chronicle, your MongoDB Client needs to be configured to match how it produces documents and naming conventions. By adding the following code, you’ll have something that matches:

* C#

```csharp
  using MongoDB.Bson;
  using MongoDB.Bson.Serialization;
  using MongoDB.Bson.Serialization.Conventions;
  using MongoDB.Bson.Serialization.Serializers;

public static class GetStartedMongoDbDefaults
  {
      public static void Configure()
      {
          BsonSerializer
              .RegisterSerializer(new GuidSerializer(GuidRepresentation.Standard));

var pack = new ConventionPack
          {
              // We want to ignore extra elements that might be in the documents, Chronicle adds some metadata to the documents
              new IgnoreExtraElementsConvention(true),

// Chronicle uses camelCase for element names, so we need to use this convention
              new CamelCaseElementNameConvention()
          };
          ConventionRegistry.Register("conventions", pack, t => true);
      }
  }
  ```

* Kotlin

```kotlin
  /**
   * Kotlin has nothing to configure here. Chronicle stores event source ids as standard UUIDs and
   * read model fields as camelCase names - which already match Kotlin property names - and reads
   * go through `IEventStore.readModels` rather than a raw MongoDB driver, so there is no
   * `MongoClientSettings`, GUID representation, or "ignore unknown elements" convention to
   * register. Unknown document fields are simply not deserialized into properties the read model
   * class does not declare.
   */
  object GetStartedMongoDbDefaults
  ```

* Java

```java
  // Java has nothing to configure here. Chronicle stores event source ids as standard UUIDs and
  // read model fields as camelCase names - which already match Java property names - and reads go
  // through IEventStore.getReadModels() rather than a raw MongoDB driver, so there is no
  // MongoClientSettings, GUID representation, or "ignore unknown elements" convention to register.
  // Unknown document fields are simply not deserialized into properties the read model class does
  // not declare.
  class GetStartedMongoDbDefaults {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

[Snippet source](https://github.com/cratis/samples/blob/main/Chronicle/Quickstart/Common/MongoDBDefaults.cs#L16-L27)

Note

These conventions match how Chronicle names and shapes the stored document, but the driver still builds the instance itself — Chronicle’s own read behavior does not travel with it. The one that bites is a child collection with no children, which is stored as an absent field: read through Chronicle and a non-nullable property comes back empty, read it with the driver and it comes back as whatever the driver does with a missing field. See [Empty child collections](/chronicle/read-models/empty-child-collections/).

It doesn’t travel the other way either: these conventions apply to the reads you make with the driver, never to a read model Chronicle hands back or injects into a command. See [What a MongoDB convention pack reaches](/chronicle/sinks/#what-a-mongodb-convention-pack-reaches).

Then register the database and the collections you want to inject, so a type can take an `IMongoCollection<Book>` dependency without ever touching `MongoClient`:

* C#

```csharp
  using Microsoft.AspNetCore.Builder;
  using Microsoft.Extensions.DependencyInjection;
  using MongoDB.Driver;

public static class AspNetCoreMongoRegistration
  {
      public static void ConfigureServices(WebApplicationBuilder builder)
      {
          builder.Services.AddSingleton<IMongoClient>(new MongoClient("mongodb://localhost:27017"));
          builder.Services.AddSingleton(provider => provider.GetRequiredService<IMongoClient>().GetDatabase("Quickstart"));
          builder.Services.AddTransient(provider => provider.GetRequiredService<IMongoDatabase>().GetCollection<GetStartedBook>("Books"));
      }
  }
  ```

* Kotlin

```kotlin
  /**
   * Kotlin needs no separate MongoDB registration step here. Queries go through
   * `IEventStore.readModels`, which the connected client already exposes - there is no raw
   * `MongoCollection` to construct or register as a bean, in Spring Boot or anywhere else. See
   * `get-started/common/mongo-query` for the equivalent query.
   */
  object AspNetCoreMongoRegistration
  ```

* Java

```java
  // Java needs no separate MongoDB registration step here. Queries go through
  // IEventStore.getReadModels(), which the connected client already exposes - there is no raw
  // MongoCollection to construct or register as a bean, in Spring Boot or anywhere else. See
  // get-started/common/mongo-query for the equivalent query.
  class AspNetCoreMongoRegistration {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Now the `Books` query from the querying section above resolves its collection straight from the container.

## Recap

[Section titled “Recap”](#recap)

You added Chronicle to an ASP.NET Core app with two lines in `Program.cs` — `AddCratisChronicle` to register and discover everything, `UseCratisChronicle` to hook into the pipeline — then appended events straight from a minimal API endpoint and read them back through MongoDB collections injected by the container. Because you’re in a DI world, your reactors, projections, and collections are all just registered services.

## Where to go next

[Section titled “Where to go next”](#where-to-go-next)

* **Put a typed UI on top** — [Arc](/arc/) adds commands, queries, and generated TypeScript proxies so React stays in lockstep with your C#. See [Build a full-stack feature](/build-a-full-app/).
* **Build the domain step by step** — the [tutorial](/chronicle/tutorial/) walks the library model one concept at a time.
* **A different host** — the same artifacts run unchanged in a [Worker Service](/chronicle/get-started/worker/) or a bare [console](/chronicle/get-started/console/) app.

# Choose an application host model

> Pick the level of host your application code runs in — console, worker service, or ASP.NET Core, with Arc as an application layer on top — then run the Chronicle kernel locally against MongoDB, PostgreSQL, SQL Server, or SQLite, or let Aspire wire the database choice for you.

Chronicle can feel like several things at once: a client library, a .NET host integration, and a kernel process your applications connect to. The trick is to separate two decisions that are both yours to make. First, **which application host your code runs in** — a console app, a worker service, or ASP.NET Core. Second, **how you run the Chronicle kernel** — locally in Docker, inside an Aspire AppHost, or as infrastructure your platform operates.

Pick the smallest level that answers the question you have today. You can move up the levels without changing your events, projections, reducers, or reactors. And by the end of this page you’ll also have a kernel running locally, ready for whichever host you picked.

```
The Chronicle kernel — run it your way

Your application host — pick a level

Arc application layer — commands, queries, proxies

Console app — explicit client

Worker service — generic host + DI

ASP.NET Core — web endpoints + DI

Local Docker / Compose

Aspire AppHost

Managed by your platform
```

## The app host decides how much wiring you own

[Section titled “The app host decides how much wiring you own”](#the-app-host-decides-how-much-wiring-you-own)

| Level                                              | What you write                                                                    | What Chronicle wires                                                                                        | Use it when                                                                  |
| -------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [Console](/chronicle/get-started/console/)         | `new ChronicleClient(...)`, `GetEventStore(...)`, append events yourself          | Nothing hidden. You see the client and event store directly.                                                | You are learning, debugging a small reproduction, or writing a script.       |
| [Worker Service](/chronicle/get-started/worker/)   | `Host.CreateApplicationBuilder`, `AddCratisChronicle(...)`, a `BackgroundService` | DI registration and artifact discovery for reactors, reducers, and projections.                             | You process events, run background workflows, or keep derived state updated. |
| [ASP.NET Core](/chronicle/get-started/aspnetcore/) | `WebApplication.CreateBuilder`, `AddCratisChronicle(...)`, `UseCratisChronicle()` | DI registration, artifact discovery, and request-pipeline integration.                                      | You expose HTTP endpoints, controllers, or minimal APIs that append events.  |
| [Arc + Chronicle](/arc/backend/chronicle/)         | Arc commands and queries; Chronicle-backed command return values and projections  | Arc’s command/query pipeline plus Chronicle event appending, identity, tenancy, and read-model integration. | You want a typed full-stack CQRS app with generated TypeScript proxies.      |

Arc is not a host model

Arc is an **application layer**, not a fourth host. It sits on top of the host you choose — in practice ASP.NET Core — and adds commands, queries, and generated TypeScript proxies above the same Chronicle wiring. Choosing Arc doesn’t exempt you from this page: you still pick a host level underneath it and still run the kernel one of the ways below.

The domain artifacts stay the same across these levels. A `BookRegistered` event, a `BookStatus` projection, and a `NotifyWaitingList` reactor can start in a console sample and later run unchanged in a worker, web API, or Arc application.

## You decide who runs the kernel

[Section titled “You decide who runs the kernel”](#you-decide-who-runs-the-kernel)

The kernel has no opinion about where it lives. It’s a container plus the storage you point it at — so you and your team choose how to run it, and you can change that choice later without touching application code:

| How you run it                                              | What it gives you                                                                                                        | Use it when                                                                       |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| [Local Docker](#run-chronicle-locally)                      | One kernel reachable at `chronicle://localhost:35000`, with the workbench at `https://localhost:35000` on the same port. | You need the fastest local feedback loop.                                         |
| [Docker Compose](/chronicle/hosting/docker-compose/)        | Chronicle and storage as named services in a local or CI topology.                                                       | You want repeatable local infrastructure for a team or pipeline.                  |
| [Aspire AppHost](#let-aspire-wire-it-up)                    | Chronicle as an Aspire resource with endpoints and storage references wired into dependent projects.                     | Your .NET solution already uses Aspire to compose services locally.               |
| [Production-managed kernel](/chronicle/hosting/production/) | A Chronicle container, durable storage, TLS, secrets, health checks, and versioned deployment owned by your platform.    | The application should only know the Chronicle connection string and credentials. |

There is no special “managed client” mode in your application. Managed simply means you’ve handed the kernel and its storage to whoever operates your infrastructure — Kubernetes, Docker, cloud services, or an internal platform team — and your app gets a connection string.

Whichever way you go in production, local development starts the same: with a kernel on your machine. Let’s get one running.

## Run Chronicle locally

[Section titled “Run Chronicle locally”](#run-chronicle-locally)

Before a single line of your host code can append an event, the kernel has to be up and reachable. You only need to do this once per machine — leave it running in the background and come back to your code.

### Prerequisites

[Section titled “Prerequisites”](#prerequisites)

* [.NET 8 or higher](https://dot.net) — the SDK you build and run your app with.
* [Docker Desktop or compatible](https://www.docker.com/products/docker-desktop/) — the kernel ships as a container.
* *Optional:* a MongoDB client such as [MongoDB Compass](https://www.mongodb.com/products/tools/compass), handy for peeking at the read models a projection builds. You don’t need it to follow the guides — the built-in [workbench](#see-it-in-the-workbench) shows you the events.

### The fastest start: the development image

[Section titled “The fastest start: the development image”](#the-fastest-start-the-development-image)

The `latest-development` image bundles MongoDB, so there’s nothing else to install or wire up — one command and the kernel is running:

```shell
docker run -d -p 27017:27017 -p 35000:35000 cratis/chronicle:latest-development
```

Two ports, two jobs — Chronicle now serves everything on one port, and it’s TLS:

| Port    | What it is                                                                                                                                                                                                 |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `35000` | The kernel endpoint your app connects to (`chronicle://localhost:35000`), and the [Chronicle workbench](#see-it-in-the-workbench) — a web UI for browsing your event store — at `https://localhost:35000`. |
| `27017` | The bundled MongoDB, where projections write their read models.                                                                                                                                            |

That’s everything most local work needs. If you’d rather run against a database you already have — or a different engine entirely — read on; otherwise jump to [picking your host guide](#next-connect-your-host).

### Bring your own database

[Section titled “Bring your own database”](#bring-your-own-database)

The `latest-development-slim` image leaves the database out, so you point Chronicle at one you run yourself. Two environment variables tell it where to go:

* `Cratis__Chronicle__Storage__Type`
* `Cratis__Chronicle__Storage__ConnectionDetails`

The Compose files below bring up the kernel and a database together. Pick the tab for your engine.

* MongoDB

Chronicle uses MongoDB transactions and change streams, so MongoDB must run as a replica set (or a sharded cluster) — a standalone `mongod` won’t do. This file initializes a single-node replica set for local development:

```yaml
  services:
    chronicle:
      image: cratis/chronicle:latest-development-slim
      depends_on:
        - mongodb
        - mongodb-init
      environment:
        - Cratis__Chronicle__Storage__Type=MongoDB
        - Cratis__Chronicle__Storage__ConnectionDetails=mongodb://mongodb:27017/?directConnection=true
      ports:
        - 35000:35000

mongodb:
      image: mongo:8
      command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
      ports:
        - 27017:27017

mongodb-init:
      image: mongo:8
      depends_on:
        - mongodb
      restart: "no"
      command:
        - /bin/bash
        - -lc
        - |
          until mongosh --host mongodb --quiet --eval "db.adminCommand('ping')" >/dev/null 2>&1; do
            sleep 1
          done
          mongosh --host mongodb --quiet --eval "
          try {
            rs.status();
          } catch (e) {
            rs.initiate({
              _id: 'rs0',
              members: [{ _id: 0, host: 'localhost:27017' }]
            });
          }"
  ```

Why this setup:

* `host: 'localhost:27017'` makes the replica set topology usable from host tools (for example `mongosh` and Compass) when they connect to `mongodb://localhost:27017/?replicaSet=rs0`.
  * Chronicle still reaches MongoDB over the Docker network (`mongodb:27017`) and uses `directConnection=true` to avoid following the advertised host back to `localhost` inside the Chronicle container.
  * `directConnection=true` does not disable transactions; transactions still work because MongoDB is running as a replica set.
  * If your existing data volume was initialized with a different replica-set host, run `docker compose down -v` (or wipe the MongoDB data volume) before starting again so `rs.initiate()` can apply the new host.

* PostgreSQL

```yaml
  services:
    chronicle:
      image: cratis/chronicle:latest-development-slim
      depends_on:
        - postgres
      environment:
        - Cratis__Chronicle__Storage__Type=PostgreSql
        - Cratis__Chronicle__Storage__ConnectionDetails=Host=postgres;Port=5432;Database=chronicle;Username=postgres;Password=postgres
      ports:
        - 35000:35000

postgres:
      image: postgres:16
      environment:
        - POSTGRES_DB=chronicle
        - POSTGRES_USER=postgres
        - POSTGRES_PASSWORD=postgres
      ports:
        - 5432:5432
  ```

* SQL Server

Caution

The SQL Server credentials in this example are for local development only. For production, use secure credentials and manage secrets through Docker secrets, environment files, or an external secret manager.

```yaml
  services:
    chronicle:
      image: cratis/chronicle:latest-development-slim
      depends_on:
        - sqlserver
      environment:
        - Cratis__Chronicle__Storage__Type=MsSql
        - Cratis__Chronicle__Storage__ConnectionDetails=Server=sqlserver,1433;Database=Chronicle;User Id=sa;Password=Your_strong_password123!;TrustServerCertificate=True;Encrypt=False
      ports:
        - 35000:35000

sqlserver:
      image: mcr.microsoft.com/mssql/server:2025-latest
      environment:
        - ACCEPT_EULA=Y
        - MSSQL_SA_PASSWORD=Your_strong_password123!
      ports:
        - 1433:1433
  ```

* SQLite

SQLite is file-based, so there’s no second container — just a volume for the database file:

```yaml
  services:
    chronicle:
      image: cratis/chronicle:latest-development-slim
      environment:
        - Cratis__Chronicle__Storage__Type=Sqlite
        - Cratis__Chronicle__Storage__ConnectionDetails=Data Source=/data/chronicle.db
      volumes:
        - chronicle-data:/data
      ports:
        - 35000:35000

volumes:
    chronicle-data:
  ```

Bring any of these up the usual way, in the background:

```shell
docker compose up -d
```

Want local observability too — logs, traces, and metrics next to the kernel? The [Docker Compose hosting guide](/chronicle/hosting/docker-compose/) adds the Aspire dashboard to the same topology.

### See it in the workbench

[Section titled “See it in the workbench”](#see-it-in-the-workbench)

Whichever image you ran, it includes the **Chronicle workbench** — a web UI for poking at your event store. Open <https://localhost:35000> and log in with the development credentials (username `Admin`, password `ChangeMeNow!`). It’s HTTPS now — in development Chronicle serves the port with a self-signed certificate it generates on the fly, so your browser will warn you the first time; accept it to continue. Pick an event store and look at **Sequences** to watch events land in order. It’s the quickest way to confirm the kernel is up and your app is actually appending.

## Let Aspire wire it up

[Section titled “Let Aspire wire it up”](#let-aspire-wire-it-up)

If your solution composes services with [Aspire](https://learn.microsoft.com/dotnet/aspire/), you don’t write Compose files at all — the database choice flows from the Aspire app model. The `Cratis.Chronicle.Aspire` package adds Chronicle as a resource in your AppHost:

```shell
dotnet add package Cratis.Chronicle.Aspire
```

For development, one line gives you the same batteries-included kernel as the `docker run` above — `AddCratisChronicle()` uses the development image with embedded MongoDB:

* C#

```csharp
  using Aspire.Hosting;

public static class GetStartedHostingBasicAppHost
  {
      public static void ConfigureAppHost(string[] args)
      {
          var builder = DistributedApplication.CreateBuilder(args);

var chronicle = builder.AddCratisChronicle();

// Reference any of your application's projects the same way -
          // builder.AddProject<Projects.MyApi>("api") when Projects.MyApi is generated from your solution
          builder.AddContainer("api", "my-org/my-api")
              .WithReference(chronicle);

builder.Build().Run();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

To choose a database, pass a configure callback. Aspire then switches to the production image (no embedded MongoDB) and the `With*` method you pick sets the kernel’s storage type and connection string from the resource you hand it — the same two environment variables you saw in the Compose files, now derived from your app model instead of hand-written:

The production image also wants certificates

Passing a configure callback moves you off the development image, and the production image does not generate the TLS certificate it serves port 35000 with, nor the certificate that protects its OAuth keys — it throws at startup and stops. The snippets below show the storage wiring only, so pair them with `WithTlsCertificate(...)` and `WithEncryptionCertificate(...)`; the [Aspire integration guide](/chronicle/hosting/aspire/) shows both. If you only wanted a kernel to develop against, stay on `AddCratisChronicle()` above — it brings its own database *and* its own certificate.

* MongoDB

* C#

```csharp
    using Aspire.Hosting;
    using Aspire.Hosting.ApplicationModel;
    using Cratis.Chronicle.Aspire;

public static class GetStartedHostingMongoDatabase
    {
        public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
        {
            var mongo = builder.AddConnectionString("chronicle-mongo");

return builder.AddCratisChronicle("chronicle", c => c.WithMongoDB(mongo));
        }
    }
    ```

* Kotlin

```text
    Kotlin does not support this workflow yet.
    ```

* Java

```text
    Java does not support this workflow yet.
    ```

* Elixir

```text
    Elixir does not support this workflow yet.
    ```

* TypeScript

```text
    TypeScript does not support this workflow yet.
    ```

`mongo` can be any resource with a connection string — a MongoDB Atlas connection string as shown, or a container added directly in the AppHost with `builder.AddMongoDB("mongo")`.

* PostgreSQL

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class GetStartedHostingMongoDatabase
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
      {
          var mongo = builder.AddConnectionString("chronicle-mongo");

return builder.AddCratisChronicle("chronicle", c => c.WithMongoDB(mongo));
      }
  }
  ```

* SQL Server

```text
  Kotlin does not support this workflow yet.
  ```

* SQLite

```text
  Java does not support this workflow yet.
  ```

* C#

```text
  Elixir does not support this workflow yet.
  ```

* Kotlin

```text
  TypeScript does not support this workflow yet.
  ```

* Java

* C#

```csharp
    using Aspire.Hosting;
    using Aspire.Hosting.ApplicationModel;
    using Cratis.Chronicle.Aspire;

public static class GetStartedHostingPostgresDatabase
    {
        public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
        {
            // Use the Aspire.Hosting.PostgreSQL integration's builder.AddPostgres(...).AddDatabase(...) when
            // your AppHost already provisions the database — any resource with a connection string works here.
            var postgres = builder.AddConnectionString("chronicle-postgres");

return builder.AddCratisChronicle("chronicle", c => c.WithPostgreSql(postgres));
        }
    }
    ```

* Kotlin

```text
    Kotlin does not support this workflow yet.
    ```

* Java

```text
    Java does not support this workflow yet.
    ```

* Elixir

```text
    Elixir does not support this workflow yet.
    ```

* TypeScript

```text
    TypeScript does not support this workflow yet.
    ```

* Elixir

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class GetStartedHostingPostgresDatabase
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
      {
          // Use the Aspire.Hosting.PostgreSQL integration's builder.AddPostgres(...).AddDatabase(...) when
          // your AppHost already provisions the database — any resource with a connection string works here.
          var postgres = builder.AddConnectionString("chronicle-postgres");

return builder.AddCratisChronicle("chronicle", c => c.WithPostgreSql(postgres));
      }
  }
  ```

* TypeScript

```text
  Kotlin does not support this workflow yet.
  ```

* C#

```text
  Java does not support this workflow yet.
  ```

* Kotlin

```text
  Elixir does not support this workflow yet.
  ```

* Java

```text
  TypeScript does not support this workflow yet.
  ```

* Elixir

* C#

```csharp
    using Aspire.Hosting;
    using Aspire.Hosting.ApplicationModel;
    using Cratis.Chronicle.Aspire;

public static class GetStartedHostingSqlServerDatabase
    {
        public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
        {
            // Use the Aspire.Hosting.SqlServer integration's builder.AddSqlServer(...).AddDatabase(...) when
            // your AppHost already provisions the database — any resource with a connection string works here.
            var sql = builder.AddConnectionString("chronicle-sql");

return builder.AddCratisChronicle("chronicle", c => c.WithMsSql(sql));
        }
    }
    ```

* Kotlin

```text
    Kotlin does not support this workflow yet.
    ```

* Java

```text
    Java does not support this workflow yet.
    ```

* Elixir

```text
    Elixir does not support this workflow yet.
    ```

* TypeScript

```text
    TypeScript does not support this workflow yet.
    ```

* TypeScript

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class GetStartedHostingSqlServerDatabase
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
      {
          // Use the Aspire.Hosting.SqlServer integration's builder.AddSqlServer(...).AddDatabase(...) when
          // your AppHost already provisions the database — any resource with a connection string works here.
          var sql = builder.AddConnectionString("chronicle-sql");

return builder.AddCratisChronicle("chronicle", c => c.WithMsSql(sql));
      }
  }
  ```

* C#

```text
  Kotlin does not support this workflow yet.
  ```

* Kotlin

```text
  Java does not support this workflow yet.
  ```

* Java

```text
  Elixir does not support this workflow yet.
  ```

* Elixir

```text
  TypeScript does not support this workflow yet.
  ```

* TypeScript

SQLite is file-based, so you pass the connection string directly instead of a resource:

* C#

```csharp
    using Aspire.Hosting;
    using Aspire.Hosting.ApplicationModel;
    using Cratis.Chronicle.Aspire;

public static class GetStartedHostingSqliteDatabase
    {
        public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder) =>
            builder.AddCratisChronicle("chronicle", c => c.WithSqlite("Data Source=/data/chronicle.db"));
    }
    ```

* Kotlin

```text
    Kotlin does not support this workflow yet.
    ```

* Java

```text
    Java does not support this workflow yet.
    ```

* Elixir

```text
    Elixir does not support this workflow yet.
    ```

* TypeScript

```text
    TypeScript does not support this workflow yet.
    ```

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class GetStartedHostingSqliteDatabase
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder) =>
          builder.AddCratisChronicle("chronicle", c => c.WithSqlite("Data Source=/data/chronicle.db"));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`WithReference(chronicle)` hands your application projects a `chronicle://host:port` connection string pointing at the kernel’s gRPC endpoint — no hardcoded ports. The [Aspire integration guide](/chronicle/hosting/aspire/) covers the rest: exposed endpoints, compliance key storage with HashiCorp Vault or Azure Key Vault, and the full AppHost walkthrough.

## Next: connect your host

[Section titled “Next: connect your host”](#next-connect-your-host)

The kernel is running and listening on `chronicle://localhost:35000`. Now connect your app to it:

* **Just exploring?** The [Get started quickstart](/chronicle/get-started/) scaffolds a ready-to-run app from a template — the fastest way to see the whole loop.
* **[Console](/chronicle/get-started/console/)** — the bare-bones version, no DI container, every connection explicit.
* **[Worker service](/chronicle/get-started/worker/)** — a background host for the reacting side of an event-sourced system.
* **[ASP.NET Core](/chronicle/get-started/aspnetcore/)** — a web API that appends events straight from its endpoints.

## Common paths

[Section titled “Common paths”](#common-paths)

| If you are…                          | Start with                                                                                               | Then move to                                                                                                                          |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Learning Chronicle from scratch      | [Get started](/chronicle/get-started/), then [Console](/chronicle/get-started/console/)                  | [Tutorial](/chronicle/tutorial/)                                                                                                      |
| Adding events to an existing web API | [Run Chronicle locally](#run-chronicle-locally), then [ASP.NET Core](/chronicle/get-started/aspnetcore/) | [Production hosting](/chronicle/hosting/production/)                                                                                  |
| Building background event processors | [Worker Service](/chronicle/get-started/worker/)                                                         | [Reactors](/chronicle/reactors/) and [Reducers](/chronicle/reducers/)                                                                 |
| Building a full-stack Cratis app     | [Arc + Chronicle](/arc/backend/chronicle/)                                                               | [Build a full-stack feature](/build-a-full-app/)                                                                                      |
| Preparing a team environment         | [Docker Compose](/chronicle/hosting/docker-compose/) or [Aspire](#let-aspire-wire-it-up)                 | [Production hosting](/chronicle/hosting/production/) and [Data Protection Key Encryption](/chronicle/hosting/encryption-certificate/) |

If you are unsure, use this rule: learn in a console app, ship user-facing endpoints in ASP.NET Core or Arc, run background work in a worker, and let your platform own the production kernel.

# Add Chronicle to a console app

> Wire Chronicle into a plain .NET console app by hand — no DI container, no web host — and watch a small library domain take shape through events, a projection, and a reactor.

A console app is the smallest place to run Chronicle: no web host, no dependency-injection container, nothing between you and the client. That’s exactly why it’s the clearest place to start — every moving part is something you write explicitly, so nothing is hidden by convention. (The [Worker Service](/chronicle/get-started/worker/) and [ASP.NET Core](/chronicle/get-started/aspnetcore/) guides let the host’s DI container wire the same pieces up for you; start here if you want to see what that wiring actually does.)

We’ll build a small, familiar domain — a library — and by the end you’ll have appended events and projected them into read models you can query in MongoDB.

## Before you start

[Section titled “Before you start”](#before-you-start)

You can also find the [complete Console quickstart sample](https://github.com/Cratis/Samples/tree/main/Chronicle/Quickstart/Console) on GitHub.

## Set up the project

[Section titled “Set up the project”](#set-up-the-project)

Create a folder for your project, then a .NET console project inside it:

```shell
dotnet new console
```

Add a reference to the [Chronicle client package](https://www.nuget.org/packages/Cratis.Chronicle):

```shell
dotnet add package Cratis.Chronicle
```

## Connect the client

[Section titled “Connect the client”](#connect-the-client)

Everything in Chronicle is reached through a `ChronicleClient`. From a client you ask for the **event store** you want to work with — here, one named `Quickstart`. Because there’s no DI container to do it for you, you create the client yourself:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Connections;

public static class GetStartedConsoleClient
  {
      public static async Task Run()
      {
          // ChronicleConnectionString.Development points at the local dev kernel on chronicle://localhost:35000
          using var client = new ChronicleClient(ChronicleConnectionString.Development);
          var eventStore = await client.GetEventStore("Quickstart");
          Console.WriteLine($"Connected to event store: {eventStore.Name}");

// Use eventStore for the lifetime of your program — appending, querying, and so on.
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.ChronicleOptions

fun run() {
      // ChronicleOptions.development() points at the local dev kernel on chronicle://localhost:35000
      val client = ChronicleClient(ChronicleOptions.development())
      val eventStore = client.getEventStore("Quickstart")
      println("Connected to event store: ${eventStore.name}")

// Use eventStore for the lifetime of your program — appending, querying, and so on.
  }
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleClient;
  import io.cratis.chronicle.ChronicleOptions;

class ConsoleConnect {
      void run() {
          // ChronicleOptions.development() points at the local dev kernel on chronicle://localhost:35000
          var client = new ChronicleClient(ChronicleOptions.Companion.development());
          var eventStore = client.getEventStore("Quickstart", "Default");
          System.out.println("Connected to event store: " + eventStore.getName());

// Use eventStore for the lifetime of your program — appending, querying, and so on.
      }
  }
  ```

* Elixir

application.ex

```elixir
  defmodule MyApp.Application do
    use Application

@impl true
    def start(_type, _args) do
      children = [
        {Chronicle.Client,
         connection_string: "chronicle://localhost:35000",
         event_store: "quickstart",
         otp_app: :my_app}
      ]

Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
    end
  end
  ```

Confirm the connection

```elixir
  {:ok, event_stores} = Chronicle.get_event_stores()
  IO.puts("Connected to event store: #{Enum.at(event_stores, 0)}")

# Use Chronicle.* functions for the lifetime of your program — appending, querying, and so on.
  ```

* TypeScript

```typescript
  import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';

async function run() {
      // ChronicleOptions.development() points at the local dev kernel on chronicle://localhost:35000
      const client = new ChronicleClient(ChronicleOptions.development());
      const eventStore = await client.getEventStore('Quickstart');
      console.log(`Connected to event store: ${eventStore.name}`);

// Use eventStore for the lifetime of your program — appending, querying, and so on.
  }
  ```

`ChronicleConnectionString.Development` is the built-in connection string for the local development kernel — the same one `new ChronicleClient()` uses when you call it with no arguments. Spelling it out keeps the console version explicit; point it elsewhere with `ChronicleConnectionString.Default` (no credentials) or your own `new ChronicleConnectionString("chronicle://…")`.

That single `eventStore` is your handle to everything that follows:

```
Your console code

ChronicleClient

event store 'Quickstart'

Chronicle kernel (Docker)
```

## Define some events

[Section titled “Define some events”](#define-some-events)

Here are the facts of a small library — a book arrives, gets borrowed, and comes back:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record GetStartedBookAdded(string Title, string Isbn);

[EventType]
  public record GetStartedBookBorrowed(string MemberName);

[EventType]
  public record GetStartedBookReturned;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class GetStartedBookAdded(val title: String, val isbn: String)

@EventType
  data class GetStartedBookBorrowed(val memberName: String)

@EventType
  class GetStartedBookReturned
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record GetStartedBookAdded(String title, String isbn) {}

@EventType
  record GetStartedBookBorrowed(String memberName) {}

@EventType
  record GetStartedBookReturned() {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.GetStartedBookAdded do
    use Chronicle.Events.EventType, id: "get-started-book-added"

defstruct [:title, :isbn]
  end

defmodule MyApp.Events.GetStartedBookBorrowed do
    use Chronicle.Events.EventType, id: "get-started-book-borrowed"

defstruct [:member_name]
  end

defmodule MyApp.Events.GetStartedBookReturned do
    use Chronicle.Events.EventType, id: "get-started-book-returned"

defstruct []
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class GetStartedBookAdded {
      constructor(
          readonly title: string,
          readonly isbn: string
      ) {}
  }

@eventType()
  class GetStartedBookBorrowed {
      constructor(readonly memberName: string) {}
  }

@eventType()
  class GetStartedBookReturned {
  }
  ```

`BookReturned` carries no data at all — that it *happened*, on a particular book’s stream, is the whole story. Not every fact needs a payload.

## Append them

[Section titled “Append them”](#append-them)

* C#

```csharp
  using Cratis.Chronicle;

public class GetStartedBookService(IEventStore eventStore)
  {
      public async Task<Guid> AddBook()
      {
          var eventLog = eventStore.EventLog;

var bookId = Guid.NewGuid();
          await eventLog.Append(bookId, new GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"));

return bookId;
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import java.util.UUID

class GetStartedBookService(private val eventStore: IEventStore) {
      suspend fun addBook(): String {
          val eventLog = eventStore.eventLog

val bookId = UUID.randomUUID().toString()
          eventLog.append(bookId, GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"))

return bookId
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingEventStore;
  import java.util.UUID;

class GetStartedBookService {
      private final BlockingEventStore eventStore;

GetStartedBookService(IEventStore eventStore) {
          this.eventStore = new BlockingEventStore(eventStore);
      }

String addBook() {
          var bookId = UUID.randomUUID().toString();

eventStore.getEventLog().append(
              bookId,
              new GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"));

return bookId;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.BookService do
    alias MyApp.Events.GetStartedBookAdded

def add_book do
      book_id = Base.encode16(:crypto.strong_rand_bytes(8), case: :lower)

:ok =
        Chronicle.append(book_id, %GetStartedBookAdded{
          title: "The Pragmatic Programmer",
          isbn: "978-0135957059"
        })

book_id
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async addBook(bookId: string): Promise<void> {
          const eventLog = this.store.eventLog;

await eventLog.append(bookId, new GetStartedBookAdded('The Pragmatic Programmer', '978-0135957059'));
      }
  }
  ```

Tip

Run your app, then open the [workbench](https://localhost:35000), pick your event store, and select **Sequences** — your `BookAdded` is sitting there at sequence number `0`, permanent and in order.

Note

![Chronicle Workbench showing events](/_astro/workbench.CcnUH1d2_Z1CPEDn.webp)

## Turn events into a read model

[Section titled “Turn events into a read model”](#turn-events-into-a-read-model)

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<GetStartedBookAdded>]
  public record GetStartedBook(
      [Key]
      Guid Id,

string Title,

string Isbn,

[SetValue<GetStartedBookAdded>(false)]
      [SetValue<GetStartedBookBorrowed>(true)]
      [SetValue<GetStartedBookReturned>(false)]
      bool OnLoan,

[SetFrom<GetStartedBookBorrowed>(nameof(GetStartedBookBorrowed.MemberName))]
      string? BorrowedBy);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.GetStartedBook do
    use Chronicle.ReadModels.ReadModel

defstruct id: nil, title: nil, isbn: nil, on_loan: false, borrowed_by: nil

from MyApp.Events.GetStartedBookAdded,
      set: [id: :event_source_id, title: :title, isbn: :isbn, on_loan: false]

from MyApp.Events.GetStartedBookBorrowed,
      set: [on_loan: true, borrowed_by: :member_name]

from MyApp.Events.GetStartedBookReturned,
      set: [on_loan: false]
  end
  ```

* TypeScript

```typescript
  import { fromEvent, Guid, readModel, setFrom, setValue } from '@cratis/chronicle';

@readModel()
  @fromEvent(GetStartedBookAdded)
  class GetStartedBook {
      id: Guid = Guid.empty;

@setFrom(GetStartedBookAdded, 'title')
      title = '';

@setFrom(GetStartedBookAdded, 'isbn')
      isbn = '';

@setValue(GetStartedBookAdded, false)
      @setValue(GetStartedBookBorrowed, true)
      @setValue(GetStartedBookReturned, false)
      onLoan = false;

@setFrom(GetStartedBookBorrowed, 'memberName')
      borrowedBy: string | null = null;
  }
  ```

Note

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<GetStartedBookBorrowed>]
  [RemovedWith<GetStartedBookReturned>]
  public record GetStartedBorrowedBook(
      [Key]
      Guid Id,

string MemberName);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWith
  import io.cratis.chronicle.readModels.ReadModel

* Java

```java
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWith;
  import io.cratis.chronicle.readModels.ReadModel;

public GetStartedBorrowedBook() {}

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getMemberName() { return memberName; }
      public void setMemberName(String memberName) { this.memberName = memberName; }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.GetStartedBorrowedBook do
    use Chronicle.ReadModels.ReadModel

defstruct id: nil, member_name: nil

from MyApp.Events.GetStartedBookBorrowed,
      set: [id: :event_source_id, member_name: :member_name]

removed_with MyApp.Events.GetStartedBookReturned, []
  end
  ```

* TypeScript

```typescript
  import { fromEvent, Guid, readModel, removedWith, setFrom } from '@cratis/chronicle';

@readModel()
  @fromEvent(GetStartedBookBorrowed)
  @removedWith(GetStartedBookReturned)
  class GetStartedBorrowedBook {
      id: Guid = Guid.empty;

@setFrom(GetStartedBookBorrowed, 'memberName')
      memberName = '';
  }
  ```

## Query the read models

[Section titled “Query the read models”](#query-the-read-models)

The most direct way to look at a read model is to ask Chronicle itself. `IReadModels` — reached through `eventStore.ReadModels` — hands you every instance of a read model, one call per view:

* C#

```csharp
  using Cratis.Chronicle;

return (books, borrowedBooks);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.BookQueryService do
    alias MyApp.ReadModels.GetStartedBook
    alias MyApp.ReadModels.GetStartedBorrowedBook

def query_books do
      {:ok, books} = Chronicle.all(GetStartedBook)
      {:ok, borrowed_books} = Chronicle.all(GetStartedBorrowedBook)

{books, borrowed_books}
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

return { books, borrowedBooks };
      }
  }
  ```

* C#

```csharp
  using Cratis.Chronicle;

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.BookPagingService do
    alias MyApp.ReadModels.GetStartedBook

def get_page do
      {:ok, result} = Chronicle.ReadModels.query(GetStartedBook, page: 1, page_size: 20)
      result.instances
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

getPage(): Promise<GetStartedBook[]> {
          return this.store.readModels.materialized.getInstances(GetStartedBook, 0, 20);
      }
  }
  ```

* C#

```csharp
  using MongoDB.Driver;

public class GetStartedBooks(IMongoCollection<GetStartedBook> collection)
  {
      public IEnumerable<GetStartedBook> OnLoan() => collection.Find(b => b.OnLoan).ToList();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class GetStartedBook(val title: String = "", val onLoan: Boolean = false)

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;
  import java.util.stream.Collectors;

@ReadModel
  record GetStartedBook(String title, boolean onLoan) {}

GetStartedBooks(IEventStore store) {
          this.store = store;
      }

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## React when something happens

[Section titled “React when something happens”](#react-when-something-happens)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.observation.Reactor

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.observation.Reactor;

* Elixir

```elixir
  defmodule MyApp.Reactors.GetStartedBookReturnedNotifier do
    use Chronicle.Reactors.Reactor

alias MyApp.Events.GetStartedBookReturned

@handles GetStartedBookReturned

* TypeScript

```typescript
  import { EventContext, reactor } from '@cratis/chronicle';

## Configure the MongoDB client

[Section titled “Configure the MongoDB client”](#configure-the-mongodb-client)

The `Books` query above reads documents Chronicle wrote. For your `IMongoCollection<Book>` to deserialize them, the MongoDB driver needs to match how Chronicle stores documents — register these conventions once at startup:

## MongoDB

[Section titled “MongoDB”](#mongodb)

* C#

```csharp
  using MongoDB.Bson;
  using MongoDB.Bson.Serialization;
  using MongoDB.Bson.Serialization.Conventions;
  using MongoDB.Bson.Serialization.Serializers;

* Kotlin

* Java

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

[Snippet source](https://github.com/cratis/samples/blob/main/Chronicle/Quickstart/Common/MongoDBDefaults.cs#L16-L27)

Note

With the conventions registered, the `Books` query reads the projection’s documents exactly as written.

## Recap

[Section titled “Recap”](#recap)

You wired Chronicle into a bare console app by hand: created a `ChronicleClient`, opened the `Quickstart` event store, appended events for a small library domain, projected them into the `Book` and `BorrowedBook` read models with model-bound attributes, queried them both on demand and from the materialized sink, and reacted to one with a reactor. Because there was no DI container, every connection was explicit and in plain sight.

## Where to go next

[Section titled “Where to go next”](#where-to-go-next)

* **[Build the same domain step by step](/chronicle/tutorial/)** — the tutorial walks the library model one concept at a time, explaining each as you go.
* **Let a host wire it up** — move the same code into a [Worker Service](/chronicle/get-started/worker/) or an [ASP.NET Core](/chronicle/get-started/aspnetcore/) app and let its DI container register the artifacts for you.
* **Understand the pieces** — the [Concepts](/chronicle/concepts/) section defines events, projections, reducers, and reactors in depth.

# Add Chronicle to a worker service

> Set up Chronicle in a .NET worker service (generic host) — the natural home for the reacting side of an event-sourced system, with the DI container wiring everything up for you.

A worker service is the natural home for the *reacting* side of an event-sourced system: no web front end, just a long-running host that processes events, runs scheduled jobs, or keeps derived data up to date. Setup is mostly a matter of letting the generic host’s DI container do the wiring — register Chronicle once, then inject what you need wherever you need it.

We’ll build the same small library domain as the other host guides. If you’re building a web API instead, the [ASP.NET Core guide](/chronicle/get-started/aspnetcore/) covers that host; for the bare-bones, no-container version, see the [console guide](/chronicle/get-started/console/).

## Before you start

[Section titled “Before you start”](#before-you-start)

## Set up the project

[Section titled “Set up the project”](#set-up-the-project)

Create a folder for your project, then a .NET worker service inside it:

```shell
dotnet new worker
```

Add a reference to the [Chronicle client package](https://www.nuget.org/packages/Cratis.Chronicle):

```shell
dotnet add package Cratis.Chronicle
```

Note

A worker only needs the base `Cratis.Chronicle` package — `Cratis.Chronicle.AspNetCore` is for web applications.

## Register Chronicle on the host

[Section titled “Register Chronicle on the host”](#register-chronicle-on-the-host)

The generic host builds your app through `IHostApplicationBuilder`, which already has a dependency-injection container. One call hooks Chronicle into it and names the event store to use:

* C#

```csharp
  using Microsoft.Extensions.Hosting;

public static class GetStartedWorkerRegistration
  {
      public static async Task ConfigureAndRun(string[] args)
      {
          var builder = Host.CreateApplicationBuilder(args);

builder.AddCratisChronicle(options => options.EventStore = "Quickstart");
          builder.Services.AddHostedService<GetStartedWorker>();

var host = builder.Build();
          await host.RunAsync();
      }
  }
  ```

* Kotlin

````kotlin
  /**
   * The starter doesn't care whether the application serves HTTP or just runs in the background -
   * the same autoconfiguration connects, discovers every artifact in this application's packages,
   * and registers them with the kernel. The entry point itself needs nothing Chronicle-specific -
   * only Spring Boot's own `@SpringBootApplication` class and `runApplication<...>(*args)`. Point
   * it at an event store with one setting in application.yml:
   *
   * ```yaml
   * cratis:
   *   chronicle:
   *     event-store: Quickstart
   * ```
   */
  object GetStartedWorkerRegistration
  ````

* Java

```java
  /**
   * The starter doesn't care whether the application serves HTTP or just runs in the background -
   * the same autoconfiguration connects, discovers every artifact in this application's packages,
   * and registers them with the kernel. The entry point itself needs nothing Chronicle-specific -
   * only Spring Boot's own {@code @SpringBootApplication} class and
   * {@code SpringApplication.run(...)}. Point it at an event store with one setting in
   * application.yml:
   *
   * <pre>
   * cratis:
   *   chronicle:
   *     event-store: Quickstart
   * </pre>
   */
  class GetStartedWorkerRegistration {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Like the [ASP.NET Core](/chronicle/get-started/aspnetcore/) host, `AddCratisChronicle` registers Chronicle’s services — `IEventStore`, `IEventLog`, `IReactors`, `IReducers`, `IProjections` — and automatically discovers and registers your artifacts (reactors, reducers, projections) from the loaded assemblies. It reads its connection settings from the `Cratis:Chronicle` section of `appsettings.json`:

```
AddCratisChronicle

Host.CreateApplicationBuilder

DI container (auto-discovers artifacts)

IEventStore · IEventLog · IReactors · IReducers · IProjections

your BackgroundService
```

appsettings.json

```json
{
  "Cratis": {
    "Chronicle": {
      "ConnectionString": "chronicle://localhost:35000",
      "EventStore": "Quickstart"
    }
  }
}
```

## Define some events

[Section titled “Define some events”](#define-some-events)

Here are the facts of a small library — a book arrives, gets borrowed, and comes back:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record GetStartedBookAdded(string Title, string Isbn);

[EventType]
  public record GetStartedBookBorrowed(string MemberName);

[EventType]
  public record GetStartedBookReturned;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class GetStartedBookAdded(val title: String, val isbn: String)

@EventType
  data class GetStartedBookBorrowed(val memberName: String)

@EventType
  class GetStartedBookReturned
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record GetStartedBookAdded(String title, String isbn) {}

@EventType
  record GetStartedBookBorrowed(String memberName) {}

@EventType
  record GetStartedBookReturned() {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.GetStartedBookAdded do
    use Chronicle.Events.EventType, id: "get-started-book-added"

defstruct [:title, :isbn]
  end

defmodule MyApp.Events.GetStartedBookBorrowed do
    use Chronicle.Events.EventType, id: "get-started-book-borrowed"

defstruct [:member_name]
  end

defmodule MyApp.Events.GetStartedBookReturned do
    use Chronicle.Events.EventType, id: "get-started-book-returned"

defstruct []
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class GetStartedBookAdded {
      constructor(
          readonly title: string,
          readonly isbn: string
      ) {}
  }

@eventType()
  class GetStartedBookBorrowed {
      constructor(readonly memberName: string) {}
  }

@eventType()
  class GetStartedBookReturned {
  }
  ```

`BookReturned` carries no data at all — that it *happened*, on a particular book’s stream, is the whole story. Not every fact needs a payload.

## Append them

[Section titled “Append them”](#append-them)

* C#

```csharp
  using Cratis.Chronicle;

public class GetStartedBookService(IEventStore eventStore)
  {
      public async Task<Guid> AddBook()
      {
          var eventLog = eventStore.EventLog;

var bookId = Guid.NewGuid();
          await eventLog.Append(bookId, new GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"));

return bookId;
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import java.util.UUID

class GetStartedBookService(private val eventStore: IEventStore) {
      suspend fun addBook(): String {
          val eventLog = eventStore.eventLog

val bookId = UUID.randomUUID().toString()
          eventLog.append(bookId, GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"))

return bookId
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingEventStore;
  import java.util.UUID;

class GetStartedBookService {
      private final BlockingEventStore eventStore;

GetStartedBookService(IEventStore eventStore) {
          this.eventStore = new BlockingEventStore(eventStore);
      }

String addBook() {
          var bookId = UUID.randomUUID().toString();

eventStore.getEventLog().append(
              bookId,
              new GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"));

return bookId;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.BookService do
    alias MyApp.Events.GetStartedBookAdded

def add_book do
      book_id = Base.encode16(:crypto.strong_rand_bytes(8), case: :lower)

:ok =
        Chronicle.append(book_id, %GetStartedBookAdded{
          title: "The Pragmatic Programmer",
          isbn: "978-0135957059"
        })

book_id
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async addBook(bookId: string): Promise<void> {
          const eventLog = this.store.eventLog;

await eventLog.append(bookId, new GetStartedBookAdded('The Pragmatic Programmer', '978-0135957059'));
      }
  }
  ```

Tip

Run your app, then open the [workbench](https://localhost:35000), pick your event store, and select **Sequences** — your `BookAdded` is sitting there at sequence number `0`, permanent and in order.

Note

![Chronicle Workbench showing events](/_astro/workbench.CcnUH1d2_Z1CPEDn.webp)

## Turn events into a read model

[Section titled “Turn events into a read model”](#turn-events-into-a-read-model)

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<GetStartedBookAdded>]
  public record GetStartedBook(
      [Key]
      Guid Id,

string Title,

string Isbn,

[SetValue<GetStartedBookAdded>(false)]
      [SetValue<GetStartedBookBorrowed>(true)]
      [SetValue<GetStartedBookReturned>(false)]
      bool OnLoan,

[SetFrom<GetStartedBookBorrowed>(nameof(GetStartedBookBorrowed.MemberName))]
      string? BorrowedBy);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.GetStartedBook do
    use Chronicle.ReadModels.ReadModel

defstruct id: nil, title: nil, isbn: nil, on_loan: false, borrowed_by: nil

from MyApp.Events.GetStartedBookAdded,
      set: [id: :event_source_id, title: :title, isbn: :isbn, on_loan: false]

from MyApp.Events.GetStartedBookBorrowed,
      set: [on_loan: true, borrowed_by: :member_name]

from MyApp.Events.GetStartedBookReturned,
      set: [on_loan: false]
  end
  ```

* TypeScript

```typescript
  import { fromEvent, Guid, readModel, setFrom, setValue } from '@cratis/chronicle';

@readModel()
  @fromEvent(GetStartedBookAdded)
  class GetStartedBook {
      id: Guid = Guid.empty;

@setFrom(GetStartedBookAdded, 'title')
      title = '';

@setFrom(GetStartedBookAdded, 'isbn')
      isbn = '';

@setValue(GetStartedBookAdded, false)
      @setValue(GetStartedBookBorrowed, true)
      @setValue(GetStartedBookReturned, false)
      onLoan = false;

@setFrom(GetStartedBookBorrowed, 'memberName')
      borrowedBy: string | null = null;
  }
  ```

Note

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<GetStartedBookBorrowed>]
  [RemovedWith<GetStartedBookReturned>]
  public record GetStartedBorrowedBook(
      [Key]
      Guid Id,

string MemberName);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWith
  import io.cratis.chronicle.readModels.ReadModel

* Java

```java
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWith;
  import io.cratis.chronicle.readModels.ReadModel;

public GetStartedBorrowedBook() {}

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getMemberName() { return memberName; }
      public void setMemberName(String memberName) { this.memberName = memberName; }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.GetStartedBorrowedBook do
    use Chronicle.ReadModels.ReadModel

defstruct id: nil, member_name: nil

from MyApp.Events.GetStartedBookBorrowed,
      set: [id: :event_source_id, member_name: :member_name]

removed_with MyApp.Events.GetStartedBookReturned, []
  end
  ```

* TypeScript

```typescript
  import { fromEvent, Guid, readModel, removedWith, setFrom } from '@cratis/chronicle';

@readModel()
  @fromEvent(GetStartedBookBorrowed)
  @removedWith(GetStartedBookReturned)
  class GetStartedBorrowedBook {
      id: Guid = Guid.empty;

@setFrom(GetStartedBookBorrowed, 'memberName')
      memberName = '';
  }
  ```

## Query the read models

[Section titled “Query the read models”](#query-the-read-models)

The most direct way to look at a read model is to ask Chronicle itself. `IReadModels` — reached through `eventStore.ReadModels` — hands you every instance of a read model, one call per view:

* C#

```csharp
  using Cratis.Chronicle;

return (books, borrowedBooks);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.BookQueryService do
    alias MyApp.ReadModels.GetStartedBook
    alias MyApp.ReadModels.GetStartedBorrowedBook

def query_books do
      {:ok, books} = Chronicle.all(GetStartedBook)
      {:ok, borrowed_books} = Chronicle.all(GetStartedBorrowedBook)

{books, borrowed_books}
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

return { books, borrowedBooks };
      }
  }
  ```

* C#

```csharp
  using Cratis.Chronicle;

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.BookPagingService do
    alias MyApp.ReadModels.GetStartedBook

def get_page do
      {:ok, result} = Chronicle.ReadModels.query(GetStartedBook, page: 1, page_size: 20)
      result.instances
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

getPage(): Promise<GetStartedBook[]> {
          return this.store.readModels.materialized.getInstances(GetStartedBook, 0, 20);
      }
  }
  ```

* C#

```csharp
  using MongoDB.Driver;

public class GetStartedBooks(IMongoCollection<GetStartedBook> collection)
  {
      public IEnumerable<GetStartedBook> OnLoan() => collection.Find(b => b.OnLoan).ToList();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class GetStartedBook(val title: String = "", val onLoan: Boolean = false)

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;
  import java.util.stream.Collectors;

@ReadModel
  record GetStartedBook(String title, boolean onLoan) {}

GetStartedBooks(IEventStore store) {
          this.store = store;
      }

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## React when something happens

[Section titled “React when something happens”](#react-when-something-happens)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.observation.Reactor

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.observation.Reactor;

* Elixir

```elixir
  defmodule MyApp.Reactors.GetStartedBookReturnedNotifier do
    use Chronicle.Reactors.Reactor

alias MyApp.Events.GetStartedBookReturned

@handles GetStartedBookReturned

* TypeScript

```typescript
  import { EventContext, reactor } from '@cratis/chronicle';

## Append from the worker

[Section titled “Append from the worker”](#append-from-the-worker)

In a worker you append from your `BackgroundService` rather than inline. Inject `IEventStore` (or `IEventLog` directly) and append inside `ExecuteAsync`:

* C#

```csharp
  using Cratis.Chronicle;
  using Microsoft.Extensions.Hosting;

public class GetStartedWorker(IEventStore eventStore) : BackgroundService
  {
      protected override async Task ExecuteAsync(CancellationToken stoppingToken)
      {
          await eventStore.Connection.Connect();

var bookId = Guid.NewGuid();
          await eventStore.EventLog.Append(bookId, new GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"));

// Keep running so reactors and projections keep processing.
          await Task.Delay(Timeout.Infinite, stoppingToken);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import kotlinx.coroutines.runBlocking
  import java.util.UUID

/**
   * A Spring `CommandLineRunner` bean (`@Component class X(...) : CommandLineRunner`) is the plain
   * Spring Boot way to do work at startup in a host with no web layer. Reactors and projections are
   * already running in the background once the starter has registered them - the function below is
   * what that runner's `run` method calls to append the first event.
   */
  fun seedFirstBook(eventStore: IEventStore) = runBlocking {
      val bookId = UUID.randomUUID().toString()
      eventStore.eventLog.append(bookId, GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"))
  }
  ```

* Java

```java
  import io.cratis.chronicle.java.BlockingEventStore;

import java.util.UUID;

// A Spring CommandLineRunner bean (@Component class X implements CommandLineRunner) is the plain
  // Spring Boot way to do work at startup in a host with no web layer. Reactors and projections are
  // already running in the background once the starter has registered them - this method is what
  // that runner's run() calls to append the first event.
  class GetStartedWorker {
      private final BlockingEventStore eventStore;

GetStartedWorker(BlockingEventStore eventStore) {
          this.eventStore = eventStore;
      }

void run() {
          String bookId = UUID.randomUUID().toString();
          eventStore.getEventLog().append(bookId, new GetStartedBookAdded("The Pragmatic Programmer", "978-0135957059"));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.GetStartedWorker do
    @moduledoc """
    Appends a book-added event once `Chronicle.Client` is running as part of
    the application's supervision tree.

Reactors and projections keep processing events in the background for as
    long as the supervision tree stays up — there is no separate "keep running
    forever" loop to write here, unlike a .NET `BackgroundService`.
    """

alias MyApp.Events.GetStartedBookAdded

def add_book do
      book_id = Base.encode16(:crypto.strong_rand_bytes(8), case: :lower)

Chronicle.append(book_id, %GetStartedBookAdded{
        title: "The Pragmatic Programmer",
        isbn: "978-0135957059"
      })
    end
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The projections and the `BookReturnedNotifier` reactor pick those events up from the kernel — the worker stays alive to keep processing them.

## Configure the MongoDB client

[Section titled “Configure the MongoDB client”](#configure-the-mongodb-client)

The `Books` query reads documents Chronicle wrote, so the MongoDB driver needs to match how Chronicle stores them — register these conventions once at startup:

## MongoDB

[Section titled “MongoDB”](#mongodb)

* C#

```csharp
  using MongoDB.Bson;
  using MongoDB.Bson.Serialization;
  using MongoDB.Bson.Serialization.Conventions;
  using MongoDB.Bson.Serialization.Serializers;

* Kotlin

* Java

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

[Snippet source](https://github.com/cratis/samples/blob/main/Chronicle/Quickstart/Common/MongoDBDefaults.cs#L16-L27)

Note

Then register the database and the collection so a type can take an `IMongoCollection<Book>` dependency:

* C#

```csharp
  using Microsoft.Extensions.DependencyInjection;
  using Microsoft.Extensions.Hosting;
  using MongoDB.Driver;

public static class GetStartedWorkerMongoRegistration
  {
      public static void ConfigureServices(IHostApplicationBuilder builder)
      {
          builder.Services.AddSingleton<IMongoClient>(new MongoClient("mongodb://localhost:27017"));
          builder.Services.AddSingleton(provider => provider.GetRequiredService<IMongoClient>().GetDatabase("Quickstart"));
          builder.Services.AddTransient(provider => provider.GetRequiredService<IMongoDatabase>().GetCollection<GetStartedBook>("Books"));
      }
  }
  ```

* Kotlin

```kotlin
  /**
   * Kotlin needs no separate MongoDB registration step here either - the same
   * `IEventStore.readModels` API used by the ASP.NET Core host works identically in a background
   * worker. There is no raw `MongoCollection` to construct or register as a bean. See
   * `get-started/common/mongo-query` for the equivalent query.
   */
  object GetStartedWorkerMongoRegistration
  ```

* Java

```java
  // Java needs no separate MongoDB registration step here either - the same
  // IEventStore.getReadModels() API used by the ASP.NET Core host works identically in a
  // background worker. There is no raw MongoCollection to construct or register as a bean. See
  // get-started/common/mongo-query for the equivalent query.
  class GetStartedWorkerMongoRegistration {
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Register your artifacts

[Section titled “Register your artifacts”](#register-your-artifacts)

Chronicle creates its discovered artifacts through the container, so they need to be registered as services. For a handful, register them explicitly; as the solution grows, let Cratis Fundamentals do it by convention:

* C#

```csharp
  using Cratis.DependencyInjection;
  using Microsoft.Extensions.DependencyInjection;
  using Microsoft.Extensions.Hosting;

public static class GetStartedWorkerConventionRegistration
  {
      public static void ConfigureServices(IHostApplicationBuilder builder)
      {
          builder.Services
              .AddBindingsByConvention()
              .AddSelfBindings();
      }
  }
  ```

* Kotlin

* Java

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`AddBindingsByConvention` registers any service that implements an interface of the same name prefixed with `I` (`IFoo` → `Foo`); `AddSelfBindings` registers concrete classes as themselves.

## Going further

[Section titled “Going further”](#going-further)

* **Multi-tenant namespaces** — provide a custom `IEventStoreNamespaceResolver` to route operations per tenant. See [Namespace resolution](/chronicle/namespaces/dotnet-client/).
* **Structural dependencies** — supply custom identity providers, correlation-id accessors, or namespace resolvers through the `configure` callback on `AddCratisChronicle`. See [Structural dependencies](/chronicle/configuration/structural-dependencies/).

## Recap

[Section titled “Recap”](#recap)

You added Chronicle to a worker service with a single `AddCratisChronicle` call, pointed it at an event store through `appsettings.json`, and appended events from a `BackgroundService` — the generic host’s DI container discovered your reactors, reducers, and projections and handed you the services to use them. The same library domain runs here unchanged from the other hosts.

## Where to go next

[Section titled “Where to go next”](#where-to-go-next)

* **[Build the domain step by step](/chronicle/tutorial/)** — the tutorial walks the library model one concept at a time.
* **Reacting to events** — a worker’s main job; see [Reactors](/chronicle/reactors/) for the patterns.
* **A different host** — the same artifacts run unchanged behind a web API ([ASP.NET Core](/chronicle/get-started/aspnetcore/)) or with no container at all ([console](/chronicle/get-started/console/)).

# Hosting

Hosting Chronicle means running the **Chronicle Kernel** as a standalone server process. The Kernel is the heart of the system — it manages the event store, processes projections, coordinates observers, and exposes the API that client applications connect to. All event-sourced state flows through it, so the Kernel must be running before any client can append or query events.

Chronicle ships as a Docker image, making it straightforward to run anywhere containers are supported — locally for development, in CI, or in production clusters.

## Getting Started

[Section titled “Getting Started”](#getting-started)

For day-to-day development, [Docker Compose](/chronicle/hosting/docker-compose/) is the fastest way to get a Kernel and MongoDB running locally. [Aspire](/chronicle/hosting/aspire/) is an alternative if your team uses the .NET Aspire application model.

## Going to Production

[Section titled “Going to Production”](#going-to-production)

Running the Kernel in production requires two things beyond a basic Docker deployment:

* **[Production](/chronicle/hosting/production/)** — how to deploy the Chronicle Docker image with MongoDB, including port configuration, Docker Compose setup, health checks, and security considerations.
* **[Data Protection Key Encryption](/chronicle/hosting/encryption-certificate/)** — Chronicle uses ASP.NET Core Data Protection to protect sensitive values at rest. In production you must supply a certificate so that data protection keys are encrypted. Without one the Kernel refuses to start, because the internal OAuth authority requires the certificate. Turn that authority off — or point Chronicle at an external one — and the Kernel starts happily while writing its data protection keys unencrypted, which is the quieter and more dangerous outcome.

Both steps are required. A production deployment that skips key encryption is not secure.

## All Hosting Topics

[Section titled “All Hosting Topics”](#all-hosting-topics)

* **[Production](/chronicle/hosting/production/)** — Docker-based production deployment
* **[Data Protection Key Encryption](/chronicle/hosting/encryption-certificate/)** — Certificate-backed key encryption for production
* **[Configuration](/chronicle/hosting/configuration/)** — Complete configuration reference
* **[Aspire](/chronicle/hosting/aspire/)** — Microsoft Aspire hosting integration
* **[Docker Compose](/chronicle/hosting/docker-compose/)** — Multi-container setup for development and testing
* **[Local Certificates](/chronicle/hosting/local-certificates/)** — TLS certificates for local development

# Aspire Integration

Chronicle provides first-class support for [Microsoft Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview), making it straightforward to run Chronicle as part of an Aspire distributed application. The `Cratis.Chronicle.Aspire` package adds a Chronicle resource to your Aspire AppHost, handling container lifecycle, endpoint wiring, and MongoDB configuration automatically.

## Installation

[Section titled “Installation”](#installation)

Add the `Cratis.Chronicle.Aspire` package to your **AppHost** project:

```shell
dotnet add package Cratis.Chronicle.Aspire
```

## Development Mode

[Section titled “Development Mode”](#development-mode)

For local development, call `AddCratisChronicle()` without arguments. This uses the Chronicle development image (`cratis/chronicle:latest-development`), which bundles MongoDB and generates its own self-signed TLS certificate at startup — so neither an external database nor a certificate is required.

* C#

```csharp
  using Aspire.Hosting;

public static class HostingAspireDevMode
  {
      public static void ConfigureAppHost(string[] args)
      {
          var builder = DistributedApplication.CreateBuilder(args);

var chronicle = builder.AddCratisChronicle();

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

builder.Build().Run();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The development image is ideal for:

* Getting started quickly without additional infrastructure
* Running in CI pipelines where a full stack is needed

## Production Mode

[Section titled “Production Mode”](#production-mode)

For production or staging environments, use the configure callback. This switches to the production image (`cratis/chronicle:latest`), which drops both the embedded MongoDB *and* the development conveniences — so it needs three things wired up before it will start:

| What                      | Method                                                        | Without it                                                                                                                                                                                                                                          |
| ------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A database                | `WithMongoDB` / `WithPostgreSql` / `WithMsSql` / `WithSqlite` | There is no storage to connect to                                                                                                                                                                                                                   |
| A TLS certificate         | `WithTlsCertificate`                                          | The server throws `No TLS certificate is configured` and exits                                                                                                                                                                                      |
| An encryption certificate | `WithEncryptionCertificate`                                   | The server throws `An encryption certificate is required in production` and exits — unless you turn the `OAuthAuthority` feature off or point `Authentication:Authority` at an external authority, which skips the internal authority that needs it |

The production image will not start without certificates

The development image generates a self-signed TLS certificate on the fly and falls back to ephemeral OAuth keys. The production image does neither — the production code paths are selected by a compile-time symbol, so no environment variable switches them back. A configure callback that wires up only a database therefore produces a container that starts, throws, and stops. Each storage section below shows **only** the storage wiring; add the two certificate calls from [Certificates](#certificates) to every one of them.

### Certificates

[Section titled “Certificates”](#certificates)

`WithTlsCertificate` and `WithEncryptionCertificate` each take a path to a PKCS#12 (`.pfx`) file **on your machine** and the password protecting it:

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspireCertificates
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
      {
          var mongo = builder.AddConnectionString("chronicle-mongo");

return builder.AddCratisChronicle("chronicle", chronicle => chronicle
              .WithMongoDB(mongo)
              .WithTlsCertificate("certs/chronicle.pfx", "YourPassword")
              .WithEncryptionCertificate("certs/encryption.pfx", "YourPassword"));
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Each method does two things: it bind-mounts the file read-only into the container (at `/certs/tls.pfx` and `/certs/encryption.pfx` respectively) and points the matching Chronicle setting at that in-container path. You do not add a `WithBindMount` of your own — a host path handed straight to the container names a file the container cannot see, so the mount is part of configuring the certificate rather than a separate step you have to remember. A relative path resolves against the AppHost directory, exactly like every other Aspire bind mount.

Point either method at a file that is not there and the AppHost fails to start with `CertificateFileDoesNotExist`, naming both the path you gave and the absolute path it resolved to. That is deliberate: Docker happily creates a *directory* at a missing bind-mount source, and the Chronicle container would then tell you no certificate is configured — the opposite of the truth — while staying up with a dead process inside. Calling either method twice for the same certificate is last-call-wins, like every other `With…` on the builder, so a base helper’s certificate can be overridden per environment.

The two calls are independent, so you can point both at the same `.pfx` if one certificate serves both purposes — they are mounted at different container paths, so nothing collides. They map to configuration like this:

| Method                      | Container environment variable                                                                                                | Chronicle setting                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `WithTlsCertificate`        | `Cratis__Chronicle__Tls__CertificatePath` / `Cratis__Chronicle__Tls__CertificatePassword`                                     | `Cratis:Chronicle:Tls:CertificatePath` / `Cratis:Chronicle:Tls:CertificatePassword`                                     |
| `WithEncryptionCertificate` | `Cratis__Chronicle__EncryptionCertificate__CertificatePath` / `Cratis__Chronicle__EncryptionCertificate__CertificatePassword` | `Cratis:Chronicle:EncryptionCertificate:CertificatePath` / `Cratis:Chronicle:EncryptionCertificate:CertificatePassword` |

The password argument is optional, but supply it: Chronicle reads the file as PKCS#12 only when a password is present, and a TLS listener needs the private key inside that PKCS#12 container. [Local Certificate Setup](/chronicle/hosting/local-certificates/) shows how to generate a suitable `.pfx` with `dotnet dev-certs` or OpenSSL; [Production Hosting](/chronicle/hosting/production/) covers what a real deployment should use instead of a self-signed one.

#### Rotating the encryption certificate

[Section titled “Rotating the encryption certificate”](#rotating-the-encryption-certificate)

`WithEncryptionCertificate` sets the **active** certificate. Chronicle also accepts previously active certificates, kept for decryption only, so a rotation needs no downtime — see [Rotating the certificate](/chronicle/hosting/encryption-certificate/#rotating-the-certificate). There is no builder method for that list yet; mount the previous certificate and point the configuration at it directly:

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspireRotationPreviousCertificate
  {
      public static IResourceBuilder<ChronicleResource> Configure(
          IDistributedApplicationBuilder builder) =>
          builder
              .AddCratisChronicle(configure: chronicle => chronicle
                  .WithTlsCertificate("certs/chronicle.pfx", "YourPassword")
                  .WithEncryptionCertificate(
                      "certs/encryption-2026.pfx",
                      "YourNewPassword"))
              .WithBindMount(
                  "certs/encryption-2025.pfx",
                  "/certs/encryption-previous.pfx",
                  isReadOnly: true)
              .WithEnvironment(
                  "Cratis__Chronicle__EncryptionCertificate__Previous__0__CertificatePath",
                  "/certs/encryption-previous.pfx")
              .WithEnvironment(
                  "Cratis__Chronicle__EncryptionCertificate__Previous__0__CertificatePassword",
                  "YourOldPassword");
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`AddCratisChronicle` returns the resource builder, so `WithBindMount` and `WithEnvironment` chain straight onto it. The bind mount is what `WithEncryptionCertificate` would have done for you: the path in the environment variable is the path *inside* the container, so a host path handed straight to Chronicle names a file it cannot see.

### MongoDB

[Section titled “MongoDB”](#mongodb)

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspireMongo
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
      {
          var mongo = builder.AddConnectionString("chronicle-mongo");

return builder.AddCratisChronicle("chronicle", c =>
              c.WithMongoDB(mongo));
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The `WithMongoDB` method sets the `Cratis__Chronicle__Storage__Type` and `Cratis__Chronicle__Storage__ConnectionDetails` environment variables on the Chronicle container using the connection string from the provided MongoDB resource.

Chronicle needs a MongoDB replica set

Chronicle uses MongoDB transactions, and its observers, projections, and observable queries rely on change streams — **both require MongoDB to run as a replica set**, not a standalone `mongod`. Against a standalone server the change-stream watch never opens, so observable read-model queries silently return their empty seed and it looks like a projection bug rather than a storage-topology problem.

Aspire’s `builder.AddMongoDB("mongo")` starts a **standalone** `mongod`, so it does not work with the production image on its own — point `WithMongoDB` at a replica set instead.

`mongo` can be any `IResourceBuilder<IResourceWithConnectionString>` that resolves to a replica set, including:

* A MongoDB Atlas connection string (`builder.AddConnectionString("...")`) — Atlas clusters are always replica sets.
* Any self-hosted or cloud MongoDB cluster reached through a connection string.

For local development against the production image, `AddCratisChronicleMongoDB()` provisions this for you — a MongoDB container that initializes itself as a single-node replica set, handed back as a connection string carrying `?directConnection=true`:

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspireMongoReplicaSetHelper
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
      {
          var mongo = builder.AddCratisChronicleMongoDB();

return builder.AddCratisChronicle(configure: chronicle => chronicle.WithMongoDB(mongo));
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

That solves the database half only. Running the production image locally still needs both certificates from [Certificates](#certificates) — if all you want is a Chronicle to develop against, `AddCratisChronicle()` with no configure callback is the shorter road, because the development image brings its own replica set *and* its own certificates.

If you would rather define the container yourself, the same recipe written out in full is:

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspireMongoReplicaSet
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
      {
          // Chronicle uses MongoDB transactions and change streams, so the database must run as a
          // replica set. This command starts a single-node replica set that initializes itself on
          // first run, keeping mongod as PID 1 for correct signal handling and privilege drop.
          const string replicaSetCommand =
              "( until mongosh --quiet --eval 'db.adminCommand({ ping: 1 })' >/dev/null 2>&1; do sleep 0.3; done; " +
              "mongosh --quiet --eval 'try { rs.status() } catch (error) { rs.initiate({ _id: \"rs0\", members: [{ _id: 0, host: \"localhost:27017\" }] }) }' ) & " +
              "exec docker-entrypoint.sh mongod --replSet rs0 --bind_ip_all";

var mongo = builder.AddContainer("mongo", "mongo", "8.0")
              .WithEndpoint(targetPort: 27017, name: "tcp")
              .WithEntrypoint("/bin/sh")
              .WithArgs("-c", replicaSetCommand);

var mongoEndpoint = mongo.GetEndpoint("tcp");

// directConnection=true stops the driver from following the advertised replica-set member
          // host (localhost:27017, only reachable inside the container) back out and hanging.
          var mongoConnection = builder.AddConnectionString(
              "chronicle-mongo",
              ReferenceExpression.Create(
                  $"mongodb://{mongoEndpoint.Property(EndpointProperty.Host)}:{mongoEndpoint.Property(EndpointProperty.Port)}/?directConnection=true"));

return builder.AddCratisChronicle("chronicle", c => c.WithMongoDB(mongoConnection));
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`directConnection=true` keeps the driver from following the advertised replica-set member host — `localhost:27017`, only reachable inside the container — back out and hanging. This is the same single-node-replica-set recipe Chronicle’s own integration tests use. The embedded development image (`AddCratisChronicle()` with no configure callback) bundles a ready replica set, which is why the development path just works; the requirement only surfaces once you move to the production image with an external database.

### PostgreSQL

[Section titled “PostgreSQL”](#postgresql)

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspirePostgres
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
      {
          var postgres = builder.AddConnectionString("chronicle-postgres");

return builder.AddCratisChronicle("chronicle", c =>
              c.WithPostgreSql(postgres));
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`postgres` can be any `IResourceBuilder<IResourceWithConnectionString>`, including:

* A connection string (`builder.AddConnectionString("...")`)
* A PostgreSQL container: `builder.AddPostgres("postgres").AddDatabase("chronicle")`

### Microsoft SQL Server

[Section titled “Microsoft SQL Server”](#microsoft-sql-server)

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspireSqlServer
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder)
      {
          var sql = builder.AddConnectionString("chronicle-sql");

return builder.AddCratisChronicle("chronicle", c =>
              c.WithMsSql(sql));
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`sql` can be any `IResourceBuilder<IResourceWithConnectionString>`, including:

* A connection string (`builder.AddConnectionString("...")`)
* A SQL Server container: `builder.AddSqlServer("sql").AddDatabase("chronicle")`

### SQLite

[Section titled “SQLite”](#sqlite)

For SQLite, provide the connection string directly (SQLite is file-based and does not require a network resource):

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspireSqlite
  {
      public static IResourceBuilder<ChronicleResource> ConfigureAppHost(IDistributedApplicationBuilder builder) =>
          builder.AddCratisChronicle("chronicle", c =>
              c.WithSqlite("Data Source=/data/chronicle.db"));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Connecting a .NET Client

[Section titled “Connecting a .NET Client”](#connecting-a-net-client)

Pass the Chronicle resource as a connection string reference to your application projects so they receive the correct endpoint at runtime:

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspireConnectingClient
  {
      public static void ConfigureAppHost(IDistributedApplicationBuilder builder, IResourceBuilder<ChronicleResource> chronicle)
      {
          // Reference any of your application's projects the same way -
          // builder.AddProject<Projects.MyApi>("api") when Projects.MyApi is generated from your solution
          builder.AddContainer("api", "my-org/my-api")
              .WithReference(chronicle);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The connection string exposed by `ChronicleResource` uses the `chronicle://` scheme and points to the gRPC port (35000 by default), matching the format expected by `ChronicleOptions.FromConnectionString()`.

## Ports

[Section titled “Ports”](#ports)

Chronicle exposes the following ports:

| Port  | Endpoint Name | Description                                                                         |
| ----- | ------------- | ----------------------------------------------------------------------------------- |
| 35000 | `grpc`        | Primary Chronicle service — gRPC (HTTP/2) and Workbench/API/OAuth/health (HTTP/1.1) |

The `grpc` endpoint is registered automatically when you call `AddCratisChronicle()`. `ChronicleResource` no longer exposes a separate `management` endpoint — everything is served on the single `grpc` endpoint.

## Complete Example

[Section titled “Complete Example”](#complete-example)

A typical Aspire AppHost `Program.cs` for a production setup with MongoDB — database plus both certificates, which is the smallest configuration the production image actually starts on:

* C#

```csharp
  using Aspire.Hosting;

public static class HostingAspireCompleteExample
  {
      public static void ConfigureAppHost(string[] args)
      {
          var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddConnectionString("chronicle-mongo");

var chronicle = builder.AddCratisChronicle("chronicle", c => c
              .WithMongoDB(mongo)
              .WithTlsCertificate("certs/chronicle.pfx", "YourPassword")
              .WithEncryptionCertificate("certs/encryption.pfx", "YourPassword"));

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

builder.Build().Run();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

For development, drop the whole callback. The development image brings its own MongoDB replica set, generates its own TLS certificate, and uses ephemeral OAuth keys, so there is nothing left to wire:

* C#

```csharp
  using Aspire.Hosting;

public static class HostingAspireCompleteExampleDev
  {
      public static void ConfigureAppHost(string[] args)
      {
          var builder = DistributedApplication.CreateBuilder(args);

var chronicle = builder.AddCratisChronicle();

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

builder.Build().Run();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Docker Images

[Section titled “Docker Images”](#docker-images)

| Image tag                                  | Description                                                                                         | Selected by                                              |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `cratis/chronicle:latest`                  | Production image — no embedded MongoDB, no self-generated certificates                              | `AddCratisChronicle(configure: ...)`                     |
| `cratis/chronicle:latest-development`      | Development image — includes embedded MongoDB, generates a TLS certificate and ephemeral OAuth keys | `AddCratisChronicle()`                                   |
| `cratis/chronicle:latest-development-slim` | Development slim image — no embedded MongoDB                                                        | Not selected by the Aspire integration — run it directly |

### Pin the image for production

[Section titled “Pin the image for production”](#pin-the-image-for-production)

Both tags above float. `AddCratisChronicle` picks the tag for you, so a production deployment tracks whatever `cratis/chronicle:latest` happens to be at pull time — two deployments of the same AppHost can land on different Chronicle versions. Pin an exact version by chaining `WithImageTag` after the call:

* C#

```csharp
  using Aspire.Hosting;
  using Aspire.Hosting.ApplicationModel;
  using Cratis.Chronicle.Aspire;

public static class HostingAspirePinImage
  {
      public static IResourceBuilder<ChronicleResource> Configure(
          IDistributedApplicationBuilder builder) =>
          builder
              .AddCratisChronicle(configure: chronicle => chronicle
                  .WithTlsCertificate("certs/chronicle.pfx", "YourPassword")
                  .WithEncryptionCertificate(
                      "certs/encryption.pfx",
                      "YourPassword"))
              .WithImageTag("16.26.0");
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`WithImageTag` overrides the tag the integration selected while leaving the image and registry alone, and it does not change which image *class* is used — a `configure` callback still selects the production image. Pin to a released Chronicle version, and treat the upgrade as a deliberate change.

See [Production Hosting](/chronicle/hosting/production/) for guidance on running Chronicle in production environments.

# Configuration

Chronicle Server can be configured using a `chronicle.json` file or environment variables. Environment variables take precedence over file-based configuration, which is useful for containerized deployments.

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "port": 35000,
  "storage": {
    "type": "MongoDB",
    "connectionDetails": "mongodb://localhost:27017"
  }
}
```

| Section                       | Description                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------- |
| Root properties               | Ports and health check endpoint                                                  |
| Features                      | API, Workbench, and OAuth authority toggles                                      |
| Storage                       | Storage provider configuration                                                   |
| Compliance                    | Dedicated storage for compliance encryption keys                                 |
| Clustering                    | Orleans clustering provider, cluster identity, and ports                         |
| Observers                     | Retry and timeout settings                                                       |
| Read models                   | Replay retention for replay-generated read model versions                        |
| Events                        | Event queue configuration                                                        |
| Jobs                          | Parallel job step throttling                                                     |
| Authentication                | External authority, default admin, and initial admin user bootstrap              |
| TLS                           | TLS certificate configuration for the Chronicle port                             |
| Encryption certificate        | Certificate protecting OAuth keys, webhook credentials, and Data Protection keys |
| Health                        | Dedicated port for the health endpoint                                           |
| Identity Provider Certificate | Dedicated certificate configuration for internal OAuth authority                 |
| Clients                       | Bootstrap client registrations created on startup                                |

## Topics

[Section titled “Topics”](#topics)

* [Configuration File](/chronicle/hosting/configuration/configuration-file/) - Structure and location of `chronicle.json`.
* [Root Properties](/chronicle/hosting/configuration/root-properties/) - Ports and health check settings.
* [Features](/chronicle/hosting/configuration/features/) - Toggle API, Workbench, and OAuth authority.
* [Storage](/chronicle/hosting/configuration/storage/) - Configure the storage provider and connection details.
* [Compliance Storage](/chronicle/hosting/configuration/compliance-storage/) - Give compliance encryption keys their own storage backend.
* [Clustering](/chronicle/hosting/configuration/clustering/) - Orleans clustering provider, cluster identity, and silo/gateway ports.
* [Observers](/chronicle/hosting/configuration/observers/) - Retry and timeout settings for observer subscriptions.
* [Read Models](/chronicle/hosting/configuration/read-models/) - Configure replay retention for replay-generated read model versions.
* [Events](/chronicle/hosting/configuration/events/) - Configure event queues.
* [Authentication](/chronicle/hosting/configuration/authentication/) - External authority and default admin settings.
* [TLS](/chronicle/hosting/configuration/tls/) - Configure the TLS certificate for the Chronicle port.
* [Data Protection Key Encryption](/chronicle/hosting/encryption-certificate/) - Configure the encryption certificate, required in production.
* [Health Endpoint](/chronicle/hosting/configuration/health-endpoint/) - Expose the health endpoint on a dedicated port with optional TLS.
* [Identity Provider Certificate](/chronicle/hosting/configuration/identity-provider-certificate/) - Configure internal OAuth authority certificates.
* [Client Bootstrap](/chronicle/hosting/configuration/client-bootstrap/) - Register client applications on startup with hashed secrets.
* [Environment Variables](/chronicle/hosting/configuration/environment-variables/) - Configure with `Cratis__Chronicle__` settings.
* [Open Telemetry](/chronicle/hosting/configuration/open-telemetry/) - Export metrics, traces, and logs via OTLP.
* [Docker Configuration](/chronicle/hosting/configuration/docker/) - Configure Chronicle in Docker.
* [Configuration Precedence](/chronicle/hosting/configuration/configuration-precedence/) - How sources override each other.
* [Best Practices](/chronicle/hosting/configuration/best-practices/) - Recommended configuration guidelines.
* [Port Reference](/chronicle/hosting/configuration/port-reference/) - Ports exposed by Chronicle Server.
* [Job Throttling](/chronicle/hosting/configuration/job-throttling/) - Limit parallel job steps to control CPU usage.

# Authentication

Authentication is enabled by default. When `authority` is not configured, Chronicle uses its built-in OpenIdDict OAuth authority. When `authority` is set to an external OAuth provider URL, Chronicle will use that instead of the internal authority.

Identity provider certificate configuration is documented on [Identity Provider Certificate](/chronicle/hosting/configuration/identity-provider-certificate/).

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "authentication": {
    "enabled": true,
    "authority": null,
    "defaultAdminUsername": "admin"
  }
}
```

| Property             | Type   | Default | Description                                                                                       |
| -------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------- |
| enabled              | bool   | true    | Whether authentication is enforced. See [Turning authentication off](#turning-authentication-off) |
| authority            | string | null    | External OAuth authority URL                                                                      |
| defaultAdminUsername | string | “admin” | Default admin username created on first startup when `adminUser` is not configured                |

## Turning authentication off

[Section titled “Turning authentication off”](#turning-authentication-off)

Setting `enabled` to `false` removes authentication from the server entirely. There is no token authority, no `/connect/token` endpoint, no identity endpoints and no bootstrap admin user, and every gRPC service and HTTP endpoint answers anonymously. A client connects to it with `auth=none` in its connection string:

```text
chronicle://localhost:35000?auth=none
```

**This is only for a Chronicle that is not reachable as a server.** It exists for an instance embedded in a single container or process, talking to its own client over loopback, thrown away with the process — a play sandbox, a disposable test host. There the credential exchange protects nothing and costs every client seconds of cold start: acquiring the first access token takes 1.9 seconds on an unconstrained machine and 3.7 under a half-core container limit, almost all of it warming the token endpoint’s request pipeline.

Anywhere a network can reach the server, leaving this off publishes the whole event store — every event, every read model, every management operation — to anyone who can open a socket to it. It is not a development convenience to be left on by accident; treat it as part of the deployment topology.

A client using `auth=none` against a server that does enforce authentication fails every call as unauthenticated. Note also that a connection string with *no* credentials does not mean this — it still performs a client-credentials exchange using the development credentials, which is what it has always done. `auth=none` is the explicit form.

## Admin user bootstrap

[Section titled “Admin user bootstrap”](#admin-user-bootstrap)

Chronicle supports pre-configuring the initial admin user’s credentials at startup via configuration or secrets management. This is useful for automated or container-based deployments where going through the Workbench’s interactive password setup flow is not practical.

### How it works

[Section titled “How it works”](#how-it-works)

1. On startup, Chronicle checks whether an admin user with the configured username already exists

2. If no matching user exists and a password is configured, Chronicle:

* Creates the admin user
   * Hashes the password immediately — the plaintext is **never retained** in memory beyond this point

3. If a user with the same username already exists, the bootstrap step is skipped entirely

4. If no `adminUser` configuration is present (or no password is set), Chronicle falls back to the default behavior: the admin user is created without a password and must go through the initial password setup flow in the Workbench

### Configuration file

[Section titled “Configuration file”](#configuration-file)

```json
{
  "authentication": {
    "adminUser": {
      "username": "admin",
      "password": "a-strong-initial-password",
      "email": "admin@example.com",
      "requirePasswordChangeOnFirstLogin": true
    }
  }
}
```

### Environment variables

[Section titled “Environment variables”](#environment-variables)

```bash
Cratis__Chronicle__Authentication__AdminUser__Username=admin
Cratis__Chronicle__Authentication__AdminUser__Password=a-strong-initial-password
Cratis__Chronicle__Authentication__AdminUser__Email=admin@example.com
Cratis__Chronicle__Authentication__AdminUser__RequirePasswordChangeOnFirstLogin=true
```

### Properties

[Section titled “Properties”](#properties)

| Property                          | Type   | Default                          | Description                                                                        |
| --------------------------------- | ------ | -------------------------------- | ---------------------------------------------------------------------------------- |
| username                          | string | "" (uses `defaultAdminUsername`) | The admin username. Falls back to `defaultAdminUsername` when empty                |
| password                          | string | ""                               | The admin password in plaintext. Hashed internally on load                         |
| email                             | string | ""                               | The admin user’s email address                                                     |
| requirePasswordChangeOnFirstLogin | bool   | false                            | When `true`, the admin can log in but must change their password before continuing |

### `requirePasswordChangeOnFirstLogin`

[Section titled “requirePasswordChangeOnFirstLogin”](#requirepasswordchangeonfirstlogin)

When this option is `true`:

* The admin user is created with the configured password
* On first login, Chronicle redirects the admin to the password change screen
* The admin must set a new password before accessing the Workbench

## Security considerations

[Section titled “Security considerations”](#security-considerations)

The `password` value should be sourced from a secrets management solution such as Azure Key Vault, Kubernetes Secrets, or Docker Secrets rather than stored directly in `chronicle.json`.

**Key security properties of admin user bootstrap:**

* The plaintext password is hashed immediately — it is never persisted to storage, event logs, or application state
* If the admin user already exists when Chronicle restarts, the bootstrap section is completely ignored — credentials are never updated through this mechanism

### Azure Key Vault

[Section titled “Azure Key Vault”](#azure-key-vault)

```bash
# Store the initial password in Key Vault
az keyvault secret set --vault-name my-vault --name chronicle-admin-password --value "strong-random-password"
```

```bash
# Reference in environment variables
Cratis__Chronicle__Authentication__AdminUser__Username=admin
Cratis__Chronicle__Authentication__AdminUser__Password=@Microsoft.KeyVault(SecretUri=https://my-vault.vault.azure.net/secrets/chronicle-admin-password)
Cratis__Chronicle__Authentication__AdminUser__RequirePasswordChangeOnFirstLogin=true
```

### Kubernetes Secrets

[Section titled “Kubernetes Secrets”](#kubernetes-secrets)

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: chronicle-admin
type: Opaque
stringData:
  admin-password: "strong-random-password"
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: chronicle
          env:
            - name: Cratis__Chronicle__Authentication__AdminUser__Username
              value: "admin"
            - name: Cratis__Chronicle__Authentication__AdminUser__Password
              valueFrom:
                secretKeyRef:
                  name: chronicle-admin
                  key: admin-password
            - name: Cratis__Chronicle__Authentication__AdminUser__RequirePasswordChangeOnFirstLogin
              value: "true"
```

### Docker Compose

[Section titled “Docker Compose”](#docker-compose)

```yaml
services:
  chronicle:
    image: cratis/chronicle:latest
    environment:
      - Cratis__Chronicle__Authentication__AdminUser__Username=admin
      - Cratis__Chronicle__Authentication__AdminUser__Password=${ADMIN_PASSWORD}
      - Cratis__Chronicle__Authentication__AdminUser__RequirePasswordChangeOnFirstLogin=true
```

## Development image

[Section titled “Development image”](#development-image)

The development image (compiled with the `DEVELOPMENT` preprocessor symbol) supports an additional configuration option for pre-configuring the admin password. This is a legacy mechanism — new deployments should use the `adminUser` section above, which works in all environments.

> **Warning:** `defaultAdminPassword` is only available in the development image (compiled with `DEVELOPMENT` preprocessor symbol) and is removed from production builds at compile time. The password is read from configuration in plain text — use only in isolated development environments. It must never be used in staging or production.

```json
{
  "authentication": {
    "defaultAdminUsername": "admin",
    "defaultAdminPassword": "YourDevPassword"
  }
}
```

You can also configure this through an environment variable:

```shell
Cratis__Chronicle__Authentication__DefaultAdminPassword=YourDevPassword
```

| Property             | Type   | Default    | Description                                                                                                                                                                    |
| -------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| defaultAdminPassword | string | "" (empty) | Pre-configured admin password. When set, the admin user is created with this password and the initial password setup flow is skipped. Only available in the development image. |

When `defaultAdminPassword` is set, the admin user is created with the password already hashed and stored, and `requiresPasswordChange` is set to `false`. If the password is not set, the admin user is created without a password and must go through the initial password setup flow.

# Best Practices

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "observers": {
    "subscriberTimeout": 5,
    "maxRetryAttempts": 10
  },
  "events": {
    "queues": 8
  }
}
```

| Property                    | Description                                                |
| --------------------------- | ---------------------------------------------------------- |
| observers.subscriberTimeout | Keep observer timeouts aligned with infrastructure latency |
| observers.maxRetryAttempts  | Tune retries to balance resilience and recovery time       |
| events.queues               | Scale queues based on expected event throughput            |

1. Use specific version tags instead of `latest` for production deployments.
2. Mount configuration as read-only to prevent accidental modifications.
3. Use environment-specific connection strings for MongoDB.
4. Configure appropriate timeouts based on your infrastructure.
5. Use environment variables for sensitive configuration like connection strings.
6. Use secrets management for production environments.
7. Set appropriate observer retry policies based on reliability requirements.
8. Configure event queues based on event throughput needs.

# Client Bootstrap Configuration

Chronicle supports declarative client configuration, allowing clients (clientId/clientSecret pairs) to be defined at startup via configuration or secrets management, rather than exclusively through the Workbench UI.

## Configuration

[Section titled “Configuration”](#configuration)

### Configuration file

[Section titled “Configuration file”](#configuration-file)

```json
{
  "clients": [
    {
      "clientId": "my-service",
      "clientSecret": "a-strong-secret-value"
    },
    {
      "clientId": "another-service",
      "clientSecret": "another-secret-value"
    }
  ]
}
```

### Environment variables

[Section titled “Environment variables”](#environment-variables)

```bash
Cratis__Chronicle__Clients__0__ClientId=my-service
Cratis__Chronicle__Clients__0__ClientSecret=a-strong-secret-value
Cratis__Chronicle__Clients__1__ClientId=another-service
Cratis__Chronicle__Clients__1__ClientSecret=another-secret-value
```

## Properties

[Section titled “Properties”](#properties)

| Property     | Type   | Required | Description                                               |
| ------------ | ------ | -------- | --------------------------------------------------------- |
| clientId     | string | Yes      | The client identifier used for authentication             |
| clientSecret | string | Yes      | The client secret in plaintext. Hashed internally on load |

## How it works

[Section titled “How it works”](#how-it-works)

1. On startup, Chronicle reads the `clients` array from configuration
2. For each client, the secret is hashed using ASP.NET Core’s `PasswordHasher`
3. The raw secret is **never retained** in memory beyond the bootstrap phase
4. If a client with the same `clientId` already exists, it is skipped (not overwritten)
5. Bootstrap clients are visible in the Workbench UI alongside manually created clients
6. The Workbench UI continues to support adding and revoking clients at runtime

## Secret management

[Section titled “Secret management”](#secret-management)

The `clientSecret` is provided as plaintext in configuration. In production, use a proper secrets management solution:

### Azure Key Vault

[Section titled “Azure Key Vault”](#azure-key-vault)

```bash
# Store secret in Key Vault
az keyvault secret set --vault-name my-vault --name chronicle-client-secret --value "strong-secret"

# Reference in environment variable
Cratis__Chronicle__Clients__0__ClientId=my-service
Cratis__Chronicle__Clients__0__ClientSecret=@Microsoft.KeyVault(SecretUri=https://my-vault.vault.azure.net/secrets/chronicle-client-secret)
```

### Kubernetes Secrets

[Section titled “Kubernetes Secrets”](#kubernetes-secrets)

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: chronicle-clients
type: Opaque
stringData:
  client-secret: "strong-secret-value"
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: chronicle
          env:
            - name: Cratis__Chronicle__Clients__0__ClientId
              value: "my-service"
            - name: Cratis__Chronicle__Clients__0__ClientSecret
              valueFrom:
                secretKeyRef:
                  name: chronicle-clients
                  key: client-secret
```

### Docker Compose with secrets

[Section titled “Docker Compose with secrets”](#docker-compose-with-secrets)

```yaml
services:
  chronicle:
    image: cratis/chronicle:latest
    environment:
      - Cratis__Chronicle__Clients__0__ClientId=my-service
      - Cratis__Chronicle__Clients__0__ClientSecret=${CLIENT_SECRET}
```

## Relationship with Workbench-managed clients

[Section titled “Relationship with Workbench-managed clients”](#relationship-with-workbench-managed-clients)

* Bootstrap clients and Workbench-managed clients coexist
* Bootstrap clients are registered as regular applications visible in the Workbench
* If a bootstrap client already exists (matching `clientId`), it is not re-registered or overwritten
* Clients created through the Workbench can be revoked through the Workbench; bootstrap clients will be re-created on next restart if removed

# Clustering

Clustering configuration controls how multiple Chronicle Server nodes form one Orleans cluster and how grain workloads are distributed across them. This enables horizontal scale out and assigning specific roles to different nodes—for example, dedicating some nodes to event sequences and others to observers (reactors, reducers, projections).

Caution

The clustering type defaults to `Localhost`, which is single-node membership. Any production deployment that runs more than one node **must** set the type to `MongoDB` on every node. Two nodes left on the default that share the same MongoDB do **not** join as one cluster - each forms its own isolated single-node cluster over the same data, a split-brain topology reported by no error at startup. Set it with the `Cratis__Chronicle__Clustering__Type=MongoDB` environment variable (or `clustering.type` in `chronicle.json`), and give every node the same `clusterId` and `serviceId`. The server logs a warning when it detects localhost clustering against non-local storage, but it does not refuse to start.

## Use cases

[Section titled “Use cases”](#use-cases)

* **Horizontal scaling**: Run multiple nodes as one cluster; separate event ingestion (event sequences) from event processing (observers) to scale independently based on load
* **Resource isolation**: Run observers on nodes with different resource profiles (e.g., more memory for complex projections)
* **Testing**: Validate multi-node behavior in integration tests by enforcing deterministic grain placement

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "clustering": {
    "type": "MongoDB",
    "siloPort": 11111,
    "gatewayPort": 30000,
    "clusterId": "chronicle",
    "serviceId": "chronicle",
    "roles": {
      "eventSequences": true,
      "observers": true
    }
  }
}
```

## Properties

[Section titled “Properties”](#properties)

| Property                 | Type     | Default   | Description                                                                                                                                                                                                                                                          |
| ------------------------ | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                     | string   | Localhost | Cluster membership. `Localhost` is single node development clustering. `MongoDB` keeps membership in the configured MongoDB storage - all nodes sharing the same storage and cluster id form one cluster.                                                            |
| siloPort                 | number   | 11111     | Port for silo to silo communication. Must differ per node when multiple nodes run on one machine.                                                                                                                                                                    |
| gatewayPort              | number   | 30000     | Port for the silo’s client gateway. Must differ per node when multiple nodes run on one machine.                                                                                                                                                                     |
| clusterId                | string   | chronicle | The cluster id - all nodes that should form one cluster must share it.                                                                                                                                                                                               |
| serviceId                | string   | chronicle | The service id - all nodes that should form one cluster must share it.                                                                                                                                                                                               |
| advertisedIP             | string   |           | The IP address the silo advertises to other cluster members. Resolved from the machine’s host name when not set; set it explicitly (e.g. `127.0.0.1`) when running multiple nodes on one machine.                                                                    |
| defunctSiloCleanupPeriod | timespan | 01:00:00  | How often defunct silo entries are swept out of the membership table when using `MongoDB` clustering. Without the sweep, dead entries from restarts and failed rollouts accumulate and slow down or block new nodes joining. Set to `00:00:00` to disable the sweep. |
| defunctSiloExpiration    | timespan | 03:00:00  | The age at which a defunct membership entry is removed by the sweep. A node never reuses a silo identity, so dead entries only have diagnostic value.                                                                                                                |
| roles.eventSequences     | boolean  | true      | When `true`, event sequence grains can be activated on this node. When `false`, event sequence grains will not be placed on this node.                                                                                                                               |
| roles.observers          | boolean  | true      | When `true`, observer grains (reactors, reducers, projections) can be activated on this node. When `false`, observer grains will not be placed on this node.                                                                                                         |

## Configuration examples

[Section titled “Configuration examples”](#configuration-examples)

### Default (all roles enabled)

[Section titled “Default (all roles enabled)”](#default-all-roles-enabled)

By default, all roles are enabled on every node. This is the standard single-node or homogeneous multi-node configuration:

```json
{
  "clustering": {
    "roles": {
      "eventSequences": true,
      "observers": true
    }
  }
}
```

### Dedicated event sequence node

[Section titled “Dedicated event sequence node”](#dedicated-event-sequence-node)

A node that only handles event sequences (event ingestion and appending):

```json
{
  "clustering": {
    "roles": {
      "eventSequences": true,
      "observers": false
    }
  }
}
```

### Dedicated observer node

[Section titled “Dedicated observer node”](#dedicated-observer-node)

A node that only processes observers (reactors, reducers, projections):

```json
{
  "clustering": {
    "roles": {
      "eventSequences": false,
      "observers": true
    }
  }
}
```

## Behavior

[Section titled “Behavior”](#behavior)

Role-based placement is applied by custom Orleans placement directors - one for event sequence grains and one for observer grains. When a grain needs to be activated, the director running on the silo that makes the placement decision:

1. Starts from the silos Orleans reports as compatible with the grain type.
2. Removes **this** silo from the candidates when this silo has the grain’s role disabled.
3. Selects one of the remaining candidates at random.
4. Throws an `InvalidOperationException` when no candidate remains - for example, when every silo has that role disabled.

Note

A placement director only sees the role configuration of the silo it runs on. It can keep a grain off the local silo when the local role is disabled, but it does not currently guarantee that a grain is never placed on a *remote* silo whose role is disabled. Role-based isolation is therefore best-effort today - treat the role settings as a scheduling hint rather than a hard cluster-wide guarantee, and run homogeneous nodes (all roles enabled, the default) when every node must accept every grain.

## Architecture

[Section titled “Architecture”](#architecture)

Chronicle uses custom Orleans placement strategies for role-based placement:

* **EventSequencePlacementStrategy**: applied to `EventSequence` grains and resolved by `EventSequencePlacementDirector`
* **ObserverPlacementStrategy**: applied to `Observer` grains (the base class for reactors, reducers, and projections) and resolved by `ObserverPlacementDirector`

Each director consults the `Clustering.Roles` configuration of the silo it runs on and selects a compatible node using random placement, excluding the local silo when its own role for that grain type is disabled.

# Compliance Storage

Chronicle stores encryption keys alongside the rest of your application data by default. When you configure a dedicated compliance storage, those keys are stored in a separate, independently secured backend — such as HashiCorp Vault — so that key material never resides in the same database as the encrypted events.

If no compliance storage is explicitly configured, Chronicle uses the general [storage](/chronicle/hosting/configuration/storage/) backend for encryption keys.

## Configuration

[Section titled “Configuration”](#configuration)

The `compliance` section now contains an `encryption` subsection that holds the `storage` configuration. Set a `type` and `connectionDetails` inside `compliance.encryption.storage`:

```json
{
  "compliance": {
    "encryption": {
      "storage": {
        "type": "<storage-type>",
        "connectionDetails": "<connection-string-or-url>"
      }
    }
  }
}
```

## Migrating from the default storage

[Section titled “Migrating from the default storage”](#migrating-from-the-default-storage)

If you are configuring a dedicated compliance storage on a system that has already been running, the keys you care about are in the general storage backend — and the new store is empty. Turning it on by itself is a one-way flip: those keys become unreachable, and every `[PII]` value they protect reads back as an **empty string**. Nothing reports it. No exception is thrown, nothing is logged, and the health endpoint stays green — the result is byte-for-byte what a completed [right-to-erasure](/chronicle/compliance/) looks like.

Set `migrateFromDefaultStorage` and there is no flip at all:

```json
{
  "compliance": {
    "encryption": {
      "storage": {
        "type": "vault",
        "connectionDetails": "http://vault:8200"
      },
      "migrateFromDefaultStorage": true
    }
  }
}
```

Both stores are now live, and Chronicle keeps them in step for you:

* A key is looked for in the dedicated store first. When it is only in the default storage, it is served from there and **written into the dedicated store as it is read** — so the migration happens through ordinary traffic, with no script to write and no verify pass to run.
* New keys are provisioned in the dedicated store and mirrored back to the default storage, so both stay complete. That is what makes the move reversible: set `migrateFromDefaultStorage` back to `false` — or drop the `storage` section entirely — and nothing is lost.
* Erasing a key erases it from **both** stores, and records the erasure in both. A deletion that only reaches one of them fails loudly rather than reporting success, because a key surviving in either store is not an erasure — and a store that has the subject recorded as erased will not accept the other store’s copy, so a half-finished erasure cannot be healed back into place by ordinary traffic.

Danger

A key store written outside Chronicle has to implement the erasure members of `IEncryptionKeyStorage` before it can be composed here. One that does not fails loudly the first time an erasure is attempted through it, because an erasure it cannot record is an erasure that can be undone by the next read. See [The encryption key lifecycle](/chronicle/compliance/key-lifecycle/).

A key moves the first time it is *read*, so a subject whose data nobody has queried still lives only in the default storage. Before you turn `migrateFromDefaultStorage` off, confirm the dedicated store actually holds every key — turning it off early puts the subjects that were never read straight back into the empty-string outcome above. Once you have confirmed it, removing the leftover keys from the general storage backend is an ordinary cleanup you decide on separately, not the irreversible last step of a sequence.

> **Note:** Leaving `migrateFromDefaultStorage` on indefinitely is valid but rarely what you want — key material keeps being written to the same database as the encrypted data, which is the separation a dedicated compliance storage exists to give you.

The setting has no effect unless `storage` is configured. Without a dedicated store there is nothing to migrate to, and the general storage backend serves the keys on its own.

| Property                  | Type | Required | Description                                                                                                                                     |
| ------------------------- | ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| migrateFromDefaultStorage | bool | No       | Keep the general storage backend serving encryption keys alongside `storage`, moving each key into `storage` as it is read. Defaults to `false` |

As an environment variable:

```shell
export Cratis__Chronicle__Compliance__Encryption__MigrateFromDefaultStorage=true
```

## Backup and restore ordering

[Section titled “Backup and restore ordering”](#backup-and-restore-ordering)

The compliance key store is the third item in a Chronicle backup set, alongside the encryption-certificate ring and the storage backend. It is an independent subsystem: **the encryption certificate does not protect these keys, and these keys do not protect anything the certificate protects.** The two are backed up separately and restored separately, and getting either wrong loses different data.

Restore in this order:

1. The [encryption-certificate ring](/chronicle/hosting/encryption-certificate/#backup-and-restore-ordering), in the shape it had when the backup was taken.
2. The storage backend (MongoDB or SQL).
3. The compliance key store — **to the same point in time as (2)**.

Step 3 is the one specific to this page, and it is a point-in-time match rather than a “latest wins”:

* A key store restored **older** than the storage is missing keys for subjects created since. Every `[PII]` value belonging to those subjects reads back as an **empty string** — byte-for-byte identical to a completed [right to erasure](/chronicle/compliance/), reported by nothing.
* A key store restored **newer** than the storage brings back keys for subjects whose erasure the storage backup predates. Nothing breaks, and that is the problem: an erasure you have already reported as complete is silently undone.

When `migrateFromDefaultStorage` is on, both stores are live and both are part of the backup set. Restoring only the dedicated store leaves the keys that had not been read yet — the ones still living only in the default storage — out of the restore.

Danger

A key store cannot be reconstructed. Deleting a key is the erasure mechanism, so there is no escrow, no recovery key and no support path — exactly as intended. Treat the key store backup with the same retention as the storage backups it has to match.

Vault and Azure Key Vault both keep every key revision as a distinct secret, so their own backup and point-in-time restore facilities cover this; when the keys live in the general storage backend instead, the database backup already carries them and steps 2 and 3 are the same restore.

## Vault

[Section titled “Vault”](#vault)

HashiCorp Vault provides a purpose-built secrets backend that is well-suited for storing PII encryption keys. Chronicle uses the [KV v2 secrets engine](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2) to store each key revision at a distinct path.

### Authentication

[Section titled “Authentication”](#authentication)

Chronicle authenticates to Vault using a [token](https://developer.hashicorp.com/vault/docs/auth/token). The token is read from the `VAULT_TOKEN` environment variable at startup. Ensure this variable is set before the Chronicle server process starts.

### Configuration

[Section titled “Configuration”](#configuration-1)

```json
{
  "compliance": {
    "encryption": {
      "storage": {
        "type": "vault",
        "connectionDetails": "http://vault:8200"
      }
    }
  }
}
```

Set `VAULT_TOKEN` in the environment:

```shell
export VAULT_TOKEN=s.myVaultToken
```

> **Note:** Never include the Vault token in the `connectionDetails` string or in `chronicle.json`. Always pass it through the environment to avoid storing secrets in your configuration files.

### KV v2 mount point

[Section titled “KV v2 mount point”](#kv-v2-mount-point)

Chronicle uses the `secret` KV v2 mount point by default. Encryption keys are organized under a path derived from the event store name, namespace, and subject identifier.

### Key paths

[Section titled “Key paths”](#key-paths)

Encryption keys are stored at:

```text
secret/<event-store>/<namespace>/<identifier>/<revision>
```

Each revision is an independent secret, which means individual revisions can be deleted without affecting others (for example, when rotating keys or when the full key history is required for a limited time).

| Property          | Type   | Required | Description                                               |
| ----------------- | ------ | -------- | --------------------------------------------------------- |
| type              | string | Yes      | Must be `vault`                                           |
| connectionDetails | string | Yes      | The Vault server address, for example `http://vault:8200` |

## Azure Key Vault

[Section titled “Azure Key Vault”](#azure-key-vault)

Azure Key Vault provides a fully managed, cloud-native secrets backend for storing PII encryption keys. Chronicle uses the Azure Key Vault Secrets API to store each key revision as a distinct secret.

### Authentication

[Section titled “Authentication”](#authentication-1)

Chronicle authenticates to Azure Key Vault using [`DefaultAzureCredential`](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential). This supports multiple authentication methods in order:

* Environment variables (`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`)
* Workload identity
* Managed identity
* Azure CLI credentials
* Visual Studio / VS Code credentials

Ensure that the identity used has the **Key Vault Secrets Officer** role (or at minimum **Get**, **List**, **Set**, and **Delete** secret permissions) on the target Key Vault.

### Configuration

[Section titled “Configuration”](#configuration-2)

```json
{
  "compliance": {
    "encryption": {
      "storage": {
        "type": "azure-key-vault",
        "connectionDetails": "https://my-vault.vault.azure.net"
      }
    }
  }
}
```

### Secret naming

[Section titled “Secret naming”](#secret-naming)

Encryption keys are stored as individual secrets. Secret names follow this pattern:

```text
chronicle--{event-store}--{namespace}--{identifier}--{revision}
```

Each component is sanitized to lowercase alphanumeric characters with single hyphens replacing any other character sequences. Double hyphens (`--`) serve as unambiguous separators between components.

| Property          | Type   | Required | Description                                                             |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------- |
| type              | string | Yes      | Must be `azure-key-vault`                                               |
| connectionDetails | string | Yes      | The Azure Key Vault URI, for example `https://my-vault.vault.azure.net` |

# Configuration File

Chronicle Server loads configuration from a `chronicle.json` file in the application root directory. In containers, this file is typically mounted at `/app/chronicle.json`.

## Example Configuration

[Section titled “Example Configuration”](#example-configuration)

```json
{
    "port": 35000,
    "healthCheckEndpoint": "/health",
    "features": {
        "api": true,
        "workbench": true,
        "changesetStorage": false,
        "oAuthAuthority": true
    },
    "storage": {
        "type": "MongoDB",
        "connectionDetails": "mongodb://localhost:27017"
    },
    "observers": {
        "subscriberTimeout": 5,
        "maxRetryAttempts": 10,
        "backoffDelay": 1,
        "exponentialBackoffDelayFactor": 2,
        "maximumBackoffDelay": 600
    },
    "readModels": {
        "replayedVersionsToKeep": 1
    },
    "events": {
        "queues": 8
    },
    "authentication": {
        "authority": null,
        "defaultAdminUsername": "admin",
        "adminUser": {
            "username": "admin",
            "password": "your-secure-password",
            "email": "admin@example.com",
            "requirePasswordChangeOnFirstLogin": true
        }
    },
    "tls": {
        "certificatePath": "/certs/chronicle.pfx",
        "certificatePassword": "your-password"
    },
    "encryptionCertificate": {
        "certificatePath": "/certs/encryption-cert.pfx",
        "certificatePassword": "your-password"
    },
    "identityProvider": {
        "certificate": {
            "enabled": true,
            "certificatePath": "/path/to/identity-provider.pfx",
            "certificatePassword": "your-password"
        }
    }
}
```

Note that the sections are **not** wrapped in `Cratis` / `Chronicle` here — Chronicle republishes everything it reads from `chronicle.json` under the `Cratis:Chronicle:` configuration path itself. That prefix belongs on environment variables only.

Environment variables can override any of these values. See [Configuration Precedence](/chronicle/hosting/configuration/configuration-precedence/) for details.

Note

Keep passwords out of the file itself. Because every value above can be overridden by an environment variable, supply secrets that way from your secret store — see [Environment Variables](/chronicle/hosting/configuration/environment-variables/).

| Section                   | Description                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| port, healthCheckEndpoint | Root properties for the port and health check path                                                        |
| features                  | Feature toggles for API, Workbench, and OAuth authority                                                   |
| storage                   | Storage provider configuration                                                                            |
| observers                 | Retry and timeout settings for observers                                                                  |
| readModels                | Replay retention settings for replay-generated read model versions                                        |
| events                    | Event queue configuration                                                                                 |
| authentication            | Authentication, default admin username, and initial admin user bootstrap                                  |
| tls                       | TLS certificate for the main Chronicle port — required in production                                      |
| encryptionCertificate     | Certificate protecting OAuth keys, webhook credentials, and Data Protection keys — required in production |
| identityProvider          | Optional internal identity provider certificate settings                                                  |

# Configuration Precedence

Configuration values are resolved in the following order, with later sources overriding earlier ones:

1. Default values
2. `chronicle.json` file
3. Environment variables

This allows you to set baseline configuration in `chronicle.json` and override specific values per environment.

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "port": 35000
}
```

| Source                | Description                                            |
| --------------------- | ------------------------------------------------------ |
| Defaults              | Built-in values used when no configuration is provided |
| chronicle.json        | File-based configuration loaded at startup             |
| Environment variables | Overrides using `Cratis__Chronicle__` variables        |

# Docker Configuration

When running Chronicle in Docker, you can configure it using either mounted configuration files or environment variables.

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "port": 35000,
  "storage": {
    "type": "MongoDB",
    "connectionDetails": "mongodb://mongo:27017"
  }
}
```

| Property                  | Type   | Description                                                                     |
| ------------------------- | ------ | ------------------------------------------------------------------------------- |
| port                      | number | The single Chronicle port exposed by the container — gRPC (HTTP/2) and HTTP/1.1 |
| storage.type              | string | Storage provider type                                                           |
| storage.connectionDetails | string | MongoDB connection string used in the container network                         |

## Using Configuration File

[Section titled “Using Configuration File”](#using-configuration-file)

Mount the `chronicle.json` file as a read-only volume:

```bash
docker run -d \
  --name chronicle \
  -p 35000:35000 \
  -v /path/to/chronicle.json:/app/chronicle.json:ro \
  cratis/chronicle:latest
```

## Using Environment Variables

[Section titled “Using Environment Variables”](#using-environment-variables)

Pass configuration via environment variables using the `-e` flag:

```bash
docker run -d \
  --name chronicle \
  -e Cratis__Chronicle__Port=35000 \
  -e Cratis__Chronicle__HealthCheckEndpoint=/health \
  -e Cratis__Chronicle__Storage__Type=MongoDB \
  -e Cratis__Chronicle__Storage__ConnectionDetails=mongodb://mongo:27017 \
  -e Cratis__Chronicle__Observers__SubscriberTimeout=10 \
  -p 35000:35000 \
  cratis/chronicle:latest
```

For Docker Compose setups, see [Running with Docker Compose](/chronicle/hosting/docker-compose/).

# Environment Variables

All configuration options can be set using environment variables with the prefix `Cratis__Chronicle__`. Use double underscores (`__`) to represent nested configuration sections.

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "port": 35000,
  "features": {
    "api": true,
    "workbench": true
  },
  "storage": {
    "type": "MongoDB",
    "connectionDetails": "mongodb://localhost:27017"
  }
}
```

## Variables

[Section titled “Variables”](#variables)

The table below covers the variables most deployments need. It is not the complete option surface — every property on Chronicle’s options types has an environment-variable form, built by joining the section names with `__`. When a setting is missing here, find it on its own configuration page and translate the JSON path the same way (`compliance.encryption.migrateFromDefaultStorage` becomes `Cratis__Chronicle__Compliance__Encryption__MigrateFromDefaultStorage`).

| Variable                                                                                | Description                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Cratis\_\_Chronicle\_\_Port                                                             | The single Chronicle port — gRPC (HTTP/2) and HTTP/1.1                                                                                                                                           |
| Cratis\_\_Chronicle\_\_HealthCheckEndpoint                                              | Health check endpoint path                                                                                                                                                                       |
| Cratis\_\_Chronicle\_\_Health\_\_Port                                                   | Dedicated HTTP/1.1 port for the health endpoint                                                                                                                                                  |
| Cratis\_\_Chronicle\_\_Health\_\_Tls                                                    | Whether the dedicated health port uses TLS (default `true`)                                                                                                                                      |
| Cratis\_\_Chronicle\_\_Features\_\_Api                                                  | Enable REST API endpoint                                                                                                                                                                         |
| Cratis\_\_Chronicle\_\_Features\_\_Workbench                                            | Enable Workbench UI                                                                                                                                                                              |
| Cratis\_\_Chronicle\_\_Features\_\_ChangesetStorage                                     | Enable changeset storage                                                                                                                                                                         |
| Cratis\_\_Chronicle\_\_Features\_\_OAuthAuthority                                       | Enable internal OAuth authority                                                                                                                                                                  |
| Cratis\_\_Chronicle\_\_Storage\_\_Type                                                  | Storage provider type                                                                                                                                                                            |
| Cratis\_\_Chronicle\_\_Storage\_\_ConnectionDetails                                     | Storage connection string                                                                                                                                                                        |
| Cratis\_\_Chronicle\_\_Observers\_\_SubscriberTimeout                                   | Seconds an observer waits for its subscriber to answer (0 = indefinitely)                                                                                                                        |
| Cratis\_\_Chronicle\_\_Observers\_\_MaxRetryAttempts                                    | Maximum retry attempts for observers                                                                                                                                                             |
| Cratis\_\_Chronicle\_\_Observers\_\_BackoffDelay                                        | Initial observer backoff delay in seconds                                                                                                                                                        |
| Cratis\_\_Chronicle\_\_Observers\_\_ExponentialBackoffDelayFactor                       | Exponential backoff multiplier                                                                                                                                                                   |
| Cratis\_\_Chronicle\_\_Observers\_\_MaximumBackoffDelay                                 | Maximum observer backoff delay in seconds                                                                                                                                                        |
| Cratis\_\_Chronicle\_\_ReadModels\_\_ReplayedVersionsToKeep                             | Number of replay-generated read model versions to keep                                                                                                                                           |
| Cratis\_\_Chronicle\_\_Events\_\_Queues                                                 | Number of event queues                                                                                                                                                                           |
| Cratis\_\_Chronicle\_\_Authentication\_\_Enabled                                        | Whether authentication is enforced (default `true`) - see [Authentication](/chronicle/hosting/configuration/authentication/#turning-authentication-off) before turning it off                    |
| Cratis\_\_Chronicle\_\_Authentication\_\_Authority                                      | External OAuth authority URL                                                                                                                                                                     |
| Cratis\_\_Chronicle\_\_Authentication\_\_DefaultAdminUsername                           | Default admin username                                                                                                                                                                           |
| Cratis\_\_Chronicle\_\_Authentication\_\_AdminUser\_\_Username                          | Bootstrap admin username (falls back to the default admin username when empty)                                                                                                                   |
| Cratis\_\_Chronicle\_\_Authentication\_\_AdminUser\_\_Password                          | Bootstrap admin password, hashed on first startup                                                                                                                                                |
| Cratis\_\_Chronicle\_\_Authentication\_\_AdminUser\_\_Email                             | Bootstrap admin email address                                                                                                                                                                    |
| Cratis\_\_Chronicle\_\_Authentication\_\_AdminUser\_\_RequirePasswordChangeOnFirstLogin | Force a password change on the admin’s first login                                                                                                                                               |
| Cratis\_\_Chronicle\_\_Jobs\_\_MaxParallelSteps                                         | Maximum parallel job steps                                                                                                                                                                       |
| Cratis\_\_Chronicle\_\_Clustering\_\_Type                                               | Clustering provider — `Localhost` (default) or `MongoDB`                                                                                                                                         |
| Cratis\_\_Chronicle\_\_Clustering\_\_ClusterId                                          | Orleans cluster id, identical on every node                                                                                                                                                      |
| Cratis\_\_Chronicle\_\_Clustering\_\_ServiceId                                          | Orleans service id, identical on every node                                                                                                                                                      |
| Cratis\_\_Chronicle\_\_Clustering\_\_SiloPort                                           | Orleans silo port (default 11111)                                                                                                                                                                |
| Cratis\_\_Chronicle\_\_Clustering\_\_GatewayPort                                        | Orleans gateway port (default 30000)                                                                                                                                                             |
| Cratis\_\_Chronicle\_\_Clustering\_\_AdvertisedIP                                       | IP address this node advertises to the cluster                                                                                                                                                   |
| Cratis\_\_Chronicle\_\_Tls\_\_CertificatePath                                           | TLS certificate path (PFX)                                                                                                                                                                       |
| Cratis\_\_Chronicle\_\_Tls\_\_CertificatePassword                                       | TLS certificate password                                                                                                                                                                         |
| Cratis\_\_Chronicle\_\_EncryptionCertificate\_\_CertificatePath                         | Encryption certificate path (PFX) — OAuth keys, webhook credentials, Data Protection keys                                                                                                        |
| Cratis\_\_Chronicle\_\_EncryptionCertificate\_\_CertificatePassword                     | Encryption certificate password                                                                                                                                                                  |
| Cratis\_\_Chronicle\_\_EncryptionCertificate\_\_Previous\_\_0\_\_CertificatePath        | Path to a certificate that was active before, kept for decryption only during a [rotation](/chronicle/hosting/encryption-certificate/#rotating-the-certificate). Index upwards for more than one |
| Cratis\_\_Chronicle\_\_EncryptionCertificate\_\_Previous\_\_0\_\_CertificatePassword    | Password for that certificate                                                                                                                                                                    |
| OTEL\_EXPORTER\_OTLP\_ENDPOINT                                                          | OTLP receiver endpoint for telemetry export                                                                                                                                                      |
| OTEL\_EXPORTER\_OTLP\_PROTOCOL                                                          | OTLP export protocol (`grpc` or `http/protobuf`)                                                                                                                                                 |
| OTEL\_EXPORTER\_OTLP\_HEADERS                                                           | Additional headers for the OTLP exporter                                                                                                                                                         |
| OTEL\_SERVICE\_NAME                                                                     | Service name reported to the telemetry backend                                                                                                                                                   |

## Port Configuration

[Section titled “Port Configuration”](#port-configuration)

```bash
# The single Chronicle port — gRPC (HTTP/2) plus HTTP/1.1 (default: 35000)
Cratis__Chronicle__Port=35000
```

## Health Check Endpoint

[Section titled “Health Check Endpoint”](#health-check-endpoint)

```bash
# Health check endpoint path (default: /health)
Cratis__Chronicle__HealthCheckEndpoint=/health
```

## Feature Toggles

[Section titled “Feature Toggles”](#feature-toggles)

```bash
# Enable or disable API (default: true)
Cratis__Chronicle__Features__Api=true

# Enable or disable Workbench (default: true)
Cratis__Chronicle__Features__Workbench=true

# Enable or disable Changeset Storage (default: false)
Cratis__Chronicle__Features__ChangesetStorage=false

# Enable or disable internal OAuth authority (default: true)
# Automatically disabled when external authority is configured
Cratis__Chronicle__Features__OAuthAuthority=true
```

## Storage

[Section titled “Storage”](#storage)

```bash
# Storage type (e.g., "MongoDB")
Cratis__Chronicle__Storage__Type=MongoDB

# MongoDB connection string
Cratis__Chronicle__Storage__ConnectionDetails=mongodb://localhost:27017
```

## Observers

[Section titled “Observers”](#observers)

```bash
# Seconds an observer waits for its subscriber to answer a batch (0 = indefinitely, default: 30)
Cratis__Chronicle__Observers__SubscriberTimeout=30

# Maximum retry attempts for failed partitions (0 = infinite, default: 10)
Cratis__Chronicle__Observers__MaxRetryAttempts=10

# Initial backoff delay in seconds (default: 1)
Cratis__Chronicle__Observers__BackoffDelay=1

# Exponential backoff factor (default: 2)
Cratis__Chronicle__Observers__ExponentialBackoffDelayFactor=2

# Maximum backoff delay in seconds (default: 600)
Cratis__Chronicle__Observers__MaximumBackoffDelay=600
```

## Events

[Section titled “Events”](#events)

```bash
# Number of appended event queues to use (default: 2)
Cratis__Chronicle__Events__Queues=2
```

## Read models

[Section titled “Read models”](#read-models)

```bash
# Number of replay-generated read model versions to keep per read model (default: 1)
Cratis__Chronicle__ReadModels__ReplayedVersionsToKeep=1
```

## Authentication

[Section titled “Authentication”](#authentication)

```bash
# External OAuth authority URL (optional)
# When not set, uses internal OpenIdDict-based authority
Cratis__Chronicle__Authentication__Authority=https://your-oauth-provider.com

# Default admin username (default: "admin")
Cratis__Chronicle__Authentication__DefaultAdminUsername=admin

# Bootstrap the initial admin user on first startup. The password is hashed
# immediately on use and never retained. Supply it from your secret store.
Cratis__Chronicle__Authentication__AdminUser__Username=admin
Cratis__Chronicle__Authentication__AdminUser__Password=your-secure-password
Cratis__Chronicle__Authentication__AdminUser__RequirePasswordChangeOnFirstLogin=true
```

When `AdminUser__Password` is left empty, the admin user is created without a password and goes through the initial password setup flow in the Workbench. See [Authentication](/chronicle/hosting/configuration/authentication/) for the full flow.

## Encryption certificate

[Section titled “Encryption certificate”](#encryption-certificate)

```bash
# Required in production - the internal OAuth authority refuses to start without it
Cratis__Chronicle__EncryptionCertificate__CertificatePath=/certs/encryption-cert.pfx
Cratis__Chronicle__EncryptionCertificate__CertificatePassword=your-certificate-password
```

See [Data Protection Key Encryption](/chronicle/hosting/encryption-certificate/) for generating and mounting the certificate.

## Clustering

[Section titled “Clustering”](#clustering)

```bash
# Clustering provider - must be MongoDB for every multi-node deployment
Cratis__Chronicle__Clustering__Type=MongoDB

# Identical on every node so they join the same cluster
Cratis__Chronicle__Clustering__ClusterId=chronicle
Cratis__Chronicle__Clustering__ServiceId=chronicle
```

See [Clustering](/chronicle/hosting/configuration/clustering/) for the full set of clustering properties.

## Open Telemetry

[Section titled “Open Telemetry”](#open-telemetry)

```bash
# OTLP receiver endpoint (e.g. local Aspire Dashboard or OpenTelemetry Collector)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Export protocol: grpc (default) or http/protobuf
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Additional headers, e.g. API keys for cloud backends
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-api-key

# Override the service name reported to the telemetry backend
OTEL_SERVICE_NAME=Chronicle
```

See the [Open Telemetry](/chronicle/hosting/configuration/open-telemetry/) configuration page for full details.

# Events

Event configuration controls how Chronicle Server queues appended events.

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "events": {
    "queues": 8
  }
}
```

| Property | Type   | Default | Description                            |
| -------- | ------ | ------- | -------------------------------------- |
| queues   | number | 2       | Number of appended event queues to use |

# Features

Feature toggles enable or disable specific Chronicle Server capabilities.

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "features": {
    "api": true,
    "workbench": true,
    "changesetStorage": false,
    "oAuthAuthority": true
  }
}
```

| Property         | Type    | Default | Description                                      |
| ---------------- | ------- | ------- | ------------------------------------------------ |
| api              | boolean | true    | Enable REST API endpoint                         |
| workbench        | boolean | true    | Enable web-based management interface            |
| changesetStorage | boolean | false   | Enable changeset storage functionality           |
| oAuthAuthority   | boolean | true    | Enable internal OpenIdDict-based OAuth authority |

If the API is disabled, the Workbench is also disabled because it depends on the API. The OAuth authority is automatically disabled when an external authority is configured via `authentication.authority`.

Disabling the OAuth authority — either explicitly or by configuring an external authority — also removes the **encryption certificate** startup requirement, because it is the internal authority that needs the certificate to protect its signing and encryption keys. A production deployment that uses an external authority therefore starts without one. See [Data Protection Key Encryption](/chronicle/hosting/encryption-certificate/).

# Health Endpoint

By default Chronicle serves its health check on the main port (35000) — the same port that carries gRPC, the Workbench, the REST API and OAuth. That single port always uses TLS, because Kestrel can only multiplex HTTP/2 (gRPC) and HTTP/1.1 on one port when ALPN negotiates the protocol per connection, and ALPN requires TLS. In development that TLS certificate is self-signed and generated automatically.

That is exactly where orchestrator and load-balancer probes run into trouble. A health probe that has to speak TLS — and sometimes validate the certificate — against a port that may be serving a self-signed certificate is awkward at best and broken at worst. The dedicated health port removes that friction: it publishes the health endpoint on its own HTTP/1.1 port where you can turn TLS off.

## Configuration

[Section titled “Configuration”](#configuration)

Set a `health` section with a `port` to expose the health endpoint on a dedicated port. When `port` is not set, nothing changes — the health endpoint stays on the main port.

```json
{
  "port": 35000,
  "healthCheckEndpoint": "/health",
  "health": {
    "port": 8080,
    "tls": false
  }
}
```

### Environment variables

[Section titled “Environment variables”](#environment-variables)

```bash
Cratis__Chronicle__Health__Port=8080
Cratis__Chronicle__Health__Tls=false
```

## Properties

[Section titled “Properties”](#properties)

| Property         | Type    | Default | Description                                                                                                                                     |
| ---------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| health.port      | number  | null    | Dedicated port for the health endpoint. When not set, the health endpoint is served on the main port.                                           |
| health.tls       | boolean | true    | Whether the dedicated health port uses TLS. Only applies when `health.port` is set.                                                             |
| health.exclusive | boolean | false   | Whether the dedicated health port serves *only* the health endpoint, answering 404 for everything else. Only applies when `health.port` is set. |

The endpoint path is the shared `healthCheckEndpoint` (default `/health`), so with the configuration above the health endpoint is reachable at `http://<host>:8080/health`.

## Behavior

[Section titled “Behavior”](#behavior)

* **`health.port` not set** — the health endpoint is served on the main port (35000) over TLS, alongside all other traffic. This is the default.
* **`health.port` set** — the health endpoint is additionally served on that dedicated HTTP/1.1 port. gRPC is never exposed on it, because gRPC needs HTTP/2 and the dedicated port serves HTTP/1.1 only.
* **`health.tls` false** — the dedicated port serves the health endpoint in cleartext. The main port still requires TLS regardless of this setting; disabling TLS here only affects the dedicated health port.
* **`health.exclusive` true** — the dedicated port answers only the health endpoint; every other path returns 404 on that port. Off by default, so enabling it never changes an existing deployment silently.
* **`health.port` equal to the main port** — treated as not set, since a second listener cannot bind the port the main listener already owns.

## Restricting the dedicated port to health only

[Section titled “Restricting the dedicated port to health only”](#restricting-the-dedicated-port-to-health-only)

The dedicated port is an additional listener on the same application rather than a separate, health-only server. By default the other HTTP/1.1 endpoints (Workbench, REST API, OAuth) are therefore reachable on it too, so the default posture is to treat it as an internal, cluster-local probe port and not expose it publicly, especially with TLS disabled.

Set `health.exclusive` to `true` to close that off. The port then serves the health endpoint and nothing else — every other path gets a 404:

```json
{
  "health": {
    "port": 8080,
    "tls": false,
    "exclusive": true
  }
}
```

The restriction keys on the local port the connection was accepted on, which a client cannot influence. It is not derived from the `Host` header or any `X-Forwarded-*` header, so a request arriving on the main port cannot dress itself up as a health-port request or vice versa. The main port is never restricted, and the option does nothing unless a dedicated `health.port` is configured and differs from the main port.

It defaults to `false` so that enabling a dedicated health port never silently removes endpoints from an existing deployment; turn it on deliberately when the probe port is reachable from somewhere the Workbench and API should not be.

## Why a plaintext health port helps in Kubernetes

[Section titled “Why a plaintext health port helps in Kubernetes”](#why-a-plaintext-health-port-helps-in-kubernetes)

Kubernetes probes and self-signed certificates do not always get along, and the details are easy to get wrong.

The kubelet’s own HTTP probes, when configured with `scheme: HTTPS`, **skip TLS certificate verification** — so a self-signed certificate technically works for kubelet liveness, readiness and startup probes. If the kubelet were the only thing probing Chronicle, the main TLS port would be fine.

In practice it usually is not the only thing. Many deployments front the pod with a cloud load balancer, ingress controller, service mesh or managed health check, and those probers commonly **do** validate the certificate — and reject a self-signed one. Probes also cannot present a client certificate, so mutual TLS is not an option for them. The result is that “the pod is healthy but the probe fails” class of problem, caused entirely by certificate validation rather than by Chronicle’s actual health.

Publishing the health endpoint on a dedicated plaintext port sidesteps certificate validation for every kind of prober:

```json
{
  "health": {
    "port": 8080,
    "tls": false
  }
}
```

```yaml
livenessProbe:
  httpGet:
    path: /health
    port: 8080
    scheme: HTTP
readinessProbe:
  httpGet:
    path: /health
    port: 8080
    scheme: HTTP
```

gRPC clients keep using the TLS main port — gRPC is never served on the plaintext port — while the probes target the dedicated port.

## Related pages

[Section titled “Related pages”](#related-pages)

* [TLS Configuration (Server)](/chronicle/hosting/configuration/tls/) for configuring the main port’s certificate.
* [Port Reference](/chronicle/hosting/configuration/port-reference/) for the full list of ports Chronicle exposes.
* [Root Properties](/chronicle/hosting/configuration/root-properties/) for the `healthCheckEndpoint` path.

# Identity Provider Certificate Configuration

When Chronicle uses the internal OAuth authority (`authentication.authority` is not set), you can configure a dedicated certificate for identity provider endpoints.

This certificate configuration is separate from the top-level TLS certificate and uses its own configuration path:

* `identityProvider.certificate`

## Fallback behavior

[Section titled “Fallback behavior”](#fallback-behavior)

Identity provider certificate resolution follows this order:

1. If `identityProvider.certificate` is set, use it.
2. If `identityProvider.certificate` is not set, fall back to top-level `tls`.

This preserves backward compatibility with existing configurations that only use `tls`.

## Configuration

[Section titled “Configuration”](#configuration)

### Dedicated identity provider certificate

[Section titled “Dedicated identity provider certificate”](#dedicated-identity-provider-certificate)

```json
{
  "authentication": {
    "authority": null
  },
  "identityProvider": {
    "certificate": {
      "enabled": true,
      "certificatePath": "/certs/identity-provider.pfx",
      "certificatePassword": "your-password"
    }
  }
}
```

### Reuse top-level TLS certificate (fallback)

[Section titled “Reuse top-level TLS certificate (fallback)”](#reuse-top-level-tls-certificate-fallback)

```json
{
  "tls": {
    "enabled": true,
    "certificatePath": "/certs/server.pfx",
    "certificatePassword": "your-password"
  },
  "authentication": {
    "authority": null
  }
}
```

In this configuration, `identityProvider.certificate` is not set, so Chronicle uses `tls` for identity provider endpoint scheme decisions.

## Environment variables

[Section titled “Environment variables”](#environment-variables)

```bash
Cratis__Chronicle__IdentityProvider__Certificate__Enabled=true
Cratis__Chronicle__IdentityProvider__Certificate__CertificatePath=/certs/identity-provider.pfx
Cratis__Chronicle__IdentityProvider__Certificate__CertificatePassword=your-password
```

## Properties

[Section titled “Properties”](#properties)

| Property                                         | Type    | Default | Description                                                 |
| ------------------------------------------------ | ------- | ------- | ----------------------------------------------------------- |
| identityProvider.certificate.enabled             | boolean | true    | Whether TLS is enabled for identity provider endpoints      |
| identityProvider.certificate.certificatePath     | string  | null    | Path to the identity provider certificate file (PFX format) |
| identityProvider.certificate.certificatePassword | string  | null    | Password for the identity provider certificate file         |

## Related topics

[Section titled “Related topics”](#related-topics)

* [Authentication](/chronicle/hosting/configuration/authentication/)
* [TLS](/chronicle/hosting/configuration/tls/)

# Job Throttling

Chronicle Server’s job system can be configured to limit the number of parallel job steps to prevent excessive CPU usage.

## Configuration

[Section titled “Configuration”](#configuration)

The maximum number of parallel job steps can be configured using the `MaxParallelSteps` option in `chronicle.json`:

```json
{
  "Jobs": {
    "MaxParallelSteps": 4
  }
}
```

Note

Do not wrap the section in `Cratis` / `Chronicle` inside `chronicle.json`. Chronicle republishes everything it reads from that file under the `Cratis:Chronicle:` configuration path already, so a nested copy binds to `Cratis:Chronicle:Cratis:Chronicle:Jobs` and is silently ignored. The `Cratis__Chronicle__` prefix belongs on environment variables only.

| Property         | Type   | Default                        | Description                                      |
| ---------------- | ------ | ------------------------------ | ------------------------------------------------ |
| MaxParallelSteps | number | Environment.ProcessorCount - 1 | Maximum number of parallel job steps (minimum 1) |

Alternatively, you can use environment variables:

```bash
Cratis__Chronicle__Jobs__MaxParallelSteps=4
```

## Default Behavior

[Section titled “Default Behavior”](#default-behavior)

If `MaxParallelSteps` is not configured, Chronicle uses a sensible default:

* Default value: `Environment.ProcessorCount - 1`
* Minimum value: `1` (even on single-core systems)

For example, on an 8-core system, the default would be 7 parallel steps.

## How It Works

[Section titled “How It Works”](#how-it-works)

1. Each job step attempts to acquire a slot before executing.
2. If all slots are in use, the step waits in a queue.
3. When a step completes (successfully or with an error), it releases its slot.
4. The next waiting step can then acquire the released slot.

This ensures that the job system never uses more than the configured number of CPU cores simultaneously.

## Use Cases

[Section titled “Use Cases”](#use-cases)

**High-throughput systems**: Limit parallel steps to leave CPU resources for other operations:

```json
{
  "Jobs": {
    "MaxParallelSteps": 2
  }
}
```

**Dedicated job processing**: Use more CPU cores for job processing:

```json
{
  "Jobs": {
    "MaxParallelSteps": 16
  }
}
```

**Testing environments**: Reduce resource usage:

```json
{
  "Jobs": {
    "MaxParallelSteps": 1
  }
}
```

# Observers

Observer configuration controls retry behavior, timeouts, watchdog monitoring, and how events fan out to scaled-out client instances.

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "observers": {
    "subscriberTimeout": 30,
    "maxRetryAttempts": 10,
    "backoffDelay": 1,
    "exponentialBackoffDelayFactor": 2,
    "maximumBackoffDelay": 600,
    "quarantineOnFailedPartitionCount": 0,
    "quarantineOnFailedPartitionPercentage": 0.0,
    "watchdogInterval": 60,
    "fanOutStrategy": "round-robin"
  }
}
```

| Property                              | Type   | Default     | Description                                                                                                                                                                                                                                                                                |
| ------------------------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| subscriberTimeout                     | number | 30          | How many seconds an observer waits for its subscriber to answer a batch before giving up on it. `0` waits indefinitely. See [Subscriber timeout](#subscriber-timeout)                                                                                                                      |
| maxRetryAttempts                      | number | 10          | Maximum retry attempts for failed partitions (0 = infinite)                                                                                                                                                                                                                                |
| quarantineOnFailedPartitionCount      | number | 0           | Quarantine the observer once this many of its partitions have failed (0 = never)                                                                                                                                                                                                           |
| quarantineOnFailedPartitionPercentage | number | 0.0         | Quarantine the observer once this share of its observed partitions have failed (0.0 = never)                                                                                                                                                                                               |
| backoffDelay                          | number | 1           | Initial backoff delay in seconds                                                                                                                                                                                                                                                           |
| exponentialBackoffDelayFactor         | number | 2           | Exponential backoff multiplier                                                                                                                                                                                                                                                             |
| maximumBackoffDelay                   | number | 600         | Maximum backoff delay in seconds                                                                                                                                                                                                                                                           |
| watchdogInterval                      | number | 60          | Interval in seconds between watchdog checks; the watchdog verifies connected clients are still active, running jobs (replay and catch-up) are still progressing, and `NextEventSequenceNumber` is up-to-date                                                                               |
| fanOutStrategy                        | string | round-robin | Strategy for distributing events across multiple connected instances of the same client. `round-robin` distributes deterministically by partition key, keeping every partition sticky to one instance and preserving per-partition ordering. `random` picks a random instance per delivery |

## Subscriber timeout

[Section titled “Subscriber timeout”](#subscriber-timeout)

Every path that hands events to an observer’s subscriber — live delivery, catch-up and replay — waits at most `subscriberTimeout` seconds for an answer. When it elapses, the batch is recorded as a failed partition of kind `Timeout` and the partition retries with the usual backoff.

Two things are worth knowing before changing it:

* **Giving up abandons the wait, not the work.** The subscriber is a grain and keeps processing the batch it was handed; the events are simply redelivered when the partition retries. Observers are expected to be idempotent, so that is safe — but it does mean a short timeout can have a subscriber working on a batch the kernel has already written off.
* **Raising it past the transport’s own response timeout has no effect**, because that one gives up first. The default deliberately matches it, so the setting bounds nothing new until you lower it. Lowering it is the point: a subscriber that should always answer in a second or two gets its partition back into retry quickly instead of holding a job step for half a minute.

Set it to `0` to wait indefinitely — the escape hatch for a subscriber whose work legitimately has no upper bound.

## What a failed partition says went wrong

[Section titled “What a failed partition says went wrong”](#what-a-failed-partition-says-went-wrong)

Every attempt recorded against a failed partition carries a **kind**, so an observer that is wrong can be told apart from one that was only waiting on a busy kernel:

| Kind           | Meaning                                                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Handling`     | The subscriber failed while handling the events. This is the failure that means something is wrong                                                                 |
| `Timeout`      | The call to the subscriber did not come back in time. The events were never rejected — the kernel ran out of patience waiting, which says the system was congested |
| `Disconnected` | The subscriber was gone by the time the events reached it                                                                                                          |
| `Unknown`      | Nothing classified the failure. Every attempt recorded before failures carried a kind reads back as this                                                           |

A partition whose last attempt is a `Timeout` does not count toward the quarantine thresholds above. Quarantining stops retries and needs an operator to undo, which is the right answer for an observer that is wrong and the wrong answer for one waiting on congestion that will clear on its own.

## Scaled-out clients

[Section titled “Scaled-out clients”](#scaled-out-clients)

When multiple instances of the same client application connect, its reactors and reducers all subscribe to the same observer. Chronicle fans event delivery out across the instances using the configured `fanOutStrategy`. If an instance disconnects, it is removed immediately and its partitions are redistributed to the remaining instances - the observer only unsubscribes when the last instance is gone.

# Open Telemetry

Chronicle exports telemetry signals through the [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/). Telemetry is always enabled and configured via standard OpenTelemetry environment variables.

## Signals

[Section titled “Signals”](#signals)

Chronicle exports the following signals:

| Signal  | Description                                                                       |
| ------- | --------------------------------------------------------------------------------- |
| Metrics | Application and infrastructure metrics (event sequences, observers, .NET runtime) |
| Traces  | Distributed traces for Chronicle operations (gRPC, HTTP, Orleans)                 |
| Logs    | Structured application logs                                                       |

## Configuration

[Section titled “Configuration”](#configuration)

Telemetry is configured using standard OpenTelemetry environment variables:

| Variable                      | Default     | Description                                           |
| ----------------------------- | ----------- | ----------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | none        | OTLP receiver endpoint (e.g. `http://localhost:4317`) |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`      | Export protocol: `grpc` or `http/protobuf`            |
| `OTEL_EXPORTER_OTLP_HEADERS`  | none        | Additional headers (e.g. API keys for cloud backends) |
| `OTEL_SERVICE_NAME`           | `Chronicle` | Service name reported to the telemetry backend        |

When `OTEL_EXPORTER_OTLP_ENDPOINT` is not set, Chronicle does not export telemetry but the instrumentation is still active.

## Local development with .NET Aspire Dashboard

[Section titled “Local development with .NET Aspire Dashboard”](#local-development-with-net-aspire-dashboard)

The Kernel ships with a `docker-compose.yml` that starts the [.NET Aspire Dashboard](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/dashboard/overview) as a lightweight all-in-one OTLP receiver and telemetry viewer.

```yaml
aspire-dashboard:
  image: mcr.microsoft.com/dotnet/aspire-dashboard:latest
  environment:
    - DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS=true
    - ALLOW_UNSECURED_TRANSPORT=true
  ports:
    - 18888:18888   # dashboard UI
    - 4317:18889    # OTLP/gRPC receiver
```

Start the services:

```bash
docker compose up -d
```

Then set the endpoint environment variable before starting the Kernel:

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 dotnet run
```

Open the Aspire Dashboard at <http://localhost:18888> to view metrics, traces, and logs.

## Example: Prometheus and Grafana

[Section titled “Example: Prometheus and Grafana”](#example-prometheus-and-grafana)

For production-grade metric collection, connect Chronicle to a Prometheus-compatible OTLP receiver (for example the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)):

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
```

## Example: cloud observability backends

[Section titled “Example: cloud observability backends”](#example-cloud-observability-backends)

Most cloud observability backends (Datadog, Honeycomb, Grafana Cloud, Azure Monitor) accept OTLP. Set the endpoint and any required authentication headers:

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.example.com
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-api-key
```

## Metrics instrumented

[Section titled “Metrics instrumented”](#metrics-instrumented)

Chronicle instruments the following meters:

| Meter                    | Description                                                      |
| ------------------------ | ---------------------------------------------------------------- |
| `Cratis.Chronicle`       | Chronicle application metrics (events appended, observers, etc.) |
| `Microsoft.Orleans`      | Orleans distributed actor framework metrics                      |
| `Grpc.AspNetCore.Server` | gRPC server request metrics                                      |
| .NET runtime             | GC, thread pool, and memory metrics from the .NET runtime        |

## Traces instrumented

[Section titled “Traces instrumented”](#traces-instrumented)

Chronicle traces the following activity sources:

| Source                          | Description                     |
| ------------------------------- | ------------------------------- |
| `Cratis.Chronicle`              | Chronicle internal operations   |
| `Microsoft.Orleans.Runtime`     | Orleans runtime activities      |
| `Microsoft.Orleans.Application` | Orleans application activities  |
| HTTP client                     | Outgoing HTTP requests          |
| ASP.NET Core                    | Incoming HTTP and gRPC requests |
| gRPC client                     | Outgoing gRPC calls             |

# Port Reference

Chronicle Server exposes the following ports:

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "port": 35000
}
```

| Port  | Service         | Description                                                                              |
| ----- | --------------- | ---------------------------------------------------------------------------------------- |
| 11111 | Orleans Silo    | Internal Orleans clustering                                                              |
| 30000 | Orleans Gateway | Client connections to Orleans cluster                                                    |
| 35000 | Chronicle       | gRPC (HTTP/2) and Workbench, REST API, OAuth and health (HTTP/1.1), multiplexed over TLS |

The port requires TLS. In development, when no certificate is configured, Chronicle generates a self-signed certificate automatically so the port works out of the box.

## Optional dedicated health port

[Section titled “Optional dedicated health port”](#optional-dedicated-health-port)

The health endpoint can additionally be published on a dedicated HTTP/1.1 port with TLS optionally disabled — useful for orchestrator and load-balancer probes that cannot validate a self-signed certificate. It is off by default. See [Health Endpoint](/chronicle/hosting/configuration/health-endpoint/).

# Read Models

Read model configuration controls how many replay-generated read model versions Chronicle keeps when projections are replayed.

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "readModels": {
    "replayedVersionsToKeep": 1
  }
}
```

| Property               | Type   | Default | Description                                                           |
| ---------------------- | ------ | ------- | --------------------------------------------------------------------- |
| replayedVersionsToKeep | number | 1       | Number of replay-generated read model versions to keep per read model |

## Replay retention behavior

[Section titled “Replay retention behavior”](#replay-retention-behavior)

When a new replay starts, Chronicle applies retention before creating the next replay context:

* Keeps the latest `replayedVersionsToKeep` replay versions for each read model.
* Removes older replay versions.
* Deletes the associated sink container for each removed version (for example, a MongoDB collection or SQL table).

Set `replayedVersionsToKeep` to:

* `0` to remove all previous replay versions on each new replay.
* `1` (default) to keep only the most recent replay version.
* A higher number if you need additional replay history for diagnostics or rollback workflows.

# Root Properties

These properties live at the root of `chronicle.json`.

## Example configuration

[Section titled “Example configuration”](#example-configuration)

```json
{
  "port": 35000,
  "healthCheckEndpoint": "/health"
}
```

| Property            | Type   | Default | Description                                                                                  |
| ------------------- | ------ | ------- | -------------------------------------------------------------------------------------------- |
| port                | number | 35000   | The single Chronicle port — gRPC (HTTP/2) and Workbench/API/OAuth/health (HTTP/1.1) over TLS |
| healthCheckEndpoint | string | /health | Health check endpoint path                                                                   |

## Health check endpoint

[Section titled “Health check endpoint”](#health-check-endpoint)

Chronicle exposes the health check endpoint on the main port (35000). You can customize the path if your environment requires a different route.

To expose the health endpoint on a dedicated port — with TLS optionally disabled for orchestrator and load-balancer probes — see [Health Endpoint](/chronicle/hosting/configuration/health-endpoint/).

# Storage

Configure the storage backend for Chronicle Server.

## Storage types

[Section titled “Storage types”](#storage-types)

| Type         | Description                        |
| ------------ | ---------------------------------- |
| `MongoDB`    | MongoDB (default)                  |
| `PostgreSql` | PostgreSQL                         |
| `MsSql`      | Microsoft SQL Server               |
| `Sqlite`     | SQLite (embedded, file-based)      |
| `InMemory`   | In-memory (ephemeral, non-durable) |

## MongoDB

[Section titled “MongoDB”](#mongodb)

```json
{
  "storage": {
    "type": "MongoDB",
    "connectionDetails": "mongodb://localhost:27017"
  }
}
```

## PostgreSQL

[Section titled “PostgreSQL”](#postgresql)

```json
{
  "storage": {
    "type": "PostgreSql",
    "connectionDetails": "Host=localhost;Port=5432;Database=chronicle;Username=chronicle;Password=secret"
  }
}
```

## Microsoft SQL Server

[Section titled “Microsoft SQL Server”](#microsoft-sql-server)

```json
{
  "storage": {
    "type": "MsSql",
    "connectionDetails": "Server=localhost;Database=chronicle;User Id=chronicle;Password=secret;TrustServerCertificate=True"
  }
}
```

## SQLite

[Section titled “SQLite”](#sqlite)

```json
{
  "storage": {
    "type": "Sqlite",
    "connectionDetails": "Data Source=/data/chronicle.db"
  }
}
```

## In-memory

[Section titled “In-memory”](#in-memory)

The in-memory backend keeps every event sequence, observer, read-model sink, and system record in process memory. There is no connection string, and `connectionDetails` is ignored.

```json
{
  "storage": {
    "type": "InMemory"
  }
}
```

Danger

The in-memory backend is **not durable** — all data is lost when the process exits, and it is scoped to a single process (it does not share state across a cluster). Use it for tests, samples, and ephemeral environments, not for production data.

When you host Chronicle programmatically, select the in-memory backend with the `WithInMemory()` builder extension instead of configuration:

* C#

```csharp
  siloBuilder.AddChronicleToSilo(chronicle => chronicle.WithInMemory());
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

| Property          | Type   | Required    | Description                                                                                                     |
| ----------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------- |
| type              | string | Yes         | Storage type: `MongoDB`, `PostgreSql`, `MsSql`, `Sqlite`, or `InMemory`                                         |
| connectionDetails | string | Conditional | Connection string for the chosen storage backend. Required for all backends except `InMemory`, which ignores it |

# TLS Configuration (Server)

The Chronicle port serves gRPC (HTTP/2) and the Workbench, REST API, OAuth and health endpoints (HTTP/1.1) on a single port. Kestrel can only multiplex the two protocols on one port over TLS, where ALPN negotiates the protocol per connection — so **the port always uses TLS and requires a certificate**.

For client-side TLS configuration, see [TLS Configuration (Client)](/chronicle/configuration/tls/).

## Configuration file

[Section titled “Configuration file”](#configuration-file)

```json
{
  "tls": {
    "certificatePath": "/path/to/certificate.pfx",
    "certificatePassword": "your-password"
  }
}
```

## Environment variables

[Section titled “Environment variables”](#environment-variables)

```bash
Cratis__Chronicle__Tls__CertificatePath=/path/to/certificate.pfx
Cratis__Chronicle__Tls__CertificatePassword=your-password
```

## Properties

[Section titled “Properties”](#properties)

| Property            | Type   | Default | Description                                   |
| ------------------- | ------ | ------- | --------------------------------------------- |
| certificatePath     | string | null    | Path to the TLS certificate file (PFX format) |
| certificatePassword | string | null    | Password for the certificate file             |

## TLS behavior

[Section titled “TLS behavior”](#tls-behavior)

* **A certificate is provided** (`certificatePath` set): Chronicle serves the port with that certificate.
* **No certificate is provided, development**: Chronicle generates an in-memory self-signed certificate so the port works out of the box. Clients accept it automatically in development, and browsers show a certificate warning you can bypass.
* **No certificate is provided, production**: the server fails to start — a certificate is required.

When TLS is terminated upstream by an ingress or reverse proxy, re-encrypt the connection to Chronicle (the backend port is always TLS) and provide a certificate for it.

## Health probes and self-signed certificates

[Section titled “Health probes and self-signed certificates”](#health-probes-and-self-signed-certificates)

Because the main port always uses TLS — and in development that certificate is self-signed — health probes can struggle to reach it. The kubelet’s own HTTPS probes skip certificate verification, but load balancers, ingress controllers and managed health checks that front the pod commonly validate the certificate and reject a self-signed one. To keep probes off the certificate entirely, publish the health endpoint on a dedicated plaintext port — see [Health Endpoint](/chronicle/hosting/configuration/health-endpoint/).

## Related TLS and certificate pages

[Section titled “Related TLS and certificate pages”](#related-tls-and-certificate-pages)

* [Identity Provider Certificate Configuration](/chronicle/hosting/configuration/identity-provider-certificate/) for internal OAuth authority certificates.

## Certificate requirements

[Section titled “Certificate requirements”](#certificate-requirements)

Chronicle requires certificates in PFX (PKCS#12) format that include a private key and, if applicable, the certificate chain.

## Docker deployment

[Section titled “Docker deployment”](#docker-deployment)

Mount the certificate and set configuration via environment variables:

```yaml
services:
  chronicle:
    image: cratis/chronicle:latest
    volumes:
      - ./chronicle.json:/app/chronicle.json:ro
      - ./certs/production.pfx:/app/certs/production.pfx:ro
    environment:
      - Cratis__Chronicle__Tls__CertificatePath=/app/certs/production.pfx
      - Cratis__Chronicle__Tls__CertificatePassword=${CERT_PASSWORD}
```

## Troubleshooting

[Section titled “Troubleshooting”](#troubleshooting)

### Server fails to start

[Section titled “Server fails to start”](#server-fails-to-start)

**Error**: “No TLS certificate is configured. The Chronicle port … requires a certificate.”

**Solution**: Provide `certificatePath` and `certificatePassword` in the top-level `tls` configuration. In development the server generates a self-signed certificate automatically, so this error only occurs in production.

# Running with Docker Compose

Using the development image of Chronicle is convenient for getting started quickly. For more control over the runtime environment, you can run Chronicle with MongoDB and other services such as telemetry collectors.

The following configures a `docker-compose.yml` with Chronicle and [Microsoft Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview).

```yaml
services:
  chronicle:
    image: cratis/chronicle:latest-development
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://aspire-dashboard:18889
    ports:
      - 27017:27017
      - 11111:11111
      - 30000:30000
      - 35000:35000

aspire-dashboard:
    image: mcr.microsoft.com/dotnet/aspire-dashboard:latest
    environment:
      - DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS=true
      - ALLOW_UNSECURED_TRANSPORT=true
      - DOTNET_ENVIRONMENT=Development
    ports:
      - 18888:18888
      - 4317:18889
```

[Snippet source](https://github.com/cratis/samples/blob/main/Chronicle/Quickstart/docker-compose.yml#L2-L23)

With this setup, Chronicle runs alongside Microsoft Aspire, which provides a dashboard for OpenTelemetry.

# Data Protection Key Encryption

Chronicle uses ASP.NET Core Data Protection to securely manage encryption keys for OAuth tokens and other sensitive data. In production environments, these keys must be protected with an X.509 certificate to ensure security across multiple Chronicle instances.

## Overview

[Section titled “Overview”](#overview)

When Chronicle runs in a clustered environment, all instances need access to the same Data Protection keys to correctly encrypt and decrypt tokens. These keys are stored in MongoDB and shared across all instances using Orleans grains.

In production, an encryption certificate is **required**. In development builds it is optional for convenience.

One PFX serves three consumers, and they fail in different ways when it is missing — worth knowing, because only one of them is loud:

| Consumer                                      | Without the certificate, in a production build                                                                                                                               |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OpenIddict** — the internal OAuth authority | **The server refuses to start.** This is the failure a production deployment hits first, before anything else can go wrong.                                                  |
| **Webhook credentials**                       | Throws `EncryptionCertificateNotConfigured` **lazily**, the first time a webhook secret is encrypted or decrypted — so a server that started fine can still fail here later. |
| **Data Protection keys**                      | Nothing fails. Chronicle starts, and the keys are simply written unencrypted. Data Protection never refuses to start and never generates a certificate of its own.           |

## Configuration

[Section titled “Configuration”](#configuration)

### JSON Configuration

[Section titled “JSON Configuration”](#json-configuration)

Add the encryption certificate configuration to your `chronicle.json`:

```json
{
    "encryptionCertificate": {
        "certificatePath": "/path/to/encryption-cert.pfx",
        "certificatePassword": "your-certificate-password"
    }
}
```

### Environment Variables

[Section titled “Environment Variables”](#environment-variables)

Configure using environment variables (recommended for containerized deployments):

```bash
# Path to the PFX certificate file
Cratis__Chronicle__EncryptionCertificate__CertificatePath=/app/certs/encryption-cert.pfx

# Certificate password
Cratis__Chronicle__EncryptionCertificate__CertificatePassword=your-certificate-password
```

### Configuration Properties

[Section titled “Configuration Properties”](#configuration-properties)

| Property            | Type   | Required (Production) | Description                                                                                                                |
| ------------------- | ------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| certificatePath     | string | Yes                   | Path to the PFX certificate file for the **active** certificate                                                            |
| certificatePassword | string | Yes\*                 | Password for the certificate (\* can be empty if cert has no password)                                                     |
| previous            | array  | No                    | Certificates that were active before, kept for decryption only — see [Rotating the certificate](#rotating-the-certificate) |

Every certificate you configure must carry its private key. A PFX exported without one is rejected at startup with `EncryptionCertificateWithoutPrivateKey`: all three consumers need to decrypt, not just encrypt.

### The certificate ring

[Section titled “The certificate ring”](#the-certificate-ring)

`certificatePath` is one position in an ordered **ring**. The certificate there is *active* — everything written from now on is protected with it. Anything under `previous` is kept loaded so what it protected stays readable, and is never used to protect anything new.

```json
{
    "encryptionCertificate": {
        "certificatePath": "/certs/encryption-2026.pfx",
        "certificatePassword": "the-new-password",
        "previous": [
            {
                "certificatePath": "/certs/encryption-2025.pfx",
                "certificatePassword": "the-old-password"
            }
        ]
    }
}
```

As environment variables, the list is indexed the way the configuration binder indexes every list:

```bash
Cratis__Chronicle__EncryptionCertificate__CertificatePath=/certs/encryption-2026.pfx
Cratis__Chronicle__EncryptionCertificate__CertificatePassword=the-new-password
Cratis__Chronicle__EncryptionCertificate__Previous__0__CertificatePath=/certs/encryption-2025.pfx
Cratis__Chronicle__EncryptionCertificate__Previous__0__CertificatePassword=the-old-password
```

An existing single-certificate configuration keeps working unchanged — it is a ring with nothing behind the active position.

The ring is read once at startup and held for the life of the process, so changing it takes a restart. **Every node in a cluster must be given the same ring**, for the same reason they must share one certificate today: Data Protection keys live in the shared storage, and any node may have to read what another wrote.

### What a broken ring does

[Section titled “What a broken ring does”](#what-a-broken-ring-does)

Chronicle refuses to start rather than run with a ring that is missing a certificate, because a certificate quietly absent from the ring is data quietly becoming unreadable:

| Configuration                                | What happens                                                        |
| -------------------------------------------- | ------------------------------------------------------------------- |
| `certificatePath` set, but no file there     | `EncryptionCertificateFileNotFound`, naming the path                |
| A `previous` entry whose file is not there   | `EncryptionCertificateFileNotFound`, naming the path                |
| A `previous` entry with no `certificatePath` | `EncryptionCertificateWithoutPath`                                  |
| `previous` set with no active certificate    | `PreviousEncryptionCertificatesWithoutActive`                       |
| The same certificate active *and* previous   | `DuplicateEncryptionCertificateInRing` — an overlap that is not one |
| A certificate carrying no private key        | `EncryptionCertificateWithoutPrivateKey`                            |

Note

Pointing `certificatePath` at a file that is not there used to be silent: Data Protection wrote its keys unencrypted and OpenIddict reported that no certificate was configured when one was. It now stops startup. If a deployment starts failing on this after an upgrade, it was never protecting its keys.

Configuring **no** certificate at all is unchanged — see [Development Mode](#development-mode).

## Generating a Certificate

[Section titled “Generating a Certificate”](#generating-a-certificate)

You can use the same certificate for both TLS and Data Protection key encryption, or generate a separate certificate specifically for key encryption.

### Using .NET CLI

[Section titled “Using .NET CLI”](#using-net-cli)

```bash
# Generate a certificate for key encryption
dotnet dev-certs https -ep ./encryption-cert.pfx -p YourSecurePassword123
```

### Using OpenSSL

[Section titled “Using OpenSSL”](#using-openssl)

```bash
# Generate a private key
openssl genrsa -out encryption.key 2048

# Create a self-signed certificate
openssl req -x509 -new -nodes -key encryption.key -sha256 -days 3650 \
    -out encryption.crt \
    -subj "/CN=Chronicle Data Protection/O=Your Organization"

# Convert to PFX format
openssl pkcs12 -export -out encryption-cert.pfx \
    -inkey encryption.key -in encryption.crt \
    -password pass:YourSecurePassword123
```

## Docker Configuration

[Section titled “Docker Configuration”](#docker-configuration)

Mount the certificate when running Chronicle in Docker:

```yaml
version: '3.8'

services:
  chronicle:
    image: cratis/chronicle:latest
    ports:
      - "35000:35000"
    volumes:
      - ./certs/encryption-cert.pfx:/app/certs/encryption-cert.pfx:ro
    environment:
      - Cratis__Chronicle__Storage__ConnectionDetails=mongodb://mongodb:27017
      - Cratis__Chronicle__EncryptionCertificate__CertificatePath=/app/certs/encryption-cert.pfx
      - Cratis__Chronicle__EncryptionCertificate__CertificatePassword=YourSecurePassword123
```

### Using Same Certificate for TLS and Encryption

[Section titled “Using Same Certificate for TLS and Encryption”](#using-same-certificate-for-tls-and-encryption)

You can use the same PFX certificate for both TLS and Data Protection key encryption:

Caution

Sharing one file means TLS renewal rotates your encryption certificate. Whatever replaces that file — cert-manager, ACME, an ingress controller — is doing a hard replacement on a schedule you do not control, and unless the file it replaces is first moved into `previous`, everything it protected becomes unreadable. If the certificate is shared, treat every TLS renewal as a [rotation](#rotating-the-certificate); if you cannot, give encryption its own certificate.

```yaml
services:
  chronicle:
    image: cratis/chronicle:latest
    volumes:
      - ./certs/chronicle.pfx:/app/certs/chronicle.pfx:ro
    environment:
      # TLS configuration
      - Cratis__Chronicle__Tls__CertificatePath=/app/certs/chronicle.pfx
      - Cratis__Chronicle__Tls__CertificatePassword=YourPassword
      # Data Protection key encryption (same certificate)
      - Cratis__Chronicle__EncryptionCertificate__CertificatePath=/app/certs/chronicle.pfx
      - Cratis__Chronicle__EncryptionCertificate__CertificatePassword=YourPassword
```

## Multi-Instance Deployments

[Section titled “Multi-Instance Deployments”](#multi-instance-deployments)

In clustered deployments, all Chronicle instances must use the **same** encryption certificate — and, during a rotation, the same `previous` list. This ensures that any instance can decrypt Data Protection keys stored in the shared MongoDB database.

```yaml
services:
  chronicle-1:
    image: cratis/chronicle:latest
    environment:
      - Cratis__Chronicle__EncryptionCertificate__CertificatePath=/app/certs/encryption-cert.pfx
      - Cratis__Chronicle__EncryptionCertificate__CertificatePassword=SharedPassword
    volumes:
      - ./certs/encryption-cert.pfx:/app/certs/encryption-cert.pfx:ro

chronicle-2:
    image: cratis/chronicle:latest
    environment:
      - Cratis__Chronicle__EncryptionCertificate__CertificatePath=/app/certs/encryption-cert.pfx
      - Cratis__Chronicle__EncryptionCertificate__CertificatePassword=SharedPassword
    volumes:
      - ./certs/encryption-cert.pfx:/app/certs/encryption-cert.pfx:ro
```

## Rotating the certificate

[Section titled “Rotating the certificate”](#rotating-the-certificate)

A rotation is forward only, and every step is a restart of **every** node with the same ring. Nothing is re-encrypted in bulk — the previous certificate stays in the ring until nothing needs it any more.

```
issue B, make it active,

move A to previous

diagnostic reports nothing

depends on A

Ring holds A

A is active

Ring holds B and A

B protects everything new,

A still reads what it protected

Ring holds B

A is retired,

its file stays in the backup set
```

1. **Issue the new certificate.** Keep the file the current one lives in — you are going to need it in the ring, and in the backup set for longer than that.
2. **Make the new one active and the old one previous.** Restart every node. From this point new Data Protection keys and new webhook credentials are protected with the new certificate, and everything the old one protected is still readable.
3. **Wait until nothing depends on the previous certificate.** Read the diagnostic below. Data Protection creates new keys on its own schedule; there is nothing to force and no migration to run.
4. **Remove the entry from `previous`.** Restart every node. The certificate is now retired.
5. **Keep the retired file in the backup set** until the oldest restorable backup is newer than step 2. See [Backup and restore ordering](#backup-and-restore-ordering) — this is the step that loses data when it is skipped.

Caution

Overwriting the file at `certificatePath` with a different key pair is **not** a rotation. The ring only helps when the previous file is kept and listed under `previous`; replacing a file in place leaves no overlap and makes everything the old key pair protected unreadable.

### What each consumer does during the overlap

[Section titled “What each consumer does during the overlap”](#what-each-consumer-does-during-the-overlap)

| Consumer                                               | During the overlap                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data Protection keys**                               | New keys are protected with the active certificate; any certificate in the ring can unprotect, so keys written before the rotation stay readable                                                                                                                                                                                                                                                                                                                                       |
| **OpenIddict** — the internal OAuth authority          | Every certificate in the ring is registered, so tokens issued under the previous one keep validating. OpenIddict chooses which certificate *issues* by its own rule — it prefers the X.509 key with the furthest expiration date, not the one Chronicle marks active. In a normal rotation the new certificate outlives the old one and the two agree; promote a certificate that expires *earlier* than one still in the ring and OpenIddict keeps issuing under the longer-lived one |
| **Webhook credentials** — Chronicle’s value encryption | Values are written with the active certificate and carry the key id of the certificate that protected them, so a value needing a retired certificate is reported as such instead of failing as if it were corrupt. Existing values are rewritten only when the credential itself is changed                                                                                                                                                                                            |

Note

Finish a rolling upgrade before rotating, and before creating or changing webhook credentials during one. A credential written by an upgraded node carries a key id, which a node still running an older version cannot read.

An **expired** certificate still decrypts — RSA does not consult the validity window — so a previous certificate that has expired keeps doing its job in the ring. It cannot be the active one.

## Watching a rotation

[Section titled “Watching a rotation”](#watching-a-rotation)

`GET /diagnostics/encryption-certificates` answers the questions a rotation raises: what is in the ring, which certificate is active, and whether anything still depends on a previous one. It requires authentication like every other non-anonymous endpoint, and it names key ids, subjects and paths — never key material.

```bash
curl --silent \
  --header "Authorization: Bearer $CHRONICLE_ACCESS_TOKEN" \
  https://chronicle:35000/diagnostics/encryption-certificates
```

```json
{
  "ring": {
    "isConfigured": true,
    "activeKeyId": "90E5D2C993BFB12A7E6B45D64664C18A7E4A93F0",
    "certificates": [
      {
        "keyId": "90E5D2C993BFB12A7E6B45D64664C18A7E4A93F0",
        "role": "Active",
        "subject": "CN=Chronicle Encryption 2026",
        "notBefore": "2026-01-01T00:00:00+00:00",
        "notAfter": "2027-01-01T00:00:00+00:00",
        "certificatePath": "/certs/encryption-2026.pfx",
        "hasExpired": false
      },
      {
        "keyId": "8CBEF43CE4B7B56664D66D6285A4A2064551ACE5",
        "role": "Previous",
        "subject": "CN=Chronicle Encryption 2025",
        "notBefore": "2025-01-01T00:00:00+00:00",
        "notAfter": "2026-01-01T00:00:00+00:00",
        "certificatePath": "/certs/encryption-2025.pfx",
        "hasExpired": true
      }
    ],
    "isRotating": true
  },
  "dataProtectionKeys": [
    {
      "keyId": "90E5D2C993BFB12A7E6B45D64664C18A7E4A93F0",
      "role": "Active",
      "keyCount": 1
    },
    {
      "keyId": "8CBEF43CE4B7B56664D66D6285A4A2064551ACE5",
      "role": "Previous",
      "keyCount": 1
    }
  ],
  "keysNotProtectedByCertificate": 0,
  "previousCertificatesInUse": true,
  "retiredCertificatesInUse": false,
  "canRetirePreviousCertificates": false
}
```

| Field                           | What it tells you                                                                                                                                                                                                |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ring`                          | The certificates this node actually loaded, active first. This is what has to match across the cluster                                                                                                           |
| `dataProtectionKeys`            | How many stored Data Protection keys are encrypted to each certificate. Read out of storage — each stored key records the certificate it needs                                                                   |
| `previousCertificatesInUse`     | Stored keys still depend on a certificate in the `previous` position. Removing it now makes them unreadable                                                                                                      |
| `retiredCertificatesInUse`      | Stored keys depend on a certificate that is in **neither** position. Those keys are already unreadable — this is what a rotation done in the wrong order, or a restore into a ring that has moved on, looks like |
| `keysNotProtectedByCertificate` | Stored keys no certificate protects at all, which is what a deployment running without an encryption certificate produces                                                                                        |
| `canRetirePreviousCertificates` | Step 4 of the rotation is safe: the ring is rotating and nothing depends on the previous certificates                                                                                                            |

Two things this does **not** cover, and they matter:

* **Webhook credentials are not enumerated.** A previous certificate reported with no Data Protection keys may still be needed by a stored webhook credential. Chronicle logs a warning the first time it reads a value with a previous certificate, naming the key id — watch for that before step 4, and rewrite the credential to move it onto the active certificate.
* **It reports this node.** Read it on every node during a rolling restart; a node left on the old ring reports the old ring.

The ring is also logged at every boot, one line per certificate, so the ring a node came up with is in its logs whether or not anyone calls the endpoint.

## Backup and restore ordering

[Section titled “Backup and restore ordering”](#backup-and-restore-ordering)

Losing this ordering loses data irrecoverably: a backup restored into a ring that no longer holds the certificate its contents were protected with is unreadable, and nothing about the restore reports it.

### What has to be in the backup set

[Section titled “What has to be in the backup set”](#what-has-to-be-in-the-backup-set)

| Item                                              | Where it lives                                                    | Why                                                                                                                                                       |
| ------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Every certificate in the ring, plus the passwords | Wherever you keep certificates — a secret store, not the database | Nothing else can decrypt what they protected                                                                                                              |
| The storage backend (MongoDB or SQL)              | Your database backups                                             | Holds the Data Protection key ring, the webhook definitions and their encrypted credentials, and the OAuth applications and tokens                        |
| The compliance key store, when one is configured  | Vault, Azure Key Vault, or the general storage                    | PII keys — a separate subsystem the encryption certificate never protects. See [Compliance Storage](/chronicle/hosting/configuration/compliance-storage/) |

The Data Protection key ring is **inside** the storage backend, not a separate artifact — a database backup already carries it. What a database backup cannot carry is the certificate that unlocks it.

### Retention: a certificate outlives its ring

[Section titled “Retention: a certificate outlives its ring”](#retention-a-certificate-outlives-its-ring)

**A certificate has to stay in the backup set for at least as long as the oldest backup you would still restore** — which is longer than it stays in the ring. Retire a certificate from the ring on Monday, delete the file on Tuesday, and every backup taken before the rotation becomes unreadable, silently, until the day someone tries to restore one.

The safe rule: never delete a certificate file until every backup that predates its rotation has aged out.

### Restore order

[Section titled “Restore order”](#restore-order)

1. **Restore the certificate ring first**, in the shape it had when the backup was taken — including every `previous` entry that was live then. Restoring the *current* ring is the mistake this ordering exists to prevent.
2. **Restore the storage backend** (MongoDB or SQL).
3. **Restore the compliance key store**, if one is configured, to the same point in time as the storage. A PII key that is newer or older than the events it protects reads back as an empty string.
4. **Start one node and read the diagnostic before starting the rest.** Keys reported with the role `Retired` mean the ring is missing a certificate the restored data needs — add it back under `previous` and restart before serving traffic.

Danger

A backup taken *before* a rotation contains data protected by the certificate that was active then. If that certificate has since been retired from the ring, restoring the backup produces data nothing can read. Put the certificate back under `previous` before you restore, not after.

### What survives losing the cluster

[Section titled “What survives losing the cluster”](#what-survives-losing-the-cluster)

Losing every running node but keeping the documented backup set is recoverable: the certificate ring restores the Data Protection keys held in the storage backup, which in turn restore every certificate- encrypted server secret. Losing the certificates is not recoverable by any means — there is no escrow, no recovery key and no support path.

## Development Mode

[Section titled “Development Mode”](#development-mode)

In development mode (when Chronicle is built with the `DEVELOPMENT` configuration), the encryption certificate is **optional**. This allows for easier local development without certificate management overhead.

### Auto-Generated Certificates (Development Only)

[Section titled “Auto-Generated Certificates (Development Only)”](#auto-generated-certificates-development-only)

When no encryption certificate is configured **and Chronicle is compiled with DEVELOPMENT mode**, the value-encryption subsystem — the one that protects webhook credentials — automatically generates a self-signed certificate the first time it needs one. This certificate is:

* **Location**: Stored in a `certificates` folder in the current working directory
* **Filename**: `encryption-cert.pfx`
* **Password**: `chronicle-auto-generated` (auto-assigned)
* **Validity**: 10 years from generation
* **Reuse**: If the certificate already exists, Chronicle will use it instead of generating a new one

This feature is designed to simplify local development and testing. The certificate is created lazily on first encrypt or decrypt rather than at startup, and persisted for subsequent runs so encrypted data remains accessible across restarts. Data Protection does not take part in this — it never generates a certificate, so its keys stay unencrypted whenever none is configured.

> **Important**: In **production builds** (without the DEVELOPMENT directive) there is no auto-generation. Two things happen instead: OpenIddict makes the server **refuse to start**, and — if you get past that — the value-encryption subsystem throws `EncryptionCertificateNotConfigured` on first use.
>
> The refusal to start comes from the **internal OAuth authority**, so it only applies when that authority is running. Turning the `oAuthAuthority` feature off, or configuring an external authority via `authentication.authority` (which disables the internal one automatically), removes the startup requirement — see [Features](/chronicle/hosting/configuration/features/). The value-encryption behavior is independent of that and is unchanged.

### Running Without Configuration

[Section titled “Running Without Configuration”](#running-without-configuration)

To run without a certificate in development:

```bash
# No certificate configuration needed in development
docker run -d \
  --name chronicle-dev \
  -p 35000:35000 \
  -e Cratis__Chronicle__Storage__ConnectionDetails=mongodb://localhost:27017 \
  cratis/chronicle:latest-development
```

> **Warning**: Auto-generated certificates should **never** be used in production environments. They are not cryptographically secure for production use and are intended only for development convenience. Production deployments **must** configure a proper encryption certificate.

## Security Best Practices

[Section titled “Security Best Practices”](#security-best-practices)

1. **Use strong passwords** - Certificate passwords should be complex and unique
2. **Protect certificate files** - Store certificates securely and limit access
3. **Rotate through the ring** - Follow [Rotating the certificate](#rotating-the-certificate); never replace the file in place
4. **Separate concerns** - Consider using different certificates for TLS and key encryption. A certificate shared with TLS is replaced on the TLS renewal schedule, which is not a schedule you control, and every such replacement is a rotation
5. **Backup certificates** - See [Backup and restore ordering](#backup-and-restore-ordering); losing the certificate means losing access to encrypted keys, with no recovery path
6. **Use secrets management** - In production, use a secrets manager (Azure Key Vault, HashiCorp Vault, etc.) to store certificate passwords

## Troubleshooting

[Section titled “Troubleshooting”](#troubleshooting)

### Certificate Not Found

[Section titled “Certificate Not Found”](#certificate-not-found)

If you see an error about the certificate not being found:

1. Verify the certificate path is correct and accessible
2. Check file permissions on the certificate file
3. Ensure the path uses forward slashes in Docker/Linux environments

### Invalid Certificate Password

[Section titled “Invalid Certificate Password”](#invalid-certificate-password)

If authentication fails after configuration:

1. Verify the certificate password is correct
2. Check for special characters that may need escaping in environment variables
3. Ensure the password matches what was used during certificate generation

### A value needs a certificate that is not in the ring

[Section titled “A value needs a certificate that is not in the ring”](#a-value-needs-a-certificate-that-is-not-in-the-ring)

`EncryptionCertificateNotInRing` names the key id the value was protected with and the key ids the ring holds. It means that certificate was retired while something still depended on it. Put the file back under `previous`, restart, and read the value — there is no way to recover it without the certificate.

`ValueNotDecryptableWithAnyCertificate` is the same situation for a value written before Chronicle labeled ciphertext with a key id: nothing in the ring opens it, so the certificate that did is gone from the ring.

Both messages name key ids and nothing else. Neither prints the protected value.

## Next Steps

[Section titled “Next Steps”](#next-steps)

* [Local Certificates](/chronicle/hosting/local-certificates/) - TLS certificate setup for development
* [Production Hosting](/chronicle/hosting/production/) - Production deployment requirements
* [Compliance Storage](/chronicle/hosting/configuration/compliance-storage/) - The PII key store and its own backup ordering
* [Configuration](/chronicle/hosting/configuration/) - Complete configuration reference

# Local Certificate Setup for Development

This guide explains how to set up your own TLS certificate for local Chronicle development. In development, Chronicle already serves its single port over TLS with an auto-generated self-signed certificate — so you only need this when you want to supply a specific certificate, for example to test with a trusted certificate or to simulate a production setup.

## Overview

[Section titled “Overview”](#overview)

Chronicle supports TLS certificates in PFX (PKCS#12) format. You can generate certificates using either OpenSSL or the .NET CLI tools. This guide covers both approaches.

## Option 1: Using .NET CLI (Recommended for .NET Developers)

[Section titled “Option 1: Using .NET CLI (Recommended for .NET Developers)”](#option-1-using-net-cli-recommended-for-net-developers)

The .NET CLI provides a simple way to generate development certificates that are automatically trusted by your system.

### Generate a Development Certificate

[Section titled “Generate a Development Certificate”](#generate-a-development-certificate)

```bash
# Generate a development certificate
dotnet dev-certs https -ep ./chronicle-dev.pfx -p YourPassword123

# Trust the certificate (optional, for client applications)
dotnet dev-certs https --trust
```

### Configure Chronicle to Use the Certificate

[Section titled “Configure Chronicle to Use the Certificate”](#configure-chronicle-to-use-the-certificate)

Update your `chronicle.json` configuration:

```json
{
  "tls": {
    "certificatePath": "./chronicle-dev.pfx",
    "certificatePassword": "YourPassword123"
  }
}
```

Or use environment variables:

```bash
export Cratis__Chronicle__Tls__CertificatePath=./chronicle-dev.pfx
export Cratis__Chronicle__Tls__CertificatePassword=YourPassword123
```

## Option 2: Using OpenSSL

[Section titled “Option 2: Using OpenSSL”](#option-2-using-openssl)

OpenSSL provides more control over certificate generation and is useful for advanced scenarios.

### Generate a Self-Signed Certificate

[Section titled “Generate a Self-Signed Certificate”](#generate-a-self-signed-certificate)

```bash
# Generate a private key
openssl genrsa -out chronicle-dev.key 2048

# Create a certificate signing request
openssl req -new -key chronicle-dev.key -out chronicle-dev.csr \
  -subj "/CN=localhost/O=Development/C=US"

# Generate a self-signed certificate
openssl x509 -req -days 365 -in chronicle-dev.csr \
  -signkey chronicle-dev.key -out chronicle-dev.crt

# Convert to PFX format (required by Chronicle)
openssl pkcs12 -export -out chronicle-dev.pfx \
  -inkey chronicle-dev.key -in chronicle-dev.crt \
  -password pass:YourPassword123
```

### Generate a Certificate with Subject Alternative Names (SAN)

[Section titled “Generate a Certificate with Subject Alternative Names (SAN)”](#generate-a-certificate-with-subject-alternative-names-san)

For production-like testing with custom domains:

```bash
# Create a configuration file for SAN
cat > san.cnf << EOF
[req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn
req_extensions = req_ext

[dn]
CN = localhost
O = Development
C = US

[req_ext]
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
DNS.2 = chronicle.local
IP.1 = 127.0.0.1
EOF

# Generate the certificate with SAN
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout chronicle-dev.key -out chronicle-dev.crt \
  -config san.cnf -extensions req_ext

# Convert to PFX
openssl pkcs12 -export -out chronicle-dev.pfx \
  -inkey chronicle-dev.key -in chronicle-dev.crt \
  -password pass:YourPassword123
```

### Configure Chronicle

[Section titled “Configure Chronicle”](#configure-chronicle)

Update your `chronicle.json`:

```json
{
  "tls": {
    "certificatePath": "./chronicle-dev.pfx",
    "certificatePassword": "YourPassword123"
  }
}
```

## Trusting Self-Signed Certificates

[Section titled “Trusting Self-Signed Certificates”](#trusting-self-signed-certificates)

For local development, you may want to trust your self-signed certificate to avoid browser warnings.

### Windows

[Section titled “Windows”](#windows)

```powershell
# Import the certificate
Import-PfxCertificate -FilePath chronicle-dev.pfx `
  -CertStoreLocation Cert:\LocalMachine\Root `
  -Password (ConvertTo-SecureString -String "YourPassword123" -AsPlainText -Force)
```

### macOS

[Section titled “macOS”](#macos)

```bash
# Extract the certificate from PFX
openssl pkcs12 -in chronicle-dev.pfx -clcerts -nokeys -out chronicle-dev.crt \
  -password pass:YourPassword123

# Add to system keychain
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain chronicle-dev.crt
```

### Linux (Ubuntu/Debian)

[Section titled “Linux (Ubuntu/Debian)”](#linux-ubuntudebian)

```bash
# Extract the certificate from PFX
openssl pkcs12 -in chronicle-dev.pfx -clcerts -nokeys -out chronicle-dev.crt \
  -password pass:YourPassword123

# Copy to the trusted certificates directory
sudo cp chronicle-dev.crt /usr/local/share/ca-certificates/

# Update the certificate store
sudo update-ca-certificates
```

### Linux (Fedora/RHEL/CentOS)

[Section titled “Linux (Fedora/RHEL/CentOS)”](#linux-fedorarhelcentos)

```bash
# Extract the certificate from PFX
openssl pkcs12 -in chronicle-dev.pfx -clcerts -nokeys -out chronicle-dev.crt \
  -password pass:YourPassword123

# Copy to the trusted certificates directory
sudo cp chronicle-dev.crt /etc/pki/ca-trust/source/anchors/

# Update the certificate store
sudo update-ca-trust
```

## Docker Development

[Section titled “Docker Development”](#docker-development)

When running Chronicle in Docker, mount the certificate file:

```yaml
version: '3.8'

services:
  chronicle:
    image: cratis/chronicle:latest
    ports:
      - "35000:35000"
    volumes:
      - ./chronicle.json:/app/chronicle.json:ro
      - ./chronicle-dev.pfx:/app/chronicle-dev.pfx:ro
    environment:
      - Cratis__Chronicle__Tls__CertificatePath=/app/chronicle-dev.pfx
      - Cratis__Chronicle__Tls__CertificatePassword=YourPassword123
```

## Client Configuration

[Section titled “Client Configuration”](#client-configuration)

When connecting to a Chronicle server with a self-signed certificate, configure the client:

* C#

```csharp
  public static class HostingLocalCertificatesClientConfiguration
  {
      public static ChronicleClient Create()
      {
          var options = new ChronicleOptions
          {
              ConnectionString = "chronicle://localhost:35000",
              Tls = new Tls
              {
                  CertificatePath = "./chronicle-dev.pfx",
                  CertificatePassword = "YourPassword123"
              }
          };

return new ChronicleClient(options);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.ChronicleOptions

// The client always connects over TLS. Chronicle Server's auto-generated self-signed development
  // certificate is never written to disk or added to a trust store, so there is nothing to validate
  // it against - skipTlsValidation accepts it. This is already Kotlin's default, spelled out here
  // explicitly for a server started with a certificate generated the way this guide describes.
  fun createClientForLocalCertificate(): ChronicleClient {
      val options = ChronicleOptions.fromConnectionString("chronicle://localhost:35000?skipTlsValidation=true")
      return ChronicleClient(options)
  }
  ```

* Java

```java
  import io.cratis.chronicle.ChronicleOptions;
  import io.cratis.chronicle.java.BlockingChronicleClient;

// The client always connects over TLS. Chronicle Server's auto-generated self-signed development
  // certificate is never written to disk or added to a trust store, so there is nothing to validate
  // it against - skipTlsValidation accepts it. This is already Java's default, spelled out here
  // explicitly for a server started with a certificate generated the way this guide describes.
  class HostingLocalCertificatesClientConfiguration {
      BlockingChronicleClient create() {
          ChronicleOptions options = ChronicleOptions.fromConnectionString(
              "chronicle://localhost:35000?skipTlsValidation=true");
          return BlockingChronicleClient.connect(options);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.HostingLocalCertificatesClientConfiguration do
    @moduledoc false

def start_link do
      children = [
        {Chronicle.Client,
         connection_string:
           "chronicle://localhost:35000?certificatePath=./chronicle-dev.pfx&certificatePassword=YourPassword123"}
      ]

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

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Security Considerations

[Section titled “Security Considerations”](#security-considerations)

⚠️ **Important**: The certificates generated in this guide are for **development only**.

* **Never use development certificates in production**
* **Do not commit certificates or passwords to source control**
* Use strong passwords for certificate protection
* Rotate certificates regularly
* For production, obtain certificates from a trusted Certificate Authority

## Troubleshooting

[Section titled “Troubleshooting”](#troubleshooting)

### Certificate Errors

[Section titled “Certificate Errors”](#certificate-errors)

If you encounter certificate validation errors:

1. **Verify the certificate path is correct**

* Use absolute paths or paths relative to the working directory

2. **Check certificate password**

* Ensure the password matches the one used during generation

3. **Verify certificate format**

* Chronicle requires PFX (PKCS#12) format
   * Use `openssl pkcs12` to convert other formats

### Connection Errors

[Section titled “Connection Errors”](#connection-errors)

If the client cannot connect:

1. **Verify TLS is enabled on both server and client**
2. **Check that the server is listening on HTTPS**
3. **Ensure the client trusts the server certificate**
4. **Check firewall rules allow HTTPS traffic**

## Next Steps

[Section titled “Next Steps”](#next-steps)

* [Production Hosting](/chronicle/hosting/production/) - Learn about production certificate requirements
* [Configuration](/chronicle/hosting/configuration/) - Complete configuration reference

# Production Hosting

Chronicle is designed for production deployment using Docker containers with MongoDB as the primary storage backend. The production setup provides a scalable, reliable event store suitable for enterprise workloads.

## Docker Image

[Section titled “Docker Image”](#docker-image)

Chronicle is distributed as a Docker image available on Docker Hub:

```bash
# Latest stable version
docker pull cratis/chronicle:latest

# Specific version (recommended for production)
docker pull cratis/chronicle:1.0.0
```

[![Docker](https://img.shields.io/docker/v/cratis/chronicle?label=Chronicle\&logo=docker\&sort=semver)](https://hub.docker.com/r/cratis/chronicle)

## Configuration

[Section titled “Configuration”](#configuration)

Chronicle requires configuration to define its runtime behavior. For complete configuration details, see the [Configuration](/chronicle/hosting/configuration/) guide.

The configuration file must be mounted into the container at `/app/chronicle.json`, or you can use environment variables with the `Cratis__Chronicle__` prefix.

### What makes a build a production build

[Section titled “What makes a build a production build”](#what-makes-a-build-a-production-build)

The production code paths are selected by the **`DEVELOPMENT` compile-time symbol**, not by `ASPNETCORE_ENVIRONMENT` or `DOTNET_ENVIRONMENT`. The symbol is defined for `Debug` builds only, so `cratis/chronicle:latest` — published from a Release build — always takes the production path, and no environment variable can switch it back. Only the `latest-development` and `latest-development-slim` images are compiled with the symbol.

That matters because the production path needs all three of these before it will run — and two of them stop startup dead:

| Setting                | Environment variable                                                                      | Why it is required                                                                                                                                                                                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Storage connection     | `Cratis__Chronicle__Storage__ConnectionDetails`                                           | Defaults to an empty string — there is no built-in fallback to connect to. Pair it with `Cratis__Chronicle__Storage__Type` when the backend is not MongoDB, which is what an unset type resolves to                                     |
| TLS certificate        | `Cratis__Chronicle__Tls__CertificatePath` (and `__CertificatePassword`)                   | Port 35000 multiplexes gRPC and HTTP/1.1 over one TLS port. Without a certificate the server throws “No TLS certificate is configured” at startup                                                                                       |
| Encryption certificate | `Cratis__Chronicle__EncryptionCertificate__CertificatePath` (and `__CertificatePassword`) | Protects the internal OAuth authority’s signing and encryption keys. Without a certificate the server throws “An encryption certificate is required in production” at startup — unless the internal authority is not in play, see below |

The encryption certificate is required because the **internal OAuth authority** needs it. It is therefore not required when that authority is out of the picture: turning the `oAuthAuthority` feature off, or pointing `Cratis__Chronicle__Authentication__Authority` at an external authority (which disables the internal one automatically), removes the requirement. See [Features](/chronicle/hosting/configuration/features/). The value-encryption subsystem is separate — it still throws `EncryptionCertificateNotConfigured` on first use if you encrypt values without a certificate configured.

“Not configured” and “configured wrongly” are different states. A `CertificatePath` pointing at a file that is not there stops startup with `EncryptionCertificateFileNotFound`, naming the path — it does not quietly fall back to running without a certificate. See [What a broken ring does](/chronicle/hosting/encryption-certificate/#what-a-broken-ring-does).

The development images generate a self-signed TLS certificate and fall back to ephemeral OAuth keys instead of throwing, which is exactly why a Compose file that works against `latest-development` fails against `latest`. See [Data Protection Key Encryption](/chronicle/hosting/encryption-certificate/) and [TLS Configuration](/chronicle/hosting/configuration/tls/) for generating and mounting the certificates.

## Storage requirements

[Section titled “Storage requirements”](#storage-requirements)

Chronicle opens MongoDB transactions when it appends events, and transactions are only served by a replica set (or a sharded cluster) — a standalone `mongod` rejects them. **Every MongoDB deployment behind Chronicle must be a replica set**, including a single-node one. The Compose recipes below initialize a single-node replica set named `rs0`; a real production deployment uses a multi-member replica set or a managed service such as MongoDB Atlas, which is already one.

Chronicle’s connection string carries `?directConnection=true` so the driver talks to the member it was given instead of following the replica set’s advertised host name. This does not disable transactions — they keep working because MongoDB is running as a replica set.

## Port Configuration

[Section titled “Port Configuration”](#port-configuration)

Chronicle exposes the following ports:

| Port  | Service         | Description                                                                                                |
| ----- | --------------- | ---------------------------------------------------------------------------------------------------------- |
| 11111 | Orleans Silo    | Internal Orleans clustering                                                                                |
| 30000 | Orleans Gateway | Client connections to Orleans cluster                                                                      |
| 35000 | Main Service    | gRPC (HTTP/2) plus REST API, Workbench, OAuth, and health checks (HTTP/1.1), multiplexed over one TLS port |

> **Note**: Port 35000 serves both HTTP/2 (gRPC) and HTTP/1.1 over TLS, so it **requires** a certificate. In production you must supply one via `Tls:CertificatePath` (and `Tls:CertificatePassword` if the certificate is protected). See [TLS Configuration](/chronicle/hosting/configuration/tls/).

## Docker Deployment

[Section titled “Docker Deployment”](#docker-deployment)

### Basic Docker Run

[Section titled “Basic Docker Run”](#basic-docker-run)

```bash
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:latest
```

Both certificates and the storage connection are mandatory — see [What makes a build a production build](#what-makes-a-build-a-production-build). The MongoDB instance this points at must be a replica set.

### Docker Compose

[Section titled “Docker Compose”](#docker-compose)

```yaml
services:
  chronicle:
    image: cratis/chronicle:latest
    ports:
      - "35000:35000"
    environment:
      Cratis__Chronicle__Storage__Type: "MongoDB"
      Cratis__Chronicle__Storage__ConnectionDetails: "mongodb://mongodb:27017/?directConnection=true"
      Cratis__Chronicle__Tls__CertificatePath: "/certs/chronicle.pfx"
      Cratis__Chronicle__Tls__CertificatePassword: "${CHRONICLE_CERTIFICATE_PASSWORD}"
      Cratis__Chronicle__EncryptionCertificate__CertificatePath: "/certs/encryption-cert.pfx"
      Cratis__Chronicle__EncryptionCertificate__CertificatePassword: "${ENCRYPTION_CERTIFICATE_PASSWORD}"
    volumes:
      - ./chronicle.json:/app/chronicle.json:ro
      - ./certs:/certs:ro
    depends_on:
      - mongodb
      - mongodb-init
    restart: unless-stopped

mongodb:
    image: mongo:8
    command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db
    restart: unless-stopped

mongodb-init:
    image: mongo:8
    depends_on:
      - mongodb
    restart: "no"
    command:
      - /bin/bash
      - -lc
      - |
        until mongosh --host mongodb --quiet --eval "db.adminCommand('ping')" >/dev/null 2>&1; do
          sleep 1
        done
        mongosh --host mongodb --quiet --eval "
        try {
          rs.status();
        } catch (e) {
          rs.initiate({
            _id: 'rs0',
            members: [{ _id: 0, host: 'localhost:27017' }]
          });
        }"

volumes:
  mongodb_data:
```

The `mongodb-init` service is a one-shot container: it waits for `mongod` to answer, initiates the `rs0` replica set if it is not already initiated, and exits. Advertising the member as `localhost:27017` keeps the replica set reachable from host tools such as `mongosh` and Compass, while Chronicle reaches MongoDB over the Compose network with `directConnection=true` so it does not follow that advertised host back into its own container.

If an existing MongoDB data volume was initialized with a different replica-set host, wipe it (`docker compose down -v`) before starting again so `rs.initiate()` can apply the new host.

The remaining settings stay in the mounted `chronicle.json`; the environment variables above override any values it holds for the same keys. Keep the certificate passwords out of the file — supply them from your secret store, as the `${...}` references do here.

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Use specific version tags** instead of `latest` for production deployments
2. **Mount configuration as read-only** (`-v /path/to/chronicle.json:/app/chronicle.json:ro`)
3. **Use environment-specific connection strings** for MongoDB
4. **Configure appropriate timeouts** based on your infrastructure (see [Configuration](/chronicle/hosting/configuration/))
5. **Enable health checks** for container orchestration
6. **Set up monitoring** for all exposed ports
7. **Use secrets management** for sensitive configuration values
8. **Enable TLS** with proper certificates (see [TLS Configuration](/chronicle/hosting/configuration/tls/))

## Health Checks

[Section titled “Health Checks”](#health-checks)

Chronicle exposes a health check endpoint at `/health` by default.

Note

**Probe Chronicle from outside the container.** The production image is built on `mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled`, which ships no shell and no `curl` or `wget`. A Docker `HEALTHCHECK` — or a Compose `healthcheck:` — runs *inside* the container, so any command you give it fails immediately and the container is reported unhealthy no matter how healthy Chronicle is.

Use your orchestrator’s own HTTP probe instead. The main port always requires TLS, and probers that validate certificates reject a self-signed one, so publish the health endpoint on a dedicated plaintext port:

```bash
Cratis__Chronicle__Health__Port=8080
Cratis__Chronicle__Health__Tls=false
```

Then point the probe at it:

```yaml
livenessProbe:
  httpGet:
    path: /health
    port: 8080
    scheme: HTTP
readinessProbe:
  httpGet:
    path: /health
    port: 8080
    scheme: HTTP
```

Treat that port as internal — it serves the other HTTP/1.1 endpoints too, so do not expose it publicly.

> **Note**: The health check endpoint path is configurable. See [Root Properties](/chronicle/hosting/configuration/root-properties/#health-check-endpoint) for details, and [Health Endpoint](/chronicle/hosting/configuration/health-endpoint/) for the dedicated port.

## Backup and restore

[Section titled “Backup and restore”](#backup-and-restore)

A Chronicle deployment is not restorable from a database backup alone. Three things have to be backed up, and restored **in this order** — restoring them in the wrong order produces data nothing can read, and nothing about the restore reports it.

| Order | What                                                                                                                                                                      | Where it lives                                 |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| 1     | The encryption-certificate ring — every certificate and its password, in the shape the ring had **when the backup was taken**                                             | Your secret store                              |
| 2     | The storage backend (MongoDB or SQL) — event store data, the Data Protection key ring, webhook definitions and their encrypted credentials, OAuth applications and tokens | Your database backups                          |
| 3     | The compliance key store, when one is configured, at the same point in time as (2)                                                                                        | Vault, Azure Key Vault, or the general storage |

The Data Protection key ring lives *inside* the storage backend, so a database backup already carries it. What a database backup cannot carry is the certificate that unlocks it — that is why the certificates come first, and why they have to be the ones that were live when the backup was taken rather than the ones live today.

Danger

**A certificate has to stay in the backup set for longer than it stays in the ring** — for at least as long as the oldest backup you would still restore. Retiring a certificate from the ring and deleting the file makes every backup taken before that rotation permanently unreadable.

Start one node after a restore and read `GET /diagnostics/encryption-certificates` before starting the rest: keys reported with the role `Retired` mean the ring is missing a certificate the restored data needs. The full procedure, the retention rule and the failure modes are in [Backup and restore ordering](/chronicle/hosting/encryption-certificate/#backup-and-restore-ordering); the PII key store has its own ordering in [Compliance Storage](/chronicle/hosting/configuration/compliance-storage/).

## Security Considerations

[Section titled “Security Considerations”](#security-considerations)

* **Network Isolation**: Run Chronicle in a private network with MongoDB
* **Connection Encryption**: Use TLS for all connections in production
* **Access Control**: Implement proper firewall rules for exposed ports
* **Secrets Management**: Use external secret management for sensitive configuration
* **Regular Updates**: Keep Chronicle and MongoDB images updated
* **TLS Certificates**: Configure valid TLS certificates for production (see [TLS Configuration](/chronicle/hosting/configuration/tls/))

## Scaling

[Section titled “Scaling”](#scaling)

Chronicle supports horizontal scaling through Orleans clustering:

1. **Multiple Instances**: Deploy multiple Chronicle containers
2. **Load Balancing**: Use a load balancer for API traffic (port 35000)
3. **Orleans Clustering**: Ensure Orleans ports (11111, 30000) are accessible between instances
4. **Shared Storage**: All instances must connect to the same MongoDB cluster

Caution

Every multi-node deployment **must** set the clustering type to `MongoDB`. The default is `Localhost`, which is single-node membership. Two containers left on the default that share one MongoDB do **not** join as one cluster - each forms its own isolated single-node cluster over the same data, a split-brain topology reported by no error at startup. The server logs a warning when it detects localhost clustering against non-local storage, but it does not refuse to start.

Set the clustering type explicitly on every node, and give every node the same cluster and service id:

```bash
Cratis__Chronicle__Clustering__Type=MongoDB
Cratis__Chronicle__Clustering__ClusterId=chronicle
Cratis__Chronicle__Clustering__ServiceId=chronicle
```

See [Clustering](/chronicle/hosting/configuration/clustering/) for the full set of clustering properties.

### Two-node Docker Compose

[Section titled “Two-node Docker Compose”](#two-node-docker-compose)

Both nodes run the same image, connect to the same MongoDB, and set `Cratis__Chronicle__Clustering__Type=MongoDB` so they form a single cluster over the shared storage:

```yaml
services:
  chronicle-1:
    image: cratis/chronicle:latest
    ports:
      - "35001:35000"
    environment:
      Cratis__Chronicle__Storage__ConnectionDetails: "mongodb://mongodb:27017/?directConnection=true"
      Cratis__Chronicle__Clustering__Type: "MongoDB"
      Cratis__Chronicle__Clustering__ClusterId: "chronicle"
      Cratis__Chronicle__Clustering__ServiceId: "chronicle"
      # Port 35000 requires a TLS certificate - see the TLS Configuration guide.
      Cratis__Chronicle__Tls__CertificatePath: "/certs/chronicle.pfx"
      Cratis__Chronicle__Tls__CertificatePassword: "${CHRONICLE_CERTIFICATE_PASSWORD}"
      # Every node must share the same encryption certificate.
      Cratis__Chronicle__EncryptionCertificate__CertificatePath: "/certs/encryption-cert.pfx"
      Cratis__Chronicle__EncryptionCertificate__CertificatePassword: "${ENCRYPTION_CERTIFICATE_PASSWORD}"
    volumes:
      - ./certs:/certs:ro
    depends_on:
      - mongodb
      - mongodb-init
    restart: unless-stopped

chronicle-2:
    image: cratis/chronicle:latest
    ports:
      - "35002:35000"
    environment:
      Cratis__Chronicle__Storage__ConnectionDetails: "mongodb://mongodb:27017/?directConnection=true"
      Cratis__Chronicle__Clustering__Type: "MongoDB"
      Cratis__Chronicle__Clustering__ClusterId: "chronicle"
      Cratis__Chronicle__Clustering__ServiceId: "chronicle"
      Cratis__Chronicle__Tls__CertificatePath: "/certs/chronicle.pfx"
      Cratis__Chronicle__Tls__CertificatePassword: "${CHRONICLE_CERTIFICATE_PASSWORD}"
      Cratis__Chronicle__EncryptionCertificate__CertificatePath: "/certs/encryption-cert.pfx"
      Cratis__Chronicle__EncryptionCertificate__CertificatePassword: "${ENCRYPTION_CERTIFICATE_PASSWORD}"
    volumes:
      - ./certs:/certs:ro
    depends_on:
      - mongodb
      - mongodb-init
    restart: unless-stopped

mongodb:
    image: mongo:8
    command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db
    restart: unless-stopped

mongodb-init:
    image: mongo:8
    depends_on:
      - mongodb
    restart: "no"
    command:
      - /bin/bash
      - -lc
      - |
        until mongosh --host mongodb --quiet --eval "db.adminCommand('ping')" >/dev/null 2>&1; do
          sleep 1
        done
        mongosh --host mongodb --quiet --eval "
        try {
          rs.status();
        } catch (e) {
          rs.initiate({
            _id: 'rs0',
            members: [{ _id: 0, host: 'localhost:27017' }]
          });
        }"

volumes:
  mongodb_data:
```

Both nodes share one encryption certificate on purpose: Data Protection keys live in the shared storage, so every instance must be able to decrypt what any other instance wrote. The same holds for the whole certificate ring during a rotation — give every node the same `Previous` list, or a node will fail to read what another one wrote. See [Data Protection Key Encryption](/chronicle/hosting/encryption-certificate/) and [Rotating the certificate](/chronicle/hosting/encryption-certificate/#rotating-the-certificate).

Each container reaches the others over the Compose network by service name, so the default advertised address works. When you instead run multiple nodes directly on one host, set `Cratis__Chronicle__Clustering__AdvertisedIP` and distinct `SiloPort`/`GatewayPort` values per node - see [Clustering](/chronicle/hosting/configuration/clustering/).

# Jobs

> Inspect and control long-running Chronicle Kernel operations such as replays and rebuilds.

Jobs represent long-running operations the Chronicle Kernel performs in the background — replaying a projection, rebuilding a read model, and similar work that runs in steps over time rather than completing instantly. Use the jobs API to see what’s running, check progress, and stop, resume, or delete a job.

## List all jobs

[Section titled “List all jobs”](#list-all-jobs)

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Jobs;

public class JobsIndexListAll(IEventStore eventStore)
  {
      public async Task<IEnumerable<Job>> GetAllJobs() => await eventStore.Jobs.GetJobs();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStore

suspend fun listJobs(store: EventStore) {
      store.jobs.getJobs().forEach { job ->
          println("${job.type}: ${job.status}")
      }
  }
  ```

* Java

```java
  import Cratis.Chronicle.Contracts.Jobs.JobsOuterClass;

import io.cratis.chronicle.EventStore;

import io.cratis.chronicle.java.JobsServiceJavaBridge;

import java.util.List;

class JobsIndexListAll {
      void listJobs(EventStore store) {
          List<JobsOuterClass.JobSummaryResponse> jobs = JobsServiceJavaBridge.getJobs(store.getJobs());
          for (JobsOuterClass.JobSummaryResponse job : jobs) {
              System.out.println(job.getType() + ": " + job.getStatus());
          }
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.JobsIndexListAll do
    def get_all_jobs do
      Chronicle.Jobs.all()
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';
  import { JobSummaryResponse } from '@cratis/chronicle.contracts';

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

async getAllJobs(): Promise<JobSummaryResponse[]> {
          return this.store.jobs.getJobs();
      }
  }
  ```

## Get a single job

[Section titled “Get a single job”](#get-a-single-job)

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Jobs;

public class JobsIndexGetOne(IEventStore eventStore)
  {
      public async Task<Job?> GetJob(JobId jobId) => await eventStore.Jobs.GetJob(jobId);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStore

suspend fun getReindexJob(store: EventStore, jobId: String) {
      val job = store.jobs.getJob(jobId)
      if (job != null) {
          println("${job.type}: ${job.status}")
      }
  }
  ```

* Java

```java
  import Cratis.Chronicle.Contracts.Jobs.JobsOuterClass;

import io.cratis.chronicle.EventStore;

import io.cratis.chronicle.java.JobsServiceJavaBridge;

class JobsIndexGetOne {
      void getReindexJob(EventStore store, String jobId) {
          JobsOuterClass.JobSummaryResponse job = JobsServiceJavaBridge.getJob(store.getJobs(), jobId);
          if (job != null) {
              System.out.println(job.getType() + ": " + job.getStatus());
          }
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.JobsIndexGetOne do
    def get_job(job_id) do
      Chronicle.Jobs.get(job_id)
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';
  import { JobSummaryResponse } from '@cratis/chronicle.contracts';

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

async getJob(jobId: string): Promise<JobSummaryResponse | undefined> {
          return this.store.jobs.getJob(jobId);
      }
  }
  ```

A missing job resolves to nothing rather than an error — check for that before using the result.

## Get the steps for a job

[Section titled “Get the steps for a job”](#get-the-steps-for-a-job)

A job is made up of one or more steps. Get them to see fine-grained progress:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Jobs;

public class JobsIndexGetSteps(IEventStore eventStore)
  {
      public async Task<IEnumerable<JobStep>?> GetSteps(JobId jobId)
      {
          var job = await eventStore.Jobs.GetJob(jobId);
          return job is null ? null : await job.GetJobSteps();
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStore

suspend fun listJobSteps(store: EventStore, jobId: String) {
      store.jobs.getJobSteps(jobId).forEach { step ->
          println("${step.name}: ${step.status}")
      }
  }
  ```

* Java

```java
  import Cratis.Chronicle.Contracts.Jobs.JobsOuterClass;

import io.cratis.chronicle.EventStore;

import io.cratis.chronicle.java.JobsServiceJavaBridge;

import java.util.List;

class JobsIndexGetSteps {
      void listJobSteps(EventStore store, String jobId) {
          List<JobsOuterClass.JobStepSummaryResponse> steps = JobsServiceJavaBridge.getJobSteps(store.getJobs(), jobId);
          for (JobsOuterClass.JobStepSummaryResponse step : steps) {
              System.out.println(step.getName() + ": " + step.getStatus());
          }
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.JobsIndexGetSteps do
    def get_steps(job_id) do
      Chronicle.Jobs.steps(job_id)
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';
  import { JobStepSummaryResponse } from '@cratis/chronicle.contracts';

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

async getSteps(jobId: string): Promise<JobStepSummaryResponse[]> {
          return this.store.jobs.getJobSteps(jobId);
      }
  }
  ```

## Stop, resume, and delete

[Section titled “Stop, resume, and delete”](#stop-resume-and-delete)

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Jobs;

public class JobsIndexStopResumeDelete(IEventStore eventStore)
  {
      public async Task StopJob(JobId jobId) => await eventStore.Jobs.Stop(jobId);

public async Task ResumeJob(JobId jobId) => await eventStore.Jobs.Resume(jobId);

public async Task DeleteJob(JobId jobId) => await eventStore.Jobs.Delete(jobId);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStore

suspend fun controlJob(store: EventStore, jobId: String) {
      store.jobs.stop(jobId)
      store.jobs.resume(jobId)
      store.jobs.delete(jobId)
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;

import io.cratis.chronicle.java.JobsServiceJavaBridge;

class JobsIndexControl {
      void controlJob(EventStore store, String jobId) {
          JobsServiceJavaBridge.stop(store.getJobs(), jobId);
          JobsServiceJavaBridge.resume(store.getJobs(), jobId);
          JobsServiceJavaBridge.delete(store.getJobs(), jobId);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.JobsIndexStopResumeDelete do
    def stop_job(job_id), do: Chronicle.Jobs.stop(job_id)
    def resume_job(job_id), do: Chronicle.Jobs.resume(job_id)
    def delete_job(job_id), do: Chronicle.Jobs.delete(job_id)
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async stopJob(jobId: string): Promise<void> {
          await this.store.jobs.stop(jobId);
      }

async resumeJob(jobId: string): Promise<void> {
          await this.store.jobs.resume(jobId);
      }

async deleteJob(jobId: string): Promise<void> {
          await this.store.jobs.delete(jobId);
      }
  }
  ```

## Related topics

[Section titled “Related topics”](#related-topics)

* [Webhooks](/chronicle/webhooks/) — pushing observed events to external HTTP endpoints, the other kernel-managed background concern.

# Migrations

Every system evolves. Business rules change, data models improve, and properties get renamed, split, or combined. In event-sourced systems this creates a challenge: events are immutable facts, and the historical record cannot simply be edited. Chronicle solves this with a declarative migration system that lets you evolve event schemas without losing backward compatibility.

```
migration

migration

Event (as written, v1)

Event v2

Event v3 (current)

Read / projected
```

## Why migrations?

[Section titled “Why migrations?”](#why-migrations)

Events in Chronicle represent things that happened, not the current state. That immutability is a feature — it gives you a reliable audit trail and the ability to replay history. But it also means you need a principled way to handle changes to event schemas over time.

Chronicle’s migration system addresses this through **generations**. Each version of an event type is a distinct generation. When you introduce a new generation, you declare how to transform events between that generation and its predecessor in both directions:

* **Upcasting** — transforming an older generation into a newer one (e.g. splitting a `Name` field into `FirstName` and `LastName`)
* **Downcasting** — transforming a newer generation back into an older one (e.g. recombining `FirstName` and `LastName` into `Name`)

## Architecture: Kernel-side migrations

[Section titled “Architecture: Kernel-side migrations”](#architecture-kernel-side-migrations)

**Migrations are a Kernel concern, not a client concern.** The Chronicle Kernel evaluates and applies migrations regardless of whether a client is connected. This is a fundamental design principle:

* Migrations run during event append inside the Kernel
* The Kernel stores every generation of an event simultaneously
* No client coordination is required for migrations to take effect
* Clients that are offline or on older code versions are unaffected

This means your migration logic is durable. Once a migrator is registered with the Kernel, it operates on every event that passes through, whether it originated from a .NET client, a REST call, or a future integration you haven’t written yet.

## Multi-version storage

[Section titled “Multi-version storage”](#multi-version-storage)

When an event with generation migrations arrives at the Kernel, it stores **all generations** of that event:

* Appending a generation 1 event with a 1→2 migration stores gen 1 and gen 2
* Appending a generation 2 event with a 1→2 migration stores gen 2 and the downcasted gen 1
* Appending a generation 3 event with 1→2 and 2→3 migrations stores gen 1, gen 2, and gen 3

This multi-version storage is what makes event-sourced systems with migrations genuinely decoupled. Consider two services that share an event type:

* **Service A** is running the latest code and expects generation 2
* **Service B** is running older code and expects generation 1

Both services read the same event and each gets the generation they expect. There is no negotiation, no shared upgrade schedule, no risk of one service breaking another. The Kernel handles the translation, and each consumer reads the generation it understands.

```text
Append gen 1 event
        │
        ▼
  Kernel receives
        │
        ├── Store gen 1  ─── Service B reads gen 1
        │
        └── Upcast to gen 2
                │
                └── Store gen 2  ─── Service A reads gen 2
```

## Migrations happen in place

[Section titled “Migrations happen in place”](#migrations-happen-in-place)

Chronicle migrations are **non-destructive**. Every generation of an event is stored permanently in the event store alongside the others. Nothing is deleted or overwritten: if you have a generation 1 event written two years ago, the event store still holds that exact record. The migration system produces additional representations alongside it, not instead of it.

This is what makes running multiple versions of the same software against the same event store safe. Service A on the latest code reads generation 2; Service B on the previous release reads generation 1. Both read from the same physical storage. Neither service needs to know about the other, and no upgrade coordination is required.

### Background upcasting for new generations

[Section titled “Background upcasting for new generations”](#background-upcasting-for-new-generations)

When a new generation is introduced and registered with the Kernel, Chronicle automatically starts a background job that replays all existing events for that event type and produces the new generation where it is missing. You do not trigger this manually and you do not need to wait for it to complete before the application is usable. The background job runs at Kernel priority and completes asynchronously.

Once the job finishes, every event in the event store that had only older generations will also have the new generation present. Consumers that expect the new generation will find it there, and consumers that expect older generations are unaffected.

## Topics

[Section titled “Topics”](#topics)

* [C# client usage](/chronicle/migrations/dotnet-client/)

# C# client usage

This guide covers how to declare event type migrations in a .NET client, the operations available to you, and what happens when your migrators are registered with the Chronicle Kernel.

## Prerequisites

[Section titled “Prerequisites”](#prerequisites)

* A Chronicle-enabled .NET application
* An event type marked with `[EventType]` that has evolved beyond generation 1

## Marking event types with generations

[Section titled “Marking event types with generations”](#marking-event-types-with-generations)

Every `[EventType]` that has evolved past its first version must declare its current generation. You keep both the old and new record types in your codebase — Chronicle identifies them as the same event type by a shared event type id, not by C# class name.

* C#

```csharp
  using Cratis.Chronicle.Events;

// Generation 2 (current) — Name has been split into FirstName and LastName
  [EventType("dotnet-client-author-registered", generation: 2)]
  public record MigrationsDotnetClientAuthorRegistered(string FirstName, string LastName);

// Generation 1 (original) — marked as a previous generation of the current record above,
  // instead of carrying its own [EventType]
  [EventTypeGenerationFor<MigrationsDotnetClientAuthorRegistered>(1)]
  public record MigrationsDotnetClientAuthorRegisteredV1(string Name);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

// Generation 2 (current) - Name has been split into firstName and lastName
  @EventType(id = "dotnet-client-author-registered", generation = 2)
  data class MigrationsDotnetClientAuthorRegistered(val firstName: String, val lastName: String)

// Generation 1 (original) - same explicit id as the current generation, only the generation differs
  @EventType(id = "dotnet-client-author-registered", generation = 1)
  data class MigrationsDotnetClientAuthorRegisteredV1(val name: String)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

// Generation 2 (current) - name has been split into firstName and lastName
  @EventType(id = "dotnet-client-author-registered", generation = 2)
  record MigrationsDotnetClientAuthorRegistered(String firstName, String lastName) {}

// Generation 1 (original) - same explicit id as the current generation, only the generation differs
  @EventType(id = "dotnet-client-author-registered", generation = 1)
  record MigrationsDotnetClientAuthorRegisteredV1(String name) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsDotnetClientAuthorRegisteredV1 do
    use Chronicle.Events.EventType, id: "dotnet-client-author-registered", generation: 1

defstruct [:name]
  end

defmodule MyApp.Events.MigrationsDotnetClientAuthorRegistered do
    use Chronicle.Events.EventType, id: "dotnet-client-author-registered", generation: 2

defstruct [:first_name, :last_name]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

// Generation 2 (current) — Name has been split into FirstName and LastName
  @eventType('dotnet-client-author-registered', 2)
  class MigrationsDotnetClientAuthorRegistered {
      constructor(readonly firstName: string, readonly lastName: string) {}
  }

// 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('dotnet-client-author-registered', 1)
  class MigrationsDotnetClientAuthorRegisteredV1 {
      constructor(readonly name: string) {}
  }
  ```

The current generation, `MigrationsDotnetClientAuthorRegistered`, carries the real `[EventType]` with its explicit id. The previous generation, `MigrationsDotnetClientAuthorRegisteredV1`, carries `[EventTypeGenerationFor<MigrationsDotnetClientAuthorRegistered>(1)]` instead — it has no independent id of its own at all. Its event type id is resolved directly from the current generation’s `[EventType]`, so the two can never end up with different ids no matter how the records are renamed later.

The old, explicit-id style still works

You can still mark every generation with its own `[EventType]`, as long as you pass the **exact same explicit id string** on all of them and vary only `generation:`. This is fully backward compatible — it is not deprecated. What it no longer is, is the recommended default: an id left off a previous generation silently falls back to the CLR type name rather than being “derived from the type name base” in any way that stays in sync with the current generation, and Chronicle then treats the two records as unrelated event types entirely. `[EventTypeGenerationFor<T>]` removes that failure mode by construction.

## Defining a migrator

[Section titled “Defining a migrator”](#defining-a-migrator)

Extend `EventTypeMigration<TUpgrade, TPrevious>` where `TUpgrade` is the **newer** generation and `TPrevious` is the **older** one:

* C#

```csharp
  using Cratis.Chronicle.Events.Migrations;

public class MigrationsDotnetClientAuthorRegisteredMigration : EventTypeMigration<MigrationsDotnetClientAuthorRegistered, MigrationsDotnetClientAuthorRegisteredV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDotnetClientAuthorRegistered, MigrationsDotnetClientAuthorRegisteredV1> builder) =>
          builder.Properties(pb => pb
              .Split(m => m.FirstName, e => e.Name, PropertySeparator.Space, SplitPartIndex.First)
              .Split(m => m.LastName, e => e.Name, PropertySeparator.Space, SplitPartIndex.Second));

public override void Downcast(IEventMigrationBuilder<MigrationsDotnetClientAuthorRegisteredV1, MigrationsDotnetClientAuthorRegistered> builder) =>
          builder.Properties(pb => pb
              .Combine(m => m.Name, PropertySeparator.Space, e => e.FirstName, e => e.LastName));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

class MigrationsDotnetClientAuthorRegisteredMigration :
      EventTypeMigration<MigrationsDotnetClientAuthorRegistered, MigrationsDotnetClientAuthorRegisteredV1>(
          MigrationsDotnetClientAuthorRegistered::class,
          MigrationsDotnetClientAuthorRegisteredV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientAuthorRegistered, MigrationsDotnetClientAuthorRegisteredV1>) {
          builder
              .split(MigrationsDotnetClientAuthorRegistered::firstName, MigrationsDotnetClientAuthorRegisteredV1::name, " ", 0)
              .split(MigrationsDotnetClientAuthorRegistered::lastName, MigrationsDotnetClientAuthorRegisteredV1::name, " ", 1)
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientAuthorRegisteredV1, MigrationsDotnetClientAuthorRegistered>) {
          builder.combine(
              MigrationsDotnetClientAuthorRegisteredV1::name,
              " ",
              MigrationsDotnetClientAuthorRegistered::firstName,
              MigrationsDotnetClientAuthorRegistered::lastName
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

class MigrationsDotnetClientAuthorRegisteredMigration
          extends EventTypeMigration<MigrationsDotnetClientAuthorRegistered,
                                     MigrationsDotnetClientAuthorRegisteredV1> {
      MigrationsDotnetClientAuthorRegisteredMigration() {
          super(MigrationsDotnetClientAuthorRegistered.class, MigrationsDotnetClientAuthorRegisteredV1.class);
      }

@Override
      public void upcast(EventTypeMigrationBuilder<MigrationsDotnetClientAuthorRegistered,
                                                   MigrationsDotnetClientAuthorRegisteredV1> builder) {
          builder
              .split("firstName", "name", " ", 0)
              .split("lastName", "name", " ", 1);
      }

@Override
      public void downcast(EventTypeMigrationBuilder<MigrationsDotnetClientAuthorRegisteredV1,
                                                     MigrationsDotnetClientAuthorRegistered> builder) {
          builder.combine("name", " ", "firstName", "lastName");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsDotnetClientMigratorAuthorRegisteredV1 do
    use Chronicle.Events.EventType, id: "dotnet-client-migrator-author-registered", generation: 1

defstruct [:name]
  end

defmodule MyApp.Events.MigrationsDotnetClientMigratorAuthorRegistered do
    use Chronicle.Events.EventType, id: "dotnet-client-migrator-author-registered", generation: 2

defstruct [:first_name, :last_name]
  end

defmodule MyApp.Migrations.MigrationsDotnetClientMigratorAuthorRegisteredMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsDotnetClientMigratorAuthorRegisteredV1, generation: 1},
      to: {MyApp.Events.MigrationsDotnetClientMigratorAuthorRegistered, generation: 2}

alias Chronicle.Events.MigrationBuilder

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

@impl true
    def downcast(builder) do
      MigrationBuilder.combine_properties(builder, [:first_name, :last_name], :name, " ")
    end
  end
  ```

* TypeScript

```typescript
  import { eventTypeMigration, IEventMigrationBuilder, IEventTypeMigration } from '@cratis/chronicle';

@eventTypeMigration(MigrationsDotnetClientAuthorRegistered, MigrationsDotnetClientAuthorRegisteredV1)
  class MigrationsDotnetClientAuthorRegisteredMigration implements IEventTypeMigration<MigrationsDotnetClientAuthorRegistered, MigrationsDotnetClientAuthorRegisteredV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsDotnetClientAuthorRegistered, MigrationsDotnetClientAuthorRegisteredV1>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .split('firstName', 'name', ' ', 0)
              .split('lastName', 'name', ' ', 1));
      }

downcast(builder: IEventMigrationBuilder<MigrationsDotnetClientAuthorRegisteredV1, MigrationsDotnetClientAuthorRegistered>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .combine('name', ' ', 'firstName', 'lastName'));
      }
  }
  ```

The `From` and `To` generation numbers are read automatically — from `TPrevious`’s `[EventTypeGenerationFor<T>]` (or its `[EventType]`, if you’re using the old style) and from `TUpgrade`’s `[EventType]`. You do not declare them yourself. The base class constructor also validates, at that point, that both generations resolve to the **same event type id** (throwing `MigrationGenerationsMustShareEventTypeId` immediately if they don’t) and that `To == From + 1` (throwing `InvalidMigrationGenerationGap` otherwise), preventing both an accidental identity mismatch and a generation gap.

Migrators are discovered automatically at startup — no explicit registration is needed. If two different migrator classes both claim to bridge the same generation pair for one event type, `EventTypeMigrators.GetMigratorsFor` throws `MultipleMigratorsForSameEventTypeGeneration` — exactly one migrator may own a given transition.

## Migration operations

[Section titled “Migration operations”](#migration-operations)

All operations are called on the property builder inside `builder.Properties(pb => ...)`. Each call declares one output property using a target property expression and one or more source property expressions drawn from the opposite generation’s record.

### Split

[Section titled “Split”](#split)

Extracts one segment of a string property by splitting on a separator and taking the part at a given index.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("dotnet-client-person-registered", generation: 2)]
  public record MigrationsDotnetClientSplitPersonRegistered(string FirstName, string LastName);

[EventTypeGenerationFor<MigrationsDotnetClientSplitPersonRegistered>(1)]
  public record MigrationsDotnetClientSplitPersonRegisteredV1(string FullName);

public class MigrationsDotnetClientSplitPersonRegisteredMigration : EventTypeMigration<MigrationsDotnetClientSplitPersonRegistered, MigrationsDotnetClientSplitPersonRegisteredV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDotnetClientSplitPersonRegistered, MigrationsDotnetClientSplitPersonRegisteredV1> builder) =>
          builder.Properties(pb => pb
              .Split(t => t.FirstName, s => s.FullName, PropertySeparator.Space, SplitPartIndex.First)
              .Split(t => t.LastName, s => s.FullName, PropertySeparator.Space, SplitPartIndex.Second));

public override void Downcast(IEventMigrationBuilder<MigrationsDotnetClientSplitPersonRegisteredV1, MigrationsDotnetClientSplitPersonRegistered> builder) =>
          builder.Properties(pb => pb
              .Combine(t => t.FullName, PropertySeparator.Space, s => s.FirstName, s => s.LastName));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "dotnet-client-person-registered", generation = 2)
  data class MigrationsDotnetClientSplitPersonRegistered(val firstName: String, val lastName: String)

@EventType(id = "dotnet-client-person-registered", generation = 1)
  data class MigrationsDotnetClientSplitPersonRegisteredV1(val fullName: String)

class MigrationsDotnetClientSplitPersonRegisteredMigration :
      EventTypeMigration<MigrationsDotnetClientSplitPersonRegistered, MigrationsDotnetClientSplitPersonRegisteredV1>(
          MigrationsDotnetClientSplitPersonRegistered::class,
          MigrationsDotnetClientSplitPersonRegisteredV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientSplitPersonRegistered, MigrationsDotnetClientSplitPersonRegisteredV1>) {
          builder
              .split(MigrationsDotnetClientSplitPersonRegistered::firstName, MigrationsDotnetClientSplitPersonRegisteredV1::fullName, " ", 0)
              .split(MigrationsDotnetClientSplitPersonRegistered::lastName, MigrationsDotnetClientSplitPersonRegisteredV1::fullName, " ", 1)
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientSplitPersonRegisteredV1, MigrationsDotnetClientSplitPersonRegistered>) {
          builder.combine(
              MigrationsDotnetClientSplitPersonRegisteredV1::fullName,
              " ",
              MigrationsDotnetClientSplitPersonRegistered::firstName,
              MigrationsDotnetClientSplitPersonRegistered::lastName
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "dotnet-client-person-registered", generation = 2)
  record MigrationsDotnetClientSplitPersonRegistered(String firstName, String lastName) {
  }

@EventType(id = "dotnet-client-person-registered", generation = 1)
  record MigrationsDotnetClientSplitPersonRegisteredV1(String fullName) {
  }

class MigrationsDotnetClientSplitPersonRegisteredMigration
          extends EventTypeMigration<MigrationsDotnetClientSplitPersonRegistered,
                                     MigrationsDotnetClientSplitPersonRegisteredV1> {
      MigrationsDotnetClientSplitPersonRegisteredMigration() {
          super(MigrationsDotnetClientSplitPersonRegistered.class,
                MigrationsDotnetClientSplitPersonRegisteredV1.class);
      }

@Override
      public void upcast(EventTypeMigrationBuilder<MigrationsDotnetClientSplitPersonRegistered,
                                                   MigrationsDotnetClientSplitPersonRegisteredV1> builder) {
          builder
              .split("firstName", "fullName", " ", 0)
              .split("lastName", "fullName", " ", 1);
      }

@Override
      public void downcast(EventTypeMigrationBuilder<MigrationsDotnetClientSplitPersonRegisteredV1,
                                                     MigrationsDotnetClientSplitPersonRegistered> builder) {
          builder.combine("fullName", " ", "firstName", "lastName");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsDotnetClientSplitPersonRegisteredV1 do
    use Chronicle.Events.EventType, id: "dotnet-client-person-registered", generation: 1

defstruct [:full_name]
  end

defmodule MyApp.Events.MigrationsDotnetClientSplitPersonRegistered do
    use Chronicle.Events.EventType, id: "dotnet-client-person-registered", generation: 2

defstruct [:first_name, :last_name]
  end

defmodule MyApp.Migrations.MigrationsDotnetClientSplitPersonRegisteredMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsDotnetClientSplitPersonRegisteredV1, generation: 1},
      to: {MyApp.Events.MigrationsDotnetClientSplitPersonRegistered, generation: 2}

alias Chronicle.Events.MigrationBuilder

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

@impl true
    def downcast(builder) do
      MigrationBuilder.combine_properties(builder, [:first_name, :last_name], :full_name, " ")
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventMigrationBuilder, IEventTypeMigration } from '@cratis/chronicle';

@eventType('dotnet-client-person-registered', 2)
  class MigrationsDotnetClientSplitPersonRegistered {
      constructor(readonly firstName: string, readonly lastName: string) {}
  }

@eventType('dotnet-client-person-registered', 1)
  class MigrationsDotnetClientSplitPersonRegisteredV1 {
      constructor(readonly fullName: string) {}
  }

@eventTypeMigration(MigrationsDotnetClientSplitPersonRegistered, MigrationsDotnetClientSplitPersonRegisteredV1)
  class MigrationsDotnetClientSplitPersonRegisteredMigration implements IEventTypeMigration<MigrationsDotnetClientSplitPersonRegistered, MigrationsDotnetClientSplitPersonRegisteredV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsDotnetClientSplitPersonRegistered, MigrationsDotnetClientSplitPersonRegisteredV1>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .split('firstName', 'fullName', ' ', 0)
              .split('lastName', 'fullName', ' ', 1));
      }

downcast(builder: IEventMigrationBuilder<MigrationsDotnetClientSplitPersonRegisteredV1, MigrationsDotnetClientSplitPersonRegistered>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .combine('fullName', ' ', 'firstName', 'lastName'));
      }
  }
  ```

`PropertySeparator.Space` is a built-in constant. Any string is also implicitly convertible to a `PropertySeparator`, so `":"` works directly for colon-delimited fields. `SplitPartIndex.First` (index 0) and `SplitPartIndex.Second` (index 1) cover the most common cases; pass any `int` for deeper splits.

### Combine

[Section titled “Combine”](#combine)

Concatenates multiple source properties into a single string target property, joining with a separator. The second argument is a `PropertySeparator` — use the built-in `PropertySeparator.Space` or pass any string (e.g. `":"`).

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("dotnet-client-shipping-address-recorded", generation: 2)]
  public record MigrationsDotnetClientCombineShippingAddressRecorded(string FullAddress);

[EventTypeGenerationFor<MigrationsDotnetClientCombineShippingAddressRecorded>(1)]
  public record MigrationsDotnetClientCombineShippingAddressRecordedV1(string Street, string City);

public class MigrationsDotnetClientCombineShippingAddressRecordedMigration : EventTypeMigration<MigrationsDotnetClientCombineShippingAddressRecorded, MigrationsDotnetClientCombineShippingAddressRecordedV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDotnetClientCombineShippingAddressRecorded, MigrationsDotnetClientCombineShippingAddressRecordedV1> builder) =>
          builder.Properties(pb => pb
              .Combine(t => t.FullAddress, PropertySeparator.Space, s => s.Street, s => s.City));

public override void Downcast(IEventMigrationBuilder<MigrationsDotnetClientCombineShippingAddressRecordedV1, MigrationsDotnetClientCombineShippingAddressRecorded> builder) =>
          builder.Properties(pb => pb
              .Split(t => t.Street, s => s.FullAddress, PropertySeparator.Space, SplitPartIndex.First)
              .Split(t => t.City, s => s.FullAddress, PropertySeparator.Space, SplitPartIndex.Second));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "dotnet-client-shipping-address-recorded", generation = 2)
  data class MigrationsDotnetClientCombineShippingAddressRecorded(val fullAddress: String)

@EventType(id = "dotnet-client-shipping-address-recorded", generation = 1)
  data class MigrationsDotnetClientCombineShippingAddressRecordedV1(val street: String, val city: String)

class MigrationsDotnetClientCombineShippingAddressRecordedMigration :
      EventTypeMigration<MigrationsDotnetClientCombineShippingAddressRecorded, MigrationsDotnetClientCombineShippingAddressRecordedV1>(
          MigrationsDotnetClientCombineShippingAddressRecorded::class,
          MigrationsDotnetClientCombineShippingAddressRecordedV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientCombineShippingAddressRecorded, MigrationsDotnetClientCombineShippingAddressRecordedV1>) {
          builder.combine(
              MigrationsDotnetClientCombineShippingAddressRecorded::fullAddress,
              " ",
              MigrationsDotnetClientCombineShippingAddressRecordedV1::street,
              MigrationsDotnetClientCombineShippingAddressRecordedV1::city
          )
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientCombineShippingAddressRecordedV1, MigrationsDotnetClientCombineShippingAddressRecorded>) {
          builder
              .split(MigrationsDotnetClientCombineShippingAddressRecordedV1::street, MigrationsDotnetClientCombineShippingAddressRecorded::fullAddress, " ", 0)
              .split(MigrationsDotnetClientCombineShippingAddressRecordedV1::city, MigrationsDotnetClientCombineShippingAddressRecorded::fullAddress, " ", 1)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "dotnet-client-shipping-address-recorded", generation = 2)
  record MigrationsDotnetClientCombineShippingAddressRecorded(String fullAddress) {
  }

@EventType(id = "dotnet-client-shipping-address-recorded", generation = 1)
  record MigrationsDotnetClientCombineShippingAddressRecordedV1(String street, String city) {
  }

class MigrationsDotnetClientCombineShippingAddressRecordedMigration
          extends EventTypeMigration<MigrationsDotnetClientCombineShippingAddressRecorded,
                                     MigrationsDotnetClientCombineShippingAddressRecordedV1> {
      MigrationsDotnetClientCombineShippingAddressRecordedMigration() {
          super(MigrationsDotnetClientCombineShippingAddressRecorded.class,
                MigrationsDotnetClientCombineShippingAddressRecordedV1.class);
      }

@Override
      public void upcast(EventTypeMigrationBuilder<MigrationsDotnetClientCombineShippingAddressRecorded,
                                                   MigrationsDotnetClientCombineShippingAddressRecordedV1> builder) {
          builder.combine("fullAddress", " ", "street", "city");
      }

@Override
      public void downcast(EventTypeMigrationBuilder<MigrationsDotnetClientCombineShippingAddressRecordedV1,
                                                     MigrationsDotnetClientCombineShippingAddressRecorded> builder) {
          builder
              .split("street", "fullAddress", " ", 0)
              .split("city", "fullAddress", " ", 1);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsDotnetClientCombineShippingAddressRecordedV1 do
    use Chronicle.Events.EventType, id: "dotnet-client-shipping-address-recorded", generation: 1

defstruct [:street, :city]
  end

defmodule MyApp.Events.MigrationsDotnetClientCombineShippingAddressRecorded do
    use Chronicle.Events.EventType, id: "dotnet-client-shipping-address-recorded", generation: 2

defstruct [:full_address]
  end

defmodule MyApp.Migrations.MigrationsDotnetClientCombineShippingAddressRecordedMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsDotnetClientCombineShippingAddressRecordedV1, generation: 1},
      to: {MyApp.Events.MigrationsDotnetClientCombineShippingAddressRecorded, generation: 2}

alias Chronicle.Events.MigrationBuilder

@impl true
    def upcast(builder) do
      MigrationBuilder.combine_properties(builder, [:street, :city], :full_address, " ")
    end

@impl true
    def downcast(builder) do
      builder
      |> MigrationBuilder.split_property(:full_address, :street, " ", 0)
      |> MigrationBuilder.split_property(:full_address, :city, " ", 1)
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventMigrationBuilder, IEventTypeMigration } from '@cratis/chronicle';

@eventType('dotnet-client-shipping-address-recorded', 2)
  class MigrationsDotnetClientCombineShippingAddressRecorded {
      constructor(readonly fullAddress: string) {}
  }

@eventType('dotnet-client-shipping-address-recorded', 1)
  class MigrationsDotnetClientCombineShippingAddressRecordedV1 {
      constructor(readonly street: string, readonly city: string) {}
  }

@eventTypeMigration(MigrationsDotnetClientCombineShippingAddressRecorded, MigrationsDotnetClientCombineShippingAddressRecordedV1)
  class MigrationsDotnetClientCombineShippingAddressRecordedMigration implements IEventTypeMigration<MigrationsDotnetClientCombineShippingAddressRecorded, MigrationsDotnetClientCombineShippingAddressRecordedV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsDotnetClientCombineShippingAddressRecorded, MigrationsDotnetClientCombineShippingAddressRecordedV1>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .combine('fullAddress', ' ', 'street', 'city'));
      }

downcast(builder: IEventMigrationBuilder<MigrationsDotnetClientCombineShippingAddressRecordedV1, MigrationsDotnetClientCombineShippingAddressRecorded>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .split('street', 'fullAddress', ' ', 0)
              .split('city', 'fullAddress', ' ', 1));
      }
  }
  ```

### RenamedFrom

[Section titled “RenamedFrom”](#renamedfrom)

Maps a property from its old name in the source generation to its new name in the target generation.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("dotnet-client-customer-registered", generation: 2)]
  public record MigrationsDotnetClientRenamedFromCustomerRegistered(string Email);

[EventTypeGenerationFor<MigrationsDotnetClientRenamedFromCustomerRegistered>(1)]
  public record MigrationsDotnetClientRenamedFromCustomerRegisteredV1(string EmailAddress);

public class MigrationsDotnetClientRenamedFromCustomerRegisteredMigration : EventTypeMigration<MigrationsDotnetClientRenamedFromCustomerRegistered, MigrationsDotnetClientRenamedFromCustomerRegisteredV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDotnetClientRenamedFromCustomerRegistered, MigrationsDotnetClientRenamedFromCustomerRegisteredV1> builder) =>
          builder.Properties(pb => pb
              .RenamedFrom(t => t.Email, s => s.EmailAddress));

public override void Downcast(IEventMigrationBuilder<MigrationsDotnetClientRenamedFromCustomerRegisteredV1, MigrationsDotnetClientRenamedFromCustomerRegistered> builder) =>
          builder.Properties(pb => pb
              .RenamedFrom(t => t.EmailAddress, s => s.Email));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "dotnet-client-customer-registered", generation = 2)
  data class MigrationsDotnetClientRenamedFromCustomerRegistered(val email: String)

@EventType(id = "dotnet-client-customer-registered", generation = 1)
  data class MigrationsDotnetClientRenamedFromCustomerRegisteredV1(val emailAddress: String)

class MigrationsDotnetClientRenamedFromCustomerRegisteredMigration :
      EventTypeMigration<MigrationsDotnetClientRenamedFromCustomerRegistered, MigrationsDotnetClientRenamedFromCustomerRegisteredV1>(
          MigrationsDotnetClientRenamedFromCustomerRegistered::class,
          MigrationsDotnetClientRenamedFromCustomerRegisteredV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientRenamedFromCustomerRegistered, MigrationsDotnetClientRenamedFromCustomerRegisteredV1>) {
          builder.renamedFrom(MigrationsDotnetClientRenamedFromCustomerRegistered::email, MigrationsDotnetClientRenamedFromCustomerRegisteredV1::emailAddress)
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientRenamedFromCustomerRegisteredV1, MigrationsDotnetClientRenamedFromCustomerRegistered>) {
          builder.renamedFrom(MigrationsDotnetClientRenamedFromCustomerRegisteredV1::emailAddress, MigrationsDotnetClientRenamedFromCustomerRegistered::email)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "dotnet-client-customer-registered", generation = 2)
  record MigrationsDotnetClientRenamedFromCustomerRegistered(String email) {
  }

@EventType(id = "dotnet-client-customer-registered", generation = 1)
  record MigrationsDotnetClientRenamedFromCustomerRegisteredV1(String emailAddress) {
  }

class MigrationsDotnetClientRenamedFromCustomerRegisteredMigration
          extends EventTypeMigration<MigrationsDotnetClientRenamedFromCustomerRegistered,
                                     MigrationsDotnetClientRenamedFromCustomerRegisteredV1> {
      MigrationsDotnetClientRenamedFromCustomerRegisteredMigration() {
          super(MigrationsDotnetClientRenamedFromCustomerRegistered.class,
                MigrationsDotnetClientRenamedFromCustomerRegisteredV1.class);
      }

@Override
      public void upcast(EventTypeMigrationBuilder<MigrationsDotnetClientRenamedFromCustomerRegistered,
                                                   MigrationsDotnetClientRenamedFromCustomerRegisteredV1> builder) {
          builder.renamedFrom("email", "emailAddress");
      }

@Override
      public void downcast(EventTypeMigrationBuilder<MigrationsDotnetClientRenamedFromCustomerRegisteredV1,
                                                     MigrationsDotnetClientRenamedFromCustomerRegistered> builder) {
          builder.renamedFrom("emailAddress", "email");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsDotnetClientRenamedFromCustomerRegisteredV1 do
    use Chronicle.Events.EventType, id: "dotnet-client-customer-registered", generation: 1

defstruct [:email_address]
  end

defmodule MyApp.Events.MigrationsDotnetClientRenamedFromCustomerRegistered do
    use Chronicle.Events.EventType, id: "dotnet-client-customer-registered", generation: 2

defstruct [:email]
  end

defmodule MyApp.Migrations.MigrationsDotnetClientRenamedFromCustomerRegisteredMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsDotnetClientRenamedFromCustomerRegisteredV1, generation: 1},
      to: {MyApp.Events.MigrationsDotnetClientRenamedFromCustomerRegistered, generation: 2}

alias Chronicle.Events.MigrationBuilder

@impl true
    def upcast(builder), do: MigrationBuilder.renamed_from(builder, :email, :email_address)

@impl true
    def downcast(builder), do: MigrationBuilder.renamed_from(builder, :email_address, :email)
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventMigrationBuilder, IEventTypeMigration } from '@cratis/chronicle';

@eventType('dotnet-client-customer-registered', 2)
  class MigrationsDotnetClientRenamedFromCustomerRegistered {
      constructor(readonly email: string) {}
  }

@eventType('dotnet-client-customer-registered', 1)
  class MigrationsDotnetClientRenamedFromCustomerRegisteredV1 {
      constructor(readonly emailAddress: string) {}
  }

@eventTypeMigration(MigrationsDotnetClientRenamedFromCustomerRegistered, MigrationsDotnetClientRenamedFromCustomerRegisteredV1)
  class MigrationsDotnetClientRenamedFromCustomerRegisteredMigration implements IEventTypeMigration<MigrationsDotnetClientRenamedFromCustomerRegistered, MigrationsDotnetClientRenamedFromCustomerRegisteredV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsDotnetClientRenamedFromCustomerRegistered, MigrationsDotnetClientRenamedFromCustomerRegisteredV1>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .renamedFrom('email', 'emailAddress'));
      }

downcast(builder: IEventMigrationBuilder<MigrationsDotnetClientRenamedFromCustomerRegisteredV1, MigrationsDotnetClientRenamedFromCustomerRegistered>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .renamedFrom('emailAddress', 'email'));
      }
  }
  ```

### DefaultValue

[Section titled “DefaultValue”](#defaultvalue)

Provides a literal default for a property that did not exist in the source generation. Chronicle applies this value to any event stored before the property was introduced.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("dotnet-client-task-created", generation: 2)]
  public record MigrationsDotnetClientDefaultValueTaskCreated(string Title, string Status, int RetryCount, bool Enabled);

[EventTypeGenerationFor<MigrationsDotnetClientDefaultValueTaskCreated>(1)]
  public record MigrationsDotnetClientDefaultValueTaskCreatedV1(string Title);

public class MigrationsDotnetClientDefaultValueTaskCreatedMigration : EventTypeMigration<MigrationsDotnetClientDefaultValueTaskCreated, MigrationsDotnetClientDefaultValueTaskCreatedV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDotnetClientDefaultValueTaskCreated, MigrationsDotnetClientDefaultValueTaskCreatedV1> builder) =>
          builder.Properties(pb => pb
              .DefaultValue(t => t.Status, "active")
              .DefaultValue(t => t.RetryCount, 0)
              .DefaultValue(t => t.Enabled, true));

public override void Downcast(IEventMigrationBuilder<MigrationsDotnetClientDefaultValueTaskCreatedV1, MigrationsDotnetClientDefaultValueTaskCreated> builder)
      {
          // Status, RetryCount, and Enabled did not exist in generation 1 — nothing to map back
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "dotnet-client-task-created", generation = 2)
  data class MigrationsDotnetClientDefaultValueTaskCreated(
      val title: String,
      val status: String,
      val retryCount: Int,
      val enabled: Boolean
  )

@EventType(id = "dotnet-client-task-created", generation = 1)
  data class MigrationsDotnetClientDefaultValueTaskCreatedV1(val title: String)

class MigrationsDotnetClientDefaultValueTaskCreatedMigration :
      EventTypeMigration<MigrationsDotnetClientDefaultValueTaskCreated, MigrationsDotnetClientDefaultValueTaskCreatedV1>(
          MigrationsDotnetClientDefaultValueTaskCreated::class,
          MigrationsDotnetClientDefaultValueTaskCreatedV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientDefaultValueTaskCreated, MigrationsDotnetClientDefaultValueTaskCreatedV1>) {
          builder
              .defaultValue(MigrationsDotnetClientDefaultValueTaskCreated::status, "active")
              .defaultValue(MigrationsDotnetClientDefaultValueTaskCreated::retryCount, 0)
              .defaultValue(MigrationsDotnetClientDefaultValueTaskCreated::enabled, true)
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientDefaultValueTaskCreatedV1, MigrationsDotnetClientDefaultValueTaskCreated>) {
          // status, retryCount, and enabled did not exist in generation 1 - nothing to map back
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "dotnet-client-task-created", generation = 2)
  record MigrationsDotnetClientDefaultValueTaskCreated(
          String title,
          String status,
          int retryCount,
          boolean enabled) {
  }

@EventType(id = "dotnet-client-task-created", generation = 1)
  record MigrationsDotnetClientDefaultValueTaskCreatedV1(String title) {
  }

class MigrationsDotnetClientDefaultValueTaskCreatedMigration
          extends EventTypeMigration<MigrationsDotnetClientDefaultValueTaskCreated,
                                     MigrationsDotnetClientDefaultValueTaskCreatedV1> {
      MigrationsDotnetClientDefaultValueTaskCreatedMigration() {
          super(MigrationsDotnetClientDefaultValueTaskCreated.class,
                MigrationsDotnetClientDefaultValueTaskCreatedV1.class);
      }

@Override
      public void upcast(EventTypeMigrationBuilder<MigrationsDotnetClientDefaultValueTaskCreated,
                                                   MigrationsDotnetClientDefaultValueTaskCreatedV1> builder) {
          builder
              .defaultValue("status", "active")
              .defaultValue("retryCount", 0)
              .defaultValue("enabled", true);
      }

@Override
      public void downcast(EventTypeMigrationBuilder<MigrationsDotnetClientDefaultValueTaskCreatedV1,
                                                     MigrationsDotnetClientDefaultValueTaskCreated> builder) {
          // status, retryCount, and enabled did not exist in generation 1 - nothing to map back
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsDotnetClientDefaultValueTaskCreatedV1 do
    use Chronicle.Events.EventType, id: "dotnet-client-task-created", generation: 1

defstruct [:title]
  end

defmodule MyApp.Events.MigrationsDotnetClientDefaultValueTaskCreated do
    use Chronicle.Events.EventType, id: "dotnet-client-task-created", generation: 2

defstruct [:title, :status, :retry_count, :enabled]
  end

defmodule MyApp.Migrations.MigrationsDotnetClientDefaultValueTaskCreatedMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsDotnetClientDefaultValueTaskCreatedV1, generation: 1},
      to: {MyApp.Events.MigrationsDotnetClientDefaultValueTaskCreated, generation: 2}

alias Chronicle.Events.MigrationBuilder

@impl true
    def upcast(builder) do
      builder
      |> MigrationBuilder.default_value(:status, "active")
      |> MigrationBuilder.default_value(:retry_count, 0)
      |> MigrationBuilder.default_value(:enabled, true)
    end

@impl true
    def downcast(builder) do
      # status, retry_count, and enabled did not exist in generation 1 — nothing to map back
      builder
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventMigrationBuilder, IEventTypeMigration } from '@cratis/chronicle';

@eventType('dotnet-client-task-created', 2)
  class MigrationsDotnetClientDefaultValueTaskCreated {
      constructor(
          readonly title: string,
          readonly status: string,
          readonly retryCount: number,
          readonly enabled: boolean
      ) {}
  }

@eventType('dotnet-client-task-created', 1)
  class MigrationsDotnetClientDefaultValueTaskCreatedV1 {
      constructor(readonly title: string) {}
  }

@eventTypeMigration(MigrationsDotnetClientDefaultValueTaskCreated, MigrationsDotnetClientDefaultValueTaskCreatedV1)
  class MigrationsDotnetClientDefaultValueTaskCreatedMigration implements IEventTypeMigration<MigrationsDotnetClientDefaultValueTaskCreated, MigrationsDotnetClientDefaultValueTaskCreatedV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsDotnetClientDefaultValueTaskCreated, MigrationsDotnetClientDefaultValueTaskCreatedV1>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .defaultValue('status', 'active')
              .defaultValue('retryCount', 0)
              .defaultValue('enabled', true));
      }

downcast(builder: IEventMigrationBuilder<MigrationsDotnetClientDefaultValueTaskCreatedV1, MigrationsDotnetClientDefaultValueTaskCreated>): void {
          // status, retryCount, and enabled did not exist in generation 1 — nothing to map back
      }
  }
  ```

## MapValues

[Section titled “MapValues”](#mapvalues)

The four operations above move values between properties. `MapValues` changes the values themselves — it says which value in one generation is which value in the other, which is what you need when an enum is renumbered or a code set is replaced wholesale.

Unlike the property-builder operations, a value map is declared by overriding `MapValues` on the migration:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

public enum MigrationsDotnetClientPaymentStatusV1
  {
      Pending = 0,
      Settled = 1
  }

public enum MigrationsDotnetClientPaymentStatus
  {
      Awaiting = 10,
      Completed = 11
  }

[EventType("dotnet-client-payment-processed", generation: 2)]
  public record MigrationsDotnetClientPaymentProcessed(MigrationsDotnetClientPaymentStatus Status);

[EventTypeGenerationFor<MigrationsDotnetClientPaymentProcessed>(1)]
  public record MigrationsDotnetClientPaymentProcessedV1(MigrationsDotnetClientPaymentStatusV1 Status);

public class MigrationsDotnetClientPaymentProcessedMigration : EventTypeMigration<MigrationsDotnetClientPaymentProcessed, MigrationsDotnetClientPaymentProcessedV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDotnetClientPaymentProcessed, MigrationsDotnetClientPaymentProcessedV1> builder)
      {
          // Status is covered by the value map
      }

public override void Downcast(IEventMigrationBuilder<MigrationsDotnetClientPaymentProcessedV1, MigrationsDotnetClientPaymentProcessed> builder)
      {
          // Status is covered by the value map
      }

public override void MapValues(IEventValueMapBuilder<MigrationsDotnetClientPaymentProcessed, MigrationsDotnetClientPaymentProcessedV1> builder) =>
          builder.For(current => current.Status, previous => previous.Status, map => map
              .Map(MigrationsDotnetClientPaymentStatusV1.Pending, MigrationsDotnetClientPaymentStatus.Awaiting)
              .Map(MigrationsDotnetClientPaymentStatusV1.Settled, MigrationsDotnetClientPaymentStatus.Completed));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The map is applied forward when upcasting and inverted when downcasting, so you state it once. Values it does not mention are carried across unchanged, and two values collapsing onto one take the first pair declared for that value on the way back.

`MapValues` runs before `Upcast` and `Downcast`, so a direction that declares its own transformation for the same property keeps it. That is also the way to express a translation that is not symmetric — several values collapsing onto one, where the way back has to make a choice the forward map cannot state. Declare that as a `MapValues` on the property builder, per direction:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

public enum MigrationsDotnetClientDeclineReasonV1
  {
      InsufficientFunds = 0,
      CardExpired = 1,
      CardReported = 2
  }

public enum MigrationsDotnetClientDeclineReason
  {
      Funds = 0,
      Card = 1
  }

[EventType("dotnet-client-payment-declined", generation: 2)]
  public record MigrationsDotnetClientPaymentDeclined(MigrationsDotnetClientDeclineReason Reason);

[EventTypeGenerationFor<MigrationsDotnetClientPaymentDeclined>(1)]
  public record MigrationsDotnetClientPaymentDeclinedV1(MigrationsDotnetClientDeclineReasonV1 Reason);

public class MigrationsDotnetClientPaymentDeclinedMigration : EventTypeMigration<MigrationsDotnetClientPaymentDeclined, MigrationsDotnetClientPaymentDeclinedV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDotnetClientPaymentDeclined, MigrationsDotnetClientPaymentDeclinedV1> builder) =>
          builder.Properties(pb => pb
              .MapValues(current => current.Reason, previous => previous.Reason, map => map
                  .Map(MigrationsDotnetClientDeclineReasonV1.InsufficientFunds, MigrationsDotnetClientDeclineReason.Funds)
                  .Map(MigrationsDotnetClientDeclineReasonV1.CardExpired, MigrationsDotnetClientDeclineReason.Card)
                  .Map(MigrationsDotnetClientDeclineReasonV1.CardReported, MigrationsDotnetClientDeclineReason.Card)));

public override void Downcast(IEventMigrationBuilder<MigrationsDotnetClientPaymentDeclinedV1, MigrationsDotnetClientPaymentDeclined> builder) =>
          builder.Properties(pb => pb
              .MapValues(previous => previous.Reason, current => current.Reason, map => map
                  .Map(MigrationsDotnetClientDeclineReason.Funds, MigrationsDotnetClientDeclineReasonV1.InsufficientFunds)
                  .Map(MigrationsDotnetClientDeclineReason.Card, MigrationsDotnetClientDeclineReasonV1.CardExpired)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Client coverage

`MapValues` is currently C#-only.

## Multi-generation migrations

[Section titled “Multi-generation migrations”](#multi-generation-migrations)

If your event type spans more than two generations, define one migrator per generation pair. Chronicle chains them automatically.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("dotnet-client-multi-gen-person-registered", generation: 3)]
  public record MigrationsDotnetClientMultiGenPersonRegistered(string Email, string FirstName, string LastName);

[EventTypeGenerationFor<MigrationsDotnetClientMultiGenPersonRegistered>(2)]
  public record MigrationsDotnetClientMultiGenPersonRegisteredV2(string Email, string Name);

[EventTypeGenerationFor<MigrationsDotnetClientMultiGenPersonRegistered>(1)]
  public record MigrationsDotnetClientMultiGenPersonRegisteredV1(string EmailAddress, string Name);

// Generation 1 → 2: rename EmailAddress to Email
  public class MigrationsDotnetClientMultiGenPersonRegisteredV1ToV2 : EventTypeMigration<MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegisteredV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegisteredV1> builder) =>
          builder.Properties(pb => pb
              .RenamedFrom(t => t.Email, s => s.EmailAddress));

public override void Downcast(IEventMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV1, MigrationsDotnetClientMultiGenPersonRegisteredV2> builder) =>
          builder.Properties(pb => pb
              .RenamedFrom(t => t.EmailAddress, s => s.Email));
  }

// Generation 2 → 3: split Name into FirstName / LastName
  public class MigrationsDotnetClientMultiGenPersonRegisteredV2ToV3 : EventTypeMigration<MigrationsDotnetClientMultiGenPersonRegistered, MigrationsDotnetClientMultiGenPersonRegisteredV2>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegistered, MigrationsDotnetClientMultiGenPersonRegisteredV2> builder) =>
          builder.Properties(pb => pb
              .Split(t => t.FirstName, s => s.Name, PropertySeparator.Space, SplitPartIndex.First)
              .Split(t => t.LastName, s => s.Name, PropertySeparator.Space, SplitPartIndex.Second));

public override void Downcast(IEventMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegistered> builder) =>
          builder.Properties(pb => pb
              .Combine(t => t.Name, PropertySeparator.Space, s => s.FirstName, s => s.LastName));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "dotnet-client-multi-gen-person-registered", generation = 3)
  data class MigrationsDotnetClientMultiGenPersonRegistered(val email: String, val firstName: String, val lastName: String)

@EventType(id = "dotnet-client-multi-gen-person-registered", generation = 2)
  data class MigrationsDotnetClientMultiGenPersonRegisteredV2(val email: String, val name: String)

@EventType(id = "dotnet-client-multi-gen-person-registered", generation = 1)
  data class MigrationsDotnetClientMultiGenPersonRegisteredV1(val emailAddress: String, val name: String)

// Generation 1 -> 2: rename emailAddress to email
  class MigrationsDotnetClientMultiGenPersonRegisteredV1ToV2 :
      EventTypeMigration<MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegisteredV1>(
          MigrationsDotnetClientMultiGenPersonRegisteredV2::class,
          MigrationsDotnetClientMultiGenPersonRegisteredV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegisteredV1>) {
          builder.renamedFrom(MigrationsDotnetClientMultiGenPersonRegisteredV2::email, MigrationsDotnetClientMultiGenPersonRegisteredV1::emailAddress)
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV1, MigrationsDotnetClientMultiGenPersonRegisteredV2>) {
          builder.renamedFrom(MigrationsDotnetClientMultiGenPersonRegisteredV1::emailAddress, MigrationsDotnetClientMultiGenPersonRegisteredV2::email)
      }
  }

// Generation 2 -> 3: split name into firstName / lastName
  class MigrationsDotnetClientMultiGenPersonRegisteredV2ToV3 :
      EventTypeMigration<MigrationsDotnetClientMultiGenPersonRegistered, MigrationsDotnetClientMultiGenPersonRegisteredV2>(
          MigrationsDotnetClientMultiGenPersonRegistered::class,
          MigrationsDotnetClientMultiGenPersonRegisteredV2::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegistered, MigrationsDotnetClientMultiGenPersonRegisteredV2>) {
          builder
              .split(MigrationsDotnetClientMultiGenPersonRegistered::firstName, MigrationsDotnetClientMultiGenPersonRegisteredV2::name, " ", 0)
              .split(MigrationsDotnetClientMultiGenPersonRegistered::lastName, MigrationsDotnetClientMultiGenPersonRegisteredV2::name, " ", 1)
      }

override fun downcast(builder: EventTypeMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegistered>) {
          builder.combine(
              MigrationsDotnetClientMultiGenPersonRegisteredV2::name,
              " ",
              MigrationsDotnetClientMultiGenPersonRegistered::firstName,
              MigrationsDotnetClientMultiGenPersonRegistered::lastName
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "dotnet-client-multi-gen-person-registered", generation = 3)
  record MigrationsDotnetClientMultiGenPersonRegistered(String email, String firstName, String lastName) {
  }

@EventType(id = "dotnet-client-multi-gen-person-registered", generation = 2)
  record MigrationsDotnetClientMultiGenPersonRegisteredV2(String email, String name) {
  }

@EventType(id = "dotnet-client-multi-gen-person-registered", generation = 1)
  record MigrationsDotnetClientMultiGenPersonRegisteredV1(String emailAddress, String name) {
  }

// Generation 1 -> 2: rename emailAddress to email
  class MigrationsDotnetClientMultiGenPersonRegisteredV1ToV2
          extends EventTypeMigration<MigrationsDotnetClientMultiGenPersonRegisteredV2,
                                     MigrationsDotnetClientMultiGenPersonRegisteredV1> {
      MigrationsDotnetClientMultiGenPersonRegisteredV1ToV2() {
          super(MigrationsDotnetClientMultiGenPersonRegisteredV2.class,
                MigrationsDotnetClientMultiGenPersonRegisteredV1.class);
      }

@Override
      public void upcast(EventTypeMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV2,
                                                   MigrationsDotnetClientMultiGenPersonRegisteredV1> builder) {
          builder.renamedFrom("email", "emailAddress");
      }

@Override
      public void downcast(EventTypeMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV1,
                                                     MigrationsDotnetClientMultiGenPersonRegisteredV2> builder) {
          builder.renamedFrom("emailAddress", "email");
      }
  }

// Generation 2 -> 3: split name into firstName / lastName
  class MigrationsDotnetClientMultiGenPersonRegisteredV2ToV3
          extends EventTypeMigration<MigrationsDotnetClientMultiGenPersonRegistered,
                                     MigrationsDotnetClientMultiGenPersonRegisteredV2> {
      MigrationsDotnetClientMultiGenPersonRegisteredV2ToV3() {
          super(MigrationsDotnetClientMultiGenPersonRegistered.class,
                MigrationsDotnetClientMultiGenPersonRegisteredV2.class);
      }

@Override
      public void upcast(EventTypeMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegistered,
                                                   MigrationsDotnetClientMultiGenPersonRegisteredV2> builder) {
          builder
              .split("firstName", "name", " ", 0)
              .split("lastName", "name", " ", 1);
      }

@Override
      public void downcast(EventTypeMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV2,
                                                     MigrationsDotnetClientMultiGenPersonRegistered> builder) {
          builder.combine("name", " ", "firstName", "lastName");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsDotnetClientMultiGenPersonRegisteredV1 do
    use Chronicle.Events.EventType, id: "dotnet-client-multi-gen-person-registered", generation: 1

defstruct [:email_address, :name]
  end

defmodule MyApp.Events.MigrationsDotnetClientMultiGenPersonRegisteredV2 do
    use Chronicle.Events.EventType, id: "dotnet-client-multi-gen-person-registered", generation: 2

defstruct [:email, :name]
  end

defmodule MyApp.Events.MigrationsDotnetClientMultiGenPersonRegistered do
    use Chronicle.Events.EventType, id: "dotnet-client-multi-gen-person-registered", generation: 3

defstruct [:email, :first_name, :last_name]
  end

# Generation 1 -> 2: rename email_address to email
  defmodule MyApp.Migrations.MigrationsDotnetClientMultiGenPersonRegisteredV1ToV2 do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsDotnetClientMultiGenPersonRegisteredV1, generation: 1},
      to: {MyApp.Events.MigrationsDotnetClientMultiGenPersonRegisteredV2, generation: 2}

alias Chronicle.Events.MigrationBuilder

@impl true
    def upcast(builder), do: MigrationBuilder.renamed_from(builder, :email, :email_address)

@impl true
    def downcast(builder), do: MigrationBuilder.renamed_from(builder, :email_address, :email)
  end

# Generation 2 -> 3: split name into first_name / last_name
  defmodule MyApp.Migrations.MigrationsDotnetClientMultiGenPersonRegisteredV2ToV3 do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsDotnetClientMultiGenPersonRegisteredV2, generation: 2},
      to: {MyApp.Events.MigrationsDotnetClientMultiGenPersonRegistered, generation: 3}

alias Chronicle.Events.MigrationBuilder

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

@impl true
    def downcast(builder) do
      MigrationBuilder.combine_properties(builder, [:first_name, :last_name], :name, " ")
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventMigrationBuilder, IEventTypeMigration } from '@cratis/chronicle';

@eventType('dotnet-client-multi-gen-person-registered', 3)
  class MigrationsDotnetClientMultiGenPersonRegistered {
      constructor(readonly email: string, readonly firstName: string, readonly lastName: string) {}
  }

@eventType('dotnet-client-multi-gen-person-registered', 2)
  class MigrationsDotnetClientMultiGenPersonRegisteredV2 {
      constructor(readonly email: string, readonly name: string) {}
  }

@eventType('dotnet-client-multi-gen-person-registered', 1)
  class MigrationsDotnetClientMultiGenPersonRegisteredV1 {
      constructor(readonly emailAddress: string, readonly name: string) {}
  }

// Generation 1 → 2: rename emailAddress to email
  @eventTypeMigration(MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegisteredV1)
  class MigrationsDotnetClientMultiGenPersonRegisteredV1ToV2 implements IEventTypeMigration<MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegisteredV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegisteredV1>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .renamedFrom('email', 'emailAddress'));
      }

downcast(builder: IEventMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV1, MigrationsDotnetClientMultiGenPersonRegisteredV2>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .renamedFrom('emailAddress', 'email'));
      }
  }

// Generation 2 → 3: split name into firstName / lastName
  @eventTypeMigration(MigrationsDotnetClientMultiGenPersonRegistered, MigrationsDotnetClientMultiGenPersonRegisteredV2)
  class MigrationsDotnetClientMultiGenPersonRegisteredV2ToV3 implements IEventTypeMigration<MigrationsDotnetClientMultiGenPersonRegistered, MigrationsDotnetClientMultiGenPersonRegisteredV2> {
      upcast(builder: IEventMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegistered, MigrationsDotnetClientMultiGenPersonRegisteredV2>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .split('firstName', 'name', ' ', 0)
              .split('lastName', 'name', ' ', 1));
      }

downcast(builder: IEventMigrationBuilder<MigrationsDotnetClientMultiGenPersonRegisteredV2, MigrationsDotnetClientMultiGenPersonRegistered>): void {
          builder.properties(propertyBuilder => propertyBuilder
              .combine('name', ' ', 'firstName', 'lastName'));
      }
  }
  ```

When a generation 1 event arrives, the Kernel chains the upcasts: 1→2, then 2→3, and stores all three generations.

## How registration works

[Section titled “How registration works”](#how-registration-works)

When your application connects to Chronicle, the client:

1. Discovers all `EventTypeMigration<TUpgrade, TPrevious>` implementations via `IClientArtifactsProvider`
2. Invokes `Upcast` and `Downcast` on each migrator to capture the transformation declarations
3. Converts the declarations into JmesPath expressions
4. Sends the complete `EventTypeDefinition` — including all generations and their migration definitions — to the Kernel during event type registration

From that point on, the Kernel applies the migrations autonomously on every event append, without any further involvement from the client.

## Validation: missing migrators

[Section titled “Validation: missing migrators”](#validation-missing-migrators)

If an event type is declared with a generation higher than 1 but has no migrators covering all generations up to the current one, Chronicle throws `MissingEventTypeMigrators` during startup. This prevents silent data loss from an incomplete migration chain.

```text
Cratis.Chronicle.Events.Migrations.MissingEventTypeMigrators:
  Event type 'AuthorRegistered' is at generation 3 but no migrators are registered for it.
```

Ensure every generation gap has a corresponding `EventTypeMigration<TUpgrade, TPrevious>` subclass before deploying an event type with a new generation.

# Generation validation

Chronicle enforces rules about how event type generations and their migration chains must be structured. These rules exist to keep your event history consistent and to prevent silent data loss caused by incomplete migration definitions.

Client coverage

These validation rules are enforced by the kernel regardless of client. Elixir has a real `MigrationBuilder.default_value/3` for the “default values for new properties” example below, and Kotlin/Java have the equivalent `EventTypeMigrationBuilder.defaultValue` (see [Event Type Migrations](/chronicle/concepts/event-type-migrations/)). The `EnableEventTypeGenerationValidation` toggle further down is a .NET-hosting-specific configuration option with no equivalent found in the other clients.

## The rules

[Section titled “The rules”](#the-rules)

When you register an event type at generation 2 or higher, Chronicle validates that:

1. **A generation 1 must exist** — every event type begins at generation 1. There is no such thing as an event that starts at generation 2.
2. **Generations must be sequential with no gaps** — if a type is at generation 3, you must have migrators for 1→2 and 2→3. Jumping directly from 1 to 3 is not allowed.
3. **Every step in the chain must have a migrator** — a migrator must be present for every consecutive generation pair from 1 up to the current generation.

A migration chain that satisfies these rules is called a **valid chain**.

### Valid chain (generation 3)

[Section titled “Valid chain (generation 3)”](#valid-chain-generation-3)

```text
Gen 1  ──(1→2 migrator)──▶  Gen 2  ──(2→3 migrator)──▶  Gen 3
```

### Invalid chain — missing start

[Section titled “Invalid chain — missing start”](#invalid-chain--missing-start)

```text
Gen 2  ──(2→3 migrator)──▶  Gen 3        ✗  no 1→2 migrator
```

This throws `MissingFirstGenerationForEventType`.

### Invalid chain — gap

[Section titled “Invalid chain — gap”](#invalid-chain--gap)

```text
Gen 1                         Gen 3        ✗  no 1→2 or 2→3 migrators
```

This throws `MissingMigrationForEventTypeGeneration`.

### Invalid chain — no migrators at all

[Section titled “Invalid chain — no migrators at all”](#invalid-chain--no-migrators-at-all)

```text
[EventType(generation: 3)]   ✗  no migrators defined
```

This throws `MissingEventTypeMigrators`.

## Default values for new properties

[Section titled “Default values for new properties”](#default-values-for-new-properties)

When a new generation adds a property that did not exist in older events, declare a default value for it in the upcast. Chronicle applies this default to any event stored before the property was introduced.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Events.Migrations;

[EventType("validation-author-registered", generation: 2)]
  public record MigrationsValidationAuthorRegistered(string Name, string Status);

[EventTypeGenerationFor<MigrationsValidationAuthorRegistered>(1)]
  public record MigrationsValidationAuthorRegisteredV1(string Name);

public class MigrationsValidationAuthorRegisteredMigration : EventTypeMigration<MigrationsValidationAuthorRegistered, MigrationsValidationAuthorRegisteredV1>
  {
      public override void Upcast(IEventMigrationBuilder<MigrationsValidationAuthorRegistered, MigrationsValidationAuthorRegisteredV1> builder) =>
          builder.Properties(pb => pb
              .DefaultValue(t => t.Status, "active")); // Name is unchanged between generations — no operation needed for it

public override void Downcast(IEventMigrationBuilder<MigrationsValidationAuthorRegisteredV1, MigrationsValidationAuthorRegistered> builder)
      {
          // Status does not exist in gen 1 — no mapping needed
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.events.migrations.EventTypeMigration
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder

@EventType(id = "migrations-validation-order-placed", generation = 1)
  data class MigrationsValidationOrderPlacedV1(val orderId: String)

@EventType(id = "migrations-validation-order-placed", generation = 2)
  data class MigrationsValidationOrderPlacedV2(val orderId: String, val currency: String)

class MigrationsValidationOrderPlacedMigration :
      EventTypeMigration<MigrationsValidationOrderPlacedV2, MigrationsValidationOrderPlacedV1>(
          MigrationsValidationOrderPlacedV2::class,
          MigrationsValidationOrderPlacedV1::class
      ) {
      override fun upcast(builder: EventTypeMigrationBuilder<MigrationsValidationOrderPlacedV2, MigrationsValidationOrderPlacedV1>) {
          builder.defaultValue(MigrationsValidationOrderPlacedV2::currency, "USD")
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.events.migrations.EventTypeMigration;
  import io.cratis.chronicle.events.migrations.EventTypeMigrationBuilder;

@EventType(id = "migrations-validation-order-placed", generation = 1)
  record MigrationsValidationOrderPlacedV1(String orderId) {
  }

@EventType(id = "migrations-validation-order-placed", generation = 2)
  record MigrationsValidationOrderPlacedV2(String orderId, String currency) {
  }

class MigrationsValidationOrderPlacedMigration
          extends EventTypeMigration<MigrationsValidationOrderPlacedV2, MigrationsValidationOrderPlacedV1> {
      MigrationsValidationOrderPlacedMigration() {
          super(MigrationsValidationOrderPlacedV2.class, MigrationsValidationOrderPlacedV1.class);
      }

@Override
      public void upcast(
              EventTypeMigrationBuilder<MigrationsValidationOrderPlacedV2, MigrationsValidationOrderPlacedV1> builder) {
          builder.defaultValue("currency", "USD");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.MigrationsValidationAuthorRegisteredV1 do
    use Chronicle.Events.EventType, id: "validation-author-registered", generation: 1

defstruct [:name]
  end

defmodule MyApp.Events.MigrationsValidationAuthorRegistered do
    use Chronicle.Events.EventType, id: "validation-author-registered", generation: 2

defstruct [:name, :status]
  end

defmodule MyApp.Migrations.MigrationsValidationAuthorRegisteredMigration do
    use Chronicle.Events.Migration,
      from: {MyApp.Events.MigrationsValidationAuthorRegisteredV1, generation: 1},
      to: {MyApp.Events.MigrationsValidationAuthorRegistered, generation: 2}

alias Chronicle.Events.MigrationBuilder

@impl true
    def upcast(builder) do
      # name is unchanged between generations — no operation needed for it
      builder
      |> MigrationBuilder.default_value(:status, "active")
    end

@impl true
    def downcast(builder) do
      # status does not exist in gen 1 — no mapping needed
      builder
    end
  end
  ```

* TypeScript

```typescript
  import { eventType, eventTypeMigration, IEventMigrationBuilder, IEventTypeMigration } from '@cratis/chronicle';

@eventType('validation-author-registered', 2)
  class MigrationsValidationAuthorRegistered {
      constructor(readonly name: string, readonly status: string) {}
  }

@eventType('validation-author-registered', 1)
  class MigrationsValidationAuthorRegisteredV1 {
      constructor(readonly name: string) {}
  }

@eventTypeMigration(MigrationsValidationAuthorRegistered, MigrationsValidationAuthorRegisteredV1)
  class MigrationsValidationAuthorRegisteredMigration implements IEventTypeMigration<MigrationsValidationAuthorRegistered, MigrationsValidationAuthorRegisteredV1> {
      upcast(builder: IEventMigrationBuilder<MigrationsValidationAuthorRegistered, MigrationsValidationAuthorRegisteredV1>): void {
          // name is unchanged between generations — no operation needed for it
          builder.properties(propertyBuilder => propertyBuilder
              .defaultValue('status', 'active'));
      }

downcast(builder: IEventMigrationBuilder<MigrationsValidationAuthorRegisteredV1, MigrationsValidationAuthorRegistered>): void {
          // status does not exist in generation 1 — no mapping needed
      }
  }
  ```

`DefaultValue` tells Chronicle: “if this property is absent from the event when upcasting, fill it with this value.” Properties that already carry a value are left unchanged.

## Schema immutability

[Section titled “Schema immutability”](#schema-immutability)

Once a generation’s schema is registered with the Kernel, it cannot be changed. If you modify an event record without bumping its generation, Chronicle detects that the schema no longer matches what was originally stored and throws:

```text
Cratis.Chronicle.Services.Events.EventTypeSchemaChanged:
  Event type 'AuthorRegistered' at generation 2 has a schema that differs from the already registered schema.
  Schema changes are not allowed without creating a new generation.
```

The fix is always to introduce a new generation and a corresponding migrator rather than silently mutating an existing one.

### What an enum may still do

[Section titled “What an enum may still do”](#what-an-enum-may-still-do)

Immutability is about what an already stored event *means*, so two kinds of change to an enum are accepted in place and update the registered schema rather than being rejected:

* **Gaining a member.** Nothing already stored carries the new value, so nothing already stored changes meaning.
* **Renaming a member.** An event’s payload carries the underlying number, not the name; the name is resolved through the schema when the value is read. An enum mirroring an external system is renamed on that system’s schedule, and Chronicle does not make you cut a generation for a spelling you do not control.

Two changes remain breaking, because both leave already stored values denoting something other than what they denoted when they were written:

* **Removing a member** — stored events carrying that value now denote nothing.
* **Renumbering a member** — the names survive but move onto different numbers, so every stored event silently reads as a different member.

For those two, cut a new generation and declare a [value map](/chronicle/concepts/event-type-migrations/#value-map) in the migration saying what the old values became. Chronicle applies it forward when upcasting and inverted when downcasting.

Everything outside enums — a property added, removed, retyped, or renamed — is unchanged: still a schema change, still needing a new generation.

## Relaxing validation for development

[Section titled “Relaxing validation for development”](#relaxing-validation-for-development)

Strict validation is **always enforced in the production image** of the Kernel. The development image relaxes this by honouring the `EnableEventTypeGenerationValidation` flag sent from the client.

`EnableEventTypeGenerationValidation` defaults to `false` in `ChronicleOptions`, so no extra configuration is needed during early development. When your event schemas are stable, opt into strict validation by setting it to `true`:

* C#

```csharp
  using Microsoft.Extensions.Hosting;

public static class MigrationsValidationEnableValidationRegistration
  {
      public static void Configure(string[] args)
      {
          var builder = Host.CreateApplicationBuilder(args);

builder.AddCratisChronicle(configureOptions: options =>
          {
              options.EnableEventTypeGenerationValidation = true;
          });
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Alternatively, set it in `appsettings.json` under the `Cratis:Chronicle` section:

```json
{
  "Cratis": {
    "Chronicle": {
      "EnableEventTypeGenerationValidation": true
    }
  }
}
```

This value is forwarded to the Kernel as part of the event-type registration request. The Kernel only honours it when running the **development image** — the production image always validates unconditionally regardless of what the client sends. This makes it impossible to accidentally disable validation in a production deployment.

## Client-side checks, before anything reaches the Kernel

[Section titled “Client-side checks, before anything reaches the Kernel”](#client-side-checks-before-anything-reaches-the-kernel)

The rules above are all enforced by the Kernel during registration. Two further checks run entirely in your own process, the moment a migrator is constructed or discovered — before a registration request is ever sent:

* **`MigrationGenerationsMustShareEventTypeId`** — thrown from `EventTypeMigration<TUpgrade, TPrevious>`’s constructor if `TUpgrade` and `TPrevious` resolve to different event type ids. This is what catches the classic mistake with the old, explicit-id style: an id omitted on the previous generation (silently defaulting to the CLR type name) or a typo that makes the two ids differ. Marking the previous generation with [`[EventTypeGenerationFor<T>]`](/chronicle/concepts/event-type-migrations/) instead removes the mistake structurally, since there is no independent id to mistype in the first place.
* **`MultipleMigratorsForSameEventTypeGeneration`** — thrown when discovering migrators if two different migrator classes both claim to bridge the same generation pair for one event type. Exactly one migrator may own a given transition.

The [code analysis](/chronicle/code-analysis/) rules [CHR0037](/chronicle/code-analysis/chr0037/) and [CHR0049](/chronicle/code-analysis/chr0049/) catch the same class of mistake at compile time, before you even run the application.

## What happens when validation fires

[Section titled “What happens when validation fires”](#what-happens-when-validation-fires)

Validation runs on the Kernel during `Register()`, which is called when the client connects to Chronicle. If validation fails the server throws an exception that the client receives as an `RpcException`. This is intentional — failing fast at startup is far better than discovering a broken migration chain at runtime.

| Exception                                | Condition                                                                                 |
| ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| `MissingEventTypeMigrators`              | Event type is at gen ≥ 2 but no migrators are defined                                     |
| `MissingFirstGenerationForEventType`     | No migrator covering the path from generation 1 exists                                    |
| `MissingMigrationForEventTypeGeneration` | A specific step in the chain (N → N+1) is missing                                         |
| `InvalidMigrationPropertyForEventType`   | A migration references a property that does not exist in the expected generation’s schema |
| `EventTypeSchemaChanged`                 | An existing generation’s schema has changed; create a new generation instead              |

# Namespaces

Namespaces provide logical segregation within a single event store. They allow Chronicle to keep events, projections, reducers, and read models isolated per namespace while still sharing the same physical infrastructure.

Use namespaces to:

* Separate tenant data in multi-tenant systems
* Partition environments like development, staging, and production
* Split business domains that share an event store

Namespaces are resolved for every operation. If no namespace is explicitly provided, the default namespace is used.

## Namespaces and tenancy

[Section titled “Namespaces and tenancy”](#namespaces-and-tenancy)

Namespaces are a practical way to implement tenant isolation. Each tenant can map to a namespace, ensuring that all event store operations remain scoped to that tenant. This keeps data separated without requiring separate event stores per tenant.

If you use Cratis Arc with the Chronicle extension, tenancy is automatically configured for namespaces. See Arc Tenancy for details.

## Topics

[Section titled “Topics”](#topics)

* [DotNET client usage](/chronicle/namespaces/dotnet-client/)
* [ASP.NET Core namespace resolution](/chronicle/namespaces/aspnetcore/)

# ASP.NET Core namespace resolution

The ASP.NET Core client provides namespace resolution designed for multi-tenant web applications. It integrates with HTTP context and offers built-in resolvers for common request patterns.

If your multi-tenant setup is based on Arc Tenancy, you can map the current tenant to a namespace. See Arc Tenancy.

## Built-in resolvers

[Section titled “Built-in resolvers”](#built-in-resolvers)

### HTTP header resolution (default)

[Section titled “HTTP header resolution (default)”](#http-header-resolution-default)

The default resolver reads the namespace from an HTTP header. Configure it through `ChronicleAspNetCoreOptions`:

* C#

```csharp
  using Microsoft.AspNetCore.Builder;

public static class NamespacesAspNetCoreHttpHeaderResolver
  {
      public static void Configure(WebApplicationBuilder builder) =>
          builder.AddCratisChronicle(options =>
          {
              options.EventStore = "my-event-store";
              options.WithHttpHeaderNamespaceResolver("x-cratis-tenant-id"); // Default header name
          });
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStoreNamespaceName
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver

/**
   * Takes the namespace from a header on the current HTTP request, falling back to the default
   * namespace for work happening outside a request. The Spring Boot integration ships this exact
   * strategy as io.cratis.chronicle.spring.namespaces.HttpHeaderNamespaceResolver, applied
   * automatically via cratis.chronicle.namespace-resolution.strategy=HTTP_HEADER - this version takes
   * the header lookup as a parameter so it has no framework dependency.
   */
  class HttpHeaderNamespaceResolver(
      private val headerName: String,
      private val currentHeaderValue: (String) -> String?
  ) : IEventStoreNamespaceResolver {
      override fun resolve(): String =
          currentHeaderValue(headerName)?.takeIf { it.isNotBlank() } ?: EventStoreNamespaceName.default.value
  }
  ```

* Java

```java
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver;

import java.util.function.Function;

// Takes the namespace from a header on the current HTTP request, falling back to the default
  // namespace for work happening outside a request. The Spring Boot integration ships this exact
  // strategy as io.cratis.chronicle.spring.namespaces.HttpHeaderNamespaceResolver, applied
  // automatically via cratis.chronicle.namespace-resolution.strategy=HTTP_HEADER - this version
  // takes the header lookup as a parameter so it has no framework dependency.
  class HttpHeaderNamespaceResolver implements IEventStoreNamespaceResolver {
      private final String headerName;
      private final Function<String, String> currentHeaderValue;

public HttpHeaderNamespaceResolver(String headerName, Function<String, String> currentHeaderValue) {
          this.headerName = headerName;
          this.currentHeaderValue = currentHeaderValue;
      }

@Override
      public String resolve() {
          String value = currentHeaderValue.apply(headerName);
          return value == null || value.isBlank() ? "Default" : value;
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

When the header is present, its value becomes the namespace for the request. If the header is missing, the default namespace is used.

### Subdomain resolution

[Section titled “Subdomain resolution”](#subdomain-resolution)

The subdomain resolver extracts the namespace from the request host (for example, `tenant1.example.com`).

* C#

```csharp
  using Microsoft.AspNetCore.Builder;

public static class NamespacesAspNetCoreSubdomainResolver
  {
      public static void Configure(WebApplicationBuilder builder) =>
          builder.AddCratisChronicle(options =>
          {
              options.EventStore = "my-event-store";
              options.WithSubdomainNamespaceResolver();
          });
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStoreNamespaceName
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver

/**
   * Takes the namespace from the subdomain of the current request's host - "acme" in
   * acme.example.com - falling back to the default namespace for a host with no subdomain, or for
   * work happening outside a request. The Spring Boot integration ships this exact strategy as
   * io.cratis.chronicle.spring.namespaces.SubdomainNamespaceResolver; this version takes the current
   * host as a parameter so it has no framework dependency.
   */
  class SubdomainNamespaceResolver(private val currentHost: () -> String?) : IEventStoreNamespaceResolver {
      override fun resolve(): String {
          val parts = currentHost()?.split('.') ?: return EventStoreNamespaceName.default.value
          return if (parts.size > 2) parts.first() else EventStoreNamespaceName.default.value
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver;

import java.util.function.Supplier;

// Takes the namespace from the subdomain of the current request's host - "acme" in
  // acme.example.com - falling back to the default namespace for a host with no subdomain, or for
  // work happening outside a request. The Spring Boot integration ships this exact strategy as
  // io.cratis.chronicle.spring.namespaces.SubdomainNamespaceResolver; this version takes the
  // current host as a parameter so it has no framework dependency.
  class SubdomainNamespaceResolver implements IEventStoreNamespaceResolver {
      private final Supplier<String> currentHost;

public SubdomainNamespaceResolver(Supplier<String> currentHost) {
          this.currentHost = currentHost;
      }

@Override
      public String resolve() {
          String host = currentHost.get();
          if (host == null) {
              return "Default";
          }
          String[] parts = host.split("\\.");
          return parts.length > 2 ? parts[0] : "Default";
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Custom resolvers

[Section titled “Custom resolvers”](#custom-resolvers)

You can configure a custom resolver either by type (DI) or using the `IChronicleBuilder` fluent API.

### Using the builder (recommended)

[Section titled “Using the builder (recommended)”](#using-the-builder-recommended)

Pass a resolver instance using the `IChronicleBuilder` configure callback:

* C#

```csharp
  using Microsoft.AspNetCore.Builder;
  using Microsoft.Extensions.Configuration;

public static class NamespacesAspNetCoreBuilderCustomResolver
  {
      public static void Configure(WebApplicationBuilder builder, IConfiguration someConfiguration) =>
          builder.AddCratisChronicle(
              configureOptions: options => options.EventStore = "my-event-store",
              configure: b => b.WithNamespaceResolver(new CustomNamespaceResolver(someConfiguration)));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStoreNamespaceName
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver

/**
   * Kotlin has no separate builder step to register a namespace resolver structurally - a resolver
   * is just an IEventStoreNamespaceResolver implementation, constructed with whatever configuration
   * it needs and handed to callers directly instead of wired up through a hosting builder.
   */
  class ConfiguredNamespaceResolver(private val configuredNamespace: String?) : IEventStoreNamespaceResolver {
      override fun resolve(): String = configuredNamespace ?: EventStoreNamespaceName.default.value
  }

fun createConfiguredResolver(tenantNamespace: String?): IEventStoreNamespaceResolver =
      ConfiguredNamespaceResolver(tenantNamespace)
  ```

* Java

```java
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver;

// Java has no separate builder step to register a namespace resolver structurally - a resolver
  // is just an IEventStoreNamespaceResolver implementation, constructed with whatever configuration
  // it needs and handed to callers directly instead of wired up through a hosting builder.
  class ConfiguredNamespaceResolver implements IEventStoreNamespaceResolver {
      private final String configuredNamespace;

public ConfiguredNamespaceResolver(String configuredNamespace) {
          this.configuredNamespace = configuredNamespace;
      }

@Override
      public String resolve() {
          return configuredNamespace == null ? "Default" : configuredNamespace;
      }

public static IEventStoreNamespaceResolver createConfiguredResolver(String tenantNamespace) {
          return new ConfiguredNamespaceResolver(tenantNamespace);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### Using type-based DI resolution

[Section titled “Using type-based DI resolution”](#using-type-based-di-resolution)

Configure the resolver type through `ChronicleAspNetCoreOptions` to let the DI container resolve it:

* C#

```csharp
  using Cratis.Chronicle.AspNetCore;
  using Microsoft.AspNetCore.Builder;
  using Microsoft.Extensions.DependencyInjection;

public static class NamespacesAspNetCoreTypeBasedCustomResolver
  {
      public static void Configure(WebApplicationBuilder builder) =>
          builder.Services.Configure<ChronicleAspNetCoreOptions>(options =>
          {
              options.EventStore = "my-event-store";
              options.EventStoreNamespaceResolverType = typeof(CustomNamespaceResolver);
          });
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStoreNamespaceName
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver

// The Spring Boot integration steps aside for a resolver the application declares as its own bean
  // (@Component, @Service, or an @Bean method) - annotating this class is enough for it to be
  // discovered and used automatically, with no explicit wiring. This is the closest Kotlin gets to
  // setting EventStoreNamespaceResolverType and letting dependency injection resolve the type.
  class TenantComponentNamespaceResolver(private val tenantContext: ITenantContext) : IEventStoreNamespaceResolver {
      override fun resolve(): String = tenantContext.currentTenantId.ifBlank { EventStoreNamespaceName.default.value }
  }
  ```

* Java

```java
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver;

// The Spring Boot integration steps aside for a resolver the application declares as its own bean
  // (@Component, @Service, or an @Bean method) - annotating this class is enough for it to be
  // discovered and used automatically, with no explicit wiring. This is the closest Java gets to
  // setting EventStoreNamespaceResolverType and letting dependency injection resolve the type.
  class TenantComponentNamespaceResolver implements IEventStoreNamespaceResolver {
      private final ITenantContext tenantContext;

public TenantComponentNamespaceResolver(ITenantContext tenantContext) {
          this.tenantContext = tenantContext;
      }

@Override
      public String resolve() {
          String tenantId = tenantContext.getCurrentTenantId();
          return tenantId == null || tenantId.isBlank() ? "Default" : tenantId;
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Configuration priority

[Section titled “Configuration priority”](#configuration-priority)

1. Resolver set via `IChronicleBuilder.WithNamespaceResolver()` or `IChronicleBuilder.NamespaceResolver`
2. Type configuration (`EventStoreNamespaceResolverType`) when provided
3. Default HTTP header resolver

## Example: Web app setup

[Section titled “Example: Web app setup”](#example-web-app-setup)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Microsoft.AspNetCore.Builder;

[EventType]
  public record NamespacesAspNetCoreItemAddedToCart(string ProductId, int Quantity);

public static class NamespacesAspNetCoreWebAppExample
  {
      public static void ConfigureApp(string[] args)
      {
          var builder = WebApplication.CreateBuilder(args);

builder.AddCratisChronicle(options =>
          {
              options.EventStore = "production-store";
              options.WithHttpHeaderNamespaceResolver("x-tenant-id");
          });

var app = builder.Build();
          app.MapPost("/api/cart/{cartId}/items", async (string cartId, IEventLog eventLog) =>
          {
              var itemAdded = new NamespacesAspNetCoreItemAddedToCart(ProductId: "product-123", Quantity: 1);
              await eventLog.Append(cartId, itemAdded);
              return Microsoft.AspNetCore.Http.Results.Ok();
          });
          app.Run();
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver

@EventType
  data class NamespacesItemAddedToCart(val productId: String = "", val quantity: Int = 0)

/**
   * Kotlin has no built-in web application builder - the same shape applies no matter which web
   * framework sits in front of it: resolve the namespace for the current request, ask the client for
   * that event store, and append. This handler works whichever way the resolver above actually reads
   * the request (a Spring Boot filter, Ktor, or a plain servlet).
   */
  class Cart(private val client: ChronicleClient, private val namespaceResolver: IEventStoreNamespaceResolver) {
      suspend fun addItem(cartId: String, productId: String, quantity: Int) {
          val eventStore = client.getEventStore("production-store", namespaceResolver.resolve())
          eventStore.eventLog.append(cartId, NamespacesItemAddedToCart(productId, quantity))
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.BlockingChronicleClient;
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver;

@EventType
  record NamespacesItemAddedToCart(String productId, int quantity) {}

// Java has no built-in web application builder - the same shape applies no matter which web
  // framework sits in front of it: resolve the namespace for the current request, ask the client
  // for that event store, and append. This handler works whichever way the resolver above actually
  // reads the request (a Spring Boot filter, or a plain servlet).
  class Cart {
      private final BlockingChronicleClient client;
      private final IEventStoreNamespaceResolver namespaceResolver;

public Cart(BlockingChronicleClient client, IEventStoreNamespaceResolver namespaceResolver) {
          this.client = client;
          this.namespaceResolver = namespaceResolver;
      }

public void addItem(String cartId, String productId, int quantity) {
          client.getEventStore("production-store", namespaceResolver.resolve())
              .getEventLog()
              .append(cartId, new NamespacesItemAddedToCart(productId, quantity));
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

For non-web contexts, see [DotNET client usage](/chronicle/namespaces/dotnet-client/).

# DotNET client usage

The .NET client resolves a namespace for every event store operation. You can configure namespace resolution by passing an `IEventStoreNamespaceResolver` implementation to the `ChronicleClient` constructor.

Client coverage

This page and [ASP.NET Core namespace resolution](/chronicle/namespaces/aspnetcore/) are intentionally .NET-specific — namespace resolution here is driven by .NET’s DI/hosting model (`IEventStoreNamespaceResolver`, ASP.NET Core HTTP-header/subdomain/claims-based resolvers), which has no equivalent hosting model documented for Kotlin, Elixir, or TypeScript in this corpus. Passing a namespace explicitly per call (rather than resolving it from the host) works the same in every client — see each client’s `IEventStore`/connection options.

## IEventStoreNamespaceResolver

[Section titled “IEventStoreNamespaceResolver”](#ieventstorenamespaceresolver)

* C#

```csharp
  using Cratis.Chronicle;

public class NamespacesDotNetClientSampleResolver : IEventStoreNamespaceResolver
  {
      public EventStoreNamespaceName Resolve() => EventStoreNamespaceName.Default;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStoreNamespaceName
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver

class NamespacesDotNetClientSampleResolver : IEventStoreNamespaceResolver {
      override fun resolve(): String = EventStoreNamespaceName.default.value
  }
  ```

* Java

```java
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver;

class NamespacesDotNetClientSampleResolver implements IEventStoreNamespaceResolver {
      @Override
      public String resolve() {
          return "Default";
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The resolver returns the namespace name to use for the current context.

## Built-in resolvers

[Section titled “Built-in resolvers”](#built-in-resolvers)

### DefaultEventStoreNamespaceResolver

[Section titled “DefaultEventStoreNamespaceResolver”](#defaulteventstorenamespaceresolver)

Always returns the default namespace. Use this when you do not need tenant isolation. This is the default when no resolver is supplied.

### ClaimsBasedNamespaceResolver

[Section titled “ClaimsBasedNamespaceResolver”](#claimsbasednamespaceresolver)

Resolves the namespace from the current principal’s claims. This is useful when you have an authenticated user and want to map the tenant from a claim.

* C#

```csharp
  using Cratis.Chronicle;

public static class NamespacesDotNetClientClaimsBased
  {
      public static ChronicleClient CreateWithDefaultClaimType(ChronicleOptions options) =>
          // Uses the default claim type "tenant_id"
          new(options, namespaceResolver: new ClaimsBasedNamespaceResolver("tenant_id"));

public static ChronicleClient CreateWithCustomClaimType(ChronicleOptions options) =>
          // Uses a custom claim type
          new(options, namespaceResolver: new ClaimsBasedNamespaceResolver("custom_tenant_claim"));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.EventStoreNamespaceName
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver

/**
   * Takes the namespace from a claim on the currently authenticated principal, falling back to the
   * default namespace for anonymous requests or work happening outside a request. The Spring Boot
   * integration ships this exact strategy as
   * io.cratis.chronicle.spring.namespaces.AuthenticationNamespaceResolver; this version takes the
   * current claims as a parameter so it has no framework dependency.
   */
  class ClaimsBasedNamespaceResolver(
      private val claim: String,
      private val currentClaims: () -> Map<String, String>?
  ) : IEventStoreNamespaceResolver {
      override fun resolve(): String = currentClaims()?.get(claim) ?: EventStoreNamespaceName.default.value
  }

fun createWithDefaultClaimType(currentClaims: () -> Map<String, String>?): IEventStoreNamespaceResolver =
      ClaimsBasedNamespaceResolver("tenant_id", currentClaims)

fun createWithCustomClaimType(currentClaims: () -> Map<String, String>?): IEventStoreNamespaceResolver =
      ClaimsBasedNamespaceResolver("custom_tenant_claim", currentClaims)
  ```

* Java

```java
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver;

import java.util.Map;
  import java.util.function.Supplier;

// Takes the namespace from a claim on the currently authenticated principal, falling back to the
  // default namespace for anonymous requests or work happening outside a request. The Spring Boot
  // integration ships this exact strategy as
  // io.cratis.chronicle.spring.namespaces.AuthenticationNamespaceResolver; this version takes the
  // current claims as a parameter so it has no framework dependency.
  class ClaimsBasedNamespaceResolver implements IEventStoreNamespaceResolver {
      private final String claim;
      private final Supplier<Map<String, String>> currentClaims;

public ClaimsBasedNamespaceResolver(String claim, Supplier<Map<String, String>> currentClaims) {
          this.claim = claim;
          this.currentClaims = currentClaims;
      }

@Override
      public String resolve() {
          Map<String, String> claims = currentClaims.get();
          String value = claims == null ? null : claims.get(claim);
          return value == null ? "Default" : value;
      }

public static IEventStoreNamespaceResolver createWithDefaultClaimType(Supplier<Map<String, String>> currentClaims) {
          return new ClaimsBasedNamespaceResolver("tenant_id", currentClaims);
      }

public static IEventStoreNamespaceResolver createWithCustomClaimType(Supplier<Map<String, String>> currentClaims) {
          return new ClaimsBasedNamespaceResolver("custom_tenant_claim", currentClaims);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

If the claim is not found or the user is not authenticated, the default namespace is used.

## Passing a resolver to ChronicleClient

[Section titled “Passing a resolver to ChronicleClient”](#passing-a-resolver-to-chronicleclient)

For console or direct-client scenarios, pass the resolver as a constructor parameter:

* C#

```csharp
  using Cratis.Chronicle;

public static class NamespacesDotNetClientDefaultResolver
  {
      public static ChronicleClient Create(ChronicleOptions options)
      {
          var resolver = new DefaultEventStoreNamespaceResolver();
          return new ChronicleClient(options, namespaceResolver: resolver);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.namespaces.DefaultEventStoreNamespaceResolver

fun getDefaultEventStore(client: ChronicleClient, name: String): IEventStore =
      client.getEventStore(name, DefaultEventStoreNamespaceResolver.resolve())
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingChronicleClient;
  import io.cratis.chronicle.namespaces.DefaultEventStoreNamespaceResolver;

class NamespacesDotNetClientDefaultResolver {
      IEventStore create(BlockingChronicleClient client, String name) {
          String namespace = DefaultEventStoreNamespaceResolver.INSTANCE.resolve();
          return client.getEventStore(name, namespace).unwrap();
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Configuring in a hosted application

[Section titled “Configuring in a hosted application”](#configuring-in-a-hosted-application)

When using `IHostApplicationBuilder` (worker service or web app), configure the resolver through `ChronicleClientOptions` or directly via `IChronicleBuilder`:

* C#

```csharp
  using Microsoft.Extensions.Hosting;

public static class NamespacesDotNetClientHostedAppConfiguration
  {
      public static void ConfigureViaOptions(IHostApplicationBuilder builder) =>
          // Via options (type is resolved from DI)
          builder.AddCratisChronicle(options =>
          {
              options.EventStore = "my-store";
              options.EventStoreNamespaceResolverType = typeof(TenantNamespaceResolver);
          });

public static void ConfigureViaBuilder(IHostApplicationBuilder builder, ITenantContext tenantContext) =>
          // Via builder (instance is used directly)
          builder.AddCratisChronicle(
              configureOptions: options => options.EventStore = "my-store",
              configure: b => b.WithNamespaceResolver(new TenantNamespaceResolver(tenantContext)));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver

/**
   * Kotlin has no separate hosted-app builder to configure a resolver on structurally - a worker
   * service resolves the namespace and asks the client for that event store exactly like a console
   * application would.
   */
  fun currentEventStore(client: ChronicleClient, name: String, resolver: IEventStoreNamespaceResolver): IEventStore =
      client.getEventStore(name, resolver.resolve())
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingChronicleClient;
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver;

// Java has no separate hosted-app builder to configure a resolver on structurally - a worker
  // service resolves the namespace and asks the client for that event store exactly like a console
  // application would.
  class NamespacesDotNetClientHostedAppConfiguration {
      IEventStore currentEventStore(BlockingChronicleClient client, String name, IEventStoreNamespaceResolver resolver) {
          return client.getEventStore(name, resolver.resolve()).unwrap();
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Custom resolvers

[Section titled “Custom resolvers”](#custom-resolvers)

Implement a resolver when your namespace comes from a custom context, such as a tenant provider or a request-scoped service.

If your application uses Arc Tenancy, you can resolve the namespace from its tenant context. See Arc Tenancy.

* C#

```csharp
  using Cratis.Chronicle;

public interface ITenantContext
  {
      EventStoreNamespaceName CurrentTenantId { get; }
  }

public class TenantNamespaceResolver : IEventStoreNamespaceResolver
  {
      readonly ITenantContext _tenantContext;

public TenantNamespaceResolver(ITenantContext tenantContext)
      {
          _tenantContext = tenantContext;
      }

public EventStoreNamespaceName Resolve() =>
          _tenantContext.CurrentTenantId;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver

interface ITenantContext {
      val currentTenantId: String
  }

class TenantNamespaceResolver(private val tenantContext: ITenantContext) : IEventStoreNamespaceResolver {
      override fun resolve(): String = tenantContext.currentTenantId
  }
  ```

* Java

```java
  import io.cratis.chronicle.namespaces.IEventStoreNamespaceResolver;

interface ITenantContext {
      String getCurrentTenantId();
  }

class TenantNamespaceResolver implements IEventStoreNamespaceResolver {
      private final ITenantContext tenantContext;

public TenantNamespaceResolver(ITenantContext tenantContext) {
          this.tenantContext = tenantContext;
      }

@Override
      public String resolve() {
          return tenantContext.getCurrentTenantId();
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

- C#

```csharp
  using Cratis.Chronicle;

public static class NamespacesDotNetClientTenantResolverUsage
  {
      public static ChronicleClient Create(ChronicleOptions options, ITenantContext tenantContext) =>
          new(options, namespaceResolver: new TenantNamespaceResolver(tenantContext));
  }
  ```

- Kotlin

```kotlin
  import io.cratis.chronicle.ChronicleClient
  import io.cratis.chronicle.IEventStore

fun getTenantEventStore(client: ChronicleClient, name: String, tenantContext: ITenantContext): IEventStore =
      client.getEventStore(name, TenantNamespaceResolver(tenantContext).resolve())
  ```

- Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingChronicleClient;

class NamespacesDotNetClientTenantResolverUsage {
      IEventStore create(BlockingChronicleClient client, String name, ITenantContext tenantContext) {
          String namespace = new TenantNamespaceResolver(tenantContext).resolve();
          return client.getEventStore(name, namespace).unwrap();
      }
  }
  ```

- Elixir

```text
  Elixir does not support this workflow yet.
  ```

- TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Best practices

[Section titled “Best practices”](#best-practices)

* Keep resolvers deterministic within a request or operation
* Provide a safe fallback to the default namespace
* Avoid expensive resolution logic, as it is called frequently

For web applications, see [ASP.NET Core namespace resolution](/chronicle/namespaces/aspnetcore/).

# Behavior Patterns

Chronicle mines the event history of a store for **recurring behavior** — combinations of context that keep leading to the same action — and lets you ask what usually happens in a situation. The answer is backed by what actually happened, not by a guess.

The question it answers is: *given this user, this day, this time of day, what does this person normally do?* An agent, a workflow, or the Workbench can ask it and act on a real answer, or learn that there is no established behavior and say so.

## What a pattern is

[Section titled “What a pattern is”](#what-a-pattern-is)

A **behavior pattern** is a combination of facets that recurred often enough and reliably enough to survive:

| Part                       | Meaning                                                            |
| -------------------------- | ------------------------------------------------------------------ |
| **Grouping key**           | The scope the behavior belongs to — normally the user              |
| **Facets**                 | The contextual dimensions the pattern constrains, and their values |
| **Occurrences**            | How many times it has been observed                                |
| **Confidence**             | How often it holds when its context is present, 0 to 1             |
| **Support**                | The share of all observed events it was seen in, 0 to 1            |
| **Weight**                 | Recency-weighted strength — decays as the behavior goes unseen     |
| **First seen / last seen** | When it was first and last observed                                |

A pattern such as `{ Day: Monday, TimeBucket: EarlyMorning, CommandType: RegisterInvoice }` with a confidence of `0.9` reads as: *first thing on a Monday, this person enters supplier invoices nine times out of ten.*

## Facets

[Section titled “Facets”](#facets)

Facets are read off an event’s **context** — never its content — so the same vocabulary applies to every event type in every event store.

| Facet               | Where it comes from                                                                    |
| ------------------- | -------------------------------------------------------------------------------------- |
| `CommandType`       | The command that produced the event; the event type when nothing above it named itself |
| `InitiatorType`     | `User`, `Agent`, `System` or `Unknown`                                                 |
| `InitiatorId`       | The identity that caused the event                                                     |
| `OnBehalfOf`        | The identity it acted for, when it acted for someone else                              |
| `CausedByCommand`   | The command one level up the causation chain                                           |
| `CorrelationRootId` | The correlation the event belongs to                                                   |
| `AggregateType`     | The event source type the event was appended to                                        |
| `Year`, `Month`     | Taken from the event’s occurred timestamp                                              |
| `Day`               | Day of week                                                                            |
| `TimeBucket`        | `EarlyMorning`, `Morning`, `Midday`, `Afternoon`, `Evening` or `Night`                 |

Every time-derived facet comes from the event’s own **occurred** timestamp, never from wall-clock time at processing. A backdated append and a replay both land in the bucket the event actually belongs to.

### Who the behavior belongs to

[Section titled “Who the behavior belongs to”](#who-the-behavior-belongs-to)

An agent acting on behalf of a person contributes to **that person’s** behavior, not its own — otherwise one habit would be split across every agent that happened to carry it out. The agent is still recorded as the initiator, so agent-driven and user-driven behavior stay distinguishable.

An event nobody can be named for is not mined at all. Its behavior belongs to no scope, and counting it into a catch-all that every unattributed append pours into produces noise rather than a pattern.

## How mining works

[Section titled “How mining works”](#how-mining-works)

Chronicle does not store anything per event. It keeps a bounded **Lossy Counting** sketch per scope:

1. Each event’s facets are expanded into every combination up to `MaximumCombinationSize` (3 by default). The cap is what keeps the candidate space polynomial rather than exponential.
2. Each combination is counted in the sketch. Memory is bounded by the `Error` parameter regardless of how long the stream runs — nothing with a true frequency above the support threshold is ever missed.
3. A combination that goes unseen **decays**: its weight is multiplied by `DecayFactor` for every day since it was last seen, so behavior that stopped happening sinks below the threshold and is pruned instead of competing forever with what a person does now.
4. Only combinations clearing both `MinimumSupport` and `MinimumConfidence` are persisted.

Storage therefore scales with **distinct recurring behavior**, not with event volume. A store that appends millions of events but sees a few hundred recurring behaviors holds a few hundred rows.

Mining happens in memory on every observed event; **persistence is deferred** — the scopes an interval touched are rewritten on the `PersistenceInterval` cadence, so a bulk ingest of thousands of events costs a handful of writes rather than one rewrite per event. Sketches are kept **per event store and per namespace**: the same scope name in two stores — or two tenants’ namespaces — is two different people’s behavior and never counts into one sketch.

### Across restarts

[Section titled “Across restarts”](#across-restarts)

The sketch lives in memory, but what survived it is persisted — so when the server restarts, a scope’s established patterns are **restored into the sketch before anything new is mined for it** and counting continues where it left off. Without that, the first events after a restart would be a fresh sketch’s only observations, held with full support, and rewriting the scope from them would wipe established behavior. `Occurrences` stays a bounded approximation: a small tail of events can be re-mined after a crash, over-counting by at most the observer’s checkpoint window.

### Confidence

[Section titled “Confidence”](#confidence)

Confidence reads as the rule *“in this context, this action follows”*: the frequency of the whole combination over the frequency of the same combination without its `CommandType` facet. A combination that names no action is pure context, and its confidence is its support.

## Configuration

[Section titled “Configuration”](#configuration)

Under `Cratis:Chronicle:PatternDetection`:

| Setting                  | Default                                                                                 | What it does                                                           |
| ------------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `Facets`                 | `CommandType`, `InitiatorType`, `CausedByCommand`, `AggregateType`, `Day`, `TimeBucket` | Which facets take part in the mined combination                        |
| `MaximumCombinationSize` | `3`                                                                                     | The largest number of facets a combination may hold                    |
| `Error`                  | `0.001`                                                                                 | The Lossy Counting error parameter — smaller buys accuracy with memory |
| `MinimumSupport`         | `0.01`                                                                                  | The smallest share of events a combination must hold to survive        |
| `MinimumConfidence`      | `0.5`                                                                                   | The smallest confidence a combination must hold to survive             |
| `DecayFactor`            | `0.99`                                                                                  | Daily decay applied to a combination that has gone unseen              |
| `PersistenceInterval`    | `5`                                                                                     | Seconds between persisting the scopes mining has touched               |

`Year` and `Month` are deliberately absent from `Facets`: they are kept on a surviving pattern for recency, but combining them multiplies the candidate space by every month the store has been running while splitting one behavior across all of them. Add them when a deployment wants to mine seasonality and can afford the cardinality.

## When capture starts

[Section titled “When capture starts”](#when-capture-starts)

Pattern capture observes the event types an event store has registered, and re-subscribes as more are registered — so a store that gains its first event types while the server is already running starts being captured then, not at the next restart. A **namespace added while the server runs** is subscribed the moment it appears, so a tenant onboarded between restarts is mined from its first event.

## Naming the command

[Section titled “Naming the command”](#naming-the-command)

For `CommandType` and `CausedByCommand` to be meaningful, something above the event has to name the command. [Cratis Arc](/arc/) records a `Command` causation naming the executing command for the duration of that command, so nested commands produce a real “caused by” chain and sibling commands do not. Anything else appending to Chronicle can do the same by putting a `commandType` property on its causation.

Without such a link the mined `CommandType` falls back to the event type, which is still a meaningful action in an event-sourced store — the fact that was recorded *is* what happened.

## Querying patterns

[Section titled “Querying patterns”](#querying-patterns)

Ask what usually happens with the [.NET client’s pattern API](/chronicle/clients/dotnet/patterns/), or over gRPC through the `Patterns` service:

* **`GetUsualActions`** — given a situation, what is usually *done* in it, ranked by confidence.
* **`GetPatterns`** — given a situation, the patterns that *describe* it, ranked by specificity and then confidence.
* **`GetPatternsForScope`** — everything a scope has established, unfiltered, for browsing.
* **`GetScopes`** — the scopes that hold any patterns at all, which is what a browsing view needs before it can offer one.

### Two questions, and why they are different calls

[Section titled “Two questions, and why they are different calls”](#two-questions-and-why-they-are-different-calls)

Most applications want the first one: *what does this person usually do here?* You describe the situation you are in — a day, a part of the day, the kind of thing being worked on — and the answer is the command.

The second is the opposite question: *is what I am looking at normal?* There you already know the command, and you want the established patterns that cover it — which is what you check an action against before flagging it as unusual.

They cannot be one call, because they compare different halves of a pattern. A pattern like `CommandType=RegisterInvoice; Day=Monday; TimeBucket=EarlyMorning` **describes** a situation only if everything it names was named in the question. But nobody asking what usually happens on a Monday morning can name the command — naming it is what they are asking for. So `GetUsualActions` compares only the *context* half of a pattern against your question and hands back the command as the answer, while `GetPatterns` compares the whole pattern and can only ever return facets you already named.

`GetUsualActions` returns **at most one answer per action**. A habit is established at several context sizes at once — on a Monday, in the early morning, and on a Monday early morning are three mined combinations describing one behavior — and returning all three says the same thing three times while pushing the second-most-likely action out of a limited result set. The one kept is the one conditioned on most of your question.

Ranking differs for the same reason. `GetPatterns` leads with specificity, because the pattern covering most of what you asked describes your situation best. `GetUsualActions` leads with **confidence**, which is already the chance of that action given the context it was established in — a number that compares directly between one answer and the next, where a facet count does not.

**Nothing clearing the confidence bar returns nothing.** An empty answer is a true statement — this scope has no established behavior for this context — and is not padded with the best of a bad set.

## Asking about a moment

[Section titled “Asking about a moment”](#asking-about-a-moment)

The context an application usually has is a person and a point in time, so every client offers that as a single call on top of `GetUsualActions`: **give it the scope, optionally give it a moment, and it fills in the rest**. The moment defaults to now.

What it fills in is the `Day` and the `TimeBucket`, derived from the moment with **the same rule the engine used when it mined the events**. That rule is the load-bearing part. A caller deriving the bucket itself owns a second copy of it, and when the two drift nothing fails loudly — the query simply asks about a slot the mining never used and comes back empty. Each client therefore exposes the bucketing rule as well, so the copy never has to exist:

| Client                                      | Ask about a moment                       | Bucket a moment         |
| ------------------------------------------- | ---------------------------------------- | ----------------------- |
| [.NET](/chronicle/clients/dotnet/patterns/) | `Patterns.GetPatternsAt(scope, moment?)` | `moment.ToTimeBucket()` |

Other clients — TypeScript, Kotlin, Elixir, Python — expose the same capability in their own idiom; see the client’s own page for the exact shape. The contract they share is the one above: scope required, moment optional and defaulting to now, day and time bucket derived by the engine’s rule rather than the caller’s.

## Seeing patterns in the Workbench

[Section titled “Seeing patterns in the Workbench”](#seeing-patterns-in-the-workbench)

Two views under an event store’s namespace read the same patterns from different angles.

**Behavior patterns** pivots every pattern in the namespace, with the scope as the first filter rather than a control above the viewer — so two people’s behavior can be compared side by side instead of one being chosen before anything can be seen. The facets become the dimensions and filters, so the same set can be approached from whichever direction the question comes: by command, by who initiated it, by day or part of day, by aggregate, by what caused it, or by how specific the pattern is. Each card carries a confidence bar, so a well-established habit is distinguishable from a marginal one without reading numbers.

**Pattern heatmap** answers the narrower question of *when*, for one scope at a time. It is a day-by-time-of-day grid where each cell is shaded by how much the scope does in that slot, with the current slot outlined. Activity rather than confidence, because confidence saturates — anything habitual sits at a hundred percent, so shading by it would make every slot a person works in look the same. Clicking a cell lists everything established for it. Above the grid, a panel names what the scope usually does *right now* — the same question [`GetUsualActions`](/chronicle/clients/dotnet/patterns/) answers from code, asked with the current day and time bucket as the context.

A pattern that constrains neither day nor time of day belongs to no cell and is left out of the grid rather than drawn somewhere arbitrary. It is still in the pivot view, which is the one that shows everything.

## Trying it out

[Section titled “Trying it out”](#trying-it-out)

The **Backoffice** sample in the Chronicle repository generates half a year of work in the internal system a mid-size company runs on — accounts payable, the ledger, procurement, HR and payroll — plus agents acting on people’s behalf, an overnight system run, and one person with no routine at all as a control.

It is the quickest way to see what the views are for, because nobody in it does only one thing. Everybody holds three or four different jobs at different points in the week, so each person’s heatmap is a different shape with several commands in it rather than one dominant block: the accounts payable clerk lights up first thing and again at lunchtime with different work in each, the controller lights up through the afternoons and twice a week at midday, and the person who covers whatever is short-handed lights up nowhere. Its README explains what was put in, so what Chronicle establishes can be checked against it.

# Projections

Your events are the source of truth, but events are a poor thing to *read* — nobody wants to replay a thousand `MoneyDeposited` facts to show an account balance. A **projection** does that folding for you: it watches a stream of events and continuously builds a **read model** — a shaped, queryable view that’s ready to serve to a UI.

The win is specialization. The same events can feed *many* projections, each tailored to one screen or question: a balance, a transaction list, a monthly summary. You never reuse one bloated model across conflicting needs — you build a focused read model per view, and each stays simple, fast, and independent.

```
maps & merges

Event

Projection

Event

Read model

Query
```

## How you’ll define one

[Section titled “How you’ll define one”](#how-youll-define-one)

Projections join **events** (never other read models), and mapping is automatic by default — name a read model property the same as an event property and it just maps. For a read model backed by events, you usually choose between three styles:

| Style                                              | What it looks like                                                                   | Reach for it when                                                                             |
| -------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| [Model-bound](/chronicle/projections/model-bound/) | Attributes on the read model record (`[FromEvent<T>]`, `[Key]`, `[ChildrenFrom<T>]`) | **The default.** Most projections — it’s the least boilerplate and reads as the model itself. |
| [Declarative](/chronicle/projections/declarative/) | A fluent `IProjectionFor<T>` definition                                              | The mapping needs logic the attributes can’t express cleanly.                                 |
| [Reducer](/chronicle/reducers/)                    | An `IReducerFor<T>` that receives the event, current state, and event context        | The read model is easier to express as state transitions or calculations over previous state. |

[Choose a read-model style](/chronicle/projections/choosing-a-read-model-style/) builds the same read model as a model-bound projection, a declarative projection, and a reducer so the trade-offs are visible side by side.

## Choose your consistency

[Section titled “Choose your consistency”](#choose-your-consistency)

The one decision worth making up front is *when* the read model has to be correct:

|                     | [Eventual](/chronicle/projections/eventual-consistency/) | [Immediate](/chronicle/projections/immediate-projections/)                 |
| ------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------- |
| **When it updates** | Shortly after the event is appended (the default)        | Synchronously, before the append returns                                   |
| **Cost**            | Cheap, scales freely                                     | More expensive — pay only when you need it                                 |
| **Use it for**      | Almost everything — lists, dashboards, history           | A value you must read back correctly *right now* (e.g. a uniqueness check) |

Start eventual. Promote a projection to immediate only when a workflow genuinely can’t tolerate the read model being a moment behind.

## Topics

[Section titled “Topics”](#topics)

| Topic                                                                            | Description                                                                          |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [Architecture](/chronicle/projections/architecture/)                             | How the projection engine turns events into read models                              |
| [Choose a read-model style](/chronicle/projections/choosing-a-read-model-style/) | Compare model-bound, declarative, and reducer approaches on the same read model      |
| [Model-Bound Projections](/chronicle/projections/model-bound/)                   | Build read models with attributes — the default style                                |
| [Declarative Projections](/chronicle/projections/declarative/)                   | Build read models with the fluent `IProjectionFor<T>` API                            |
| [Immediate Projections](/chronicle/projections/immediate-projections/)           | Strong consistency — the read model updates before the append returns                |
| [Eventual Consistency](/chronicle/projections/eventual-consistency/)             | The default — how and when eventual projections catch up                             |
| [Registration lifecycle](/chronicle/projections/registration-lifecycle/)         | What happens when projections register, change, fail, or are no longer declared      |
| [Tagging Projections](/chronicle/projections/tagging-projections/)               | Organize and tag projections                                                         |
| [Appended event metadata filters](/chronicle/events/filtering/)                  | How tags and metadata correlate reducers and reactors that run alongside projections |

Once your read model exists, expose it to the frontend with a [query](/chronicle/read-models/) — or see the whole loop in [Build a full-stack feature](/build-a-full-app/).

# Projection Architecture

Chronicle supports three distinct approaches for defining projections, each designed for different use cases and developer preferences. This page explains the architecture and how these approaches work together.

## Three Projection Approaches

[Section titled “Three Projection Approaches”](#three-projection-approaches)

```
Execution

Core Processing

Projection Declaration Approaches

Compiler

Reflection

Builder

Projection Declaration Language (Declaration)

Model-Bound (Attributes/Annotations)

Declarative (Fluent API)

ProjectionDefinition

Projection Pipeline

Event Stream

Projector

Read Model Storage
```

### 1. Projection Declaration Language

[Section titled “1. Projection Declaration Language”](#1-projection-declaration-language)

The Projection Declaration Language provides a concise, indentation-based syntax optimized for readability and quick authoring. Typically available from the tooling like Workbench.

**Example:**

```pdl
projection MyModel
    from MyEvent
        set name = $.eventProperty
        set count = $count + 1
```

**Benefits:**

* Minimal syntax and ceremony
* Easy to read and understand
* Fast iteration with live preview
* Context-sensitive auto-completion in editors

**Use when:**

* Building new projections
* Prototyping and experimentation
* Working with the Workbench UI
* Team prefers concise, declarative syntax

### 2. Model-Bound Projections

[Section titled “2. Model-Bound Projections”](#2-model-bound-projections)

Model-bound projections use attributes or annotations on your read model classes, keeping the projection logic close to the data structure.

**Example:**

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record ArchitectureModelBoundItemAdded(string Category);

[FromEvent<ArchitectureModelBoundItemAdded>(key: nameof(ArchitectureModelBoundItemAdded.Category))]
  public record ArchitectureModelBoundSummary(
      [Key] string Category,
      [Count<ArchitectureModelBoundItemAdded>] int Count);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.Count
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class ArchitectureModelBoundItemAdded(val category: String)

@ReadModel
  @FromEvent(ArchitectureModelBoundItemAdded::class, key = "category")
  data class ArchitectureModelBoundSummary(
      @Count(ArchitectureModelBoundItemAdded::class)
      val count: Int = 0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.Count;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record ArchitectureModelBoundItemAdded(String category) {}

@ReadModel
  @FromEvent(eventType = ArchitectureModelBoundItemAdded.class, key = "category")
  class ArchitectureModelBoundSummary {
      @Count(eventType = ArchitectureModelBoundItemAdded.class)
      public int count = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ArchitectureModelBoundItemAdded do
    use Chronicle.Events.EventType, id: "architecture-model-bound-item-added"

defstruct [:category]
  end

defmodule MyApp.ReadModels.ArchitectureModelBoundSummary do
    use Chronicle.ReadModels.ReadModel

defstruct category: nil, count: 0

from MyApp.Events.ArchitectureModelBoundItemAdded,
      key: :category,
      count: :count
  end
  ```

* TypeScript

```typescript
  import { count, eventType, fromEvent, readModel } from '@cratis/chronicle';

@eventType()
  class ArchitectureModelBoundItemAdded {
      category = '';
  }

@readModel()
  @fromEvent(ArchitectureModelBoundItemAdded, { key: 'category' })
  class ArchitectureModelBoundSummary {
      category = '';

@count(ArchitectureModelBoundItemAdded)
      count = 0;
  }
  ```

**Benefits:**

* Type-safe at compile time
* Co-located with read model definition
* Leverages your language’s tooling and IntelliSense
* Natural for developers already using attributes/annotations elsewhere

**Use when:**

* Strong type safety is required
* Using an attribute/annotation-first development workflow
* Read model and projection logic should be together
* Refactoring tools are important

### 3. Declarative Projections

[Section titled “3. Declarative Projections”](#3-declarative-projections)

Declarative projections use a fluent API to define projections programmatically with maximum flexibility.

**Example:**

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record ArchitectureDeclarativeItemAdded(string Category);

public record ArchitectureDeclarativeSummary(
      string Category,
      int Count);

public class ArchitectureDeclarativeSummaryProjection : IProjectionFor<ArchitectureDeclarativeSummary>
  {
      public void Define(IProjectionBuilderFor<ArchitectureDeclarativeSummary> builder) => builder
          .From<ArchitectureDeclarativeItemAdded>(_ => _
              .UsingKey(e => e.Category)
              .Count(m => m.Count));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class ArchitectureDeclarativeItemAdded(val category: String)

data class ArchitectureDeclarativeSummary(
      val category: String = "",
      val count: Int = 0
  )

class ArchitectureDeclarativeSummaryProjection : IProjectionFor<ArchitectureDeclarativeSummary> {
      override fun define(builder: IProjectionBuilderFor<ArchitectureDeclarativeSummary>) {
          builder
              .from(ArchitectureDeclarativeItemAdded::class) {
                  it.usingKey("category")
                  it.count(ArchitectureDeclarativeSummary::count)
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record ArchitectureDeclarativeItemAdded(String category) {}

class ArchitectureDeclarativeSummary {
      public String category = "";
      public int count = 0;
  }

class ArchitectureDeclarativeSummaryProjection implements IProjectionFor<ArchitectureDeclarativeSummary> {
      @Override
      public void define(IProjectionBuilderFor<ArchitectureDeclarativeSummary> builder) {
          builder
              .from(ArchitectureDeclarativeItemAdded.class, fb -> {
                  fb.usingKey("category");
                  fb.count("count");
              });
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ArchitectureDeclarativeItemAdded do
    use Chronicle.Events.EventType, id: "architecture-declarative-item-added"

defstruct [:category]
  end

defmodule MyApp.ReadModels.ArchitectureDeclarativeSummary do
    use Chronicle.ReadModels.ReadModel

defstruct category: nil, count: 0
  end

defmodule MyApp.Projections.ArchitectureDeclarativeSummaryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.ArchitectureDeclarativeSummary

from MyApp.Events.ArchitectureDeclarativeItemAdded,
      key: :category,
      count: :count
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  The declarative projection builder declares a `.count()` method, but it
  currently throws "count is not implemented yet." at runtime.
  Track the client SDK issue before relying on declarative counting from TypeScript.
  ```

**Benefits:**

* Full programmatic control
* Complex conditional logic
* Dynamic projection generation
* Maximum flexibility

**Use when:**

* Complex business rules require code
* Generating projections dynamically
* Advanced scenarios beyond declaration language capabilities
* Need for custom extensions

## Architecture Components

[Section titled “Architecture Components”](#architecture-components)

```
Runtime Layer

Core Layer

Compilation Layer

Frontend Layer

Declaration Text

Workbench UI

Monaco Editor + Language Service

Screenplay Compiler (Cratis.Screenplay)

Semantic Validator

ProjectionDefinition Visitor

ProjectionDefinition

Projection Registry

Projection Engine

Event Stream

Projector

Storage Sink
```

### Frontend Layer

[Section titled “Frontend Layer”](#frontend-layer)

**Workbench UI**: Web-based interface for creating, editing, and testing projections.

**Monaco Editor with Language Service**: Provides rich editing experience with:

* Syntax highlighting for all declaration keywords
* Context-sensitive auto-completion
* Real-time validation with schema awareness
* Hover documentation
* Error markers

### Compilation Layer

[Section titled “Compilation Layer”](#compilation-layer)

**Screenplay Compiler**: The projection language is part of the [Cratis Screenplay language](/screenplay/projections/), and parsing is owned by the `Cratis.Screenplay` package:

* Indentation-based structure with 1-based line and column tracking
* Keywords, identifiers, string literals and expressions
* Nested blocks (children, nested objects, joins, composite keys)
* Syntax errors reported as diagnostics with precise locations

**Semantic Validator**: Performs semantic validation over the parsed syntax:

* Checks event types exist
* Validates property names against schemas
* Ensures composite key types are objects
* Verifies expression syntax

**ProjectionDefinition Visitor**: Chronicle’s implementation of Screenplay’s `IProjectionSyntaxVisitor<T>` that turns the syntax tree into the final `ProjectionDefinition` object all three approaches produce.

### Core Layer

[Section titled “Core Layer”](#core-layer)

**ProjectionDefinition**: Unified representation of projection logic, regardless of source (Projection Declaration, Model-Bound, or Declarative).

**Projection Registry**: Manages all registered projections in the system.

**Projection Engine**: Coordinates projection execution, handles event replay, and manages state.

### Runtime Layer

[Section titled “Runtime Layer”](#runtime-layer)

**Event Stream**: Source of events to be projected.

**Projector**: Executes projection logic for each event:

* Applies transformations
* Manages read model instances
* Handles keys and lookups
* Performs joins and child operations

**Storage Sink**: Persists read models (typically MongoDB or another database).

## Data Flow

[Section titled “Data Flow”](#data-flow)

```
StorageEvent StreamProjection EngineCompilerMonaco EditorUserStorageEvent StreamProjection EngineCompilerMonaco EditorUserWrite DeclarationSyntax HighlightCompile on ChangeReturn Errors/WarningsShow MarkersSave & ActivateRegister ProjectionNew EventMatch Event TypeExecute ProjectionUpdate Read ModelQuery Results
```

## Choosing an Approach

[Section titled “Choosing an Approach”](#choosing-an-approach)

| Criterion               | Declaration | Model-Bound | Declarative |
| ----------------------- | ----------- | ----------- | ----------- |
| **Ease of Learning**    | ⭐⭐⭐⭐⭐       | ⭐⭐⭐⭐        | ⭐⭐⭐         |
| **Type Safety**         | ⭐⭐          | ⭐⭐⭐⭐⭐       | ⭐⭐⭐⭐⭐       |
| **Conciseness**         | ⭐⭐⭐⭐⭐       | ⭐⭐⭐         | ⭐⭐⭐         |
| **Flexibility**         | ⭐⭐⭐         | ⭐⭐⭐         | ⭐⭐⭐⭐⭐       |
| **Refactoring Support** | ⭐⭐          | ⭐⭐⭐⭐⭐       | ⭐⭐⭐⭐⭐       |
| **Prototyping Speed**   | ⭐⭐⭐⭐⭐       | ⭐⭐⭐         | ⭐⭐          |
| **Complex Logic**       | ⭐⭐          | ⭐⭐⭐         | ⭐⭐⭐⭐⭐       |

**Recommendation**: Start with the **Projection Declaration Language** for rapid development and prototyping. Move to **Model-Bound** when type safety becomes critical. Use **Declarative** for advanced scenarios requiring programmatic control.

## Common Patterns Across All Approaches

[Section titled “Common Patterns Across All Approaches”](#common-patterns-across-all-approaches)

Regardless of which approach you choose, all projections share these concepts:

* **Event Types**: Define which events trigger the projection
* **Keys**: Identify read model instances
* **Property Mappings**: Transform event data to read model properties
* **Joins**: Link to other read models
* **Children**: Model parent-child relationships
* **Filters**: Conditionally process events
* **Operations**: Set, increment, decrement, count, add, subtract

All three approaches compile down to the same `ProjectionDefinition` format, ensuring consistent behavior and performance.

# Choose a read-model style

> Compare model-bound projections, declarative projections, and reducers by building the same Chronicle read model three ways.

Every read model answers the same question: “given the events so far, what should this screen or workflow read now?” Chronicle gives you more than one way to express that answer because different problems read better in different shapes.

Let’s keep one library read model up to date. A book is registered, borrowed, and returned:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record ChoosingStyleBookRegistered(string Title, string Isbn);

[EventType]
  public record ChoosingStyleBookBorrowed(string MemberName);

[EventType]
  public record ChoosingStyleBookReturned;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class ChoosingStyleBookRegistered(val title: String, val isbn: String)

@EventType
  data class ChoosingStyleBookBorrowed(val memberName: String)

@EventType
  class ChoosingStyleBookReturned
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record ChoosingStyleBookRegistered(String title, String isbn) {}

@EventType
  record ChoosingStyleBookBorrowed(String memberName) {}

@EventType
  record ChoosingStyleBookReturned() {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ChoosingStyleBookRegistered do
    use Chronicle.Events.EventType, id: "choosing-style-book-registered"

defstruct [:title, :isbn]
  end

defmodule MyApp.Events.ChoosingStyleBookBorrowed do
    use Chronicle.Events.EventType, id: "choosing-style-book-borrowed"

defstruct [:member_name]
  end

defmodule MyApp.Events.ChoosingStyleBookReturned do
    use Chronicle.Events.EventType, id: "choosing-style-book-returned"

defstruct []
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class ChoosingStyleBookRegistered {
      title = '';
      isbn = '';
  }

@eventType()
  class ChoosingStyleBookBorrowed {
      memberName = '';
  }

@eventType()
  class ChoosingStyleBookReturned {
  }
  ```

The read model we want is deliberately small:

* C#

```csharp
  public record ChoosingStyleBookStatus(
      string Id,
      string Title,
      string Isbn,
      bool IsBorrowed,
      string? BorrowedBy);
  ```

* Kotlin

```kotlin
  data class ChoosingStyleBookStatus(
      val id: String = "",
      val title: String = "",
      val isbn: String = "",
      val isBorrowed: Boolean = false,
      val borrowedBy: String? = null
  )
  ```

* Java

```java
  class ChoosingStyleBookStatus {
      public String id = "";
      public String title = "";
      public String isbn = "";
      public boolean isBorrowed = false;
      public String borrowedBy = null;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.ChoosingStyleBookStatus do
    defstruct id: "", title: "", isbn: "", is_borrowed: false, borrowed_by: nil
  end
  ```

* TypeScript

```typescript
  class ChoosingStyleBookStatus {
      id = '';
      title = '';
      isbn = '';
      isBorrowed = false;
      borrowedBy: string | null = null;
  }
  ```

## Model-bound projection: put the mapping on the model

[Section titled “Model-bound projection: put the mapping on the model”](#model-bound-projection-put-the-mapping-on-the-model)

For simple property mapping, model-bound projections are the shortest route. The read model declares how events populate it:

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

public record ChoosingStyleBookStatusModelBound(
      [Key] string Id,

[SetFrom<ChoosingStyleBookRegistered>] string Title,
      [SetFrom<ChoosingStyleBookRegistered>] string Isbn,

[SetValue<ChoosingStyleBookBorrowed>(true)]
      [SetValue<ChoosingStyleBookReturned>(false)]
      bool IsBorrowed,

[SetFrom<ChoosingStyleBookBorrowed>(nameof(ChoosingStyleBookBorrowed.MemberName))]
      [SetValue<ChoosingStyleBookReturned>(null!)] // null! - SetValue's constructor takes non-nullable object
      string? BorrowedBy);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  The model-bound `@SetFrom` annotation maps a property from an event, but there is
  no equivalent to C#'s `[SetValue<TEvent>(...)]` for assigning a constant value —
  so a flag like `isBorrowed` cannot be toggled per event type through model-bound
  attributes alone. Track the client SDK issue, or use a reducer instead.
  ```

* Java

```text
  Java does not support this workflow yet.
  The model-bound `@SetFrom` annotation maps a property from an event, but there is
  no equivalent to C#'s `[SetValue<TEvent>(...)]` for assigning a constant value —
  so a flag like `isBorrowed` cannot be toggled per event type through model-bound
  attributes alone. Track the client SDK issue, or use a reducer instead.
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.ChoosingStyleBookStatusModelBound do
    use Chronicle.ReadModels.ReadModel

defstruct id: "", title: "", isbn: "", is_borrowed: false, borrowed_by: nil

from MyApp.Events.ChoosingStyleBookRegistered,
      set: [id: :event_source_id, title: :title, isbn: :isbn, is_borrowed: false, borrowed_by: nil]

from MyApp.Events.ChoosingStyleBookBorrowed,
      set: [is_borrowed: true, borrowed_by: :member_name]

from MyApp.Events.ChoosingStyleBookReturned,
      set: [is_borrowed: false, borrowed_by: nil]
  end
  ```

* TypeScript

```typescript
  import { readModel, setFrom, setValue } from '@cratis/chronicle';

@readModel()
  class ChoosingStyleBookStatusModelBound {
      id = '';

@setFrom(ChoosingStyleBookRegistered, 'title')
      title = '';

@setFrom(ChoosingStyleBookRegistered, 'isbn')
      isbn = '';

@setValue(ChoosingStyleBookBorrowed, true)
      @setValue(ChoosingStyleBookReturned, false)
      isBorrowed = false;

@setFrom(ChoosingStyleBookBorrowed, 'memberName')
      @setValue(ChoosingStyleBookReturned, null)
      borrowedBy: string | null = null;
  }
  ```

Chronicle discovers the projection from the attributes. There is no separate projection class, and the mapping sits directly next to the read model the UI or query will read. Reach for this first when the events set, add, subtract, count, or clear properties in a way the attributes can express.

## Declarative projection: separate the mapping from the model

[Section titled “Declarative projection: separate the mapping from the model”](#declarative-projection-separate-the-mapping-from-the-model)

When the mapping needs to be more explicit, keep the read model clean and define the projection with `IProjectionFor<T>`:

* C#

```csharp
  using Cratis.Chronicle.Projections;

public record ChoosingStyleBookStatusFluent(
      string Id,
      string Title,
      string Isbn,
      bool IsBorrowed,
      string? BorrowedBy);

public class ChoosingStyleBookStatusProjection : IProjectionFor<ChoosingStyleBookStatusFluent>
  {
      public void Define(IProjectionBuilderFor<ChoosingStyleBookStatusFluent> builder) => builder
          .From<ChoosingStyleBookRegistered>(_ => _
              .Set(m => m.Id).ToEventSourceId()
              .Set(m => m.Title).To(e => e.Title)
              .Set(m => m.Isbn).To(e => e.Isbn)
              .Set(m => m.IsBorrowed).ToValue(false)
              .Clear(m => m.BorrowedBy))
          .From<ChoosingStyleBookBorrowed>(_ => _
              .Set(m => m.IsBorrowed).ToValue(true)
              .Set(m => m.BorrowedBy).To(e => e.MemberName))
          .From<ChoosingStyleBookReturned>(_ => _
              .Set(m => m.IsBorrowed).ToValue(false)
              .Clear(m => m.BorrowedBy));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

data class ChoosingStyleBookStatusFluent(
      val id: String = "",
      val title: String = "",
      val isbn: String = "",
      val isBorrowed: Boolean = false,
      val borrowedBy: String? = null
  )

class ChoosingStyleBookStatusProjection : IProjectionFor<ChoosingStyleBookStatusFluent> {
      override fun define(builder: IProjectionBuilderFor<ChoosingStyleBookStatusFluent>) {
          builder
              .from(ChoosingStyleBookRegistered::class) {
                  it.set(ChoosingStyleBookStatusFluent::id).toEventSourceId()
                  it.set(ChoosingStyleBookStatusFluent::title).to { e -> e.title }
                  it.set(ChoosingStyleBookStatusFluent::isbn).to { e -> e.isbn }
                  it.set(ChoosingStyleBookStatusFluent::isBorrowed).to { false }
                  it.set(ChoosingStyleBookStatusFluent::borrowedBy).to { null }
              }
              .from(ChoosingStyleBookBorrowed::class) {
                  it.set(ChoosingStyleBookStatusFluent::isBorrowed).to { true }
                  it.set(ChoosingStyleBookStatusFluent::borrowedBy).to { e -> e.memberName }
              }
              .from(ChoosingStyleBookReturned::class) {
                  it.set(ChoosingStyleBookStatusFluent::isBorrowed).to { false }
                  it.set(ChoosingStyleBookStatusFluent::borrowedBy).to { null }
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

class ChoosingStyleBookStatusFluent {
      public String id = "";
      public String title = "";
      public String isbn = "";
      public boolean isBorrowed = false;
      public String borrowedBy = null;
  }

class ChoosingStyleBookStatusProjection implements IProjectionFor<ChoosingStyleBookStatusFluent> {
      @Override
      public void define(IProjectionBuilderFor<ChoosingStyleBookStatusFluent> builder) {
          builder
              .from(ChoosingStyleBookRegistered.class, fb -> {
                  fb.set("id").toEventSourceId();
                  fb.<String>set("title").to(e -> e.title());
                  fb.<String>set("isbn").to(e -> e.isbn());
                  fb.<Boolean>set("isBorrowed").to(e -> false);
                  fb.<String>set("borrowedBy").to(e -> null);
              })
              .from(ChoosingStyleBookBorrowed.class, fb -> {
                  fb.<Boolean>set("isBorrowed").to(e -> true);
                  fb.<String>set("borrowedBy").to(e -> e.memberName());
              })
              .from(ChoosingStyleBookReturned.class, fb -> {
                  fb.<Boolean>set("isBorrowed").to(e -> false);
                  fb.<String>set("borrowedBy").to(e -> null);
              });
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.ChoosingStyleBookStatusFluent do
    use Chronicle.ReadModels.ReadModel

defstruct id: "", title: "", isbn: "", is_borrowed: false, borrowed_by: nil
  end

defmodule MyApp.Projections.ChoosingStyleBookStatusProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.ChoosingStyleBookStatusFluent

from MyApp.Events.ChoosingStyleBookRegistered,
      set: [id: :event_source_id, title: :title, isbn: :isbn, is_borrowed: false, borrowed_by: nil]

from MyApp.Events.ChoosingStyleBookBorrowed,
      set: [is_borrowed: true, borrowed_by: :member_name]

from MyApp.Events.ChoosingStyleBookReturned,
      set: [is_borrowed: false, borrowed_by: nil]
  end
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

class ChoosingStyleBookStatusFluent {
      id = '';
      title = '';
      isbn = '';
      isBorrowed = false;
      borrowedBy: string | null = null;
  }

@projection()
  class ChoosingStyleBookStatusProjection implements IProjectionFor<ChoosingStyleBookStatusFluent> {
      define(builder: IProjectionBuilderFor<ChoosingStyleBookStatusFluent>): void {
          builder
              .from(ChoosingStyleBookRegistered, _ => _
                  .set(m => m.id).toEventSourceId()
                  .set(m => m.title).to(e => e.title)
                  .set(m => m.isbn).to(e => e.isbn)
                  .set(m => m.isBorrowed).toValue(false)
                  .set(m => m.borrowedBy).toValue(null))
              .from(ChoosingStyleBookBorrowed, _ => _
                  .set(m => m.isBorrowed).toValue(true)
                  .set(m => m.borrowedBy).to(e => e.memberName))
              .from(ChoosingStyleBookReturned, _ => _
                  .set(m => m.isBorrowed).toValue(false)
                  .set(m => m.borrowedBy).toValue(null));
      }
  }
  ```

This produces the same `BookStatus` documents as the model-bound version, but the trade-off is different: more code, more room for explicit mapping, and the read model stays free of Chronicle attributes. Use it when a projection needs joins, nested child mapping, event-context mapping, or naming/transformation logic that would make attributes hard to scan.

## Reducer: fold the events as code

[Section titled “Reducer: fold the events as code”](#reducer-fold-the-events-as-code)

Reducers build read models too, but the shape is imperative: Chronicle passes the event and the current state into a method, and you return the next state.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

public record ChoosingStyleBookStatusReducerModel(
      string Id,
      string Title,
      string Isbn,
      bool IsBorrowed,
      string? BorrowedBy);

public class ChoosingStyleBookStatusReducer : IReducerFor<ChoosingStyleBookStatusReducerModel>
  {
      public ChoosingStyleBookStatusReducerModel OnBookRegistered(
          ChoosingStyleBookRegistered @event,
          ChoosingStyleBookStatusReducerModel? current,
          EventContext context) =>
          new(
              Id: context.EventSourceId.Value,
              Title: @event.Title,
              Isbn: @event.Isbn,
              IsBorrowed: false,
              BorrowedBy: null);

public ChoosingStyleBookStatusReducerModel OnBookBorrowed(
          ChoosingStyleBookBorrowed @event,
          ChoosingStyleBookStatusReducerModel? current,
          EventContext context) =>
          current! with
          {
              IsBorrowed = true,
              BorrowedBy = @event.MemberName
          };

public ChoosingStyleBookStatusReducerModel OnBookReturned(
          ChoosingStyleBookReturned @event,
          ChoosingStyleBookStatusReducerModel? current,
          EventContext context) =>
          current! with
          {
              IsBorrowed = false,
              BorrowedBy = null
          };
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reducer

data class ChoosingStyleBookStatusReducerModel(
      val title: String = "",
      val isbn: String = "",
      val isBorrowed: Boolean = false,
      val borrowedBy: String? = null
  )

@Reducer
  class ChoosingStyleBookStatusReducer {
      fun choosingStyleBookRegistered(event: ChoosingStyleBookRegistered): ChoosingStyleBookStatusReducerModel =
          ChoosingStyleBookStatusReducerModel(
              title = event.title,
              isbn = event.isbn,
              isBorrowed = false,
              borrowedBy = null
          )

fun choosingStyleBookBorrowed(
          event: ChoosingStyleBookBorrowed,
          current: ChoosingStyleBookStatusReducerModel
      ): ChoosingStyleBookStatusReducerModel =
          current.copy(isBorrowed = true, borrowedBy = event.memberName)

fun choosingStyleBookReturned(
          event: ChoosingStyleBookReturned,
          current: ChoosingStyleBookStatusReducerModel
      ): ChoosingStyleBookStatusReducerModel =
          current.copy(isBorrowed = false, borrowedBy = null)
  }
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reducer;

record ChoosingStyleBookStatusReducerModel(
      String title,
      String isbn,
      boolean isBorrowed,
      String borrowedBy) {}

@Reducer
  class ChoosingStyleBookStatusReducer {
      ChoosingStyleBookStatusReducerModel choosingStyleBookRegistered(ChoosingStyleBookRegistered event) {
          return new ChoosingStyleBookStatusReducerModel(event.title(), event.isbn(), false, null);
      }

ChoosingStyleBookStatusReducerModel choosingStyleBookBorrowed(
          ChoosingStyleBookBorrowed event,
          ChoosingStyleBookStatusReducerModel current) {
          return new ChoosingStyleBookStatusReducerModel(
              current.title(), current.isbn(), true, event.memberName());
      }

ChoosingStyleBookStatusReducerModel choosingStyleBookReturned(
          ChoosingStyleBookReturned event,
          ChoosingStyleBookStatusReducerModel current) {
          return new ChoosingStyleBookStatusReducerModel(
              current.title(), current.isbn(), false, null);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.ChoosingStyleBookStatusReducerModel do
    defstruct title: "", isbn: "", is_borrowed: false, borrowed_by: nil
  end

defmodule MyApp.Reducers.ChoosingStyleBookStatusReducer do
    use Chronicle.Reducers.Reducer, model: MyApp.ReadModels.ChoosingStyleBookStatusReducerModel

alias MyApp.Events.{
      ChoosingStyleBookBorrowed,
      ChoosingStyleBookRegistered,
      ChoosingStyleBookReturned
    }

@handles ChoosingStyleBookRegistered
    @handles ChoosingStyleBookBorrowed
    @handles ChoosingStyleBookReturned

@impl true
    def reduce(%ChoosingStyleBookRegistered{} = event, _model, _context) do
      %MyApp.ReadModels.ChoosingStyleBookStatusReducerModel{
        title: event.title,
        isbn: event.isbn,
        is_borrowed: false,
        borrowed_by: nil
      }
    end

def reduce(%ChoosingStyleBookBorrowed{} = event, model, _context) do
      %{model | is_borrowed: true, borrowed_by: event.member_name}
    end

def reduce(%ChoosingStyleBookReturned{}, model, _context) do
      %{model | is_borrowed: false, borrowed_by: nil}
    end
  end
  ```

* TypeScript

```typescript
  import { reducer } from '@cratis/chronicle';

class ChoosingStyleBookStatusReducerModel {
      title = '';
      isbn = '';
      isBorrowed = false;
      borrowedBy: string | null = null;
  }

// Handler methods receive only the event and the current state - there is no
  // event-context parameter, unlike the C# reducer's EventContext argument.
  // The method name must be the exact camelCase of the event's class name -
  // Chronicle discovers handlers by name, not by parameter type.
  @reducer('', undefined, ChoosingStyleBookStatusReducerModel)
  class ChoosingStyleBookStatusReducer {
      choosingStyleBookRegistered(
          event: ChoosingStyleBookRegistered,
          current: ChoosingStyleBookStatusReducerModel | undefined
      ): ChoosingStyleBookStatusReducerModel {
          return {
              title: event.title,
              isbn: event.isbn,
              isBorrowed: false,
              borrowedBy: null
          };
      }

choosingStyleBookBorrowed(
          event: ChoosingStyleBookBorrowed,
          current: ChoosingStyleBookStatusReducerModel
      ): ChoosingStyleBookStatusReducerModel {
          return { ...current, isBorrowed: true, borrowedBy: event.memberName };
      }

choosingStyleBookReturned(
          event: ChoosingStyleBookReturned,
          current: ChoosingStyleBookStatusReducerModel
      ): ChoosingStyleBookStatusReducerModel {
          return { ...current, isBorrowed: false, borrowedBy: null };
      }
  }
  ```

> **TypeScript note:** the C# reducer also receives the `EventContext` (used above to read the event source ID into `Id`) — the TypeScript reducer’s handler methods only receive `(event, currentState)`, with no context parameter, so the TypeScript example omits the `Id` field.

This is still the same read model, but the expression is a fold over state rather than a projection definition. Reach for a reducer when the logic is easier to read as C#: branching, derived values, totals with guard logic, temporal state, or calculations that span several previous events.

## How they differ

[Section titled “How they differ”](#how-they-differ)

| Style                                                         | Mental model                                                    | Strength                                                                                  | Cost                                                                         |
| ------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [Model-bound projection](/chronicle/projections/model-bound/) | The read model declares how events fill its properties.         | Least code; best default for straightforward screen models.                               | Attributes can get dense when the mapping becomes complex.                   |
| [Declarative projection](/chronicle/projections/declarative/) | A separate projection definition maps events to the read model. | Explicit mapping, joins, nested structures, transformations, and a clean read model type. | More ceremony than attributes.                                               |
| [Reducer](/chronicle/reducers/)                               | Event plus current state returns next state.                    | Complex calculations and temporal logic read naturally as code.                           | More responsibility: handle missing current state and keep the reducer pure. |

Use the simplest style that keeps the intent obvious. Model-bound first, declarative when the mapping needs structure, reducer when the calculation reads better as a state transition.

## Testing the choice

[Section titled “Testing the choice”](#testing-the-choice)

You can exercise all three styles with the same [read-model scenario](/chronicle/testing/read-models/scenario/). The scenario discovers a model-bound projection, an `IProjectionFor<T>`, or an `IReducerFor<T>` for the read model type and runs the events in memory. That makes style changes cheap: rewrite the projection as a reducer, keep the same events and expected `BookStatus`, and the test tells you whether the behavior stayed the same.

# Declarative Projections

Declarative projections let you define read models with a fluent, code-first projection builder. They are ideal when you need explicit mapping, joins, or hierarchical projections that go beyond simple attribute mapping.

## Overview

[Section titled “Overview”](#overview)

Declarative projections implement `IProjectionFor<TReadModel>` and use an `IProjectionBuilderFor<TReadModel>` to define how events map to read model properties. The builder gives you control over mapping, relationships, and event context while keeping the projection definition separate from the read model type.

## Basic Example

[Section titled “Basic Example”](#basic-example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecIndexUserRegistered(string Name, string Email, DateTimeOffset RegisteredAt);

public record DecIndexUserProfile(string Name, string Email, DateTimeOffset RegisteredAt);

public class DecIndexUserProfileProjection : IProjectionFor<DecIndexUserProfile>
  {
      public void Define(IProjectionBuilderFor<DecIndexUserProfile> builder) => builder
          .From<DecIndexUserRegistered>();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor
  import java.time.OffsetDateTime

@EventType
  data class DecIndexUserRegistered(val name: String, val email: String, val registeredAt: OffsetDateTime)

data class DecIndexUserProfile(
      val name: String = "",
      val email: String = "",
      val registeredAt: OffsetDateTime? = null
  )

class DecIndexUserProfileProjection : IProjectionFor<DecIndexUserProfile> {
      override fun define(builder: IProjectionBuilderFor<DecIndexUserProfile>) {
          builder.from(DecIndexUserRegistered::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecIndexUserRegistered(String name, String email, String registeredAt) {}

class DecIndexUserProfile {
      public String name = "";
      public String email = "";
      public String registeredAt = null;
  }

class DecIndexUserProfileProjection implements IProjectionFor<DecIndexUserProfile> {
      @Override
      public void define(IProjectionBuilderFor<DecIndexUserProfile> builder) {
          builder.from(DecIndexUserRegistered.class);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.DecIndexUserRegistered do
    use Chronicle.Events.EventType, id: "dec-index-user-registered"

defstruct [:name, :email, :registered_at]
  end

defmodule MyApp.ReadModels.DecIndexUserProfile do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, :email, :registered_at]
  end

defmodule MyApp.Projections.DecIndexUserProfileProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecIndexUserProfile

alias MyApp.Events.DecIndexUserRegistered

from DecIndexUserRegistered
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecIndexUserRegistered {
      name = '';
      email = '';
      registeredAt = new Date();
  }

class DecIndexUserProfile {
      name = '';
      email = '';
      registeredAt = new Date();
  }

@projection()
  class DecIndexUserProfileProjection implements IProjectionFor<DecIndexUserProfile> {
      define(builder: IProjectionBuilderFor<DecIndexUserProfile>): void {
          builder.from(DecIndexUserRegistered);
      }
  }
  ```

Auto-mapping is enabled by default at the top level, so matching properties are mapped automatically. When you need explicit mappings, you can use `.Set()`, `.Add()`, `.Subtract()`, and other builder operations.

## Discovery

[Section titled “Discovery”](#discovery)

Projection types are discovered by implementing `IProjectionFor<TReadModel>`. Event types used in projection definitions must be marked with `[EventType]`.

## Key Features

[Section titled “Key Features”](#key-features)

* **Auto mapping by default** with the option to turn it off or override per event
* **Explicit property mappings** for custom transformations
* **Hierarchies** with child collections and nested projections
* **Joins** across streams for richer read models
* **FromEvery** for applying mappings to all events
* **Event context** access for timestamps, sequence numbers, and IDs
* **Event sequence selection** for sourcing from non-default sequences
* **Passive and not rewindable projections** for specialized observation behavior

## When to Use

[Section titled “When to Use”](#when-to-use)

Use declarative projections when:

* You need control over mapping logic and transformations
* You need relationships or hierarchical read models
* You want to share a projection definition across multiple read models

Use model-bound projections when:

* The mapping is straightforward and attribute-based
* You want to keep projection metadata close to the read model
* You prefer concise, declarative attributes over fluent definitions

## Projection recipes

[Section titled “Projection recipes”](#projection-recipes)

| Recipe                                                                       | Description                                       |
| ---------------------------------------------------------------------------- | ------------------------------------------------- |
| [Simple projection](/chronicle/projections/declarative/simple-projection/)   | Basic projection using AutoMap()                  |
| [AutoMap](/chronicle/projections/declarative/auto-map/)                      | Automatic property mapping at different levels    |
| [Passive](/chronicle/projections/declarative/passive/)                       | In-memory projections for on-demand lookups       |
| [Set properties](/chronicle/projections/declarative/set-properties/)         | Explicit property mapping and transformations     |
| [Children](/chronicle/projections/declarative/children/)                     | Hierarchical data models with child collections   |
| [Joins](/chronicle/projections/declarative/joins/)                           | Cross-stream projections using joins              |
| [Functions](/chronicle/projections/declarative/functions/)                   | Arithmetic and other functions                    |
| [Composite keys](/chronicle/projections/declarative/composite-keys/)         | Multi-property key identification                 |
| [Event context](/chronicle/projections/declarative/event-context/)           | Using event metadata in projections               |
| [FromEvery](/chronicle/projections/declarative/from-every/)                  | Setting properties for all events in a projection |
| [FromAll](/chronicle/projections/declarative/from-all/)                      | Subscribe to all event types without filtering    |
| [Initial values](/chronicle/projections/declarative/initial-values/)         | Default values for read model properties          |
| [RemoveWithJoin](/chronicle/projections/declarative/remove-with-join/)       | Cross-stream child removal                        |
| [FromEventSequence](/chronicle/projections/declarative/from-event-sequence/) | Sourcing events from specific event sequences     |
| [NotRewindable](/chronicle/projections/declarative/not-rewindable/)          | Forward-only projections that cannot be replayed  |

## Reading Your Declarative Projections

[Section titled “Reading Your Declarative Projections”](#reading-your-declarative-projections)

Once you’ve defined a declarative projection, you can retrieve and observe the resulting read models using the `IReadModels` API:

* [Getting a Single Instance](/chronicle/read-models/getting-single-instance/) - Retrieve a specific instance by key with strong consistency
* [Getting a Collection of Instances](/chronicle/read-models/getting-collection-instances/) - Retrieve all instances for reporting and analysis
* [Getting Snapshots](/chronicle/read-models/getting-snapshots/) - Retrieve historical state snapshots grouped by correlation ID
* [Watching Read Models](/chronicle/read-models/watching-read-models/) - Observe real-time changes as events are applied

## Key concepts

[Section titled “Key concepts”](#key-concepts)

### Auto-mapping vs explicit mapping

[Section titled “Auto-mapping vs explicit mapping”](#auto-mapping-vs-explicit-mapping)

* **Auto-mapping**: Automatically maps properties with matching names between events and read models

* Use `.AutoMap()` in fluent projections (`IProjectionFor<T>`)
  * Use `[FromEvent<TEvent>]` in model-bound projections for the same functionality

* **Explicit mapping**: Gives you full control over property transformations and mappings

* Use `.Set()`, `.Add()`, etc. in fluent projections
  * Use `[SetFrom<TEvent>]`, `[AddFrom<TEvent>]`, etc. in model-bound projections

### Event handling

[Section titled “Event handling”](#event-handling)

* Projections can handle multiple event types
* Each event type can have its own property mappings
* Properties are updated incrementally as events are processed

### Keys and identification

[Section titled “Keys and identification”](#keys-and-identification)

* **EventSourceId** is used as the default key for both read models and parent identification in child collections

* **Child identifiers**: Use `.IdentifiedBy()` to specify how child items are uniquely identified within collections

* **Parent key resolution**:

* By default, the EventSourceId is used to identify the parent when adding children
  * Use `.UsingParentKey(e => e.Property)` when the parent identifier is in the event content
  * Use `.UsingParentKeyFromContext(ctx => ctx.EventSourceId)` to explicitly document default behavior

* **Child key specification**: Use `.UsingKey(e => e.Property)` to extract the child identifier from event content

* **Joins**: Use keys to link data from different event streams using `.On(m => m.Property)`

### Performance

[Section titled “Performance”](#performance)

* Projections are automatically maintained as events are appended
* The system handles indexing and query optimization
* Consider join complexity and update frequency when designing projections

# Projection AutoMap

AutoMap maps event properties to read model properties when their names and types are compatible. It is the default behavior for declarative projections, so the usual projection only needs to say which events it consumes.

Use explicit mapping when the event shape and read model shape intentionally differ. Use the AutoMap controls when a projection should opt out of convention-based mapping for part of its definition and then opt back in later.

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

When event and read model property names match, declare the events and let AutoMap fill the matching properties.

* C#

AutoMap by convention

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record AutoMapUserCreated(string Name, string Email);

[EventType]
  public record AutoMapUserRenamed(string Name);

public record AutoMapUser(string Name, string Email);

public class AutoMapUserProjection : IProjectionFor<AutoMapUser>
  {
      public void Define(IProjectionBuilderFor<AutoMapUser> builder) => builder
          .From<AutoMapUserCreated>()
          .From<AutoMapUserRenamed>();
  }
  ```

* Kotlin

AutoMap by convention

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class AutoMapUserCreated(val name: String, val email: String)

@EventType
  data class AutoMapUserRenamed(val name: String)

data class AutoMapUser(val name: String = "", val email: String = "")

class AutoMapUserProjection : IProjectionFor<AutoMapUser> {
      override fun define(builder: IProjectionBuilderFor<AutoMapUser>) {
          builder
              .from(AutoMapUserCreated::class)
              .from(AutoMapUserRenamed::class)
      }
  }
  ```

* Java

AutoMap by convention

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record AutoMapUserCreated(String name, String email) {}

@EventType
  record AutoMapUserRenamed(String name) {}

class AutoMapUser {
      public String name = "";
      public String email = "";
  }

class AutoMapUserProjection implements IProjectionFor<AutoMapUser> {
      @Override
      public void define(IProjectionBuilderFor<AutoMapUser> builder) {
          builder.from(AutoMapUserCreated.class);
          builder.from(AutoMapUserRenamed.class);
      }
  }
  ```

* Elixir

AutoMap by convention

```elixir
  defmodule MyApp.Events.AutoMapUserCreated do
    use Chronicle.Events.EventType, id: "auto-map-user-created"

defstruct [:name, :email]
  end

defmodule MyApp.Events.AutoMapUserRenamed do
    use Chronicle.Events.EventType, id: "auto-map-user-renamed"

defstruct [:name]
  end

defmodule MyApp.ReadModels.AutoMapUser do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, :email]
  end

defmodule MyApp.Projections.AutoMapUserProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.AutoMapUser

alias MyApp.Events.{AutoMapUserCreated, AutoMapUserRenamed}

from AutoMapUserCreated
    from AutoMapUserRenamed
  end
  ```

* TypeScript

AutoMap by convention

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class AutoMapUserCreated {
      constructor(readonly name: string, readonly email: string) {}
  }

@eventType()
  class AutoMapUserRenamed {
      constructor(readonly name: string) {}
  }

@readModel()
  class AutoMapUser {
      name = '';
      email = '';
  }

@projection('', AutoMapUser)
  class AutoMapUserProjection implements IProjectionFor<AutoMapUser> {
      define(builder: IProjectionBuilderFor<AutoMapUser>): void {
          builder
              .from(AutoMapUserCreated)
              .from(AutoMapUserRenamed);
      }
  }
  ```

## How AutoMap Works

[Section titled “How AutoMap Works”](#how-automap-works)

AutoMap applies the same convention to every event handled by the projection:

| Rule              | Behavior                                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| Property names    | Event and read model property names must match after the client’s serialization naming policy is applied. |
| Property types    | Values must be assignable to the read model property type.                                                |
| Explicit mappings | Explicit mappings handle properties that do not match by convention.                                      |
| Scope             | A projection can disable or re-enable AutoMap for the builder scope that the client supports.             |

AutoMap is evaluated when the projection definition is built. It does not add a per-event reflection step while projections process events.

## Disable AutoMap

[Section titled “Disable AutoMap”](#disable-automap)

Disable AutoMap when a projection should map only the properties you name explicitly.

* C#

Disable AutoMap

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record AutoMapDisabledAccountRegistered(string AccountName, string ContactEmail);

public record AutoMapDisabledAccount(
      string Name,
      string Email,
      DateTimeOffset CreatedAt);

public class AutoMapDisabledAccountProjection : IProjectionFor<AutoMapDisabledAccount>
  {
      public void Define(IProjectionBuilderFor<AutoMapDisabledAccount> builder) => builder
          .NoAutoMap()
          .From<AutoMapDisabledAccountRegistered>(_ => _
              .Set(m => m.Name).To(e => e.AccountName)
              .Set(m => m.Email).To(e => e.ContactEmail)
              .Set(m => m.CreatedAt).ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

Disable AutoMap

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class AutoMapDisabledAccountRegistered(val accountName: String, val contactEmail: String)

data class AutoMapDisabledAccount(
      val name: String = "",
      val email: String = "",
      val createdAt: String = ""
  )

class AutoMapDisabledAccountProjection : IProjectionFor<AutoMapDisabledAccount> {
      override fun define(builder: IProjectionBuilderFor<AutoMapDisabledAccount>) {
          builder
              .noAutoMap()
              .from(AutoMapDisabledAccountRegistered::class) {
                  it.set(AutoMapDisabledAccount::name).toProperty("accountName")
                  it.set(AutoMapDisabledAccount::email).toProperty("contactEmail")
                  it.set(AutoMapDisabledAccount::createdAt).toEventContextProperty("occurred")
              }
      }
  }
  ```

* Java

Disable AutoMap

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record AutoMapDisabledAccountRegistered(String accountName, String contactEmail) {}

class AutoMapDisabledAccount {
      public String name = "";
      public String email = "";
      public String createdAt = "";
  }

class AutoMapDisabledAccountProjection implements IProjectionFor<AutoMapDisabledAccount> {
      @Override
      public void define(IProjectionBuilderFor<AutoMapDisabledAccount> builder) {
          builder
              .noAutoMap()
              .from(AutoMapDisabledAccountRegistered.class, fb -> {
                  fb.set("name").toProperty("accountName");
                  fb.set("email").toProperty("contactEmail");
                  fb.set("createdAt").toEventContextProperty("occurred");
              });
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.AutoMapDisabledAccountRegistered do
    use Chronicle.Events.EventType, id: "auto-map-disabled-account-registered"

defstruct [:account_name, :contact_email]
  end

defmodule MyApp.ReadModels.AutoMapDisabledAccount do
    use Chronicle.ReadModels.ReadModel

defstruct name: nil, email: nil, created_at: nil

# Nothing is mapped by name - every property has to be stated.
    no_auto_map()

from MyApp.Events.AutoMapDisabledAccountRegistered,
      set: [
        name: :account_name,
        email: :contact_email,
        created_at: :occurred
      ]
  end
  ```

* TypeScript

Disable AutoMap

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class AutoMapDisabledAccountRegistered {
      constructor(readonly accountName: string, readonly contactEmail: string) {}
  }

@readModel()
  class AutoMapDisabledAccount {
      name = '';
      email = '';
      createdAt = new Date(0);
  }

@projection('', AutoMapDisabledAccount)
  class AutoMapDisabledAccountProjection implements IProjectionFor<AutoMapDisabledAccount> {
      define(builder: IProjectionBuilderFor<AutoMapDisabledAccount>): void {
          builder
              .noAutoMap()
              .from(AutoMapDisabledAccountRegistered, _ => _
                  .set(m => m.name).to(e => e.accountName)
                  .set(m => m.email).to(e => e.contactEmail)
                  .set(m => m.createdAt).toEventContextProperty('occurred'));
      }
  }
  ```

## Re-enable AutoMap In A Child Scope

[Section titled “Re-enable AutoMap In A Child Scope”](#re-enable-automap-in-a-child-scope)

Calling the AutoMap enable method is redundant at the top level. It is useful in a child builder scope when the parent projection has disabled AutoMap and the child scope should opt back in.

Client coverage

This scoped re-enable only makes sense in a client that supports child projection scopes at all. Kotlin, Java, Elixir, and TypeScript do not yet support declarative child collections (see [Children](/chronicle/projections/declarative/children/)), so there is no child builder scope to re-enable AutoMap on. This example is C#-only until child projection scopes land elsewhere.

* C#

Re-enable AutoMap for children

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record AutoMapTeamFormed(string TeamName);

[EventType]
  public record AutoMapMemberJoinedTeam(string MemberId, string DisplayName);

public record AutoMapTeamMember(string MemberId, string DisplayName);

public record AutoMapTeam(
      string Name,
      DateTimeOffset CreatedAt,
      IEnumerable<AutoMapTeamMember> Members);

public class AutoMapTeamProjection : IProjectionFor<AutoMapTeam>
  {
      public void Define(IProjectionBuilderFor<AutoMapTeam> builder) => builder
          .NoAutoMap()
          .From<AutoMapTeamFormed>(_ => _
              .Set(m => m.Name).To(e => e.TeamName)
              .Set(m => m.CreatedAt).ToEventContextProperty(c => c.Occurred))
          .Children(m => m.Members, children => children
              .IdentifiedBy(m => m.MemberId)
              .AutoMap()
              .From<AutoMapMemberJoinedTeam>(_ => _
                  .UsingKey(e => e.MemberId)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `IProjectionBuilderFor` has no AutoMap toggle at all — no `noAutoMap()`/`autoMap()` method on the
  builder or on `IChildrenBuilderFor`, so there is no child scope to re-enable AutoMap on.
  ```

* Java

```text
  Java does not support this workflow yet.
  `IProjectionBuilderFor` has no AutoMap toggle at all — no `noAutoMap()`/`autoMap()` method on the
  builder or on `IChildrenBuilderFor`, so there is no child scope to re-enable AutoMap on.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class AutoMapTeamFormed {
      constructor(readonly teamName: string) {}
  }

@eventType()
  class AutoMapMemberJoinedTeam {
      constructor(readonly memberId: string, readonly displayName: string) {}
  }

class AutoMapTeamMember {
      memberId = '';
      displayName = '';
  }

class AutoMapTeam {
      name = '';
      createdAt = new Date();
      members: AutoMapTeamMember[] = [];
  }

@projection()
  class AutoMapTeamProjection implements IProjectionFor<AutoMapTeam> {
      define(builder: IProjectionBuilderFor<AutoMapTeam>): void {
          builder
              .noAutoMap()
              .from(AutoMapTeamFormed, _ => _
                  .set(m => m.name).to(e => e.teamName)
                  .set(m => m.createdAt).toEventContextProperty('occurred'))
              .children<AutoMapTeamMember>(m => m.members, children => children
                  .identifiedBy(m => m.memberId)
                  .autoMap()
                  .from(AutoMapMemberJoinedTeam, _ => _
                      .usingKey(e => e.memberId)));
      }
  }
  ```

## Combine With Explicit Mappings

[Section titled “Combine With Explicit Mappings”](#combine-with-explicit-mappings)

AutoMap and explicit mappings can be used together. Let convention handle the properties that match, and map the exceptional properties directly.

* C#

AutoMap with explicit mappings

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record AutoMapAccountOpened(string Name, string Email);

[EventType]
  public record AutoMapAccountEmailChanged(string Email);

public record AutoMapAccount(
      string Name,
      string Email,
      string Status,
      DateTimeOffset CreatedAt);

public class AutoMapAccountProjection : IProjectionFor<AutoMapAccount>
  {
      public void Define(IProjectionBuilderFor<AutoMapAccount> builder) => builder
          .From<AutoMapAccountOpened>(_ => _
              .Set(m => m.Status).ToValue("Active")
              .Set(m => m.CreatedAt).ToEventContextProperty(c => c.Occurred))
          .From<AutoMapAccountEmailChanged>();
  }
  ```

* Kotlin

AutoMap with explicit mappings

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class AutoMapAccountOpened(val name: String, val email: String)

@EventType
  data class AutoMapAccountEmailChanged(val email: String)

data class AutoMapAccount(
      val name: String = "",
      val email: String = "",
      val status: String = ""
  )

class AutoMapAccountProjection : IProjectionFor<AutoMapAccount> {
      override fun define(builder: IProjectionBuilderFor<AutoMapAccount>) {
          builder
              .from(AutoMapAccountOpened::class) {
                  it.set(AutoMapAccount::status).to { "Active" }
              }
              .from(AutoMapAccountEmailChanged::class)
      }
  }
  ```

* Java

AutoMap with explicit mappings

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record AutoMapAccountOpened(String name, String email) {}

@EventType
  record AutoMapAccountEmailChanged(String email) {}

class AutoMapAccount {
      public String name = "";
      public String email = "";
      public String status = "";
  }

class AutoMapAccountProjection implements IProjectionFor<AutoMapAccount> {
      @Override
      public void define(IProjectionBuilderFor<AutoMapAccount> builder) {
          builder
              .from(AutoMapAccountOpened.class, fb -> {
                  fb.<String>set("status").to(e -> "Active");
              })
              .from(AutoMapAccountEmailChanged.class);
      }
  }
  ```

* Elixir

AutoMap with explicit mappings

```elixir
  defmodule MyApp.Events.AutoMapAccountOpened do
    use Chronicle.Events.EventType, id: "auto-map-account-opened"

defstruct [:name, :email]
  end

defmodule MyApp.Events.AutoMapAccountEmailChanged do
    use Chronicle.Events.EventType, id: "auto-map-account-email-changed"

defstruct [:email]
  end

defmodule MyApp.ReadModels.AutoMapAccount do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, :email, :status, :created_at]
  end

defmodule MyApp.Projections.AutoMapAccountProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.AutoMapAccount

alias MyApp.Events.{AutoMapAccountEmailChanged, AutoMapAccountOpened}

# `name` and `email` are mapped automatically by AutoMap; only the
    # exceptions below need an explicit set:.
    from AutoMapAccountOpened,
      set: [
        status: "$value(Active)",
        created_at: :occurred
      ]

# Uses AutoMap for `email` — no set: list needed.
    from AutoMapAccountEmailChanged
  end
  ```

* TypeScript

AutoMap with explicit mappings

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class AutoMapAccountOpened {
      constructor(readonly name: string, readonly email: string) {}
  }

@eventType()
  class AutoMapAccountEmailChanged {
      constructor(readonly email: string) {}
  }

@readModel()
  class AutoMapAccount {
      name = '';
      email = '';
      status = '';
      createdAt = new Date(0);
  }

@projection('', AutoMapAccount)
  class AutoMapAccountProjection implements IProjectionFor<AutoMapAccount> {
      define(builder: IProjectionBuilderFor<AutoMapAccount>): void {
          builder
              .from(AutoMapAccountOpened, _ => _
                  .set(m => m.status).toValue('Active')
                  .set(m => m.createdAt).toEventContextProperty('occurred'))
              .from(AutoMapAccountEmailChanged);
      }
  }
  ```

## AutoMap With Joins

[Section titled “AutoMap With Joins”](#automap-with-joins)

Joined events can also contribute matching properties through AutoMap. Use the join condition to connect the joined event to the read model; matching joined-event properties can then flow into the model.

* C#

AutoMap with a join

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record AutoMapEmployeeHired(string EmployeeName, string DepartmentId);

[EventType]
  public record AutoMapDepartmentRenamed(string DepartmentName);

public record AutoMapEmployee(
      string EmployeeName,
      string DepartmentId,
      string DepartmentName);

public class AutoMapEmployeeProjection : IProjectionFor<AutoMapEmployee>
  {
      public void Define(IProjectionBuilderFor<AutoMapEmployee> builder) => builder
          .From<AutoMapEmployeeHired>()
          .Join<AutoMapDepartmentRenamed>(_ => _
              .On(m => m.DepartmentId));
  }
  ```

* Kotlin

AutoMap with a join

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class AutoMapEmployeeHired(val employeeName: String, val departmentId: String)

@EventType
  data class AutoMapDepartmentRenamed(val departmentName: String)

data class AutoMapEmployee(
      val employeeName: String = "",
      val departmentId: String = "",
      val departmentName: String = ""
  )

class AutoMapEmployeeProjection : IProjectionFor<AutoMapEmployee> {
      override fun define(builder: IProjectionBuilderFor<AutoMapEmployee>) {
          builder
              .from(AutoMapEmployeeHired::class)
              .join(AutoMapDepartmentRenamed::class) {
                  it.on(AutoMapEmployee::departmentId)
              }
      }
  }
  ```

* Java

AutoMap with a join

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record AutoMapEmployeeHired(String employeeName, String departmentId) {}

@EventType
  record AutoMapDepartmentRenamed(String departmentName) {}

class AutoMapEmployee {
      public String employeeName = "";
      public String departmentId = "";
      public String departmentName = "";
  }

class AutoMapEmployeeProjection implements IProjectionFor<AutoMapEmployee> {
      @Override
      public void define(IProjectionBuilderFor<AutoMapEmployee> builder) {
          builder
              .from(AutoMapEmployeeHired.class)
              .join(AutoMapDepartmentRenamed.class, jb -> {
                  jb.on("departmentId");
              });
      }
  }
  ```

* Elixir

AutoMap with a join

```elixir
  defmodule MyApp.Events.AutoMapEmployeeHired do
    use Chronicle.Events.EventType, id: "auto-map-employee-hired"

defstruct [:employee_name, :department_id]
  end

defmodule MyApp.Events.AutoMapDepartmentRenamed do
    use Chronicle.Events.EventType, id: "auto-map-department-renamed"

defstruct [:department_name]
  end

defmodule MyApp.ReadModels.AutoMapEmployee do
    use Chronicle.ReadModels.ReadModel

defstruct [:employee_name, :department_id, :department_name]
  end

defmodule MyApp.Projections.AutoMapEmployeeProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.AutoMapEmployee

alias MyApp.Events.{AutoMapEmployeeHired, AutoMapDepartmentRenamed}

from AutoMapEmployeeHired

join AutoMapDepartmentRenamed, on: :department_id
  end
  ```

* TypeScript

AutoMap with a join

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class AutoMapEmployeeHired {
      constructor(readonly employeeName: string, readonly departmentId: string) {}
  }

@eventType()
  class AutoMapDepartmentRenamed {
      constructor(readonly departmentName: string) {}
  }

@readModel()
  class AutoMapEmployee {
      employeeName = '';
      departmentId = '';
      departmentName = '';
  }

@projection('', AutoMapEmployee)
  class AutoMapEmployeeProjection implements IProjectionFor<AutoMapEmployee> {
      define(builder: IProjectionBuilderFor<AutoMapEmployee>): void {
          builder
              .from(AutoMapEmployeeHired)
              .join(AutoMapDepartmentRenamed, _ => _
                  .on(m => m.departmentId));
      }
  }
  ```

## Aggregate-Only Events

[Section titled “Aggregate-Only Events”](#aggregate-only-events)

An event a projection subscribes to **only to aggregate** — `Count`, `Increment`, `Decrement`, `Add`, or `Subtract` — does not contribute its other properties to AutoMap. Aggregating an event does not copy its unrelated fields onto the read model, so a property on it that happens to share a name with one you set from another event cannot overwrite that value. You do not need to disable AutoMap for this — it is the default behavior.

* C#

Aggregating an event does not map its other properties

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DeclAggArrangementSet(string Location);

[EventType]
  public record DeclAggCandidateSubmitted(string Name, string Location);

public record DeclAggAssignmentSummary(string Location, int CandidateCount);

public class DeclAggAssignmentProjection : IProjectionFor<DeclAggAssignmentSummary>
  {
      public void Define(IProjectionBuilderFor<DeclAggAssignmentSummary> builder) => builder
          .From<DeclAggArrangementSet>()
          .From<DeclAggCandidateSubmitted>(_ => _
              .Count(m => m.CandidateCount));
  }
  ```

* Kotlin

Aggregating an event does not map its other properties

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DeclAggArrangementSet(val location: String)

@EventType
  data class DeclAggCandidateSubmitted(val name: String, val location: String)

data class DeclAggAssignmentSummary(val location: String = "", val candidateCount: Int = 0)

class DeclAggAssignmentProjection : IProjectionFor<DeclAggAssignmentSummary> {
      override fun define(builder: IProjectionBuilderFor<DeclAggAssignmentSummary>) {
          builder
              .from(DeclAggArrangementSet::class)
              .from(DeclAggCandidateSubmitted::class) {
                  it.count(DeclAggAssignmentSummary::candidateCount)
              }
      }
  }
  ```

* Java

Aggregating an event does not map its other properties

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DeclAggArrangementSet(String location) {}

@EventType
  record DeclAggCandidateSubmitted(String name, String location) {}

class DeclAggAssignmentSummary {
      public String location = "";
      public int candidateCount = 0;
  }

class DeclAggAssignmentProjection implements IProjectionFor<DeclAggAssignmentSummary> {
      @Override
      public void define(IProjectionBuilderFor<DeclAggAssignmentSummary> builder) {
          builder
              .from(DeclAggArrangementSet.class)
              .from(DeclAggCandidateSubmitted.class, fb -> {
                  fb.count("candidateCount");
              });
      }
  }
  ```

* Elixir

Aggregating an event does not map its other properties

```elixir
  defmodule MyApp.Events.DeclAggArrangementSet do
    use Chronicle.Events.EventType, id: "decl-agg-arrangement-set-v1"

defstruct [:location]
  end

defmodule MyApp.Events.DeclAggCandidateSubmitted do
    use Chronicle.Events.EventType, id: "decl-agg-candidate-submitted-v1"

defstruct [:name, :location]
  end

defmodule MyApp.ReadModels.DeclAggAssignmentSummary do
    use Chronicle.ReadModels.ReadModel

defstruct [:location, candidate_count: 0]
  end

defmodule MyApp.Projections.DeclAggAssignmentProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DeclAggAssignmentSummary

alias MyApp.Events.{DeclAggArrangementSet, DeclAggCandidateSubmitted}

from DeclAggArrangementSet

# DeclAggCandidateSubmitted is subscribed only to be counted, so its own
    # `location` field is never mapped over the value set from
    # DeclAggArrangementSet.
    from DeclAggCandidateSubmitted, count: :candidate_count
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DeclAggArrangementSet {
      constructor(readonly location: string) {}
  }

@eventType()
  class DeclAggCandidateSubmitted {
      constructor(readonly name: string, readonly location: string) {}
  }

class DeclAggAssignmentSummary {
      location = '';
      candidateCount = 0;
  }

@projection()
  class DeclAggAssignmentProjection implements IProjectionFor<DeclAggAssignmentSummary> {
      define(builder: IProjectionBuilderFor<DeclAggAssignmentSummary>): void {
          builder
              .from(DeclAggArrangementSet)
              .from(DeclAggCandidateSubmitted, _ => _
                  .count(m => m.candidateCount));
      }
  }
  ```

## When To Use AutoMap

[Section titled “When To Use AutoMap”](#when-to-use-automap)

Use AutoMap when:

* Event property names match read model property names.
* The property types are directly compatible.
* The projection follows stable naming conventions.
* The read model should reflect the event shape without transformation.

Use explicit mappings when:

* Property names differ.
* A constant, event context field, or event source id should be mapped.
* The projection increments, decrements, counts, or combines values.
* You want a projection definition that documents every mapped property.

## Related Projection Shapes

[Section titled “Related Projection Shapes”](#related-projection-shapes)

Child and nested projections can have their own AutoMap behavior in clients that support those builder scopes. Use the dedicated pages for those shapes:

* [Children](/chronicle/projections/declarative/children/)
* [Nested objects](/chronicle/projections/declarative/nested/)
* [Set properties](/chronicle/projections/declarative/set-properties/)

# Projection with children

Projections can manage hierarchical data by defining child collections. This allows you to build read models that contain arrays or lists of related data.

Client coverage

Declarative child-collection builders (`Children()`/`IdentifiedBy()`/`RemovedWith()`) are currently a C#-only mechanism. Kotlin and Java have no fluent child-collection API at all, TypeScript’s builder throws `not implemented yet` for this method, and Elixir has no verified, working pattern for embedding a child collection into a parent read model. The examples on this page are shown in C# only until child projection scopes are implemented for the other clients.

## Defining a projection with children

[Section titled “Defining a projection with children”](#defining-a-projection-with-children)

Use the child-collection builder to select the collection property, declare how each child is identified, and map the events that add, update, or remove items.

* C#

Projection with children

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record GroupCreatedForChildren(string Name, string Description);

[EventType]
  public record UserAddedToGroupForChildren(string UserId, string Role);

[EventType]
  public record UserRoleChangedForChildren(string UserId, string Role);

[EventType]
  public record UserRemovedFromGroupForChildren(string UserId);

public record GroupForChildren(
      string Name,
      string Description,
      IEnumerable<GroupMemberForChildren> Members);

public record GroupMemberForChildren(
      string UserId,
      string Role);

public class GroupProjectionForChildren : IProjectionFor<GroupForChildren>
  {
      public void Define(IProjectionBuilderFor<GroupForChildren> builder) => builder
          .From<GroupCreatedForChildren>()
          .Children(m => m.Members, children => children
              .IdentifiedBy(m => m.UserId)
              .From<UserAddedToGroupForChildren>(b => b
                  .UsingKey(e => e.UserId))
              .From<UserRoleChangedForChildren>(b => b
                  .UsingKey(e => e.UserId))
              .RemovedWith<UserRemovedFromGroupForChildren>(b => b
                  .UsingKey(e => e.UserId)));
  }
  ```

* Kotlin

Projection with children

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class GroupCreatedForChildren(val name: String, val description: String)

@EventType
  data class UserAddedToGroupForChildren(val userId: String, val role: String)

@EventType
  data class UserRoleChangedForChildren(val userId: String, val role: String)

data class GroupForChildren(
      val name: String = "",
      val description: String = "",
      val members: List<GroupMemberForChildren> = emptyList()
  )

data class GroupMemberForChildren(
      val userId: String = "",
      val role: String = ""
  )

class GroupProjectionForChildren : IProjectionFor<GroupForChildren> {
      override fun define(builder: IProjectionBuilderFor<GroupForChildren>) {
          builder
              .from(GroupCreatedForChildren::class)
              .children(GroupForChildren::members, GroupMemberForChildren::class) { children ->
                  children
                      .identifiedBy("userId")
                      .from(UserAddedToGroupForChildren::class) { it.usingKey("userId") }
                      .from(UserRoleChangedForChildren::class) { it.usingKey("userId") }
              }
      }
  }
  ```

* Java

Projection with children

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.util.List;

@EventType
  record GroupCreatedForChildren(String name, String description) {}

@EventType
  record UserAddedToGroupForChildren(String userId, String role) {}

@EventType
  record UserRoleChangedForChildren(String userId, String role) {}

record GroupForChildren(String name, String description, List<GroupMemberForChildren> members) {}

record GroupMemberForChildren(String userId, String role) {}

class GroupProjectionForChildren implements IProjectionFor<GroupForChildren> {
      @Override
      public void define(IProjectionBuilderFor<GroupForChildren> builder) {
          builder
              .from(GroupCreatedForChildren.class)
              .children("members", GroupMemberForChildren.class, children -> {
                  children
                      .identifiedBy("userId")
                      .from(UserAddedToGroupForChildren.class, fb -> {
                          fb.usingKey("userId");
                      })
                      .from(UserRoleChangedForChildren.class, fb -> {
                          fb.usingKey("userId");
                      });
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class GroupCreatedForChildren {
      constructor(readonly name: string, readonly description: string) {}
  }

@eventType()
  class UserAddedToGroupForChildren {
      constructor(readonly userId: string, readonly role: string) {}
  }

@eventType()
  class UserRoleChangedForChildren {
      constructor(readonly userId: string, readonly role: string) {}
  }

@eventType()
  class UserRemovedFromGroupForChildren {
      constructor(readonly userId: string) {}
  }

class GroupMemberForChildren {
      userId = '';
      role = '';
  }

class GroupForChildren {
      name = '';
      description = '';
      members: GroupMemberForChildren[] = [];
  }

@projection()
  class GroupProjectionForChildren implements IProjectionFor<GroupForChildren> {
      define(builder: IProjectionBuilderFor<GroupForChildren>): void {
          builder
              .from(GroupCreatedForChildren)
              .children<GroupMemberForChildren>(m => m.members, children => children
                  .identifiedBy(m => m.userId)
                  .from(UserAddedToGroupForChildren, b => b
                      .usingKey(e => e.userId))
                  .from(UserRoleChangedForChildren, b => b
                      .usingKey(e => e.userId))
                  .removedWith(UserRemovedFromGroupForChildren, b => b
                      .usingKey(e => e.userId)));
      }
  }
  ```

## Read model with children

[Section titled “Read model with children”](#read-model-with-children)

The read model includes a collection property for the children:

* C#

Read model with children

```csharp
  public record GroupWithMembers(
      string Name,
      string Description,
      IEnumerable<GroupMember> Members);

public record GroupMember(
      string UserId,
      string Role);
  ```

* Kotlin

Read model with children

```kotlin
  data class GroupWithMembers(
      val name: String = "",
      val description: String = "",
      val members: List<GroupMember> = emptyList()
  )

data class GroupMember(
      val userId: String = "",
      val role: String = ""
  )
  ```

* Java

Read model with children

```java
  import java.util.List;

record GroupWithMembers(String name, String description, List<GroupMember> members) {}

record GroupMember(String userId, String role) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  class GroupMember {
      userId = '';
      role = '';
  }

class GroupWithMembers {
      name = '';
      description = '';
      members: GroupMember[] = [];
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

Events that affect children use keys to identify which child to update:

* C#

Child lifecycle events

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record GroupCreatedForChildEvents(string Name, string Description);

[EventType]
  public record UserAddedToGroupForChildEvents(string UserId, string Role);

[EventType]
  public record UserRoleChangedForChildEvents(string UserId, string Role);

[EventType]
  public record UserRemovedFromGroupForChildEvents(string UserId);
  ```

* Kotlin

Child lifecycle events

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class GroupCreatedForChildEvents(val name: String, val description: String)

@EventType
  data class UserAddedToGroupForChildEvents(val userId: String, val role: String)

@EventType
  data class UserRoleChangedForChildEvents(val userId: String, val role: String)

@EventType
  data class UserRemovedFromGroupForChildEvents(val userId: String)
  ```

* Java

Child lifecycle events

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record GroupCreatedForChildEvents(String name, String description) {}

@EventType
  record UserAddedToGroupForChildEvents(String userId, String role) {}

@EventType
  record UserRoleChangedForChildEvents(String userId, String role) {}

@EventType
  record UserRemovedFromGroupForChildEvents(String userId) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class GroupCreatedForChildEvents {
      constructor(readonly name: string, readonly description: string) {}
  }

@eventType()
  class UserAddedToGroupForChildEvents {
      constructor(readonly userId: string, readonly role: string) {}
  }

@eventType()
  class UserRoleChangedForChildEvents {
      constructor(readonly userId: string, readonly role: string) {}
  }

@eventType()
  class UserRemovedFromGroupForChildEvents {
      constructor(readonly userId: string) {}
  }
  ```

## How children work

[Section titled “How children work”](#how-children-work)

1. **Root events** (`GroupCreated`) update properties on the main read model
2. **Child events** (`UserAddedToGroup`, `UserRoleChanged`) are routed to child items
3. `IdentifiedBy()` specifies how to identify child items (by `UserId` in this example)
4. `UsingKey()` tells the projection which property contains the child identifier
5. Child items are created, updated, or remain unchanged based on the events

## Parent key resolution

[Section titled “Parent key resolution”](#parent-key-resolution)

By default, when a child event is processed, the framework uses the **EventSourceId** to identify the parent. This works well when the event is appended with the parent’s identifier as the EventSourceId.

### Default behavior (EventSourceId as parent key)

[Section titled “Default behavior (EventSourceId as parent key)”](#default-behavior-eventsourceid-as-parent-key)

In most scenarios, you don’t need to specify the parent key explicitly:

* C#

Default parent key

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record GroupCreatedWithDefaultParentKey(string Name);

[EventType]
  public record UserAddedWithDefaultParentKey(string UserId, string Role);

public record GroupWithDefaultParentKey(
      string Name,
      IEnumerable<GroupMemberWithDefaultParentKey> Members);

public record GroupMemberWithDefaultParentKey(
      string UserId,
      string Role);

public class GroupWithDefaultParentKeyProjection : IProjectionFor<GroupWithDefaultParentKey>
  {
      public void Define(IProjectionBuilderFor<GroupWithDefaultParentKey> builder) => builder
          .From<GroupCreatedWithDefaultParentKey>()
          .Children(m => m.Members, children => children
              .IdentifiedBy(m => m.UserId)
              .From<UserAddedWithDefaultParentKey>(b => b
                  .UsingKey(e => e.UserId)));
  }
  ```

* Kotlin

Default parent key

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class GroupCreatedWithDefaultParentKey(val name: String)

@EventType
  data class UserAddedWithDefaultParentKey(val userId: String, val role: String)

data class GroupWithDefaultParentKey(
      val name: String = "",
      val members: List<GroupMemberWithDefaultParentKey> = emptyList()
  )

data class GroupMemberWithDefaultParentKey(
      val userId: String = "",
      val role: String = ""
  )

class GroupWithDefaultParentKeyProjection : IProjectionFor<GroupWithDefaultParentKey> {
      override fun define(builder: IProjectionBuilderFor<GroupWithDefaultParentKey>) {
          builder
              .from(GroupCreatedWithDefaultParentKey::class)
              .children(GroupWithDefaultParentKey::members, GroupMemberWithDefaultParentKey::class) { children ->
                  children
                      .identifiedBy("userId")
                      .from(UserAddedWithDefaultParentKey::class) { it.usingKey("userId") }
              }
      }
  }
  ```

* Java

Default parent key

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.util.List;

@EventType
  record GroupCreatedWithDefaultParentKey(String name) {}

record GroupWithDefaultParentKey(String name, List<GroupMemberWithDefaultParentKey> members) {}

record GroupMemberWithDefaultParentKey(String userId, String role) {}

class GroupWithDefaultParentKeyProjection implements IProjectionFor<GroupWithDefaultParentKey> {
      @Override
      public void define(IProjectionBuilderFor<GroupWithDefaultParentKey> builder) {
          builder
              .from(GroupCreatedWithDefaultParentKey.class)
              .children("members", GroupMemberWithDefaultParentKey.class, children -> {
                  children
                      .identifiedBy("userId")
                      .from(UserAddedWithDefaultParentKey.class, fb -> {
                          fb.usingKey("userId");
                      });
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class GroupCreatedWithDefaultParentKey {
      constructor(readonly name: string) {}
  }

@eventType()
  class UserAddedWithDefaultParentKey {
      constructor(readonly userId: string, readonly role: string) {}
  }

class GroupMemberWithDefaultParentKey {
      userId = '';
      role = '';
  }

class GroupWithDefaultParentKey {
      name = '';
      members: GroupMemberWithDefaultParentKey[] = [];
  }

@projection()
  class GroupWithDefaultParentKeyProjection implements IProjectionFor<GroupWithDefaultParentKey> {
      define(builder: IProjectionBuilderFor<GroupWithDefaultParentKey>): void {
          builder
              .from(GroupCreatedWithDefaultParentKey)
              .children<GroupMemberWithDefaultParentKey>(m => m.members, children => children
                  .identifiedBy(m => m.userId)
                  .from(UserAddedWithDefaultParentKey, b => b
                      .usingKey(e => e.userId)));
      }
  }
  ```

When you append the event:

* C#

Append child event to parent

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class GroupMembershipWithDefaultParentKey(IEventStore eventStore)
  {
      public Task AddUserToGroup(EventSourceId groupId, string userId, string role) =>
          eventStore.EventLog.Append(groupId, new UserAddedWithDefaultParentKey(userId, role));
  }
  ```

* Kotlin

Append child event to parent

```kotlin
  import io.cratis.chronicle.IEventStore

class GroupMembershipWithDefaultParentKey(private val eventStore: IEventStore) {
      suspend fun addUserToGroup(groupId: String, userId: String, role: String) =
          eventStore.eventLog.append(groupId, UserAddedWithDefaultParentKey(userId, role))
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
  record UserAddedWithDefaultParentKey(String userId, String role) {}

class GroupMembershipWithDefaultParentKey {
      private final EventStore eventStore;

GroupMembershipWithDefaultParentKey(EventStore eventStore) {
          this.eventStore = eventStore;
      }

void addUserToGroup(String groupId, String userId, String role) {
          EventLogJavaBridge.append(eventStore.getEventLog(), groupId, new UserAddedWithDefaultParentKey(userId, role), null);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

class GroupMembershipWithDefaultParentKey {
      constructor(private readonly eventStore: IEventStore) {}

addUserToGroup(groupId: string, userId: string, role: string): Promise<unknown> {
          return this.eventStore.eventLog.append(groupId, new UserAddedWithDefaultParentKey(userId, role));
      }
  }
  ```

The `groupId` (EventSourceId) is automatically used to find the parent `Group`.

### Extracting parent key from event content

[Section titled “Extracting parent key from event content”](#extracting-parent-key-from-event-content)

If your event contains the parent key as a property (instead of using EventSourceId), use `UsingParentKey()`:

* C#

Parent key from event content

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record GroupCreatedWithEventParentKey(string Name);

[EventType]
  public record UserAddedWithEventParentKey(string GroupId, string UserId, string Role);

public record GroupWithEventParentKey(
      string Name,
      IEnumerable<GroupMemberWithEventParentKey> Members);

public record GroupMemberWithEventParentKey(
      string UserId,
      string Role);

public class GroupWithEventParentKeyProjection : IProjectionFor<GroupWithEventParentKey>
  {
      public void Define(IProjectionBuilderFor<GroupWithEventParentKey> builder) => builder
          .From<GroupCreatedWithEventParentKey>()
          .Children(m => m.Members, children => children
              .IdentifiedBy(m => m.UserId)
              .From<UserAddedWithEventParentKey>(b => b
                  .UsingParentKey(e => e.GroupId)
                  .UsingKey(e => e.UserId)));
  }
  ```

* Kotlin

Parent key from event content

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class GroupCreatedWithEventParentKey(val name: String)

@EventType
  data class UserAddedWithEventParentKey(val groupId: String, val userId: String, val role: String)

data class GroupWithEventParentKey(
      val name: String = "",
      val members: List<GroupMemberWithEventParentKey> = emptyList()
  )

data class GroupMemberWithEventParentKey(
      val userId: String = "",
      val role: String = ""
  )

class GroupWithEventParentKeyProjection : IProjectionFor<GroupWithEventParentKey> {
      override fun define(builder: IProjectionBuilderFor<GroupWithEventParentKey>) {
          builder
              .from(GroupCreatedWithEventParentKey::class)
              .children(GroupWithEventParentKey::members, GroupMemberWithEventParentKey::class) { children ->
                  children
                      .identifiedBy("userId")
                      .from(UserAddedWithEventParentKey::class) {
                          it.usingParentKey("groupId")
                              .usingKey("userId")
                      }
              }
      }
  }
  ```

* Java

Parent key from event content

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.util.List;

@EventType
  record GroupCreatedWithEventParentKey(String name) {}

record GroupWithEventParentKey(String name, List<GroupMemberWithEventParentKey> members) {}

record GroupMemberWithEventParentKey(String userId, String role) {}

class GroupWithEventParentKeyProjection implements IProjectionFor<GroupWithEventParentKey> {
      @Override
      public void define(IProjectionBuilderFor<GroupWithEventParentKey> builder) {
          builder
              .from(GroupCreatedWithEventParentKey.class)
              .children("members", GroupMemberWithEventParentKey.class, children -> {
                  children
                      .identifiedBy("userId")
                      .from(UserAddedWithEventParentKey.class, fb -> {
                          fb.usingParentKey("groupId");
                          fb.usingKey("userId");
                      });
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class GroupCreatedWithEventParentKey {
      constructor(readonly name: string) {}
  }

@eventType()
  class UserAddedWithEventParentKey {
      constructor(readonly groupId: string, readonly userId: string, readonly role: string) {}
  }

class GroupMemberWithEventParentKey {
      userId = '';
      role = '';
  }

class GroupWithEventParentKey {
      name = '';
      members: GroupMemberWithEventParentKey[] = [];
  }

@projection()
  class GroupWithEventParentKeyProjection implements IProjectionFor<GroupWithEventParentKey> {
      define(builder: IProjectionBuilderFor<GroupWithEventParentKey>): void {
          builder
              .from(GroupCreatedWithEventParentKey)
              .children<GroupMemberWithEventParentKey>(m => m.members, children => children
                  .identifiedBy(m => m.userId)
                  .from(UserAddedWithEventParentKey, b => b
                      .usingParentKey(e => e.groupId)
                      .usingKey(e => e.userId)));
      }
  }
  ```

When you append the event:

* C#

Append child event with parent key

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class GroupMembershipWithEventParentKey(IEventStore eventStore)
  {
      public Task AddUserToGroup(EventSourceId userId, string groupId, string role) =>
          eventStore.EventLog.Append(userId, new UserAddedWithEventParentKey(groupId, userId.Value, role));
  }
  ```

* Kotlin

Append child event with parent key

```kotlin
  import io.cratis.chronicle.IEventStore

class GroupMembershipWithEventParentKey(private val eventStore: IEventStore) {
      suspend fun addUserToGroup(userId: String, groupId: String, role: String) =
          eventStore.eventLog.append(userId, UserAddedWithEventParentKey(groupId, userId, role))
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
  record UserAddedWithEventParentKey(String groupId, String userId, String role) {}

class GroupMembershipWithEventParentKey {
      private final EventStore eventStore;

GroupMembershipWithEventParentKey(EventStore eventStore) {
          this.eventStore = eventStore;
      }

void addUserToGroup(String userId, String groupId, String role) {
          EventLogJavaBridge.append(eventStore.getEventLog(), userId, new UserAddedWithEventParentKey(groupId, userId, role), null);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

class GroupMembershipWithEventParentKey {
      constructor(private readonly eventStore: IEventStore) {}

addUserToGroup(userId: string, groupId: string, role: string): Promise<unknown> {
          return this.eventStore.eventLog.append(userId, new UserAddedWithEventParentKey(groupId, userId, role));
      }
  }
  ```

The `groupId` property from the event content is used to find the parent `Group`.

### Using EventSourceId explicitly with UsingParentKeyFromContext

[Section titled “Using EventSourceId explicitly with UsingParentKeyFromContext”](#using-eventsourceid-explicitly-with-usingparentkeyfromcontext)

In some advanced scenarios, you might want to explicitly indicate that the EventSourceId should be used as the parent key (e.g., for documentation clarity):

* C#

Explicit parent key from context

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record GroupCreatedWithContextParentKey(string Name);

[EventType]
  public record UserAddedWithContextParentKey(string UserId, string Role);

public record GroupWithContextParentKey(
      string Name,
      IEnumerable<GroupMemberWithContextParentKey> Members);

public record GroupMemberWithContextParentKey(
      string UserId,
      string Role);

public class GroupWithContextParentKeyProjection : IProjectionFor<GroupWithContextParentKey>
  {
      public void Define(IProjectionBuilderFor<GroupWithContextParentKey> builder) => builder
          .From<GroupCreatedWithContextParentKey>()
          .Children(m => m.Members, children => children
              .IdentifiedBy(m => m.UserId)
              .From<UserAddedWithContextParentKey>(b => b
                  .UsingParentKeyFromContext(c => c.EventSourceId)
                  .UsingKey(e => e.UserId)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `IChildFromBuilderFor` only has `usingParentKey(eventPropertyName: String)`, which reads the parent
  key from an event property. There is no `usingParentKeyFromContext`-equivalent for explicitly
  documenting that the EventSourceId is used — that is only ever the implicit default.
  ```

* Java

```text
  Java does not support this workflow yet.
  `IChildFromBuilderFor` only has `usingParentKey(eventPropertyName: String)`, which reads the parent
  key from an event property. There is no `usingParentKeyFromContext`-equivalent for explicitly
  documenting that the EventSourceId is used — that is only ever the implicit default.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class GroupCreatedWithContextParentKey {
      constructor(readonly name: string) {}
  }

@eventType()
  class UserAddedWithContextParentKey {
      constructor(readonly userId: string, readonly role: string) {}
  }

class GroupMemberWithContextParentKey {
      userId = '';
      role = '';
  }

class GroupWithContextParentKey {
      name = '';
      members: GroupMemberWithContextParentKey[] = [];
  }

@projection()
  class GroupWithContextParentKeyProjection implements IProjectionFor<GroupWithContextParentKey> {
      define(builder: IProjectionBuilderFor<GroupWithContextParentKey>): void {
          builder
              .from(GroupCreatedWithContextParentKey)
              .children<GroupMemberWithContextParentKey>(m => m.members, children => children
                  .identifiedBy(m => m.userId)
                  .from(UserAddedWithContextParentKey, b => b
                      .usingParentKeyFromContext('eventSourceId')
                      .usingKey(e => e.userId)));
      }
  }
  ```

This is functionally equivalent to not specifying the parent key at all, but can make the intent clearer in complex projections.

### When to use each approach

[Section titled “When to use each approach”](#when-to-use-each-approach)

* **No parent key specified** (default): Use when EventSourceId represents the parent identifier
* **`UsingParentKey(e => e.Property)`**: Use when parent identifier is in the event content
* **`UsingParentKeyFromContext(ctx => ctx.EventSourceId)`**: Use for explicit documentation of default behavior

## Child lifecycle

[Section titled “Child lifecycle”](#child-lifecycle)

* **Adding children**: When a new event arrives with a previously unseen key, a new child is created
* **Updating children**: When an event arrives with an existing key, that child is updated
* **Removing children**: Use `RemovedWith<>()` to specify which events remove child items

## Removing children

[Section titled “Removing children”](#removing-children)

The `RemovedWith<>()` method specifies how to remove child items from collections:

* C#

Remove children

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record GroupCreatedWithRemoval(string Name);

[EventType]
  public record UserAddedWithRemoval(string UserId, string Role);

[EventType]
  public record UserRemovedWithRemoval(string UserId);

public record GroupWithRemoval(
      string Name,
      IEnumerable<GroupMemberWithRemoval> Members);

public record GroupMemberWithRemoval(
      string UserId,
      string Role);

public class GroupWithRemovalProjection : IProjectionFor<GroupWithRemoval>
  {
      public void Define(IProjectionBuilderFor<GroupWithRemoval> builder) => builder
          .From<GroupCreatedWithRemoval>()
          .Children(m => m.Members, children => children
              .IdentifiedBy(m => m.UserId)
              .From<UserAddedWithRemoval>(b => b
                  .UsingKey(e => e.UserId))
              .RemovedWith<UserRemovedWithRemoval>(b => b
                  .UsingKey(e => e.UserId)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `IChildrenBuilderFor`/`IChildFromBuilderFor` have no `removedWith`-equivalent method, and
  `ProjectionsService` never wires a removal list into the children definition it builds from the
  fluent builder — only model-bound `@RemovedWith`/`@RemovedWithJoin` on a `@ChildrenFrom` property
  can remove a single child today.
  ```

* Java

```text
  Java does not support this workflow yet.
  `IChildrenBuilderFor`/`IChildFromBuilderFor` have no `removedWith`-equivalent method, and
  `ProjectionsService` never wires a removal list into the children definition it builds from the
  fluent builder — only model-bound `@RemovedWith`/`@RemovedWithJoin` on a `@ChildrenFrom` property
  can remove a single child today.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class GroupCreatedWithRemoval {
      constructor(readonly name: string) {}
  }

@eventType()
  class UserAddedWithRemoval {
      constructor(readonly userId: string, readonly role: string) {}
  }

@eventType()
  class UserRemovedWithRemoval {
      constructor(readonly userId: string) {}
  }

class GroupMemberWithRemoval {
      userId = '';
      role = '';
  }

class GroupWithRemoval {
      name = '';
      members: GroupMemberWithRemoval[] = [];
  }

@projection()
  class GroupWithRemovalProjection implements IProjectionFor<GroupWithRemoval> {
      define(builder: IProjectionBuilderFor<GroupWithRemoval>): void {
          builder
              .from(GroupCreatedWithRemoval)
              .children<GroupMemberWithRemoval>(m => m.members, children => children
                  .identifiedBy(m => m.userId)
                  .from(UserAddedWithRemoval, b => b
                      .usingKey(e => e.userId))
                  .removedWith(UserRemovedWithRemoval, b => b
                      .usingKey(e => e.userId)));
      }
  }
  ```

When a `UserRemovedFromGroup` event is processed:

1. The projection looks up the child using the specified key (`e.UserId`)
2. If found, the child is removed from the collection
3. If not found, the event is ignored

You can also remove children conditionally or based on other criteria by using multiple `RemovedWith<>()` calls.

## Multiple child collections

[Section titled “Multiple child collections”](#multiple-child-collections)

A single projection can have multiple child collections:

* C#

Multiple child collections

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record GroupCreatedWithMultipleCollections(string Name);

[EventType]
  public record MemberAddedToGroup(string UserId, string Role);

[EventType]
  public record TaskAssignedToGroup(string TaskId, string Title);

public record GroupWithMultipleCollections(
      string Name,
      IEnumerable<GroupMemberInMultipleCollections> Members,
      IEnumerable<GroupTaskInMultipleCollections> Tasks);

public record GroupMemberInMultipleCollections(
      string UserId,
      string Role);

public record GroupTaskInMultipleCollections(
      string TaskId,
      string Title);

public class GroupWithMultipleCollectionsProjection : IProjectionFor<GroupWithMultipleCollections>
  {
      public void Define(IProjectionBuilderFor<GroupWithMultipleCollections> builder) => builder
          .From<GroupCreatedWithMultipleCollections>()
          .Children(m => m.Members, children => children
              .IdentifiedBy(m => m.UserId)
              .From<MemberAddedToGroup>(b => b
                  .UsingKey(e => e.UserId)))
          .Children(m => m.Tasks, children => children
              .IdentifiedBy(m => m.TaskId)
              .From<TaskAssignedToGroup>(b => b
                  .UsingKey(e => e.TaskId)));
  }
  ```

* Kotlin

Multiple child collections

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class GroupCreatedWithMultipleCollections(val name: String)

@EventType
  data class MemberAddedToGroup(val userId: String, val role: String)

@EventType
  data class TaskAssignedToGroup(val taskId: String, val title: String)

data class GroupWithMultipleCollections(
      val name: String = "",
      val members: List<GroupMemberInMultipleCollections> = emptyList(),
      val tasks: List<GroupTaskInMultipleCollections> = emptyList()
  )

data class GroupMemberInMultipleCollections(
      val userId: String = "",
      val role: String = ""
  )

data class GroupTaskInMultipleCollections(
      val taskId: String = "",
      val title: String = ""
  )

class GroupWithMultipleCollectionsProjection : IProjectionFor<GroupWithMultipleCollections> {
      override fun define(builder: IProjectionBuilderFor<GroupWithMultipleCollections>) {
          builder
              .from(GroupCreatedWithMultipleCollections::class)
              .children(GroupWithMultipleCollections::members, GroupMemberInMultipleCollections::class) { children ->
                  children
                      .identifiedBy("userId")
                      .from(MemberAddedToGroup::class) { it.usingKey("userId") }
              }
              .children(GroupWithMultipleCollections::tasks, GroupTaskInMultipleCollections::class) { children ->
                  children
                      .identifiedBy("taskId")
                      .from(TaskAssignedToGroup::class) { it.usingKey("taskId") }
              }
      }
  }
  ```

* Java

Multiple child collections

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.util.List;

@EventType
  record GroupCreatedWithMultipleCollections(String name) {}

@EventType
  record MemberAddedToGroup(String userId, String role) {}

@EventType
  record TaskAssignedToGroup(String taskId, String title) {}

record GroupWithMultipleCollections(
      String name,
      List<GroupMemberInMultipleCollections> members,
      List<GroupTaskInMultipleCollections> tasks) {}

record GroupMemberInMultipleCollections(String userId, String role) {}

record GroupTaskInMultipleCollections(String taskId, String title) {}

class GroupWithMultipleCollectionsProjection implements IProjectionFor<GroupWithMultipleCollections> {
      @Override
      public void define(IProjectionBuilderFor<GroupWithMultipleCollections> builder) {
          builder
              .from(GroupCreatedWithMultipleCollections.class)
              .children("members", GroupMemberInMultipleCollections.class, children -> {
                  children
                      .identifiedBy("userId")
                      .from(MemberAddedToGroup.class, fb -> {
                          fb.usingKey("userId");
                      });
              })
              .children("tasks", GroupTaskInMultipleCollections.class, children -> {
                  children
                      .identifiedBy("taskId")
                      .from(TaskAssignedToGroup.class, fb -> {
                          fb.usingKey("taskId");
                      });
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class GroupCreatedWithMultipleCollections {
      constructor(readonly name: string) {}
  }

@eventType()
  class MemberAddedToGroup {
      constructor(readonly userId: string, readonly role: string) {}
  }

@eventType()
  class TaskAssignedToGroup {
      constructor(readonly taskId: string, readonly title: string) {}
  }

class GroupMemberInMultipleCollections {
      userId = '';
      role = '';
  }

class GroupTaskInMultipleCollections {
      taskId = '';
      title = '';
  }

class GroupWithMultipleCollections {
      name = '';
      members: GroupMemberInMultipleCollections[] = [];
      tasks: GroupTaskInMultipleCollections[] = [];
  }

@projection()
  class GroupWithMultipleCollectionsProjection implements IProjectionFor<GroupWithMultipleCollections> {
      define(builder: IProjectionBuilderFor<GroupWithMultipleCollections>): void {
          builder
              .from(GroupCreatedWithMultipleCollections)
              .children<GroupMemberInMultipleCollections>(m => m.members, children => children
                  .identifiedBy(m => m.userId)
                  .from(MemberAddedToGroup, b => b
                      .usingKey(e => e.userId)))
              .children<GroupTaskInMultipleCollections>(m => m.tasks, children => children
                  .identifiedBy(m => m.taskId)
                  .from(TaskAssignedToGroup, b => b
                      .usingKey(e => e.taskId)));
      }
  }
  ```

This pattern allows you to build rich, hierarchical read models from events.

# Projection with composite keys

When a single property isn’t sufficient to uniquely identify a projection instance, you can use composite keys made up of multiple values. This is useful for multi-tenant scenarios, hierarchical data, or when you need complex keys.

## Defining a composite key

[Section titled “Defining a composite key”](#defining-a-composite-key)

Define a key made up of multiple properties when one event value is not enough to identify the read model instance:

* C#

Composite key projection

```csharp
  using Cratis.Chronicle.Projections;

public class CompositeOrderProjection : IProjectionFor<CompositeOrder>
  {
      public void Define(IProjectionBuilderFor<CompositeOrder> builder) => builder
          .From<CompositeOrderCreated>(created => created
              .UsingCompositeKey<CompositeOrderKey>(key => key
                  .Set(k => k.CustomerId).To(e => e.CustomerId)
                  .Set(k => k.OrderNumber).To(e => e.OrderNumber)))
          .From<CompositeOrderShipped>(shipped => shipped
              .UsingCompositeKey<CompositeOrderKey>(key => key
                  .Set(k => k.CustomerId).To(e => e.CustomerId)
                  .Set(k => k.OrderNumber).To(e => e.OrderNumber)));
  }
  ```

* Kotlin

Composite key projection

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

class CompositeOrderProjection : IProjectionFor<CompositeOrder> {
      override fun define(builder: IProjectionBuilderFor<CompositeOrder>) {
          builder
              .from(CompositeOrderCreated::class) {
                  it.usingCompositeKey { key ->
                      key.property("customerId", "customerId")
                          .property("orderNumber", "orderNumber")
                  }
              }
              .from(CompositeOrderShipped::class) {
                  it.usingCompositeKey { key ->
                      key.property("customerId", "customerId")
                          .property("orderNumber", "orderNumber")
                  }
              }
      }
  }
  ```

* Java

Composite key projection

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

class CompositeOrderProjection implements IProjectionFor<CompositeOrder> {
      @Override
      public void define(IProjectionBuilderFor<CompositeOrder> builder) {
          builder.from(CompositeOrderCreated.class, it -> {
              it.usingCompositeKey(key -> {
                  key.property("customerId", "customerId").property("orderNumber", "orderNumber");
              });
          });
          builder.from(CompositeOrderShipped.class, it -> {
              it.usingCompositeKey(key -> {
                  key.property("customerId", "customerId").property("orderNumber", "orderNumber");
              });
          });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection('')
  class CompositeOrderProjection implements IProjectionFor<CompositeOrder> {
      define(builder: IProjectionBuilderFor<CompositeOrder>): void {
          builder
              .from(CompositeOrderCreated, from => from
                  .usingCompositeKey<CompositeOrderKey>(key => key
                      .set(target => target.customerId, event => event.customerId)
                      .set(target => target.orderNumber, event => event.orderNumber)))
              .from(CompositeOrderShipped, from => from
                  .usingCompositeKey<CompositeOrderKey>(key => key
                      .set(target => target.customerId, event => event.customerId)
                      .set(target => target.orderNumber, event => event.orderNumber)));
      }
  }
  ```

## Composite key type

[Section titled “Composite key type”](#composite-key-type)

Define a record or class to represent your composite key:

* C#

Composite key type

```csharp
  public record CompositeOrderKey(string CustomerId, string OrderNumber);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Composite key type

```elixir
  defmodule MyApp.ReadModels.CompositeOrderKey do
    defstruct [:customer_id, :order_number]
  end
  ```

* TypeScript

```typescript
  class CompositeOrderKey {
      customerId = '';
      orderNumber = '';
  }
  ```

## Read model with composite key

[Section titled “Read model with composite key”](#read-model-with-composite-key)

The read model’s `Id` property should match your composite key type:

* C#

Read model with composite key

```csharp
  public record CompositeOrder(
      CompositeOrderKey Id,
      string CustomerName,
      DateTimeOffset OrderDate,
      DateTimeOffset? ShippedDate);
  ```

* Kotlin

Read model addressed by a composite key

```kotlin
  data class CompositeOrder(
      val customerName: String = "",
      val orderDate: String = "",
      val shippedDate: String? = null
  )
  ```

* Java

Read model addressed by a composite key

```java
  class CompositeOrder {
      public String customerName = "";
      public String orderDate = "";
      public String shippedDate = null;
  }
  ```

* Elixir

Read model with composite key

```elixir
  defmodule MyApp.ReadModels.CompositeOrder do
    defstruct [:id, :customer_name, :order_date, :shipped_date]
  end
  ```

* TypeScript

```typescript
  import { readModel } from '@cratis/chronicle';

@readModel()
  class CompositeOrder {
      id = '';
      customerName = '';
      orderDate = new Date();
      shippedDate?: Date;
  }
  ```

## Composite keys with event context

[Section titled “Composite keys with event context”](#composite-keys-with-event-context)

You can combine event properties with event context properties in composite keys:

* C#

Composite key from event content and context

```csharp
  using Cratis.Chronicle.Projections;

public class AuditEntryProjectionWithCompositeKey : IProjectionFor<AuditEntryWithCompositeKey>
  {
      public void Define(IProjectionBuilderFor<AuditEntryWithCompositeKey> builder) => builder
          .From<CompositeUserAction>(action => action
              .UsingCompositeKey<AuditEntryKey>(key => key
                  .Set(k => k.UserId).To(e => e.UserId)
                  .Set(k => k.Timestamp).ToEventContextProperty(c => c.Occurred)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The corresponding key and read model:

* C#

Composite audit key and read model

```csharp
  public record AuditEntryKey(string UserId, DateTimeOffset Timestamp);

public record AuditEntryWithCompositeKey(
      AuditEntryKey Id,
      string Action,
      string Details);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Composite audit key and read model

```elixir
  defmodule MyApp.ReadModels.AuditEntryKey do
    defstruct [:user_id, :timestamp]
  end

defmodule MyApp.ReadModels.AuditEntryWithCompositeKey do
    defstruct [:id, :action, :details]
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Composite keys in child collections

[Section titled “Composite keys in child collections”](#composite-keys-in-child-collections)

Composite keys work with child collections too:

* C#

Composite key in a child collection

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record CompositeOrderCreatedForItems(string CustomerId, string OrderNumber);

[EventType]
  public record CompositeItemAddedToOrder(
      string CustomerId,
      string OrderNumber,
      string ProductId,
      string Variant,
      int Quantity);

public record CompositeOrderWithItems(
      CompositeOrderKey Id,
      IEnumerable<CompositeOrderItem> OrderItems);

public record CompositeOrderItem(
      CompositeItemKey Id,
      string ProductId,
      string Variant,
      int Quantity);

public record CompositeItemKey(string ProductId, string Variant);

public class CompositeOrderItemsProjection : IProjectionFor<CompositeOrderWithItems>
  {
      public void Define(IProjectionBuilderFor<CompositeOrderWithItems> builder) => builder
          .From<CompositeOrderCreatedForItems>(created => created
              .UsingCompositeKey<CompositeOrderKey>(key => key
                  .Set(k => k.CustomerId).To(e => e.CustomerId)
                  .Set(k => k.OrderNumber).To(e => e.OrderNumber)))
          .Children(m => m.OrderItems, items => items
              .IdentifiedBy(m => m.Id)
              .From<CompositeItemAddedToOrder>(added => added
                  .UsingParentCompositeKey<CompositeOrderKey>(key => key
                      .Set(k => k.CustomerId).To(e => e.CustomerId)
                      .Set(k => k.OrderNumber).To(e => e.OrderNumber))
                  .UsingCompositeKey<CompositeItemKey>(key => key
                      .Set(k => k.ProductId).To(e => e.ProductId)
                      .Set(k => k.Variant).To(e => e.Variant))));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class CompositeItemAddedToOrder {
      constructor(
          readonly customerId: string = '',
          readonly orderNumber: string = '',
          readonly productId: string = '',
          readonly variant: string = '',
          readonly quantity: number = 0
      ) {}
  }

class CompositeItemKey {
      productId = '';
      variant = '';
  }

class CompositeOrderItem {
      id = '';
      productId = '';
      variant = '';
      quantity = 0;
  }

@readModel()
  class CompositeOrderWithItems {
      id = '';
      orderItems: CompositeOrderItem[] = [];
  }

@projection('', CompositeOrderWithItems)
  class CompositeOrderItemsProjection implements IProjectionFor<CompositeOrderWithItems> {
      define(builder: IProjectionBuilderFor<CompositeOrderWithItems>): void {
          builder
              .from(CompositeOrderCreated, from => from
                  .usingCompositeKey<CompositeOrderKey>(key => key
                      .set(target => target.customerId, event => event.customerId)
                      .set(target => target.orderNumber, event => event.orderNumber)))
              .children<CompositeOrderItem>(model => model.orderItems, items => items
                  .identifiedBy(model => model.id)
                  .from(CompositeItemAddedToOrder, from => from
                      .usingParentCompositeKey<CompositeOrderKey>(key => key
                          .set(target => target.customerId, event => event.customerId)
                          .set(target => target.orderNumber, event => event.orderNumber))
                      .usingCompositeKey<CompositeItemKey>(key => key
                          .set(target => target.productId, event => event.productId)
                          .set(target => target.variant, event => event.variant))));
      }
  }
  ```

## Joins with composite keys

[Section titled “Joins with composite keys”](#joins-with-composite-keys)

Composite keys can be used in join scenarios:

* C#

Join with a composite key

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record CompositeProductUpdated(
      string ProductId,
      string Variant,
      string ProductName);

public record CompositeProductKey(string ProductId, string Variant);

public record CompositeOrderLine(
      CompositeProductKey ProductKey,
      string ProductName);

public class CompositeOrderLineProjection : IProjectionFor<CompositeOrderLine>
  {
      public void Define(IProjectionBuilderFor<CompositeOrderLine> builder) => builder
          .Join<CompositeProductUpdated>(product => product
              .On(m => m.ProductKey)
              .UsingCompositeKey<CompositeProductKey>(key => key
                  .Set(k => k.ProductId).To(e => e.ProductId)
                  .Set(k => k.Variant).To(e => e.Variant)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class CompositeProductUpdated {
      constructor(
          readonly productId: string = '',
          readonly variant: string = '',
          readonly productName: string = ''
      ) {}
  }

class CompositeProductKey {
      productId = '';
      variant = '';
  }

@readModel()
  class CompositeOrderLine {
      id = '';
      productName = '';
  }

@projection('', CompositeOrderLine)
  class CompositeOrderLineProjection implements IProjectionFor<CompositeOrderLine> {
      define(builder: IProjectionBuilderFor<CompositeOrderLine>): void {
          builder
              .join(CompositeProductUpdated, join => join
                  .on(model => model.id)
                  .usingCompositeKey<CompositeProductKey>(key => key
                      .set(target => target.productId, event => event.productId)
                      .set(target => target.variant, event => event.variant)));
      }
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

* C#

Events used by composite key projections

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record CompositeOrderCreated(
      string CustomerId,
      string OrderNumber,
      string CustomerName,
      DateTimeOffset OrderDate);

[EventType]
  public record CompositeOrderShipped(
      string CustomerId,
      string OrderNumber,
      DateTimeOffset ShippedDate);

[EventType]
  public record CompositeUserAction(
      string UserId,
      string Action,
      string Details);
  ```

* Kotlin

Events used by composite key projections

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class CompositeOrderCreated(
      val customerId: String,
      val orderNumber: String,
      val customerName: String,
      val orderDate: String
  )

@EventType
  data class CompositeOrderShipped(
      val customerId: String,
      val orderNumber: String,
      val shippedDate: String
  )

@EventType
  data class CompositeUserAction(
      val userId: String,
      val action: String,
      val details: String
  )
  ```

* Java

Events used by composite key projections

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record CompositeOrderCreated(
      String customerId,
      String orderNumber,
      String customerName,
      String orderDate) {}

@EventType
  record CompositeOrderShipped(
      String customerId,
      String orderNumber,
      String shippedDate) {}

@EventType
  record CompositeUserAction(
      String userId,
      String action,
      String details) {}
  ```

* Elixir

Events used by composite key projections

```elixir
  defmodule MyApp.Events.CompositeOrderCreated do
    use Chronicle.Events.EventType, id: "composite-order-created"

defstruct [:customer_id, :order_number, :customer_name, :order_date]
  end

defmodule MyApp.Events.CompositeOrderShipped do
    use Chronicle.Events.EventType, id: "composite-order-shipped"

defstruct [:customer_id, :order_number, :shipped_date]
  end

defmodule MyApp.Events.CompositeUserAction do
    use Chronicle.Events.EventType, id: "composite-user-action"

defstruct [:user_id, :action, :details]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class CompositeOrderCreated {
      constructor(
          readonly customerId: string = '',
          readonly orderNumber: string = '',
          readonly customerName: string = '',
          readonly orderDate: Date = new Date()
      ) {}
  }

@eventType()
  class CompositeOrderShipped {
      constructor(
          readonly customerId: string = '',
          readonly orderNumber: string = '',
          readonly shippedDate: Date = new Date()
      ) {}
  }
  ```

## Key composition rules

[Section titled “Key composition rules”](#key-composition-rules)

1. **Consistent structure**: All events that target the same projection must use the same composite key structure
2. **Immutable parts**: Key components should not change during the lifetime of a projection instance
3. **Uniqueness**: The combination of all key parts must uniquely identify each projection instance
4. **Type safety**: Key components are strongly typed and validated at compile time

## Performance considerations

[Section titled “Performance considerations”](#performance-considerations)

* **Index efficiency**: Composite keys create complex indexes in the underlying storage
* **Query patterns**: Consider how you’ll query the data when designing key structure
* **Key size**: Larger composite keys use more storage and may impact performance
* **Sort order**: The order of properties in the composite key affects index efficiency

Composite keys provide powerful flexibility for complex identification scenarios while maintaining type safety and performance.

# Constant Keys

A constant key allows all events of a given type to accumulate into a **single** read model instance, regardless of which event source the events originate from. This is useful for global aggregates, system-wide counters, and singleton read models.

## Defining a constant key

[Section titled “Defining a constant key”](#defining-a-constant-key)

Use `UsingConstantKey(string value)` to specify a fixed key value for a `from` block. The read model is a normal record or class — the constant key becomes its `_id` in the underlying store:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecConstantKeyOrderPlaced(decimal Total);

public record DecConstantKeyGlobalCounter(int TotalOrders);

public class DecConstantKeyGlobalCounterProjection : IProjectionFor<DecConstantKeyGlobalCounter>
  {
      public void Define(IProjectionBuilderFor<DecConstantKeyGlobalCounter> builder) => builder
          .From<DecConstantKeyOrderPlaced>(_ => _
              .UsingConstantKey("global")
              .Count(m => m.TotalOrders));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Constant key

```elixir
  defmodule MyApp.Events.DecConstantKeyOrderPlaced do
    use Chronicle.Events.EventType, id: "dec-constant-key-order-placed"

defstruct [:total]
  end

defmodule MyApp.ReadModels.DecConstantKeyGlobalCounter do
    use Chronicle.ReadModels.ReadModel

defstruct total_orders: 0
  end

defmodule MyApp.Projections.DecConstantKeyGlobalCounterProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecConstantKeyGlobalCounter

alias MyApp.Events.DecConstantKeyOrderPlaced

from DecConstantKeyOrderPlaced,
      key: "global",
      count: :total_orders
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecConstantKeyOrderPlaced {
      constructor(readonly total: number) {}
  }

class DecConstantKeyGlobalCounter {
      totalOrders = 0;
  }

@projection()
  class DecConstantKeyGlobalCounterProjection implements IProjectionFor<DecConstantKeyGlobalCounter> {
      define(builder: IProjectionBuilderFor<DecConstantKeyGlobalCounter>): void {
          builder
              .from(DecConstantKeyOrderPlaced, _ => _
                  .usingConstantKey('global')
                  .count(m => m.totalOrders));
      }
  }
  ```

Every `OrderPlaced` event, from every event source, updates the single `GlobalCounter` instance with the key `"global"`.

> **TypeScript note:** the fluent builder’s `count()` is not implemented yet (`FromBuilder.ts` throws at runtime even though it type-checks). This particular example — an unconditional occurrence counter — is C#-only for now. `increment()`/`decrement()` **are** implemented; see the next example.

## Combining with functions

[Section titled “Combining with functions”](#combining-with-functions)

Constant keys work with all counting and arithmetic functions, making them ideal for global aggregates. The TypeScript example below tracks only `activeSessions` via `increment()`/`decrement()` — it omits the C# example’s `count()`-based `totalUsers`, since `count()` isn’t implemented in TypeScript yet:

* C#

```csharp
  [EventType]
  public record DecConstantKeyUserRegistered(string Name);

[EventType]
  public record DecConstantKeyUserLoggedIn;

[EventType]
  public record DecConstantKeyUserLoggedOut;

public record DecConstantKeySiteStatistics(
      int TotalUsers,
      int ActiveSessions);

public class DecConstantKeySiteStatisticsProjection : IProjectionFor<DecConstantKeySiteStatistics>
  {
      public void Define(IProjectionBuilderFor<DecConstantKeySiteStatistics> builder) => builder
          .From<DecConstantKeyUserRegistered>(_ => _
              .UsingConstantKey("site")
              .Count(m => m.TotalUsers))
          .From<DecConstantKeyUserLoggedIn>(_ => _
              .UsingConstantKey("site")
              .Increment(m => m.ActiveSessions))
          .From<DecConstantKeyUserLoggedOut>(_ => _
              .UsingConstantKey("site")
              .Decrement(m => m.ActiveSessions));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DecConstantKeyUserRegistered(val name: String)

@EventType
  data class DecConstantKeyUserLoggedIn(val placeholder: Boolean = true)

@EventType
  data class DecConstantKeyUserLoggedOut(val placeholder: Boolean = true)

data class DecConstantKeySiteStatistics(
      val totalUsers: Int = 0,
      val activeSessions: Int = 0
  )

class DecConstantKeySiteStatisticsProjection : IProjectionFor<DecConstantKeySiteStatistics> {
      override fun define(builder: IProjectionBuilderFor<DecConstantKeySiteStatistics>) {
          builder
              .from(DecConstantKeyUserRegistered::class) {
                  it.usingConstantKey("site")
                  it.count(DecConstantKeySiteStatistics::totalUsers)
              }
              .from(DecConstantKeyUserLoggedIn::class) {
                  it.usingConstantKey("site")
                  it.increment(DecConstantKeySiteStatistics::activeSessions)
              }
              .from(DecConstantKeyUserLoggedOut::class) {
                  it.usingConstantKey("site")
                  it.decrement(DecConstantKeySiteStatistics::activeSessions)
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecConstantKeyUserRegistered(String name) {}

@EventType
  record DecConstantKeyUserLoggedIn() {}

@EventType
  record DecConstantKeyUserLoggedOut() {}

class DecConstantKeySiteStatistics {
      public int totalUsers = 0;
      public int activeSessions = 0;
  }

class DecConstantKeySiteStatisticsProjection implements IProjectionFor<DecConstantKeySiteStatistics> {
      @Override
      public void define(IProjectionBuilderFor<DecConstantKeySiteStatistics> builder) {
          builder
              .from(DecConstantKeyUserRegistered.class, fb -> {
                  fb.usingConstantKey("site");
                  fb.count("totalUsers");
              })
              .from(DecConstantKeyUserLoggedIn.class, fb -> {
                  fb.usingConstantKey("site");
                  fb.increment("activeSessions");
              })
              .from(DecConstantKeyUserLoggedOut.class, fb -> {
                  fb.usingConstantKey("site");
                  fb.decrement("activeSessions");
              });
      }
  }
  ```

* Elixir

Increment/decrement with a constant key

```elixir
  defmodule MyApp.Events.DecConstantKeyUserRegistered do
    use Chronicle.Events.EventType, id: "dec-constant-key-user-registered"

defstruct [:name]
  end

defmodule MyApp.Events.DecConstantKeyUserLoggedIn do
    use Chronicle.Events.EventType, id: "dec-constant-key-user-logged-in"

defstruct []
  end

defmodule MyApp.Events.DecConstantKeyUserLoggedOut do
    use Chronicle.Events.EventType, id: "dec-constant-key-user-logged-out"

defstruct []
  end

defmodule MyApp.ReadModels.DecConstantKeySiteStatistics do
    use Chronicle.ReadModels.ReadModel

defstruct total_users: 0, active_sessions: 0
  end

defmodule MyApp.Projections.DecConstantKeySiteStatisticsProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecConstantKeySiteStatistics

alias MyApp.Events.{DecConstantKeyUserRegistered, DecConstantKeyUserLoggedIn, DecConstantKeyUserLoggedOut}

from DecConstantKeyUserRegistered,
      key: "site",
      count: :total_users

from DecConstantKeyUserLoggedIn,
      key: "site",
      add: [active_sessions: 1]

from DecConstantKeyUserLoggedOut,
      key: "site",
      subtract: [active_sessions: 1]
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecConstantKeyUserLoggedIn {
  }

@eventType()
  class DecConstantKeyUserLoggedOut {
  }

class DecConstantKeySiteStatistics {
      activeSessions = 0;
  }

@projection()
  class DecConstantKeySiteStatisticsProjection implements IProjectionFor<DecConstantKeySiteStatistics> {
      define(builder: IProjectionBuilderFor<DecConstantKeySiteStatistics>): void {
          builder
              .from(DecConstantKeyUserLoggedIn, _ => _
                  .usingConstantKey('site')
                  .increment(m => m.activeSessions))
              .from(DecConstantKeyUserLoggedOut, _ => _
                  .usingConstantKey('site')
                  .decrement(m => m.activeSessions));
      }
  }
  ```

## Constant parent keys

[Section titled “Constant parent keys”](#constant-parent-keys)

Use `UsingConstantParentKey(string value)` when working with child collections and you want all events to target the same parent read model:

Client coverage

This example depends on declarative child collections, which are currently C#-only (see [Children](/chronicle/projections/declarative/children/)). It stays C#-only until child projection scopes are available in the other clients.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecConstantKeyUserJoined(string UserId, string UserName);

public record DecConstantKeyTeamMember(string UserId, string Name);

public record DecConstantKeyTeam(IEnumerable<DecConstantKeyTeamMember> Members);

public class DecConstantKeyTeamActivityProjection : IProjectionFor<DecConstantKeyTeam>
  {
      public void Define(IProjectionBuilderFor<DecConstantKeyTeam> builder) => builder
          .Children(m => m.Members, children => children
              .IdentifiedBy(e => e.UserId)
              .From<DecConstantKeyUserJoined>(_ => _
                  .UsingConstantParentKey("main-team")
                  .Set(m => m.Name).To(e => e.UserName)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `IChildFromBuilderFor` only has `usingKey(String)` and `usingParentKey(String)` — there is no
  `usingConstantParentKey` for targeting the same parent instance from every child event.
  ```

* Java

```text
  Java does not support this workflow yet.
  `IChildFromBuilderFor` only has `usingKey(String)` and `usingParentKey(String)` — there is no
  `usingConstantParentKey` for targeting the same parent instance from every child event.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecConstantKeyUserJoined {
      constructor(readonly userId: string, readonly userName: string) {}
  }

class DecConstantKeyTeamMember {
      userId = '';
      name = '';
  }

class DecConstantKeyTeam {
      members: DecConstantKeyTeamMember[] = [];
  }

@projection()
  class DecConstantKeyTeamActivityProjection implements IProjectionFor<DecConstantKeyTeam> {
      define(builder: IProjectionBuilderFor<DecConstantKeyTeam>): void {
          builder
              .children<DecConstantKeyTeamMember>(m => m.members, children => children
                  .identifiedBy(e => e.userId)
                  .from(DecConstantKeyUserJoined, _ => _
                      .usingConstantParentKey('main-team')
                      .set(m => m.name).to(e => e.userName)));
      }
  }
  ```

## Comparison to other key strategies

[Section titled “Comparison to other key strategies”](#comparison-to-other-key-strategies)

| Strategy        | Method                                 | When to use                                |
| --------------- | -------------------------------------- | ------------------------------------------ |
| Event source ID | (default)                              | Each event stream is one instance          |
| Event property  | `UsingKey(e => e.Property)`            | Property on the event identifies instance  |
| Event context   | `UsingKeyFromContext(c => c.Property)` | Event context property identifies instance |
| Composite       | `UsingCompositeKey<T>(...)`            | Multiple values together form identity     |
| **Constant**    | **`UsingConstantKey("value")`**        | **All events update the same instance**    |

## Full example

[Section titled “Full example”](#full-example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecConstantKeyPageViewed(string PageUrl);

[EventType]
  public record DecConstantKeyButtonClicked(string ButtonId);

[EventType]
  public record DecConstantKeyFormSubmitted(string FormId);

public record DecConstantKeyEngagementMetrics(
      int PageViews,
      int ButtonClicks,
      int FormSubmissions);

public class DecConstantKeyEngagementMetricsProjection : IProjectionFor<DecConstantKeyEngagementMetrics>
  {
      public void Define(IProjectionBuilderFor<DecConstantKeyEngagementMetrics> builder) => builder
          .From<DecConstantKeyPageViewed>(_ => _
              .UsingConstantKey("metrics")
              .Count(m => m.PageViews))
          .From<DecConstantKeyButtonClicked>(_ => _
              .UsingConstantKey("metrics")
              .Count(m => m.ButtonClicks))
          .From<DecConstantKeyFormSubmitted>(_ => _
              .UsingConstantKey("metrics")
              .Count(m => m.FormSubmissions));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DecConstantKeyPageViewed(val pageUrl: String)

@EventType
  data class DecConstantKeyButtonClicked(val buttonId: String)

@EventType
  data class DecConstantKeyFormSubmitted(val formId: String)

data class DecConstantKeyEngagementMetrics(
      val pageViews: Int = 0,
      val buttonClicks: Int = 0,
      val formSubmissions: Int = 0
  )

class DecConstantKeyEngagementMetricsProjection : IProjectionFor<DecConstantKeyEngagementMetrics> {
      override fun define(builder: IProjectionBuilderFor<DecConstantKeyEngagementMetrics>) {
          builder
              .from(DecConstantKeyPageViewed::class) {
                  it.usingConstantKey("metrics")
                  it.count(DecConstantKeyEngagementMetrics::pageViews)
              }
              .from(DecConstantKeyButtonClicked::class) {
                  it.usingConstantKey("metrics")
                  it.count(DecConstantKeyEngagementMetrics::buttonClicks)
              }
              .from(DecConstantKeyFormSubmitted::class) {
                  it.usingConstantKey("metrics")
                  it.count(DecConstantKeyEngagementMetrics::formSubmissions)
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecConstantKeyPageViewed(String pageUrl) {}

@EventType
  record DecConstantKeyButtonClicked(String buttonId) {}

@EventType
  record DecConstantKeyFormSubmitted(String formId) {}

class DecConstantKeyEngagementMetrics {
      public int pageViews = 0;
      public int buttonClicks = 0;
      public int formSubmissions = 0;
  }

class DecConstantKeyEngagementMetricsProjection implements IProjectionFor<DecConstantKeyEngagementMetrics> {
      @Override
      public void define(IProjectionBuilderFor<DecConstantKeyEngagementMetrics> builder) {
          builder
              .from(DecConstantKeyPageViewed.class, fb -> {
                  fb.usingConstantKey("metrics");
                  fb.count("pageViews");
              })
              .from(DecConstantKeyButtonClicked.class, fb -> {
                  fb.usingConstantKey("metrics");
                  fb.count("buttonClicks");
              })
              .from(DecConstantKeyFormSubmitted.class, fb -> {
                  fb.usingConstantKey("metrics");
                  fb.count("formSubmissions");
              });
      }
  }
  ```

* Elixir

Multiple events sharing a constant key

```elixir
  defmodule MyApp.Events.DecConstantKeyPageViewed do
    use Chronicle.Events.EventType, id: "dec-constant-key-page-viewed"

defstruct [:page_url]
  end

defmodule MyApp.Events.DecConstantKeyButtonClicked do
    use Chronicle.Events.EventType, id: "dec-constant-key-button-clicked"

defstruct [:button_id]
  end

defmodule MyApp.Events.DecConstantKeyFormSubmitted do
    use Chronicle.Events.EventType, id: "dec-constant-key-form-submitted"

defstruct [:form_id]
  end

defmodule MyApp.ReadModels.DecConstantKeyEngagementMetrics do
    use Chronicle.ReadModels.ReadModel

defstruct page_views: 0, button_clicks: 0, form_submissions: 0
  end

defmodule MyApp.Projections.DecConstantKeyEngagementMetricsProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecConstantKeyEngagementMetrics

alias MyApp.Events.{DecConstantKeyPageViewed, DecConstantKeyButtonClicked, DecConstantKeyFormSubmitted}

from DecConstantKeyPageViewed,
      key: "metrics",
      count: :page_views

from DecConstantKeyButtonClicked,
      key: "metrics",
      count: :button_clicks

from DecConstantKeyFormSubmitted,
      key: "metrics",
      count: :form_submissions
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecConstantKeyPageViewed {
      constructor(readonly pageUrl: string) {}
  }

@eventType()
  class DecConstantKeyButtonClicked {
      constructor(readonly buttonId: string) {}
  }

@eventType()
  class DecConstantKeyFormSubmitted {
      constructor(readonly formId: string) {}
  }

class DecConstantKeyEngagementMetrics {
      pageViews = 0;
      buttonClicks = 0;
      formSubmissions = 0;
  }

@projection()
  class DecConstantKeyEngagementMetricsProjection implements IProjectionFor<DecConstantKeyEngagementMetrics> {
      define(builder: IProjectionBuilderFor<DecConstantKeyEngagementMetrics>): void {
          builder
              .from(DecConstantKeyPageViewed, _ => _
                  .usingConstantKey('metrics')
                  .count(m => m.pageViews))
              .from(DecConstantKeyButtonClicked, _ => _
                  .usingConstantKey('metrics')
                  .count(m => m.buttonClicks))
              .from(DecConstantKeyFormSubmitted, _ => _
                  .usingConstantKey('metrics')
                  .count(m => m.formSubmissions));
      }
  }
  ```

This projection collects engagement events from all users and event sources into a single `EngagementMetrics` document with the key `"metrics"`.

# Projection with event context values

Event context contains metadata about each event, such as when it occurred, its sequence number, and causation information. Projections can access these values to enrich read models with event metadata.

## Available event context properties

[Section titled “Available event context properties”](#available-event-context-properties)

The `EventContext` contains the following properties you can map to:

* `EventSourceId` - The identifier of the event source that produced the event
* `SequenceNumber` - The position of the event in the event sequence
* `Occurred` - When the event occurred (timestamp)
* `EventType` - Information about the event type
* `EventSourceType` - The type of the event source
* `EventStreamType` - The type of the event stream
* `EventStreamId` - The identifier of the event stream
* `CorrelationId` - The correlation identifier linking related operations
* `Causation` - Information about what caused this event
* `CausedBy` - Identity information about who caused the event

## Mapping to event source ID

[Section titled “Mapping to event source ID”](#mapping-to-event-source-id)

Use `ToEventSourceId()` to map the event source ID to a property:

* C#

```csharp
  using Cratis.Chronicle.Projections;

public class DecEventContextUserActivityProjection : IProjectionFor<DecEventContextUserActivity>
  {
      public void Define(IProjectionBuilderFor<DecEventContextUserActivity> builder) => builder
          .From<DecEventContextUserLoggedIn>(_ => _
              .Set(m => m.UserId).ToEventSourceId()
              .Set(m => m.LastLogin).ToEventContextProperty(c => c.Occurred))
          .From<DecEventContextUserPerformedAction>(_ => _
              .Set(m => m.UserId).ToEventSourceId()
              .Set(m => m.LastActivity).ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

class DecEventContextUserActivityProjection : IProjectionFor<DecEventContextUserActivity> {
      override fun define(builder: IProjectionBuilderFor<DecEventContextUserActivity>) {
          builder
              .from(DecEventContextUserLoggedIn::class) {
                  it.set(DecEventContextUserActivity::userId).toEventSourceId()
                  it.set(DecEventContextUserActivity::lastLogin).toEventContextProperty("occurred")
              }
              .from(DecEventContextUserPerformedAction::class) {
                  it.set(DecEventContextUserActivity::userId).toEventSourceId()
                  it.set(DecEventContextUserActivity::lastActivity).toEventContextProperty("occurred")
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

class DecEventContextUserActivityProjection implements IProjectionFor<DecEventContextUserActivity> {
      @Override
      public void define(IProjectionBuilderFor<DecEventContextUserActivity> builder) {
          builder
              .from(DecEventContextUserLoggedIn.class, fb -> {
                  fb.set("userId").toEventSourceId();
                  fb.set("lastLogin").toEventContextProperty("occurred");
              })
              .from(DecEventContextUserPerformedAction.class, fb -> {
                  fb.set("userId").toEventSourceId();
                  fb.set("lastActivity").toEventContextProperty("occurred");
              });
      }
  }
  ```

* Elixir

Mapping event context properties

```elixir
  defmodule MyApp.Projections.DecEventContextUserActivityProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecEventContextUserActivity

alias MyApp.Events.{DecEventContextUserLoggedIn, DecEventContextUserPerformedAction}

from DecEventContextUserLoggedIn,
      set: [
        user_id: :event_source_id,
        last_login: :occurred
      ]

from DecEventContextUserPerformedAction,
      set: [
        user_id: :event_source_id,
        last_activity: :occurred
      ]
  end
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecEventContextUserActivityProjection implements IProjectionFor<DecEventContextUserActivity> {
      define(builder: IProjectionBuilderFor<DecEventContextUserActivity>): void {
          builder
              .from(DecEventContextUserLoggedIn, _ => _
                  .set(m => m.userId).toEventSourceId()
                  .set(m => m.lastLogin).toEventContextProperty('occurred'))
              .from(DecEventContextUserPerformedAction, _ => _
                  .set(m => m.userId).toEventSourceId()
                  .set(m => m.lastActivity).toEventContextProperty('occurred'));
      }
  }
  ```

## Mapping to event context properties

[Section titled “Mapping to event context properties”](#mapping-to-event-context-properties)

Use `ToEventContextProperty()` to map any event context property:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecEventContextUserAction(string UserId, string ActionType);

public class DecEventContextAuditTrailProjection : IProjectionFor<DecEventContextAuditEntry>
  {
      public void Define(IProjectionBuilderFor<DecEventContextAuditEntry> builder) => builder
          .AutoMap()
          .From<DecEventContextUserAction>(_ => _
              .Set(m => m.EventId).ToEventContextProperty(c => c.SequenceNumber)
              .Set(m => m.OccurredAt).ToEventContextProperty(c => c.Occurred)
              .Set(m => m.CorrelationId).ToEventContextProperty(c => c.CorrelationId));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DecEventContextUserAction(val userId: String, val actionType: String)

class DecEventContextAuditTrailProjection : IProjectionFor<DecEventContextAuditEntry> {
      override fun define(builder: IProjectionBuilderFor<DecEventContextAuditEntry>) {
          builder
              .autoMap()
              .from(DecEventContextUserAction::class) {
                  it.set(DecEventContextAuditEntry::eventId).toEventContextProperty("sequenceNumber")
                  it.set(DecEventContextAuditEntry::occurredAt).toEventContextProperty("occurred")
                  it.set(DecEventContextAuditEntry::correlationId).toEventContextProperty("correlationId")
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecEventContextUserAction(String userId, String actionType) {}

class DecEventContextAuditTrailProjection implements IProjectionFor<DecEventContextAuditEntry> {
      @Override
      public void define(IProjectionBuilderFor<DecEventContextAuditEntry> builder) {
          builder
              .autoMap()
              .from(DecEventContextUserAction.class, fb -> {
                  fb.set("eventId").toEventContextProperty("sequenceNumber");
                  fb.set("occurredAt").toEventContextProperty("occurred");
                  fb.set("correlationId").toEventContextProperty("correlationId");
              });
      }
  }
  ```

* Elixir

AutoMap combined with context mapping

```elixir
  defmodule MyApp.Events.DecEventContextUserAction do
    use Chronicle.Events.EventType, id: "dec-event-context-user-action"

defstruct [:user_id, :action_type]
  end

defmodule MyApp.Projections.DecEventContextAuditTrailProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecEventContextAuditEntry

alias MyApp.Events.DecEventContextUserAction

from DecEventContextUserAction,
      set: [
        event_id: "$context.sequenceNumber",
        occurred_at: :occurred,
        correlation_id: "$context.correlationId"
      ]
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecEventContextUserAction {
      userId = '';
      actionType = '';
  }

@projection()
  class DecEventContextAuditTrailProjection implements IProjectionFor<DecEventContextAuditEntry> {
      define(builder: IProjectionBuilderFor<DecEventContextAuditEntry>): void {
          builder
              .autoMap()
              .from(DecEventContextUserAction, _ => _
                  .set(m => m.eventId).toEventContextProperty('sequenceNumber')
                  .set(m => m.occurredAt).toEventContextProperty('occurred')
                  .set(m => m.correlationId).toEventContextProperty('correlationId'));
      }
  }
  ```

## Read models with context data

[Section titled “Read models with context data”](#read-models-with-context-data)

Your read models can include properties for event metadata:

* C#

```csharp
  public record DecEventContextUserActivity(
      string UserId,
      DateTimeOffset LastLogin,
      DateTimeOffset LastActivity);

public record DecEventContextAuditEntry(
      ulong EventId,
      DateTimeOffset OccurredAt,
      string CorrelationId,
      string ActionType,
      string UserId);
  ```

* Kotlin

```kotlin
  data class DecEventContextUserActivity(
      val userId: String = "",
      val lastLogin: String = "",
      val lastActivity: String = ""
  )

data class DecEventContextAuditEntry(
      val eventId: Long = 0,
      val occurredAt: String = "",
      val correlationId: String = "",
      val actionType: String = "",
      val userId: String = ""
  )
  ```

* Java

```java
  class DecEventContextUserActivity {
      public String userId = "";
      public String lastLogin = "";
      public String lastActivity = "";
  }

class DecEventContextAuditEntry {
      public long eventId = 0;
      public String occurredAt = "";
      public String correlationId = "";
      public String actionType = "";
      public String userId = "";
  }
  ```

* Elixir

Read models

```elixir
  defmodule MyApp.ReadModels.DecEventContextUserActivity do
    use Chronicle.ReadModels.ReadModel

defstruct [:user_id, :last_login, :last_activity]
  end

defmodule MyApp.ReadModels.DecEventContextAuditEntry do
    use Chronicle.ReadModels.ReadModel

defstruct [:event_id, :occurred_at, :correlation_id, :action_type, :user_id]
  end
  ```

* TypeScript

```typescript
  class DecEventContextUserActivity {
      userId = '';
      lastLogin = new Date();
      lastActivity = new Date();
  }

class DecEventContextAuditEntry {
      eventId: bigint = 0n;
      occurredAt = new Date();
      correlationId = '';
      actionType = '';
      userId = '';
  }
  ```

## Composite keys with event context

[Section titled “Composite keys with event context”](#composite-keys-with-event-context)

Event context properties can be part of composite keys:

Client coverage

Composite keys are currently a C#-only mechanism — Kotlin, Java, TypeScript, and Elixir have no working composite-key builder yet (see [Composite Keys](/chronicle/projections/declarative/composite-keys/)). This example stays C#-only until that lands elsewhere.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecEventContextUserActionForKey(string UserId, string ActionType);

public record DecEventContextEventLogKey(DateTimeOffset Date, ulong SequenceNumber);

public record DecEventContextEventLogEntry(
      DecEventContextEventLogKey Id,
      string ActionType,
      string UserId);

public class DecEventContextEventLogProjection : IProjectionFor<DecEventContextEventLogEntry>
  {
      public void Define(IProjectionBuilderFor<DecEventContextEventLogEntry> builder) => builder
          .From<DecEventContextUserActionForKey>(_ => _
              .UsingCompositeKey<DecEventContextEventLogKey>(_ => _
                  .Set(k => k.Date).ToEventContextProperty(c => c.Occurred)
                  .Set(k => k.SequenceNumber).ToEventContextProperty(c => c.SequenceNumber))
              .Set(m => m.ActionType).To(e => e.ActionType)
              .Set(m => m.UserId).To(e => e.UserId));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `ICompositeKeyBuilderFor.property(targetPropertyName, eventPropertyName)` only pairs a read model
  property with a plain event property name — there is no way to source a composite key part from an
  event context property (e.g. `Occurred`, `SequenceNumber`), and there is no typed composite-key
  result shape like C#'s `UsingCompositeKey<TKey>`.
  ```

* Java

```text
  Java does not support this workflow yet.
  `ICompositeKeyBuilderFor.property(targetPropertyName, eventPropertyName)` only pairs a read model
  property with a plain event property name — there is no way to source a composite key part from an
  event context property (e.g. `Occurred`, `SequenceNumber`), and there is no typed composite-key
  result shape like C#'s `UsingCompositeKey<TKey>`.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Event context in children and joins

[Section titled “Event context in children and joins”](#event-context-in-children-and-joins)

Event context properties work in child collections and joins:

Client coverage

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecEventContextActivityPerformed(string ActivityId, string ActivityType);

public record DecEventContextActivityLogEntry(
      string ActivityId,
      DateTimeOffset Timestamp,
      ulong SequenceNumber);

public record DecEventContextUserWithActivityLog(
      IEnumerable<DecEventContextActivityLogEntry> ActivityLog);

public class DecEventContextUserActivityLogProjection : IProjectionFor<DecEventContextUserWithActivityLog>
  {
      public void Define(IProjectionBuilderFor<DecEventContextUserWithActivityLog> builder) => builder
          .Children(m => m.ActivityLog, children => children
              .IdentifiedBy(e => e.ActivityId)
              .AutoMap()
              .From<DecEventContextActivityPerformed>(_ => _
                  .UsingKey(e => e.ActivityId)
                  .Set(m => m.Timestamp).ToEventContextProperty(c => c.Occurred)
                  .Set(m => m.SequenceNumber).ToEventContextProperty(c => c.SequenceNumber)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `ISetBuilderFor` (used by both the top-level `from()` and the child `from()` builders) only has
  `to()`, `toEventSourceId()` and `toProperty()` — `toEventContextProperty()` exists solely on
  `IAllSetBuilderFor`, reachable only through `fromEvery()`/`fromAll()`, which apply to every event the
  projection observes rather than a single event type inside a child collection.
  ```

* Java

```text
  Java does not support this workflow yet.
  `ISetBuilderFor` (used by both the top-level `from()` and the child `from()` builders) only has
  `to()`, `toEventSourceId()` and `toProperty()` — `toEventContextProperty()` exists solely on
  `IAllSetBuilderFor`, reachable only through `fromEvery()`/`fromAll()`, which apply to every event the
  projection observes rather than a single event type inside a child collection.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecEventContextActivityPerformed {
      constructor(readonly activityId: string, readonly activityType: string) {}
  }

class DecEventContextActivityLogEntry {
      activityId = '';
      timestamp = new Date();
      sequenceNumber = 0n;
  }

class DecEventContextUserWithActivityLog {
      activityLog: DecEventContextActivityLogEntry[] = [];
  }

@projection()
  class DecEventContextUserActivityLogProjection implements IProjectionFor<DecEventContextUserWithActivityLog> {
      define(builder: IProjectionBuilderFor<DecEventContextUserWithActivityLog>): void {
          builder
              .children<DecEventContextActivityLogEntry>(m => m.activityLog, children => children
                  .identifiedBy(e => e.activityId)
                  .autoMap()
                  .from(DecEventContextActivityPerformed, _ => _
                      .usingKey(e => e.activityId)
                      .set(m => m.timestamp).toEventContextProperty('occurred')
                      .set(m => m.sequenceNumber).toEventContextProperty('sequenceNumber')));
      }
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record DecEventContextUserLoggedIn(string Username);

[EventType]
  public record DecEventContextUserPerformedAction(string UserId, string ActionType);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class DecEventContextUserLoggedIn(val username: String)

@EventType
  data class DecEventContextUserPerformedAction(val userId: String, val actionType: String)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record DecEventContextUserLoggedIn(String username) {}

@EventType
  record DecEventContextUserPerformedAction(String userId, String actionType) {}
  ```

* Elixir

Events

```elixir
  defmodule MyApp.Events.DecEventContextUserLoggedIn do
    use Chronicle.Events.EventType, id: "dec-event-context-user-logged-in"

defstruct [:username]
  end

defmodule MyApp.Events.DecEventContextUserPerformedAction do
    use Chronicle.Events.EventType, id: "dec-event-context-user-performed-action"

defstruct [:user_id, :action_type]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class DecEventContextUserLoggedIn {
      username = '';
  }

@eventType()
  class DecEventContextUserPerformedAction {
      userId = '';
      actionType = '';
  }
  ```

## Common use cases

[Section titled “Common use cases”](#common-use-cases)

### Audit trails

[Section titled “Audit trails”](#audit-trails)

Map `Occurred`, `SequenceNumber`, and `CausedBy` for complete audit information.

### Debugging and diagnostics

[Section titled “Debugging and diagnostics”](#debugging-and-diagnostics)

Include `CorrelationId` to trace related operations across services.

### Time-based queries

[Section titled “Time-based queries”](#time-based-queries)

Use `Occurred` for time-series analysis and historical reporting.

### Event ordering

[Section titled “Event ordering”](#event-ordering)

Use `SequenceNumber` when you need to preserve exact event ordering.

### Source tracking

[Section titled “Source tracking”](#source-tracking)

Use `EventSourceId` to identify which event source produced the event.

Event context properties provide rich metadata that can significantly enhance your read models with timing, traceability, and debugging information.

# Projection With FromAll

`FromAll` is a .NET declarative projection API that maps properties from every event considered by the projection, excluding child projection events by default. Other clients expose the same underlying concept through their every-event APIs configured to exclude children; see [Projection With FromEvery](/chronicle/projections/declarative/from-every/) for the full every-event feature set.

Use `FromAll` in .NET when the projection should express that a mapping belongs to the all-events portion of the projection definition. In Elixir, the same default (excluding child projection events) is what `from_every` does when `:include_children` is omitted. In TypeScript, call `excludeChildProjections()` on the `fromEvery` builder to get the same behavior.

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

* C#

Declarative FromAll

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record UserCreatedDeclarativeAll(string Name, string Email);

[EventType]
  public record UserEmailChangedDeclarativeAll(string Email);

public record UserProfileDeclarativeAll(
      string Name,
      string Email,
      DateTimeOffset LastUpdated);

public class UserProfileDeclarativeAllProjection : IProjectionFor<UserProfileDeclarativeAll>
  {
      public void Define(IProjectionBuilderFor<UserProfileDeclarativeAll> builder) => builder
          .From<UserCreatedDeclarativeAll>()
          .From<UserEmailChangedDeclarativeAll>()
          .FromAll(_ => _
              .Set(m => m.LastUpdated)
              .ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

Declarative FromAll

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class UserCreatedDeclarativeAll(val name: String, val email: String)

@EventType
  data class UserEmailChangedDeclarativeAll(val email: String)

data class UserProfileDeclarativeAll(
      val name: String = "",
      val email: String = "",
      val lastUpdated: String = ""
  )

class UserProfileDeclarativeAllProjection : IProjectionFor<UserProfileDeclarativeAll> {
      override fun define(builder: IProjectionBuilderFor<UserProfileDeclarativeAll>) {
          builder
              .from(UserCreatedDeclarativeAll::class)
              .from(UserEmailChangedDeclarativeAll::class)
              .fromAll { it.set(UserProfileDeclarativeAll::lastUpdated).toEventContextProperty("occurred") }
      }
  }
  ```

* Java

Declarative FromAll

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record UserCreatedDeclarativeAll(String name, String email) {}

@EventType
  record UserEmailChangedDeclarativeAll(String email) {}

class UserProfileDeclarativeAll {
      public String name = "";
      public String email = "";
      public String lastUpdated = "";
  }

class UserProfileDeclarativeAllProjection implements IProjectionFor<UserProfileDeclarativeAll> {
      @Override
      public void define(IProjectionBuilderFor<UserProfileDeclarativeAll> builder) {
          builder
              .from(UserCreatedDeclarativeAll.class)
              .from(UserEmailChangedDeclarativeAll.class)
              .fromAll(feb -> {
                  feb.set("lastUpdated").toEventContextProperty("occurred");
              });
      }
  }
  ```

* Elixir

Declarative FromAll

```elixir
  defmodule MyApp.Events.UserCreatedDeclarativeAll do
    use Chronicle.Events.EventType, id: "user-created-declarative-all-v1"

defstruct [:name, :email]
  end

defmodule MyApp.Events.UserEmailChangedDeclarativeAll do
    use Chronicle.Events.EventType, id: "user-email-changed-declarative-all-v1"

defstruct [:email]
  end

defmodule MyApp.ReadModels.UserProfileDeclarativeAll do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, :email, :last_updated]
  end

defmodule MyApp.Projections.UserProfileDeclarativeAllProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.UserProfileDeclarativeAll

alias MyApp.Events.{UserCreatedDeclarativeAll, UserEmailChangedDeclarativeAll}

from UserCreatedDeclarativeAll
    from UserEmailChangedDeclarativeAll

from_every set: [last_updated: :occurred]
  end
  ```

* TypeScript

Declarative FromAll

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class UserCreatedDeclarativeAll {
      constructor(readonly name: string, readonly email: string) {}
  }

@eventType()
  class UserEmailChangedDeclarativeAll {
      constructor(readonly email: string) {}
  }

@readModel()
  class UserProfileDeclarativeAll {
      name = '';
      email = '';
      lastUpdated = new Date();
  }

@projection('', UserProfileDeclarativeAll)
  class UserProfileDeclarativeAllProjection implements IProjectionFor<UserProfileDeclarativeAll> {
      define(builder: IProjectionBuilderFor<UserProfileDeclarativeAll>): void {
          builder
              .from(UserCreatedDeclarativeAll)
              .from(UserEmailChangedDeclarativeAll)
              .fromEvery(_ => _
                  .set(m => m.lastUpdated)
                  .toEventContextProperty('occurred')
                  .excludeChildProjections());
      }
  }
  ```

## Event Context Fields

[Section titled “Event Context Fields”](#event-context-fields)

* C#

Map context fields with FromAll

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record AccountTouchedDeclarativeAll(string Reason);

public record AccountAuditDeclarativeAll(
      DateTimeOffset LastUpdated,
      EventSequenceNumber LastEventSequence,
      string LastCorrelationId);

public class AccountAuditDeclarativeAllProjection : IProjectionFor<AccountAuditDeclarativeAll>
  {
      public void Define(IProjectionBuilderFor<AccountAuditDeclarativeAll> builder) => builder
          .From<AccountTouchedDeclarativeAll>()
          .FromAll(_ => _
              .Set(m => m.LastUpdated).ToEventContextProperty(c => c.Occurred)
              .Set(m => m.LastEventSequence).ToEventContextProperty(c => c.SequenceNumber)
              .Set(m => m.LastCorrelationId).ToEventContextProperty(c => c.CorrelationId));
  }
  ```

* Kotlin

Map context fields with FromAll

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class AccountTouchedDeclarativeAll(val reason: String)

data class AccountAuditDeclarativeAll(
      val lastUpdated: String = "",
      val lastEventSequence: String = "",
      val lastCorrelationId: String = ""
  )

class AccountAuditDeclarativeAllProjection : IProjectionFor<AccountAuditDeclarativeAll> {
      override fun define(builder: IProjectionBuilderFor<AccountAuditDeclarativeAll>) {
          builder
              .from(AccountTouchedDeclarativeAll::class)
              .fromAll {
                  it.set(AccountAuditDeclarativeAll::lastUpdated).toEventContextProperty("occurred")
                  it.set(AccountAuditDeclarativeAll::lastEventSequence).toEventContextProperty("sequenceNumber")
                  it.set(AccountAuditDeclarativeAll::lastCorrelationId).toEventContextProperty("correlationId")
              }
      }
  }
  ```

* Java

Map context fields with FromAll

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record AccountTouchedDeclarativeAll(String reason) {}

class AccountAuditDeclarativeAll {
      public String lastUpdated = "";
      public String lastEventSequence = "";
      public String lastCorrelationId = "";
  }

class AccountAuditDeclarativeAllProjection implements IProjectionFor<AccountAuditDeclarativeAll> {
      @Override
      public void define(IProjectionBuilderFor<AccountAuditDeclarativeAll> builder) {
          builder
              .from(AccountTouchedDeclarativeAll.class)
              .fromAll(feb -> {
                  feb.set("lastUpdated").toEventContextProperty("occurred");
                  feb.set("lastEventSequence").toEventContextProperty("sequenceNumber");
                  feb.set("lastCorrelationId").toEventContextProperty("correlationId");
              });
      }
  }
  ```

* Elixir

Map context fields with FromAll

```elixir
  defmodule MyApp.Events.AccountTouchedDeclarativeAll do
    use Chronicle.Events.EventType, id: "account-touched-declarative-all-v1"

defstruct [:reason]
  end

defmodule MyApp.ReadModels.AccountAuditDeclarativeAll do
    use Chronicle.ReadModels.ReadModel

defstruct [:last_updated, :last_event_sequence, :last_correlation_id]
  end

defmodule MyApp.Projections.AccountAuditDeclarativeAllProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.AccountAuditDeclarativeAll

alias MyApp.Events.AccountTouchedDeclarativeAll

from AccountTouchedDeclarativeAll

from_every set: [
      last_updated: :occurred,
      last_event_sequence: "$context.sequenceNumber",
      last_correlation_id: "$context.correlationId"
    ]
  end
  ```

* TypeScript

Map context fields with FromAll

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class AccountTouchedDeclarativeAll {
      constructor(readonly reason: string) {}
  }

@readModel()
  class AccountAuditDeclarativeAll {
      lastUpdated = new Date();
      lastEventSequence = 0n;
      lastCorrelationId = '';
  }

@projection('', AccountAuditDeclarativeAll)
  class AccountAuditDeclarativeAllProjection implements IProjectionFor<AccountAuditDeclarativeAll> {
      define(builder: IProjectionBuilderFor<AccountAuditDeclarativeAll>): void {
          builder
              .from(AccountTouchedDeclarativeAll)
              .fromEvery(_ => _
                  .set(m => m.lastUpdated).toEventContextProperty('occurred')
                  .set(m => m.lastEventSequence).toEventContextProperty('sequenceNumber')
                  .set(m => m.lastCorrelationId).toEventContextProperty('correlationId')
                  .excludeChildProjections());
      }
  }
  ```

## Event Source Id

[Section titled “Event Source Id”](#event-source-id)

* C#

Map event source id with FromAll

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record AccountOpenedDeclarativeAll(string OwnerName);

public record AccountSummaryDeclarativeAll(
      string AccountId,
      string OwnerName);

public class AccountSummaryDeclarativeAllProjection : IProjectionFor<AccountSummaryDeclarativeAll>
  {
      public void Define(IProjectionBuilderFor<AccountSummaryDeclarativeAll> builder) => builder
          .From<AccountOpenedDeclarativeAll>()
          .FromAll(_ => _
              .Set(m => m.AccountId)
              .ToEventSourceId());
  }
  ```

* Kotlin

Map the event source id with FromAll

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class AccountOpenedDeclarativeAll(val ownerName: String)

data class AccountSummaryDeclarativeAll(
      val accountId: String = "",
      val ownerName: String = ""
  )

class AccountSummaryDeclarativeAllProjection : IProjectionFor<AccountSummaryDeclarativeAll> {
      override fun define(builder: IProjectionBuilderFor<AccountSummaryDeclarativeAll>) {
          builder
              .from(AccountOpenedDeclarativeAll::class)
              .fromAll { it.set(AccountSummaryDeclarativeAll::accountId).toEventSourceId() }
      }
  }
  ```

* Java

Map the event source id with FromAll

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record AccountOpenedDeclarativeAll(String ownerName) {}

class AccountSummaryDeclarativeAll {
      public String accountId = "";
      public String ownerName = "";
  }

class AccountSummaryDeclarativeAllProjection implements IProjectionFor<AccountSummaryDeclarativeAll> {
      @Override
      public void define(IProjectionBuilderFor<AccountSummaryDeclarativeAll> builder) {
          builder
              .from(AccountOpenedDeclarativeAll.class)
              .fromAll(feb -> {
                  feb.set("accountId").toEventSourceId();
              });
      }
  }
  ```

* Elixir

Map event source id with FromAll

```elixir
  defmodule MyApp.Events.AccountOpenedDeclarativeAll do
    use Chronicle.Events.EventType, id: "account-opened-declarative-all-v1"

defstruct [:owner_name]
  end

defmodule MyApp.ReadModels.AccountSummaryDeclarativeAll do
    use Chronicle.ReadModels.ReadModel

defstruct [:account_id, :owner_name]
  end

defmodule MyApp.Projections.AccountSummaryDeclarativeAllProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.AccountSummaryDeclarativeAll

alias MyApp.Events.AccountOpenedDeclarativeAll

from AccountOpenedDeclarativeAll

from_every set: [account_id: :event_source_id]
  end
  ```

* TypeScript

Map event source id with FromAll

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class AccountOpenedDeclarativeAll {
      constructor(readonly ownerName: string) {}
  }

@readModel()
  class AccountSummaryDeclarativeAll {
      accountId = '';
      ownerName = '';
  }

@projection('', AccountSummaryDeclarativeAll)
  class AccountSummaryDeclarativeAllProjection implements IProjectionFor<AccountSummaryDeclarativeAll> {
      define(builder: IProjectionBuilderFor<AccountSummaryDeclarativeAll>): void {
          builder
              .from(AccountOpenedDeclarativeAll)
              .fromEvery(_ => _
                  .set(m => m.accountId)
                  .toEventSourceId()
                  .excludeChildProjections());
      }
  }
  ```

## With Event-Specific Mappings

[Section titled “With Event-Specific Mappings”](#with-event-specific-mappings)

`FromAll` can sit beside event-specific `From` mappings. Use event-specific mappings for business state, and reserve `FromAll` for metadata that should update for every projected event.

* C#

Combine FromAll with event-specific mappings

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record OrderCreatedDeclarativeAll(string OrderNumber);

[EventType]
  public record OrderShippedDeclarativeAll(string TrackingNumber);

public record OrderDeclarativeAll(
      string OrderNumber,
      string Status,
      DateTimeOffset LastModified);

public class OrderDeclarativeAllProjection : IProjectionFor<OrderDeclarativeAll>
  {
      public void Define(IProjectionBuilderFor<OrderDeclarativeAll> builder) => builder
          .FromAll(_ => _
              .Set(m => m.LastModified)
              .ToEventContextProperty(c => c.Occurred))
          .From<OrderCreatedDeclarativeAll>(_ => _
              .Set(m => m.Status)
              .ToValue("Placed"))
          .From<OrderShippedDeclarativeAll>(_ => _
              .Set(m => m.Status)
              .ToValue("Shipped"));
  }
  ```

* Kotlin

Combine FromAll with event-specific mappings

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class OrderCreatedDeclarativeAll(val orderNumber: String)

@EventType
  data class OrderShippedDeclarativeAll(val trackingNumber: String)

data class OrderDeclarativeAll(
      val orderNumber: String = "",
      val status: String = "",
      val lastModified: String = ""
  )

class OrderDeclarativeAllProjection : IProjectionFor<OrderDeclarativeAll> {
      override fun define(builder: IProjectionBuilderFor<OrderDeclarativeAll>) {
          builder
              .fromAll { it.set(OrderDeclarativeAll::lastModified).toEventContextProperty("occurred") }
              .from(OrderCreatedDeclarativeAll::class) {
                  it.set(OrderDeclarativeAll::status).to { "Placed" }
              }
              .from(OrderShippedDeclarativeAll::class) {
                  it.set(OrderDeclarativeAll::status).to { "Shipped" }
              }
      }
  }
  ```

* Java

Combine FromAll with event-specific mappings

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record OrderCreatedDeclarativeAll(String orderNumber) {}

@EventType
  record OrderShippedDeclarativeAll(String trackingNumber) {}

class OrderDeclarativeAll {
      public String orderNumber = "";
      public String status = "";
      public String lastModified = "";
  }

class OrderDeclarativeAllProjection implements IProjectionFor<OrderDeclarativeAll> {
      @Override
      public void define(IProjectionBuilderFor<OrderDeclarativeAll> builder) {
          builder
              .fromAll(feb -> {
                  feb.set("lastModified").toEventContextProperty("occurred");
              })
              .from(OrderCreatedDeclarativeAll.class, fb -> {
                  fb.<String>set("status").to(e -> "Placed");
              })
              .from(OrderShippedDeclarativeAll.class, fb -> {
                  fb.<String>set("status").to(e -> "Shipped");
              });
      }
  }
  ```

* Elixir

Combine from\_every with event-specific mappings

```elixir
  defmodule MyApp.Events.OrderCreatedDeclarativeAll do
    use Chronicle.Events.EventType, id: "order-created-declarative-all"

defstruct [:order_number]
  end

defmodule MyApp.Events.OrderShippedDeclarativeAll do
    use Chronicle.Events.EventType, id: "order-shipped-declarative-all"

defstruct [:tracking_number]
  end

defmodule MyApp.ReadModels.OrderDeclarativeAll do
    use Chronicle.ReadModels.ReadModel

defstruct [:order_number, :status, :last_modified]
  end

defmodule MyApp.Projections.OrderDeclarativeAllProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.OrderDeclarativeAll

alias MyApp.Events.{OrderCreatedDeclarativeAll, OrderShippedDeclarativeAll}

# Elixir's from_every excludes child-projection events by default — the
    # same default FromAll uses in .NET.
    from_every set: [last_modified: :occurred]

from OrderCreatedDeclarativeAll,
      set: [
        order_number: :order_number,
        status: "$value(Placed)"
      ]

from OrderShippedDeclarativeAll,
      set: [status: "$value(Shipped)"]
  end
  ```

* TypeScript

Combine FromAll with event-specific mappings

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class OrderCreatedDeclarativeAll {
      constructor(readonly orderNumber: string) {}
  }

@eventType()
  class OrderShippedDeclarativeAll {
      constructor(readonly trackingNumber: string) {}
  }

@readModel()
  class OrderDeclarativeAll {
      orderNumber = '';
      status = '';
      lastModified = new Date();
  }

@projection('', OrderDeclarativeAll)
  class OrderDeclarativeAllProjection implements IProjectionFor<OrderDeclarativeAll> {
      define(builder: IProjectionBuilderFor<OrderDeclarativeAll>): void {
          builder
              .fromEvery(_ => _
                  .set(m => m.lastModified)
                  .toEventContextProperty('occurred')
                  .excludeChildProjections())
              .from(OrderCreatedDeclarativeAll, _ => _
                  .set(m => m.status)
                  .toValue('Placed'))
              .from(OrderShippedDeclarativeAll, _ => _
                  .set(m => m.status)
                  .toValue('Shipped'));
      }
  }
  ```

## FromAll And FromEvery

[Section titled “FromAll And FromEvery”](#fromall-and-fromevery)

| API         | Use it when                                                                                                    |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| `FromAll`   | You are using the .NET declarative projection API and want to express an all-events mapping.                   |
| `FromEvery` | You want the portable every-event concept, or you are using a client that exposes the concept under that name. |

Prefer event context sources for audit fields because every event has the same context shape. Use event payload properties only when the event contracts intentionally share the same property.

# Projection with FromEventSequence

The `FromEventSequence()` method allows you to specify which event sequence a projection should source events from. This is useful when you have multiple event sequences in your system and want to create projections that only process events from specific sequences.

## Defining a projection with specific event sequence

[Section titled “Defining a projection with specific event sequence”](#defining-a-projection-with-specific-event-sequence)

Use `FromEventSequence()` to specify the event sequence to source events from:

* C#

```csharp
  using Cratis.Chronicle.Projections;

public class DecFromEventSequenceOrderProjection : IProjectionFor<DecFromEventSequenceOrder>
  {
      public void Define(IProjectionBuilderFor<DecFromEventSequenceOrder> builder) => builder
          .FromEventSequence("order-management")
          .AutoMap()
          .From<DecFromEventSequenceOrderCreated>()
          .From<DecFromEventSequenceOrderUpdated>()
          .From<DecFromEventSequenceOrderShipped>();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor
  import io.cratis.chronicle.projections.Projection

@Projection(eventSequence = "order-management")
  class DecFromEventSequenceOrderProjection : IProjectionFor<DecFromEventSequenceOrder> {
      override fun define(builder: IProjectionBuilderFor<DecFromEventSequenceOrder>) {
          builder
              .from(DecFromEventSequenceOrderCreated::class)
              .from(DecFromEventSequenceOrderUpdated::class)
              .from(DecFromEventSequenceOrderShipped::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;
  import io.cratis.chronicle.projections.Projection;

@Projection(eventSequence = "order-management")
  class DecFromEventSequenceOrderProjection implements IProjectionFor<DecFromEventSequenceOrder> {
      @Override
      public void define(IProjectionBuilderFor<DecFromEventSequenceOrder> builder) {
          builder.from(DecFromEventSequenceOrderCreated.class);
          builder.from(DecFromEventSequenceOrderUpdated.class);
          builder.from(DecFromEventSequenceOrderShipped.class);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.FromEventSequenceOrderCreated do
    use Chronicle.Events.EventType, id: "from-event-sequence-order-created"

defstruct [:customer]
  end

defmodule MyApp.ReadModels.FromEventSequenceOrder do
    use Chronicle.ReadModels.ReadModel, event_sequence: "order-management"

defstruct id: nil, customer: nil

from MyApp.Events.FromEventSequenceOrderCreated,
      set: [id: :event_source_id, customer: :customer]
  end
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecFromEventSequenceOrderProjection implements IProjectionFor<DecFromEventSequenceOrder> {
      define(builder: IProjectionBuilderFor<DecFromEventSequenceOrder>): void {
          builder
              .fromEventSequence('order-management')
              .autoMap()
              .from(DecFromEventSequenceOrderCreated)
              .from(DecFromEventSequenceOrderUpdated)
              .from(DecFromEventSequenceOrderShipped);
      }
  }
  ```

This projection:

* Only processes events from the “order-management” event sequence
* Ignores events from other sequences like “user-management” or “inventory-management”
* Uses the specified sequence for all event handling

## Event sequence identification

[Section titled “Event sequence identification”](#event-sequence-identification)

Event sequences can be identified using string names or EventSequenceId:

* C#

```csharp
  public static class DecFromEventSequenceEventSequences
  {
      public const string OrderManagement = "order-management";
  }

public class DecFromEventSequenceOrderProjectionWithConstant : IProjectionFor<DecFromEventSequenceOrder>
  {
      public void Define(IProjectionBuilderFor<DecFromEventSequenceOrder> builder) => builder
          // Using a constant instead of a raw string keeps the sequence identifier consistent
          // wherever it is referenced.
          .FromEventSequence(DecFromEventSequenceEventSequences.OrderManagement)
          .AutoMap()
          .From<DecFromEventSequenceOrderCreated>();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor
  import io.cratis.chronicle.projections.Projection

object DecFromEventSequenceEventSequences {
      const val OrderManagement = "order-management"
  }

// Using a constant instead of a raw string keeps the sequence identifier consistent
  // wherever it is referenced.
  @Projection(eventSequence = DecFromEventSequenceEventSequences.OrderManagement)
  class DecFromEventSequenceOrderProjectionWithConstant : IProjectionFor<DecFromEventSequenceOrder> {
      override fun define(builder: IProjectionBuilderFor<DecFromEventSequenceOrder>) {
          builder.from(DecFromEventSequenceOrderCreated::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;
  import io.cratis.chronicle.projections.Projection;

class DecFromEventSequenceEventSequences {
      // Using a constant instead of a raw string keeps the sequence identifier consistent
      // wherever it is referenced.
      public static final String ORDER_MANAGEMENT = "order-management";
  }

@Projection(eventSequence = DecFromEventSequenceEventSequences.ORDER_MANAGEMENT)
  class DecFromEventSequenceOrderProjectionWithConstant implements IProjectionFor<DecFromEventSequenceOrder> {
      @Override
      public void define(IProjectionBuilderFor<DecFromEventSequenceOrder> builder) {
          builder.from(DecFromEventSequenceOrderCreated.class);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

const eventSequences = {
      orderManagement: 'order-management'
  };

@projection()
  class DecFromEventSequenceOrderProjectionWithConstant implements IProjectionFor<DecFromEventSequenceOrder> {
      define(builder: IProjectionBuilderFor<DecFromEventSequenceOrder>): void {
          builder
              // Using a constant instead of a raw string keeps the sequence identifier consistent
              // wherever it is referenced.
              .fromEventSequence(eventSequences.orderManagement)
              .autoMap()
              .from(DecFromEventSequenceOrderCreated);
      }
  }
  ```

## Read model definition

[Section titled “Read model definition”](#read-model-definition)

The read model remains the same regardless of the event sequence:

* C#

```csharp
  public record DecFromEventSequenceOrder(
      string OrderNumber,
      string CustomerId,
      decimal TotalAmount,
      DecFromEventSequenceOrderStatus Status,
      DateTimeOffset CreatedAt,
      DateTimeOffset? ShippedAt);

public enum DecFromEventSequenceOrderStatus
  {
      Created,
      Processing,
      Shipped,
      Delivered,
      Cancelled
  }
  ```

* Kotlin

```kotlin
  enum class DecFromEventSequenceOrderStatus {
      Created,
      Processing,
      Shipped,
      Delivered,
      Cancelled
  }

data class DecFromEventSequenceOrder(
      val orderNumber: String = "",
      val customerId: String = "",
      val totalAmount: Double = 0.0,
      val status: DecFromEventSequenceOrderStatus = DecFromEventSequenceOrderStatus.Created,
      val shippedAt: String? = null
  )
  ```

* Java

```java
  enum DecFromEventSequenceOrderStatus {
      Created,
      Processing,
      Shipped,
      Delivered,
      Cancelled
  }

class DecFromEventSequenceOrder {
      public String orderNumber = "";
      public String customerId = "";
      public double totalAmount = 0.0;
      public DecFromEventSequenceOrderStatus status = DecFromEventSequenceOrderStatus.Created;
      public String shippedAt = null;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.DecFromEventSequenceOrder do
    # status is one of :created, :processing, :shipped, :delivered, :canceled
    defstruct [
      :order_number,
      :customer_id,
      :total_amount,
      :status,
      :created_at,
      :shipped_at
    ]
  end
  ```

* TypeScript

```typescript
  enum DecFromEventSequenceOrderStatus {
      Created = 'Created',
      Processing = 'Processing',
      Shipped = 'Shipped',
      Delivered = 'Delivered',
      Cancelled = 'Cancelled'
  }

class DecFromEventSequenceOrder {
      orderNumber = '';
      customerId = '';
      totalAmount = 0;
      status = DecFromEventSequenceOrderStatus.Created;
      createdAt = new Date();
      shippedAt: Date | null = null;
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

Events should be designed to work within the specific sequence context:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record DecFromEventSequenceOrderCreated(
      string OrderNumber,
      string CustomerId,
      decimal TotalAmount);

[EventType]
  public record DecFromEventSequenceOrderUpdated(
      string OrderNumber,
      decimal NewTotalAmount);

[EventType]
  public record DecFromEventSequenceOrderShipped(
      string OrderNumber,
      DateTimeOffset ShippedAt);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class DecFromEventSequenceOrderCreated(
      val orderNumber: String,
      val customerId: String,
      val totalAmount: Double
  )

@EventType
  data class DecFromEventSequenceOrderUpdated(
      val orderNumber: String,
      val newTotalAmount: Double
  )

@EventType
  data class DecFromEventSequenceOrderShipped(
      val orderNumber: String,
      val shippedAt: String
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record DecFromEventSequenceOrderCreated(
      String orderNumber,
      String customerId,
      double totalAmount) {}

@EventType
  record DecFromEventSequenceOrderUpdated(
      String orderNumber,
      double newTotalAmount) {}

@EventType
  record DecFromEventSequenceOrderShipped(
      String orderNumber,
      String shippedAt) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.DecFromEventSequenceOrderCreated do
    use Chronicle.Events.EventType, id: "dec-from-event-sequence-order-created"

defstruct [:order_number, :customer_id, :total_amount]
  end

defmodule MyApp.Events.DecFromEventSequenceOrderUpdated do
    use Chronicle.Events.EventType, id: "dec-from-event-sequence-order-updated"

defstruct [:order_number, :new_total_amount]
  end

defmodule MyApp.Events.DecFromEventSequenceOrderShipped do
    use Chronicle.Events.EventType, id: "dec-from-event-sequence-order-shipped"

defstruct [:order_number, :shipped_at]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class DecFromEventSequenceOrderCreated {
      orderNumber = '';
      customerId = '';
      totalAmount = 0;
  }

@eventType()
  class DecFromEventSequenceOrderUpdated {
      orderNumber = '';
      newTotalAmount = 0;
  }

@eventType()
  class DecFromEventSequenceOrderShipped {
      orderNumber = '';
      shippedAt = new Date();
  }
  ```

## How it works

[Section titled “How it works”](#how-it-works)

When using `FromEventSequence()`:

1. The projection subscribes only to the specified event sequence
2. Events from other sequences are ignored, even if they match the event types
3. The projection processes events in the order they appear in the specified sequence
4. Event sequence numbers and ordering are maintained within that specific sequence

## Multiple event sequences

[Section titled “Multiple event sequences”](#multiple-event-sequences)

You can create different projections for different event sequences:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecFromEventSequencePackageCreated(string PackageId);

[EventType]
  public record DecFromEventSequencePackageShipped(string PackageId, DateTimeOffset ShippedAt);

[EventType]
  public record DecFromEventSequencePackageDelivered(string PackageId, DateTimeOffset DeliveredAt);

public record DecFromEventSequenceShipping(
      string PackageId,
      DateTimeOffset? ShippedAt,
      DateTimeOffset? DeliveredAt);

// Projection for order management events
  public class DecFromEventSequenceMultiOrderProjection : IProjectionFor<DecFromEventSequenceOrder>
  {
      public void Define(IProjectionBuilderFor<DecFromEventSequenceOrder> builder) => builder
          .FromEventSequence("order-management")
          .AutoMap()
          .From<DecFromEventSequenceOrderCreated>(_ => _
              .Set(m => m.Status).ToValue(DecFromEventSequenceOrderStatus.Created));
  }

// Projection for shipping events from a different sequence
  public class DecFromEventSequenceShippingProjection : IProjectionFor<DecFromEventSequenceShipping>
  {
      public void Define(IProjectionBuilderFor<DecFromEventSequenceShipping> builder) => builder
          .FromEventSequence("shipping-management")
          .AutoMap()
          .From<DecFromEventSequencePackageCreated>()
          .From<DecFromEventSequencePackageShipped>()
          .From<DecFromEventSequencePackageDelivered>();
  }
  ```

* Kotlin

@EventType
  data class DecFromEventSequencePackageCreated(val packageId: String)

@EventType
  data class DecFromEventSequencePackageShipped(val packageId: String, val shippedAt: String)

@EventType
  data class DecFromEventSequencePackageDelivered(val packageId: String, val deliveredAt: String)

data class DecFromEventSequenceShipping(
      val packageId: String = "",
      val shippedAt: String? = null,
      val deliveredAt: String? = null
  )

// Projection for order management events
  @Projection(eventSequence = "order-management")
  class DecFromEventSequenceMultiOrderProjection : IProjectionFor<DecFromEventSequenceOrder> {
      override fun define(builder: IProjectionBuilderFor<DecFromEventSequenceOrder>) {
          builder
              .from(DecFromEventSequenceOrderCreated::class)
              .from(DecFromEventSequenceOrderUpdated::class)
              .from(DecFromEventSequenceOrderShipped::class)
      }
  }

// Projection for shipping events from a different sequence
  @Projection(eventSequence = "shipping-management")
  class DecFromEventSequenceShippingProjection : IProjectionFor<DecFromEventSequenceShipping> {
      override fun define(builder: IProjectionBuilderFor<DecFromEventSequenceShipping>) {
          builder
              .from(DecFromEventSequencePackageCreated::class)
              .from(DecFromEventSequencePackageShipped::class)
              .from(DecFromEventSequencePackageDelivered::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;
  import io.cratis.chronicle.projections.Projection;

@EventType
  record DecFromEventSequencePackageCreated(String packageId) {}

@EventType
  record DecFromEventSequencePackageShipped(String packageId, String shippedAt) {}

@EventType
  record DecFromEventSequencePackageDelivered(String packageId, String deliveredAt) {}

class DecFromEventSequenceShipping {
      public String packageId = "";
      public String shippedAt = null;
      public String deliveredAt = null;
  }

// Projection for order management events
  @Projection(eventSequence = "order-management")
  class DecFromEventSequenceMultiOrderProjection implements IProjectionFor<DecFromEventSequenceOrder> {
      @Override
      public void define(IProjectionBuilderFor<DecFromEventSequenceOrder> builder) {
          builder.from(DecFromEventSequenceOrderCreated.class);
          builder.from(DecFromEventSequenceOrderUpdated.class);
          builder.from(DecFromEventSequenceOrderShipped.class);
      }
  }

// Projection for shipping events from a different sequence
  @Projection(eventSequence = "shipping-management")
  class DecFromEventSequenceShippingProjection implements IProjectionFor<DecFromEventSequenceShipping> {
      @Override
      public void define(IProjectionBuilderFor<DecFromEventSequenceShipping> builder) {
          builder.from(DecFromEventSequencePackageCreated.class);
          builder.from(DecFromEventSequencePackageShipped.class);
          builder.from(DecFromEventSequencePackageDelivered.class);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecFromEventSequencePackageCreated {
      packageId = '';
  }

@eventType()
  class DecFromEventSequencePackageShipped {
      packageId = '';
      shippedAt = new Date();
  }

@eventType()
  class DecFromEventSequencePackageDelivered {
      packageId = '';
      deliveredAt = new Date();
  }

class DecFromEventSequenceShipping {
      packageId = '';
      shippedAt: Date | null = null;
      deliveredAt: Date | null = null;
  }

// Projection for order management events
  @projection()
  class DecFromEventSequenceMultiOrderProjection implements IProjectionFor<DecFromEventSequenceOrder> {
      define(builder: IProjectionBuilderFor<DecFromEventSequenceOrder>): void {
          builder
              .fromEventSequence('order-management')
              .autoMap()
              .from(DecFromEventSequenceOrderCreated, _ => _
                  .set(m => m.status).toValue(DecFromEventSequenceOrderStatus.Created));
      }
  }

// Projection for shipping events from a different sequence
  @projection()
  class DecFromEventSequenceShippingProjection implements IProjectionFor<DecFromEventSequenceShipping> {
      define(builder: IProjectionBuilderFor<DecFromEventSequenceShipping>): void {
          builder
              .fromEventSequence('shipping-management')
              .autoMap()
              .from(DecFromEventSequencePackageCreated)
              .from(DecFromEventSequencePackageShipped)
              .from(DecFromEventSequencePackageDelivered);
      }
  }
  ```

## When to use FromEventSequence

[Section titled “When to use FromEventSequence”](#when-to-use-fromeventsequence)

Use `FromEventSequence()` when:

* **Bounded contexts**: You have separate domains with their own event sequences
* **Data partitioning**: Events are logically separated by business area or tenant
* **Security boundaries**: Different sequences have different access requirements
* **Performance optimization**: You want to reduce the number of events a projection processes
* **Legacy integration**: You need to process events from specific legacy systems
* **Multi-tenant scenarios**: Each tenant has their own event sequence

## Default behavior

[Section titled “Default behavior”](#default-behavior)

If you don’t specify `FromEventSequence()`:

* The projection uses the default `event-log` event sequence.
* All events matching the specified types are processed regardless of sequence
* This is suitable for most single-sequence scenarios

## Performance considerations

[Section titled “Performance considerations”](#performance-considerations)

* Specifying an event sequence can improve performance by reducing the number of events processed
* Each sequence maintains its own ordering and sequence numbers
* Consider the volume and frequency of events in each sequence when designing projections
* Event sequence isolation can help with parallel processing and scaling

# Projection With FromEvery

Use an every-event mapping in a declarative projection when a read model property should update whenever any event handled by the projection is processed. This is most useful for audit metadata, event source identifiers, and other fields that should stay synchronized with the latest event.

The exact API name depends on the client. .NET and TypeScript expose `FromEvery` / `fromEvery`, while Elixir exposes `from_every`.

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

Map event context metadata when the read model needs to know when it was last touched.

* C#

Declarative FromEvery

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record UserCreatedDeclarativeEvery(string Name, string Email);

[EventType]
  public record UserEmailChangedDeclarativeEvery(string Email);

public record UserProfileDeclarativeEvery(
      string Name,
      string Email,
      DateTimeOffset LastUpdated);

public class UserProfileDeclarativeEveryProjection : IProjectionFor<UserProfileDeclarativeEvery>
  {
      public void Define(IProjectionBuilderFor<UserProfileDeclarativeEvery> builder) => builder
          .From<UserCreatedDeclarativeEvery>()
          .From<UserEmailChangedDeclarativeEvery>()
          .FromEvery(_ => _
              .Set(m => m.LastUpdated)
              .ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

Declarative FromEvery

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class UserCreatedDeclarativeEvery(val name: String, val email: String)

@EventType
  data class UserEmailChangedDeclarativeEvery(val email: String)

data class UserProfileDeclarativeEvery(
      val name: String = "",
      val email: String = "",
      val lastUpdated: String = ""
  )

class UserProfileDeclarativeEveryProjection : IProjectionFor<UserProfileDeclarativeEvery> {
      override fun define(builder: IProjectionBuilderFor<UserProfileDeclarativeEvery>) {
          builder
              .from(UserCreatedDeclarativeEvery::class)
              .from(UserEmailChangedDeclarativeEvery::class)
              .fromEvery { it.set(UserProfileDeclarativeEvery::lastUpdated).toEventContextProperty("occurred") }
      }
  }
  ```

* Java

Declarative FromEvery

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record UserCreatedDeclarativeEvery(String name, String email) {}

@EventType
  record UserEmailChangedDeclarativeEvery(String email) {}

class UserProfileDeclarativeEvery {
      public String name = "";
      public String email = "";
      public String lastUpdated = "";
  }

class UserProfileDeclarativeEveryProjection implements IProjectionFor<UserProfileDeclarativeEvery> {
      @Override
      public void define(IProjectionBuilderFor<UserProfileDeclarativeEvery> builder) {
          builder
              .from(UserCreatedDeclarativeEvery.class)
              .from(UserEmailChangedDeclarativeEvery.class)
              .fromEvery(feb -> {
                  feb.set("lastUpdated").toEventContextProperty("occurred");
              });
      }
  }
  ```

* Elixir

Declarative from\_every

```elixir
  defmodule MyApp.Events.UserCreatedDeclarativeEvery do
    use Chronicle.Events.EventType, id: "user-created-declarative-every-v1"

defstruct [:name, :email]
  end

defmodule MyApp.Events.UserEmailChangedDeclarativeEvery do
    use Chronicle.Events.EventType, id: "user-email-changed-declarative-every-v1"

defstruct [:email]
  end

defmodule MyApp.ReadModels.UserProfileDeclarativeEvery do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, :email, :last_updated]
  end

defmodule MyApp.Projections.UserProfileDeclarativeEveryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.UserProfileDeclarativeEvery

alias MyApp.Events.{UserCreatedDeclarativeEvery, UserEmailChangedDeclarativeEvery}

from UserCreatedDeclarativeEvery,
      set: [
        name: :name,
        email: :email
      ]

from UserEmailChangedDeclarativeEvery,
      set: [email: :email]

from_every set: [last_updated: :occurred]
  end
  ```

* TypeScript

Declarative fromEvery

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class UserCreatedDeclarativeEvery {
      constructor(readonly name: string, readonly email: string) {}
  }

@eventType()
  class UserEmailChangedDeclarativeEvery {
      constructor(readonly email: string) {}
  }

@readModel()
  class UserProfileDeclarativeEvery {
      name = '';
      email = '';
      lastUpdated = new Date();
  }

@projection('', UserProfileDeclarativeEvery)
  class UserProfileDeclarativeEveryProjection implements IProjectionFor<UserProfileDeclarativeEvery> {
      define(builder: IProjectionBuilderFor<UserProfileDeclarativeEvery>): void {
          builder
              .from(UserCreatedDeclarativeEvery)
              .from(UserEmailChangedDeclarativeEvery)
              .fromEvery(_ => _
                  .set(m => m.lastUpdated)
                  .toEventContextProperty('occurred'));
      }
  }
  ```

## Event Context Fields

[Section titled “Event Context Fields”](#event-context-fields)

Every-event mappings can map more than one context field.

* C#

Map multiple context fields

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record AccountTouchedDeclarativeEvery(string Reason);

public record AccountAuditDeclarativeEvery(
      DateTimeOffset LastUpdated,
      EventSequenceNumber LastEventSequence,
      string LastCorrelationId);

public class AccountAuditDeclarativeEveryProjection : IProjectionFor<AccountAuditDeclarativeEvery>
  {
      public void Define(IProjectionBuilderFor<AccountAuditDeclarativeEvery> builder) => builder
          .From<AccountTouchedDeclarativeEvery>()
          .FromEvery(_ => _
              .Set(m => m.LastUpdated).ToEventContextProperty(c => c.Occurred)
              .Set(m => m.LastEventSequence).ToEventContextProperty(c => c.SequenceNumber)
              .Set(m => m.LastCorrelationId).ToEventContextProperty(c => c.CorrelationId));
  }
  ```

* Kotlin

Map multiple context fields

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class AccountTouchedDeclarativeEvery(val reason: String)

data class AccountAuditDeclarativeEvery(
      val lastUpdated: String = "",
      val lastEventSequence: String = "",
      val lastCorrelationId: String = ""
  )

class AccountAuditDeclarativeEveryProjection : IProjectionFor<AccountAuditDeclarativeEvery> {
      override fun define(builder: IProjectionBuilderFor<AccountAuditDeclarativeEvery>) {
          builder
              .from(AccountTouchedDeclarativeEvery::class)
              .fromEvery {
                  it.set(AccountAuditDeclarativeEvery::lastUpdated).toEventContextProperty("occurred")
                  it.set(AccountAuditDeclarativeEvery::lastEventSequence).toEventContextProperty("sequenceNumber")
                  it.set(AccountAuditDeclarativeEvery::lastCorrelationId).toEventContextProperty("correlationId")
              }
      }
  }
  ```

* Java

Map multiple context fields

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record AccountTouchedDeclarativeEvery(String reason) {}

class AccountAuditDeclarativeEvery {
      public String lastUpdated = "";
      public String lastEventSequence = "";
      public String lastCorrelationId = "";
  }

class AccountAuditDeclarativeEveryProjection implements IProjectionFor<AccountAuditDeclarativeEvery> {
      @Override
      public void define(IProjectionBuilderFor<AccountAuditDeclarativeEvery> builder) {
          builder
              .from(AccountTouchedDeclarativeEvery.class)
              .fromEvery(feb -> {
                  feb.set("lastUpdated").toEventContextProperty("occurred");
                  feb.set("lastEventSequence").toEventContextProperty("sequenceNumber");
                  feb.set("lastCorrelationId").toEventContextProperty("correlationId");
              });
      }
  }
  ```

* Elixir

Map multiple context fields

```elixir
  defmodule MyApp.Events.AccountTouchedDeclarativeEvery do
    use Chronicle.Events.EventType, id: "account-touched-declarative-every-v1"

defstruct [:reason]
  end

defmodule MyApp.ReadModels.AccountAuditDeclarativeEvery do
    use Chronicle.ReadModels.ReadModel

defstruct [:last_updated, :last_event_sequence, :last_correlation_id]
  end

defmodule MyApp.Projections.AccountAuditDeclarativeEveryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.AccountAuditDeclarativeEvery

alias MyApp.Events.AccountTouchedDeclarativeEvery

from AccountTouchedDeclarativeEvery

from_every set: [
      last_updated: :occurred,
      last_event_sequence: "$context.sequenceNumber",
      last_correlation_id: "$context.correlationId"
    ]
  end
  ```

* TypeScript

Map multiple context fields

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class AccountTouchedDeclarativeEvery {
      constructor(readonly reason: string) {}
  }

@readModel()
  class AccountAuditDeclarativeEvery {
      lastUpdated = new Date();
      lastEventSequence = 0n;
      lastCorrelationId = '';
  }

@projection('', AccountAuditDeclarativeEvery)
  class AccountAuditDeclarativeEveryProjection implements IProjectionFor<AccountAuditDeclarativeEvery> {
      define(builder: IProjectionBuilderFor<AccountAuditDeclarativeEvery>): void {
          builder
              .from(AccountTouchedDeclarativeEvery)
              .fromEvery(_ => _
                  .set(m => m.lastUpdated).toEventContextProperty('occurred')
                  .set(m => m.lastEventSequence).toEventContextProperty('sequenceNumber')
                  .set(m => m.lastCorrelationId).toEventContextProperty('correlationId'));
      }
  }
  ```

## Event Source Id

[Section titled “Event Source Id”](#event-source-id)

Map the event source id when the read model’s primary identifier is not otherwise populated from each event payload.

* C#

Map the event source id

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record AccountOpenedDeclarativeEvery(string OwnerName);

public record AccountSummaryDeclarativeEvery(
      string AccountId,
      string OwnerName);

public class AccountSummaryDeclarativeEveryProjection : IProjectionFor<AccountSummaryDeclarativeEvery>
  {
      public void Define(IProjectionBuilderFor<AccountSummaryDeclarativeEvery> builder) => builder
          .From<AccountOpenedDeclarativeEvery>()
          .FromEvery(_ => _
              .Set(m => m.AccountId)
              .ToEventSourceId());
  }
  ```

* Kotlin

Map the event source id

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class AccountOpenedDeclarativeEvery(val ownerName: String)

data class AccountSummaryDeclarativeEvery(
      val accountId: String = "",
      val ownerName: String = ""
  )

class AccountSummaryDeclarativeEveryProjection : IProjectionFor<AccountSummaryDeclarativeEvery> {
      override fun define(builder: IProjectionBuilderFor<AccountSummaryDeclarativeEvery>) {
          builder
              .from(AccountOpenedDeclarativeEvery::class)
              .fromEvery { it.set(AccountSummaryDeclarativeEvery::accountId).toEventSourceId() }
      }
  }
  ```

* Java

Map the event source id

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record AccountOpenedDeclarativeEvery(String ownerName) {}

class AccountSummaryDeclarativeEvery {
      public String accountId = "";
      public String ownerName = "";
  }

class AccountSummaryDeclarativeEveryProjection implements IProjectionFor<AccountSummaryDeclarativeEvery> {
      @Override
      public void define(IProjectionBuilderFor<AccountSummaryDeclarativeEvery> builder) {
          builder
              .from(AccountOpenedDeclarativeEvery.class)
              .fromEvery(feb -> {
                  feb.set("accountId").toEventSourceId();
              });
      }
  }
  ```

* Elixir

Map the event source id

```elixir
  defmodule MyApp.Events.AccountOpenedDeclarativeEvery do
    use Chronicle.Events.EventType, id: "account-opened-declarative-every-v1"

defstruct [:owner_name]
  end

defmodule MyApp.ReadModels.AccountSummaryDeclarativeEvery do
    use Chronicle.ReadModels.ReadModel

defstruct [:account_id, :owner_name]
  end

defmodule MyApp.Projections.AccountSummaryDeclarativeEveryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.AccountSummaryDeclarativeEvery

alias MyApp.Events.AccountOpenedDeclarativeEvery

from AccountOpenedDeclarativeEvery,
      set: [owner_name: :owner_name]

from_every set: [account_id: :event_source_id]
  end
  ```

* TypeScript

Map the event source id

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class AccountOpenedDeclarativeEvery {
      constructor(readonly ownerName: string) {}
  }

@readModel()
  class AccountSummaryDeclarativeEvery {
      accountId = '';
      ownerName = '';
  }

@projection('', AccountSummaryDeclarativeEvery)
  class AccountSummaryDeclarativeEveryProjection implements IProjectionFor<AccountSummaryDeclarativeEvery> {
      define(builder: IProjectionBuilderFor<AccountSummaryDeclarativeEvery>): void {
          builder
              .from(AccountOpenedDeclarativeEvery)
              .fromEvery(_ => _
                  .set(m => m.accountId)
                  .toEventSourceId());
      }
  }
  ```

## Child Projection Inclusion

[Section titled “Child Projection Inclusion”](#child-projection-inclusion)

Some clients let the projection decide whether child projection events should update parent-level every-event fields.

* C#

Exclude child projection events

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record OrderCreatedDeclarativeEveryExclude(string OrderNumber);

public record OrderAuditDeclarativeEveryExclude(
      string OrderNumber,
      DateTimeOffset LastUpdated);

public class OrderAuditDeclarativeEveryExcludeProjection : IProjectionFor<OrderAuditDeclarativeEveryExclude>
  {
      public void Define(IProjectionBuilderFor<OrderAuditDeclarativeEveryExclude> builder) => builder
          .From<OrderCreatedDeclarativeEveryExclude>()
          .FromEvery(_ => _
              .Set(m => m.LastUpdated)
              .ToEventContextProperty(c => c.Occurred)
              .ExcludeChildProjections());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Exclude child projection events

```elixir
  defmodule MyApp.Events.OrderCreatedDeclarativeEveryExclude do
    use Chronicle.Events.EventType, id: "order-created-declarative-every-exclude-v1"

defstruct [:order_number]
  end

defmodule MyApp.ReadModels.OrderAuditDeclarativeEveryExclude do
    use Chronicle.ReadModels.ReadModel

defstruct [:order_number, :last_updated]
  end

defmodule MyApp.Projections.OrderAuditDeclarativeEveryExcludeProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.OrderAuditDeclarativeEveryExclude

alias MyApp.Events.OrderCreatedDeclarativeEveryExclude

from OrderCreatedDeclarativeEveryExclude

from_every set: [last_updated: :occurred], include_children: false
  end
  ```

* TypeScript

Exclude child projection events

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class OrderCreatedDeclarativeEveryExclude {
      constructor(readonly orderNumber: string) {}
  }

@readModel()
  class OrderAuditDeclarativeEveryExclude {
      orderNumber = '';
      lastUpdated = new Date();
  }

@projection('', OrderAuditDeclarativeEveryExclude)
  class OrderAuditDeclarativeEveryExcludeProjection implements IProjectionFor<OrderAuditDeclarativeEveryExclude> {
      define(builder: IProjectionBuilderFor<OrderAuditDeclarativeEveryExclude>): void {
          builder
              .from(OrderCreatedDeclarativeEveryExclude)
              .fromEvery(_ => _
                  .set(m => m.lastUpdated)
                  .toEventContextProperty('occurred')
                  .excludeChildProjections());
      }
  }
  ```

When child projections are included, parent metadata can update for events that only affect a child item.

Client coverage

* C#

Include child projection events

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record OrderCreatedDeclarativeEveryChildren(string OrderNumber);

[EventType]
  public record ItemAddedDeclarativeEveryChildren(string OrderId, string ProductId, string ProductName, int Quantity);

[EventType]
  public record ItemQuantityChangedDeclarativeEveryChildren(string OrderId, string ProductId, int Quantity);

public record OrderDeclarativeEveryChildren(
      string OrderNumber,
      DateTimeOffset LastModified,
      IEnumerable<OrderItemDeclarativeEveryChildren> Items);

public record OrderItemDeclarativeEveryChildren(
      string ProductId,
      string ProductName,
      int Quantity);

public class OrderDeclarativeEveryChildrenProjection : IProjectionFor<OrderDeclarativeEveryChildren>
  {
      public void Define(IProjectionBuilderFor<OrderDeclarativeEveryChildren> builder) => builder
          .From<OrderCreatedDeclarativeEveryChildren>()
          .FromEvery(_ => _
              .Set(m => m.LastModified)
              .ToEventContextProperty(c => c.Occurred))
          .Children(m => m.Items, children => children
              .IdentifiedBy(m => m.ProductId)
              .From<ItemAddedDeclarativeEveryChildren>(_ => _
                  .UsingKey(e => e.ProductId)
                  .UsingParentKey(e => e.OrderId))
              .From<ItemQuantityChangedDeclarativeEveryChildren>(_ => _
                  .UsingKey(e => e.ProductId)
                  .UsingParentKey(e => e.OrderId)));
  }
  ```

* Kotlin

Include child projection events

@EventType
  data class OrderCreatedDeclarativeEveryChildren(val orderNumber: String)

@EventType
  data class ItemAddedDeclarativeEveryChildren(
      val orderId: String,
      val productId: String,
      val productName: String,
      val quantity: Int
  )

@EventType
  data class ItemQuantityChangedDeclarativeEveryChildren(
      val orderId: String,
      val productId: String,
      val quantity: Int
  )

data class OrderDeclarativeEveryChildren(
      val orderNumber: String = "",
      val lastModified: Instant = Instant.EPOCH,
      val items: List<OrderItemDeclarativeEveryChildren> = emptyList()
  )

data class OrderItemDeclarativeEveryChildren(
      val productId: String = "",
      val productName: String = "",
      val quantity: Int = 0
  )

class OrderDeclarativeEveryChildrenProjection : IProjectionFor<OrderDeclarativeEveryChildren> {
      override fun define(builder: IProjectionBuilderFor<OrderDeclarativeEveryChildren>) {
          builder
              .from(OrderCreatedDeclarativeEveryChildren::class)
              .fromEvery { it.set(OrderDeclarativeEveryChildren::lastModified).toEventContextProperty("occurred") }
              .children(OrderDeclarativeEveryChildren::items, OrderItemDeclarativeEveryChildren::class) { children ->
                  children
                      .identifiedBy("productId")
                      .from(ItemAddedDeclarativeEveryChildren::class) {
                          it.usingKey("productId").usingParentKey("orderId")
                      }
                      .from(ItemQuantityChangedDeclarativeEveryChildren::class) {
                          it.usingKey("productId").usingParentKey("orderId")
                      }
              }
      }
  }
  ```

* Java

Include child projection events

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.time.Instant;
  import java.util.List;

@EventType
  record OrderCreatedDeclarativeEveryChildren(String orderNumber) {}

@EventType
  record ItemAddedDeclarativeEveryChildren(String orderId, String productId, String productName, int quantity) {}

@EventType
  record ItemQuantityChangedDeclarativeEveryChildren(String orderId, String productId, int quantity) {}

class OrderDeclarativeEveryChildren {
      public String orderNumber = "";
      public Instant lastModified = Instant.EPOCH;
      public List<OrderItemDeclarativeEveryChildren> items = List.of();
  }

record OrderItemDeclarativeEveryChildren(String productId, String productName, int quantity) {}

class OrderDeclarativeEveryChildrenProjection implements IProjectionFor<OrderDeclarativeEveryChildren> {
      @Override
      public void define(IProjectionBuilderFor<OrderDeclarativeEveryChildren> builder) {
          builder
              .from(OrderCreatedDeclarativeEveryChildren.class)
              .fromEvery(feb -> {
                  feb.set("lastModified").toEventContextProperty("occurred");
              })
              .children("items", OrderItemDeclarativeEveryChildren.class, children -> {
                  children
                      .identifiedBy("productId")
                      .from(ItemAddedDeclarativeEveryChildren.class, fb -> {
                          fb.usingKey("productId");
                          fb.usingParentKey("orderId");
                      })
                      .from(ItemQuantityChangedDeclarativeEveryChildren.class, fb -> {
                          fb.usingKey("productId");
                          fb.usingParentKey("orderId");
                      });
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class OrderCreatedDeclarativeEveryChildren {
      constructor(readonly orderNumber: string) {}
  }

@eventType()
  class ItemAddedDeclarativeEveryChildren {
      constructor(
          readonly orderId: string,
          readonly productId: string,
          readonly productName: string,
          readonly quantity: number
      ) {}
  }

@eventType()
  class ItemQuantityChangedDeclarativeEveryChildren {
      constructor(readonly orderId: string, readonly productId: string, readonly quantity: number) {}
  }

class OrderItemDeclarativeEveryChildren {
      productId = '';
      productName = '';
      quantity = 0;
  }

class OrderDeclarativeEveryChildren {
      orderNumber = '';
      lastModified = new Date();
      items: OrderItemDeclarativeEveryChildren[] = [];
  }

@projection()
  class OrderDeclarativeEveryChildrenProjection implements IProjectionFor<OrderDeclarativeEveryChildren> {
      define(builder: IProjectionBuilderFor<OrderDeclarativeEveryChildren>): void {
          builder
              .from(OrderCreatedDeclarativeEveryChildren)
              .fromEvery(_ => _
                  .set(m => m.lastModified)
                  .toEventContextProperty('occurred'))
              .children<OrderItemDeclarativeEveryChildren>(m => m.items, children => children
                  .identifiedBy(m => m.productId)
                  .from(ItemAddedDeclarativeEveryChildren, _ => _
                      .usingKey(e => e.productId)
                      .usingParentKey(e => e.orderId))
                  .from(ItemQuantityChangedDeclarativeEveryChildren, _ => _
                      .usingKey(e => e.productId)
                      .usingParentKey(e => e.orderId)));
      }
  }
  ```

## Multiple Declarations

[Section titled “Multiple Declarations”](#multiple-declarations)

Clients that support multiple every-event declarations merge the property mappings into one projection definition.

Elixir

Elixir’s `from_every/1` macro accumulates multiple declarations, but the registration coordinator currently only sends the first one to the kernel — a second `from_every` call is silently dropped. Use a single `from_every` call with all of the property mappings combined instead.

* C#

Multiple FromEvery declarations

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record UserChangedDeclarativeEveryMultiple(string Name);

public record UserAuditDeclarativeEveryMultiple(
      string Name,
      DateTimeOffset LastUpdated,
      string ModifiedBy);

public class UserAuditDeclarativeEveryMultipleProjection : IProjectionFor<UserAuditDeclarativeEveryMultiple>
  {
      public void Define(IProjectionBuilderFor<UserAuditDeclarativeEveryMultiple> builder) => builder
          .From<UserChangedDeclarativeEveryMultiple>()
          .FromEvery(_ => _
              .Set(m => m.LastUpdated)
              .ToEventContextProperty(c => c.Occurred))
          .FromEvery(_ => _
              .Set(m => m.ModifiedBy)
              .ToEventContextProperty(c => c.CausedBy));
  }
  ```

* Kotlin

Multiple FromEvery declarations

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class UserChangedDeclarativeEveryMultiple(val name: String)

data class UserAuditDeclarativeEveryMultiple(
      val name: String = "",
      val lastUpdated: String = "",
      val modifiedBy: String = ""
  )

class UserAuditDeclarativeEveryMultipleProjection : IProjectionFor<UserAuditDeclarativeEveryMultiple> {
      override fun define(builder: IProjectionBuilderFor<UserAuditDeclarativeEveryMultiple>) {
          builder
              .from(UserChangedDeclarativeEveryMultiple::class)
              .fromEvery { it.set(UserAuditDeclarativeEveryMultiple::lastUpdated).toEventContextProperty("occurred") }
              .fromEvery { it.set(UserAuditDeclarativeEveryMultiple::modifiedBy).toEventContextProperty("causedBy") }
      }
  }
  ```

* Java

Multiple FromEvery declarations

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record UserChangedDeclarativeEveryMultiple(String name) {}

class UserAuditDeclarativeEveryMultiple {
      public String name = "";
      public String lastUpdated = "";
      public String modifiedBy = "";
  }

class UserAuditDeclarativeEveryMultipleProjection implements IProjectionFor<UserAuditDeclarativeEveryMultiple> {
      @Override
      public void define(IProjectionBuilderFor<UserAuditDeclarativeEveryMultiple> builder) {
          builder
              .from(UserChangedDeclarativeEveryMultiple.class)
              .fromEvery(feb -> {
                  feb.set("lastUpdated").toEventContextProperty("occurred");
              })
              .fromEvery(feb -> {
                  feb.set("modifiedBy").toEventContextProperty("causedBy");
              });
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.UserChangedEveryMultiple do
    use Chronicle.Events.EventType, id: "user-changed-every-multiple"

defstruct [:name]
  end

defmodule MyApp.ReadModels.UserAuditEveryMultiple do
    use Chronicle.ReadModels.ReadModel

defstruct id: nil, name: nil, last_updated: nil, subject_id: nil

from MyApp.Events.UserChangedEveryMultiple,
      set: [name: :name]

# Every declaration contributes - they are merged, not replaced.
    from_every(set: [last_updated: :occurred])
    from_every(set: [subject_id: :event_source_id])
  end
  ```

* TypeScript

Multiple fromEvery declarations

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class UserChangedDeclarativeEveryMultiple {
      constructor(readonly name: string) {}
  }

@readModel()
  class UserAuditDeclarativeEveryMultiple {
      name = '';
      lastUpdated = new Date();
      modifiedBy = '';
  }

@projection('', UserAuditDeclarativeEveryMultiple)
  class UserAuditDeclarativeEveryMultipleProjection implements IProjectionFor<UserAuditDeclarativeEveryMultiple> {
      define(builder: IProjectionBuilderFor<UserAuditDeclarativeEveryMultiple>): void {
          builder
              .from(UserChangedDeclarativeEveryMultiple)
              .fromEvery(_ => _
                  .set(m => m.lastUpdated)
                  .toEventContextProperty('occurred'))
              .fromEvery(_ => _
                  .set(m => m.modifiedBy)
                  .toEventContextProperty('causedBy'));
      }
  }
  ```

## Common Use Cases

[Section titled “Common Use Cases”](#common-use-cases)

| Use case                    | Typical source                |
| --------------------------- | ----------------------------- |
| Audit timestamp             | Event context occurrence time |
| Event sequencing            | Event context sequence number |
| Correlation tracking        | Event context correlation id  |
| Event source identification | Event source id               |

Use event-specific mappings when the property should update only for selected event types.

# Projection functions

Projections support several built-in functions for mathematical operations and counting. These functions allow you to perform calculations directly within projections without needing custom logic.

> **TypeScript note:** of these, only `Increment()`/`Decrement()` are implemented in TypeScript’s fluent builder today. `Count()`, `Add()`, and `Subtract()` type-check but throw `Error('... is not implemented yet.')` at runtime (`FromBuilder.ts`), so those examples below are C#-only.

## Counting events

[Section titled “Counting events”](#counting-events)

Use `Count()` to increment a counter each time an event is processed:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecFunctionsUserLoggedIn(string Username);

[EventType]
  public record DecFunctionsUserPerformedAction(string Username, string ActionType);

public record DecFunctionsUserActivity(
      string Username,
      int LoginCount,
      int ActionCount);

public class DecFunctionsUserActivityProjection : IProjectionFor<DecFunctionsUserActivity>
  {
      public void Define(IProjectionBuilderFor<DecFunctionsUserActivity> builder) => builder
          .AutoMap()
          .From<DecFunctionsUserLoggedIn>(_ => _
              .Count(m => m.LoginCount))
          .From<DecFunctionsUserPerformedAction>(_ => _
              .Count(m => m.ActionCount));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DecFunctionsUserLoggedIn(val username: String)

@EventType
  data class DecFunctionsUserPerformedAction(val username: String, val actionType: String)

data class DecFunctionsUserActivity(
      val username: String = "",
      val loginCount: Int = 0,
      val actionCount: Int = 0
  )

class DecFunctionsUserActivityProjection : IProjectionFor<DecFunctionsUserActivity> {
      override fun define(builder: IProjectionBuilderFor<DecFunctionsUserActivity>) {
          builder
              .autoMap()
              .from(DecFunctionsUserLoggedIn::class) {
                  it.count(DecFunctionsUserActivity::loginCount)
              }
              .from(DecFunctionsUserPerformedAction::class) {
                  it.count(DecFunctionsUserActivity::actionCount)
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecFunctionsUserLoggedIn(String username) {}

@EventType
  record DecFunctionsUserPerformedAction(String username, String actionType) {}

class DecFunctionsUserActivity {
      public String username = "";
      public int loginCount = 0;
      public int actionCount = 0;
  }

class DecFunctionsUserActivityProjection implements IProjectionFor<DecFunctionsUserActivity> {
      @Override
      public void define(IProjectionBuilderFor<DecFunctionsUserActivity> builder) {
          builder
              .autoMap()
              .from(DecFunctionsUserLoggedIn.class, fb -> {
                  fb.count("loginCount");
              })
              .from(DecFunctionsUserPerformedAction.class, fb -> {
                  fb.count("actionCount");
              });
      }
  }
  ```

* Elixir

Count function

```elixir
  defmodule MyApp.Events.DecFunctionsUserLoggedIn do
    use Chronicle.Events.EventType, id: "dec-functions-user-logged-in"

defstruct [:username]
  end

defmodule MyApp.Events.DecFunctionsUserPerformedAction do
    use Chronicle.Events.EventType, id: "dec-functions-user-performed-action"

defstruct [:username, :action_type]
  end

defmodule MyApp.ReadModels.DecFunctionsUserActivity do
    use Chronicle.ReadModels.ReadModel

defstruct [:username, login_count: 0, action_count: 0]
  end

defmodule MyApp.Projections.DecFunctionsUserActivityProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecFunctionsUserActivity

alias MyApp.Events.{DecFunctionsUserLoggedIn, DecFunctionsUserPerformedAction}

from DecFunctionsUserLoggedIn,
      count: :login_count

from DecFunctionsUserPerformedAction,
      count: :action_count
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecFunctionsUserLoggedIn {
      constructor(readonly username: string) {}
  }

@eventType()
  class DecFunctionsUserPerformedAction {
      constructor(readonly username: string, readonly actionType: string) {}
  }

class DecFunctionsUserActivity {
      username = '';
      loginCount = 0;
      actionCount = 0;
  }

@projection()
  class DecFunctionsUserActivityProjection implements IProjectionFor<DecFunctionsUserActivity> {
      define(builder: IProjectionBuilderFor<DecFunctionsUserActivity>): void {
          builder
              .autoMap()
              .from(DecFunctionsUserLoggedIn, _ => _
                  .count(m => m.loginCount))
              .from(DecFunctionsUserPerformedAction, _ => _
                  .count(m => m.actionCount));
      }
  }
  ```

## Increment and decrement

[Section titled “Increment and decrement”](#increment-and-decrement)

Use `Increment()` and `Decrement()` to add or subtract 1 from a property:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecFunctionsItemAdded(string Name);

[EventType]
  public record DecFunctionsItemRemoved(string Name);

public record DecFunctionsInventory(int Quantity);

public class DecFunctionsInventoryProjection : IProjectionFor<DecFunctionsInventory>
  {
      public void Define(IProjectionBuilderFor<DecFunctionsInventory> builder) => builder
          .AutoMap()
          .From<DecFunctionsItemAdded>(_ => _
              .Increment(m => m.Quantity))
          .From<DecFunctionsItemRemoved>(_ => _
              .Decrement(m => m.Quantity));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DecFunctionsItemAdded(val name: String)

@EventType
  data class DecFunctionsItemRemoved(val name: String)

data class DecFunctionsInventory(val quantity: Int = 0)

class DecFunctionsInventoryProjection : IProjectionFor<DecFunctionsInventory> {
      override fun define(builder: IProjectionBuilderFor<DecFunctionsInventory>) {
          builder
              .autoMap()
              .from(DecFunctionsItemAdded::class) {
                  it.increment(DecFunctionsInventory::quantity)
              }
              .from(DecFunctionsItemRemoved::class) {
                  it.decrement(DecFunctionsInventory::quantity)
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecFunctionsItemAdded(String name) {}

@EventType
  record DecFunctionsItemRemoved(String name) {}

class DecFunctionsInventory {
      public int quantity = 0;
  }

class DecFunctionsInventoryProjection implements IProjectionFor<DecFunctionsInventory> {
      @Override
      public void define(IProjectionBuilderFor<DecFunctionsInventory> builder) {
          builder
              .autoMap()
              .from(DecFunctionsItemAdded.class, fb -> {
                  fb.increment("quantity");
              })
              .from(DecFunctionsItemRemoved.class, fb -> {
                  fb.decrement("quantity");
              });
      }
  }
  ```

* Elixir

Increment/decrement functions

```elixir
  defmodule MyApp.Events.DecFunctionsItemAdded do
    use Chronicle.Events.EventType, id: "dec-functions-item-added"

defstruct [:name]
  end

defmodule MyApp.Events.DecFunctionsItemRemoved do
    use Chronicle.Events.EventType, id: "dec-functions-item-removed"

defstruct [:name]
  end

defmodule MyApp.ReadModels.DecFunctionsInventory do
    use Chronicle.ReadModels.ReadModel

defstruct quantity: 0
  end

defmodule MyApp.Projections.DecFunctionsInventoryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecFunctionsInventory

alias MyApp.Events.{DecFunctionsItemAdded, DecFunctionsItemRemoved}

from DecFunctionsItemAdded,
      add: [quantity: 1]

from DecFunctionsItemRemoved,
      subtract: [quantity: 1]
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecFunctionsItemAdded {
      name = '';
  }

@eventType()
  class DecFunctionsItemRemoved {
      name = '';
  }

class DecFunctionsInventory {
      quantity = 0;
  }

@projection()
  class DecFunctionsInventoryProjection implements IProjectionFor<DecFunctionsInventory> {
      define(builder: IProjectionBuilderFor<DecFunctionsInventory>): void {
          builder
              .autoMap()
              .from(DecFunctionsItemAdded, _ => _
                  .increment(m => m.quantity))
              .from(DecFunctionsItemRemoved, _ => _
                  .decrement(m => m.quantity));
      }
  }
  ```

These functions always change the value by exactly 1.

## Add and subtract with values

[Section titled “Add and subtract with values”](#add-and-subtract-with-values)

Use `Add()` and `Subtract()` to add or subtract specific values from event properties:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecFunctionsAccountOpened(string Number);

[EventType]
  public record DecFunctionsMoneyDeposited(decimal Amount);

[EventType]
  public record DecFunctionsMoneyWithdrawn(decimal Amount);

public record DecFunctionsAccount(string Number, decimal Balance);

public class DecFunctionsAccountProjection : IProjectionFor<DecFunctionsAccount>
  {
      public void Define(IProjectionBuilderFor<DecFunctionsAccount> builder) => builder
          .AutoMap()
          .From<DecFunctionsAccountOpened>(_ => _
              .Set(m => m.Balance).ToValue(0m))
          .From<DecFunctionsMoneyDeposited>(_ => _
              .Add(m => m.Balance).With(e => e.Amount))
          .From<DecFunctionsMoneyWithdrawn>(_ => _
              .Subtract(m => m.Balance).With(e => e.Amount));
  }
  ```

* Kotlin

@EventType
  data class DecFunctionsAccountOpened(val number: String)

@EventType
  data class DecFunctionsMoneyDeposited(val amount: BigDecimal)

@EventType
  data class DecFunctionsMoneyWithdrawn(val amount: BigDecimal)

data class DecFunctionsAccount(val number: String = "", val balance: BigDecimal = BigDecimal.ZERO)

class DecFunctionsAccountProjection : IProjectionFor<DecFunctionsAccount> {
      override fun define(builder: IProjectionBuilderFor<DecFunctionsAccount>) {
          builder
              .autoMap()
              .from(DecFunctionsAccountOpened::class)
              .from(DecFunctionsMoneyDeposited::class) {
                  it.add(DecFunctionsAccount::balance).with("amount")
              }
              .from(DecFunctionsMoneyWithdrawn::class) {
                  it.subtract(DecFunctionsAccount::balance).with("amount")
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.math.BigDecimal;

@EventType
  record DecFunctionsAccountOpened(String number) {}

@EventType
  record DecFunctionsMoneyDeposited(BigDecimal amount) {}

@EventType
  record DecFunctionsMoneyWithdrawn(BigDecimal amount) {}

class DecFunctionsAccount {
      public String number = "";
      public BigDecimal balance = BigDecimal.ZERO;
  }

class DecFunctionsAccountProjection implements IProjectionFor<DecFunctionsAccount> {
      @Override
      public void define(IProjectionBuilderFor<DecFunctionsAccount> builder) {
          builder
              .autoMap()
              .from(DecFunctionsAccountOpened.class)
              .from(DecFunctionsMoneyDeposited.class, fb -> {
                  fb.add("balance").with("amount");
              })
              .from(DecFunctionsMoneyWithdrawn.class, fb -> {
                  fb.subtract("balance").with("amount");
              });
      }
  }
  ```

* Elixir

Add/subtract functions

```elixir
  defmodule MyApp.Events.DecFunctionsAccountOpened do
    use Chronicle.Events.EventType, id: "dec-functions-account-opened"

defstruct [:number]
  end

defmodule MyApp.Events.DecFunctionsMoneyDeposited do
    use Chronicle.Events.EventType, id: "dec-functions-money-deposited"

defstruct [:amount]
  end

defmodule MyApp.Events.DecFunctionsMoneyWithdrawn do
    use Chronicle.Events.EventType, id: "dec-functions-money-withdrawn"

defstruct [:amount]
  end

defmodule MyApp.ReadModels.DecFunctionsAccount do
    use Chronicle.ReadModels.ReadModel

defstruct number: "", balance: 0
  end

defmodule MyApp.Projections.DecFunctionsAccountProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecFunctionsAccount

alias MyApp.Events.{DecFunctionsAccountOpened, DecFunctionsMoneyDeposited, DecFunctionsMoneyWithdrawn}

from DecFunctionsAccountOpened,
      set: [balance: 0]

from DecFunctionsMoneyDeposited,
      add: [balance: :amount]

from DecFunctionsMoneyWithdrawn,
      subtract: [balance: :amount]
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecFunctionsAccountOpened {
      constructor(readonly number: string) {}
  }

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

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

class DecFunctionsAccount {
      number = '';
      balance = 0;
  }

@projection()
  class DecFunctionsAccountProjection implements IProjectionFor<DecFunctionsAccount> {
      define(builder: IProjectionBuilderFor<DecFunctionsAccount>): void {
          builder
              .autoMap()
              .from(DecFunctionsAccountOpened, _ => _
                  .set(m => m.balance).toValue(0))
              .from(DecFunctionsMoneyDeposited, _ => _
                  .add(m => m.balance).with(e => e.amount))
              .from(DecFunctionsMoneyWithdrawn, _ => _
                  .subtract(m => m.balance).with(e => e.amount));
      }
  }
  ```

## Supported types

[Section titled “Supported types”](#supported-types)

All projection functions work with these numeric types:

* `int`
* `long`
* `float`
* `double`
* `decimal`

The functions automatically handle type conversion and maintain the target property’s type.

## How functions work

[Section titled “How functions work”](#how-functions-work)

1. **Initialization**: Properties start at 0 (or their default value) when first accessed
2. **Accumulation**: Functions apply their operations incrementally as events are processed
3. **Type safety**: Values are converted to match the target property type
4. **State preservation**: Current values are maintained between events

## Combining functions

[Section titled “Combining functions”](#combining-functions)

You can use multiple functions in a single projection:

* C#

```csharp
  [EventType]
  public record DecFunctionsTransaction(decimal Amount);

public record DecFunctionsTransactionSummary(
      int TransactionCount,
      decimal TotalAmount,
      int ProcessedEvents);

public class DecFunctionsTransactionSummaryProjection : IProjectionFor<DecFunctionsTransactionSummary>
  {
      public void Define(IProjectionBuilderFor<DecFunctionsTransactionSummary> builder) => builder
          .From<DecFunctionsTransaction>(_ => _
              .Count(m => m.TransactionCount)
              .Add(m => m.TotalAmount).With(e => e.Amount)
              .Increment(m => m.ProcessedEvents));
  }
  ```

* Kotlin

@EventType
  data class DecFunctionsTransaction(val amount: BigDecimal)

data class DecFunctionsTransactionSummary(
      val transactionCount: Int = 0,
      val totalAmount: BigDecimal = BigDecimal.ZERO,
      val processedEvents: Int = 0
  )

class DecFunctionsTransactionSummaryProjection : IProjectionFor<DecFunctionsTransactionSummary> {
      override fun define(builder: IProjectionBuilderFor<DecFunctionsTransactionSummary>) {
          builder
              .from(DecFunctionsTransaction::class) {
                  it.count(DecFunctionsTransactionSummary::transactionCount)
                  it.add(DecFunctionsTransactionSummary::totalAmount).with("amount")
                  it.increment(DecFunctionsTransactionSummary::processedEvents)
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.math.BigDecimal;

@EventType
  record DecFunctionsTransaction(BigDecimal amount) {}

class DecFunctionsTransactionSummary {
      public int transactionCount = 0;
      public BigDecimal totalAmount = BigDecimal.ZERO;
      public int processedEvents = 0;
  }

class DecFunctionsTransactionSummaryProjection implements IProjectionFor<DecFunctionsTransactionSummary> {
      @Override
      public void define(IProjectionBuilderFor<DecFunctionsTransactionSummary> builder) {
          builder
              .from(DecFunctionsTransaction.class, fb -> {
                  fb.count("transactionCount");
                  fb.add("totalAmount").with("amount");
                  fb.increment("processedEvents");
              });
      }
  }
  ```

* Elixir

Combined functions

```elixir
  defmodule MyApp.Events.DecFunctionsTransaction do
    use Chronicle.Events.EventType, id: "dec-functions-transaction"

defstruct [:amount]
  end

defmodule MyApp.ReadModels.DecFunctionsTransactionSummary do
    use Chronicle.ReadModels.ReadModel

defstruct transaction_count: 0, total_amount: 0, processed_events: 0
  end

defmodule MyApp.Projections.DecFunctionsTransactionSummaryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecFunctionsTransactionSummary

alias MyApp.Events.DecFunctionsTransaction

from DecFunctionsTransaction,
      count: :transaction_count,
      add: [total_amount: :amount, processed_events: 1]
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

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

class DecFunctionsTransactionSummary {
      transactionCount = 0;
      totalAmount = 0;
      processedEvents = 0;
  }

@projection()
  class DecFunctionsTransactionSummaryProjection implements IProjectionFor<DecFunctionsTransactionSummary> {
      define(builder: IProjectionBuilderFor<DecFunctionsTransactionSummary>): void {
          builder
              .from(DecFunctionsTransaction, _ => _
                  .count(m => m.transactionCount)
                  .add(m => m.totalAmount).with(e => e.amount)
                  .increment(m => m.processedEvents));
      }
  }
  ```

These functions provide powerful aggregation capabilities while keeping projection logic simple and declarative.

# Projection With Initial Values

Initial values define the read model state Chronicle starts from before applying event mappings. Use them when a property needs a meaningful default even though no event has assigned it yet.

The exact API name depends on the client. .NET exposes `WithInitialValues`, while TypeScript exposes `withInitialValues`.

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

Provide a factory that returns a fresh read model instance with the desired default values. Event mappings then apply on top of that initial state.

Kotlin and Elixir don’t have a `WithInitialValues`-style builder call, but they reach the same result idiomatically: as the client builds the projection definition it registers, it reads the read model type’s own declared defaults — Kotlin’s primary-constructor defaults, Elixir’s `defstruct` defaults — and captures them into that definition (see [Collections](#collections) below for a working example that doesn’t need event context). That capture is why the defaults reach the stored state: they travel with the registered definition, exactly as `WithInitialValues` values do. Nothing runs the constructor when a document is later read — see [The constructor may not run](/chronicle/concepts/designing-read-models/#the-constructor-may-not-run). This particular example also maps an event context property (`Occurred`), which neither client’s fluent projection API can access yet.

* C#

Initial values

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

public enum InitialValuesUserStatus
  {
      Inactive,
      Active
  }

[EventType]
  public record InitialValuesUserCreated(string Name, string Email);

public record InitialValuesUserProfile(
      string Name,
      string Email,
      InitialValuesUserStatus Status,
      DateTimeOffset CreatedAt,
      DateTimeOffset? LastLogin,
      int LoginCount,
      bool IsVerified);

public class InitialValuesUserProfileProjection : IProjectionFor<InitialValuesUserProfile>
  {
      public void Define(IProjectionBuilderFor<InitialValuesUserProfile> builder) => builder
          .WithInitialValues(() => new InitialValuesUserProfile(
              Name: "Unknown user",
              Email: string.Empty,
              Status: InitialValuesUserStatus.Inactive,
              CreatedAt: DateTimeOffset.UnixEpoch,
              LastLogin: null,
              LoginCount: 0,
              IsVerified: false))
          .From<InitialValuesUserCreated>(_ => _
              .Set(m => m.Status).ToValue(InitialValuesUserStatus.Active)
              .Set(m => m.CreatedAt).ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

Initial values

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

enum class InitialValuesUserStatus {
      Inactive,
      Active
  }

@EventType
  data class InitialValuesUserCreated(val name: String, val email: String)

// Kotlin default parameter values are the read model's initial values — the kernel builds
  // the starting instance by calling the primary constructor with none of its arguments supplied.
  data class InitialValuesUserProfile(
      val name: String = "Unknown user",
      val email: String = "",
      val status: InitialValuesUserStatus = InitialValuesUserStatus.Inactive,
      val lastLogin: String? = null,
      val loginCount: Int = 0,
      val isVerified: Boolean = false
  )

class InitialValuesUserProfileProjection : IProjectionFor<InitialValuesUserProfile> {
      override fun define(builder: IProjectionBuilderFor<InitialValuesUserProfile>) {
          builder.from(InitialValuesUserCreated::class)
      }
  }
  ```

* Java

Initial values

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

enum InitialValuesUserStatus {
      Inactive,
      Active
  }

@EventType
  record InitialValuesUserCreated(String name, String email) {}

// Field initializers are the read model's initial values — the kernel builds the starting
  // instance by calling the no-argument constructor.
  class InitialValuesUserProfile {
      public String name = "Unknown user";
      public String email = "";
      public InitialValuesUserStatus status = InitialValuesUserStatus.Inactive;
      public String lastLogin = null;
      public int loginCount = 0;
      public boolean isVerified = false;
  }

class InitialValuesUserProfileProjection implements IProjectionFor<InitialValuesUserProfile> {
      @Override
      public void define(IProjectionBuilderFor<InitialValuesUserProfile> builder) {
          builder.from(InitialValuesUserCreated.class);
      }
  }
  ```

* Elixir

Initial values

```elixir
  defmodule MyApp.Events.DecInitialValuesUserCreated do
    use Chronicle.Events.EventType, id: "dec-initial-values-user-created"

defstruct [:name, :email]
  end

defmodule MyApp.ReadModels.DecInitialValuesUserProfile do
    use Chronicle.ReadModels.ReadModel

# Elixir has no separate WithInitialValues builder call — the struct's own
    # defaults are captured as the projection's initial model state.
    defstruct name: "Unknown user",
              email: "",
              status: "Inactive",
              created_at: ~U[1970-01-01 00:00:00Z],
              last_login: nil,
              login_count: 0,
              is_verified: false
  end

defmodule MyApp.Projections.DecInitialValuesUserProfileProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecInitialValuesUserProfile

alias MyApp.Events.DecInitialValuesUserCreated

from DecInitialValuesUserCreated,
      set: [
        status: "$value(Active)",
        created_at: :occurred
      ]
  end
  ```

* TypeScript

Initial values

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

enum InitialValuesUserStatus {
      Inactive = 'Inactive',
      Active = 'Active'
  }

@eventType()
  class InitialValuesUserCreated {
      constructor(readonly name: string, readonly email: string) {}
  }

@readModel()
  class InitialValuesUserProfile {
      name = 'Unknown user';
      email = '';
      status = InitialValuesUserStatus.Inactive;
      createdAt = new Date(0);
      lastLogin: Date | null = null;
      loginCount = 0;
      isVerified = false;
  }

@projection('', InitialValuesUserProfile)
  class InitialValuesUserProfileProjection implements IProjectionFor<InitialValuesUserProfile> {
      define(builder: IProjectionBuilderFor<InitialValuesUserProfile>): void {
          builder
              .withInitialValues(() => new InitialValuesUserProfile())
              .from(InitialValuesUserCreated, _ => _
                  .set(m => m.status).toValue(InitialValuesUserStatus.Active)
                  .set(m => m.createdAt).toEventContextProperty('occurred'));
      }
  }
  ```

## Why Use Initial Values

[Section titled “Why Use Initial Values”](#why-use-initial-values)

Without initial values, properties that are not touched by a projection mapping keep the platform’s default representation. That can mean `null`, `0`, `false`, an empty string, or an unset date depending on the client and storage representation.

Initial values are useful for:

| Need                 | Example                                                                             |
| -------------------- | ----------------------------------------------------------------------------------- |
| Business defaults    | A new order starts as draft until an event changes its status.                      |
| Non-null collections | A customer read model starts with empty address and tag collections.                |
| Sentinel values      | A timestamp starts at a known sentinel until the first event provides a real value. |
| Partial events       | Inventory limits are configured once while stock events update only quantities.     |

## Business Defaults

[Section titled “Business Defaults”](#business-defaults)

Set defaults that describe the domain state before the first relevant event changes it.

* C#

Business defaults

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

public enum InitialValuesOrderStatus
  {
      Draft,
      Submitted
  }

[EventType]
  public record InitialValuesOrderSubmitted(string CustomerName, decimal TotalAmount);

public record InitialValuesOrderSummary(
      string CustomerName,
      InitialValuesOrderStatus Status,
      decimal TotalAmount,
      DateTimeOffset SubmittedAt,
      string Notes);

public class InitialValuesOrderSummaryProjection : IProjectionFor<InitialValuesOrderSummary>
  {
      public void Define(IProjectionBuilderFor<InitialValuesOrderSummary> builder) => builder
          .WithInitialValues(() => new InitialValuesOrderSummary(
              CustomerName: string.Empty,
              Status: InitialValuesOrderStatus.Draft,
              TotalAmount: 0m,
              SubmittedAt: DateTimeOffset.UnixEpoch,
              Notes: "No notes"))
          .From<InitialValuesOrderSubmitted>(_ => _
              .Set(m => m.Status).ToValue(InitialValuesOrderStatus.Submitted)
              .Set(m => m.SubmittedAt).ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

Business defaults

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

enum class InitialValuesOrderStatus {
      Draft,
      Submitted
  }

@EventType
  data class InitialValuesOrderSubmitted(val customerName: String, val totalAmount: Double)

data class InitialValuesOrderSummary(
      val customerName: String = "",
      val status: InitialValuesOrderStatus = InitialValuesOrderStatus.Draft,
      val totalAmount: Double = 0.0,
      val notes: String = "No notes"
  )

class InitialValuesOrderSummaryProjection : IProjectionFor<InitialValuesOrderSummary> {
      override fun define(builder: IProjectionBuilderFor<InitialValuesOrderSummary>) {
          builder.from(InitialValuesOrderSubmitted::class)
      }
  }
  ```

* Java

Business defaults

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

enum InitialValuesOrderStatus {
      Draft,
      Submitted
  }

@EventType
  record InitialValuesOrderSubmitted(String customerName, double totalAmount) {}

class InitialValuesOrderSummary {
      public String customerName = "";
      public InitialValuesOrderStatus status = InitialValuesOrderStatus.Draft;
      public double totalAmount = 0.0;
      public String notes = "No notes";
  }

class InitialValuesOrderSummaryProjection implements IProjectionFor<InitialValuesOrderSummary> {
      @Override
      public void define(IProjectionBuilderFor<InitialValuesOrderSummary> builder) {
          builder.from(InitialValuesOrderSubmitted.class);
      }
  }
  ```

* Elixir

Business defaults

```elixir
  defmodule MyApp.Events.DecInitialValuesOrderSubmitted do
    use Chronicle.Events.EventType, id: "dec-initial-values-order-submitted"

defstruct [:customer_name, :total_amount]
  end

defmodule MyApp.ReadModels.DecInitialValuesOrderSummary do
    use Chronicle.ReadModels.ReadModel

defstruct customer_name: "",
              status: "Draft",
              total_amount: 0,
              submitted_at: ~U[1970-01-01 00:00:00Z],
              notes: "No notes"
  end

defmodule MyApp.Projections.DecInitialValuesOrderSummaryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecInitialValuesOrderSummary

alias MyApp.Events.DecInitialValuesOrderSubmitted

from DecInitialValuesOrderSubmitted,
      set: [
        status: "$value(Submitted)",
        submitted_at: :occurred
      ]
  end
  ```

* TypeScript

Business defaults

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

enum InitialValuesOrderStatus {
      Draft = 'Draft',
      Submitted = 'Submitted'
  }

@eventType()
  class InitialValuesOrderSubmitted {
      constructor(readonly customerName: string, readonly totalAmount: number) {}
  }

@readModel()
  class InitialValuesOrderSummary {
      customerName = '';
      status = InitialValuesOrderStatus.Draft;
      totalAmount = 0;
      submittedAt = new Date(0);
      notes = 'No notes';
  }

@projection('', InitialValuesOrderSummary)
  class InitialValuesOrderSummaryProjection implements IProjectionFor<InitialValuesOrderSummary> {
      define(builder: IProjectionBuilderFor<InitialValuesOrderSummary>): void {
          builder
              .withInitialValues(() => new InitialValuesOrderSummary())
              .from(InitialValuesOrderSubmitted, _ => _
                  .set(m => m.status).toValue(InitialValuesOrderStatus.Submitted)
                  .set(m => m.submittedAt).toEventContextProperty('occurred'));
      }
  }
  ```

## Collections

[Section titled “Collections”](#collections)

Initialize collections so consumers can treat them as empty collections instead of checking for missing values.

* C#

Initialize collections

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

public record InitialValuesAddress(string Street, string City);

[EventType]
  public record InitialValuesCustomerRegistered(string Name);

public record InitialValuesCustomerRecord(
      string Name,
      IEnumerable<InitialValuesAddress> Addresses,
      IEnumerable<string> Tags);

public class InitialValuesCustomerRecordProjection : IProjectionFor<InitialValuesCustomerRecord>
  {
      public void Define(IProjectionBuilderFor<InitialValuesCustomerRecord> builder) => builder
          .WithInitialValues(() => new InitialValuesCustomerRecord(
              Name: string.Empty,
              Addresses: Array.Empty<InitialValuesAddress>(),
              Tags: Array.Empty<string>()))
          .From<InitialValuesCustomerRegistered>();
  }
  ```

* Kotlin

Initialize collections

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

data class InitialValuesAddress(val street: String, val city: String)

@EventType
  data class InitialValuesCustomerRegistered(val name: String)

data class InitialValuesCustomerRecord(
      val name: String = "",
      val addresses: List<InitialValuesAddress> = emptyList(),
      val tags: List<String> = emptyList()
  )

class InitialValuesCustomerRecordProjection : IProjectionFor<InitialValuesCustomerRecord> {
      override fun define(builder: IProjectionBuilderFor<InitialValuesCustomerRecord>) {
          builder.from(InitialValuesCustomerRegistered::class)
      }
  }
  ```

* Java

Initialize collections

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.util.Collections;
  import java.util.List;

class InitialValuesAddress {
      public String street;
      public String city;

InitialValuesAddress(String street, String city) {
          this.street = street;
          this.city = city;
      }
  }

@EventType
  record InitialValuesCustomerRegistered(String name) {}

class InitialValuesCustomerRecord {
      public String name = "";
      public List<InitialValuesAddress> addresses = Collections.emptyList();
      public List<String> tags = Collections.emptyList();
  }

class InitialValuesCustomerRecordProjection implements IProjectionFor<InitialValuesCustomerRecord> {
      @Override
      public void define(IProjectionBuilderFor<InitialValuesCustomerRecord> builder) {
          builder.from(InitialValuesCustomerRegistered.class);
      }
  }
  ```

* Elixir

Initialize collections

```elixir
  defmodule MyApp.Events.InitialValuesCustomerRegistered do
    use Chronicle.Events.EventType, id: "initial-values-customer-registered"

defstruct [:name]
  end

defmodule MyApp.ReadModels.InitialValuesCustomerRecord do
    use Chronicle.ReadModels.ReadModel

defstruct name: "", addresses: [], tags: []
  end

defmodule MyApp.Projections.InitialValuesCustomerRecordProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.InitialValuesCustomerRecord

alias MyApp.Events.InitialValuesCustomerRegistered

from InitialValuesCustomerRegistered
  end
  ```

* TypeScript

Initialize collections

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

class InitialValuesAddress {
      street = '';
      city = '';
  }

@eventType()
  class InitialValuesCustomerRegistered {
      constructor(readonly name: string) {}
  }

@readModel()
  class InitialValuesCustomerRecord {
      name = '';
      addresses: InitialValuesAddress[] = [];
      tags: string[] = [];
  }

@projection('', InitialValuesCustomerRecord)
  class InitialValuesCustomerRecordProjection implements IProjectionFor<InitialValuesCustomerRecord> {
      define(builder: IProjectionBuilderFor<InitialValuesCustomerRecord>): void {
          builder
              .withInitialValues(() => new InitialValuesCustomerRecord())
              .from(InitialValuesCustomerRegistered);
      }
  }
  ```

Caution

This does not work for a child collection. A children path is applied only by the child add and remove operations, so an initial value for it is dropped before it reaches the sink — deliberately, because writing an empty array from the root event would erase a child a parallel replay had already added. Declare the property non-nullable instead, and Chronicle materializes it as an empty collection on read. See [Empty child collections](/chronicle/read-models/empty-child-collections/).

## Events That Do Not Cover Every Property

[Section titled “Events That Do Not Cover Every Property”](#events-that-do-not-cover-every-property)

Initial values are useful when events update operational fields but leave configuration fields unchanged.

> **TypeScript note:** this example uses `Add()`/`With()`, the fluent builder’s variable-delta accumulation operators. TypeScript’s `add()`/`subtract()` are not implemented yet (`FromBuilder.ts` throws at runtime even though the call type-checks), so this specific example is unsupported in TypeScript for now. Elixir’s `add:`/`subtract:` property options **do** work, so this example is also shown there.

* C#

Defaults for fields events do not set

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record InitialValuesStockReceived(int Quantity);

[EventType]
  public record InitialValuesStockReserved(int Quantity);

public record InitialValuesInventoryItem(
      int CurrentStock,
      int ReservedStock,
      DateTimeOffset LastUpdated,
      int MinimumLevel,
      int MaximumLevel,
      int ReorderPoint);

public class InitialValuesInventoryProjection : IProjectionFor<InitialValuesInventoryItem>
  {
      public void Define(IProjectionBuilderFor<InitialValuesInventoryItem> builder) => builder
          .WithInitialValues(() => new InitialValuesInventoryItem(
              CurrentStock: 0,
              ReservedStock: 0,
              LastUpdated: DateTimeOffset.UnixEpoch,
              MinimumLevel: 10,
              MaximumLevel: 1000,
              ReorderPoint: 20))
          .From<InitialValuesStockReceived>(_ => _
              .Add(m => m.CurrentStock).With(e => e.Quantity)
              .Set(m => m.LastUpdated).ToEventContextProperty(c => c.Occurred))
          .From<InitialValuesStockReserved>(_ => _
              .Add(m => m.ReservedStock).With(e => e.Quantity)
              .Set(m => m.LastUpdated).ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Defaults for fields events do not set

```elixir
  defmodule MyApp.Events.InitialValuesStockReceived do
    use Chronicle.Events.EventType, id: "initial-values-stock-received"

defstruct [:quantity]
  end

defmodule MyApp.Events.InitialValuesStockReserved do
    use Chronicle.Events.EventType, id: "initial-values-stock-reserved"

defstruct [:quantity]
  end

defmodule MyApp.ReadModels.InitialValuesInventoryItem do
    use Chronicle.ReadModels.ReadModel

defstruct current_stock: 0,
              reserved_stock: 0,
              last_updated: nil,
              minimum_level: 10,
              maximum_level: 1000,
              reorder_point: 20
  end

defmodule MyApp.Projections.InitialValuesInventoryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.InitialValuesInventoryItem

alias MyApp.Events.{InitialValuesStockReceived, InitialValuesStockReserved}

from InitialValuesStockReceived,
      add: [current_stock: :quantity],
      set: [last_updated: :occurred]

from InitialValuesStockReserved,
      add: [reserved_stock: :quantity],
      set: [last_updated: :occurred]
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Best Practices

[Section titled “Best Practices”](#best-practices)

* Use the factory form so each read model starts from a fresh instance.
* Prefer deterministic defaults. The initial state is captured when the projection definition is built.
* Keep defaults domain meaningful; do not duplicate platform defaults unless the value communicates intent.
* Initialize collections that readers naturally expect to enumerate.
* Let events own facts that actually happened; initial values are for the state before those facts are projected.

# Projection with joins

Joins allow projections to incorporate data from events that don’t share the same event source ID. This enables building read models that combine data from different streams.

## Defining a projection with joins

[Section titled “Defining a projection with joins”](#defining-a-projection-with-joins)

Use the `Join()` method to include data from events with different keys:

* C#

```csharp
  using Cratis.Chronicle.Projections;

public class DecJoinsUserProjection : IProjectionFor<DecJoinsUser>
  {
      public void Define(IProjectionBuilderFor<DecJoinsUser> builder) => builder
          .AutoMap()
          .From<DecJoinsUserCreated>()
          .From<DecJoinsUserAssignedToGroup>(b => b
              .UsingKey(e => e.UserId)
              .Set(m => m.GroupId).ToEventSourceId())
          .Join<DecJoinsGroupCreated>(j => j
              .On(m => m.GroupId))
          .Join<DecJoinsGroupRenamed>(j => j
              .On(m => m.GroupId));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

class DecJoinsUserProjection : IProjectionFor<DecJoinsUser> {
      override fun define(builder: IProjectionBuilderFor<DecJoinsUser>) {
          builder
              .from(DecJoinsUserCreated::class)
              .from(DecJoinsUserAssignedToGroup::class) {
                  it.usingKey("userId")
                  it.set(DecJoinsUser::groupId).toEventSourceId()
              }
              .join(DecJoinsGroupCreated::class) { it.on(DecJoinsUser::groupId) }
              .join(DecJoinsGroupRenamed::class) { it.on(DecJoinsUser::groupId) }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

class DecJoinsUserProjection implements IProjectionFor<DecJoinsUser> {
      @Override
      public void define(IProjectionBuilderFor<DecJoinsUser> builder) {
          builder
              .from(DecJoinsUserCreated.class)
              .from(DecJoinsUserAssignedToGroup.class, fb -> {
                  fb.usingKey("userId");
                  fb.set("groupId").toEventSourceId();
              })
              .join(DecJoinsGroupCreated.class, jb -> {
                  jb.on("groupId");
              })
              .join(DecJoinsGroupRenamed.class, jb -> {
                  jb.on("groupId");
              });
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Projections.DecJoinsUserProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecJoinsUser

alias MyApp.Events.{
      DecJoinsUserCreated,
      DecJoinsUserAssignedToGroup,
      DecJoinsGroupCreated,
      DecJoinsGroupRenamed
    }

from DecJoinsUserCreated

from DecJoinsUserAssignedToGroup,
      key: :user_id,
      set: [group_id: :event_source_id]

join DecJoinsGroupCreated, on: :group_id
    join DecJoinsGroupRenamed, on: :group_id
  end
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecJoinsUserProjection implements IProjectionFor<DecJoinsUser> {
      define(builder: IProjectionBuilderFor<DecJoinsUser>): void {
          builder
              .autoMap()
              .from(DecJoinsUserCreated)
              .from(DecJoinsUserAssignedToGroup, b => b
                  .usingKey(e => e.userId)
                  .set(m => m.groupId).toEventSourceId())
              .join(DecJoinsGroupCreated, j => j
                  .on(m => m.groupId))
              .join(DecJoinsGroupRenamed, j => j
                  .on(m => m.groupId));
      }
  }
  ```

## Read model with joined data

[Section titled “Read model with joined data”](#read-model-with-joined-data)

The read model includes properties populated from different event sources:

* C#

```csharp
  public record DecJoinsUser(
      string Name,
      string Email,
      string? GroupId,
      string? GroupName,
      string? GroupDescription);
  ```

* Kotlin

```kotlin
  data class DecJoinsUser(
      val name: String = "",
      val email: String = "",
      val groupId: String? = null,
      val groupName: String? = null,
      val groupDescription: String? = null
  )
  ```

* Java

```java
  class DecJoinsUser {
      public String name = "";
      public String email = "";
      public String groupId = null;
      public String groupName = null;
      public String groupDescription = null;
  }
  ```

* Elixir

Read model

```elixir
  defmodule MyApp.ReadModels.DecJoinsUser do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, :email, :group_id, :group_name, :group_description]
  end
  ```

* TypeScript

```typescript
  class DecJoinsUser {
      name = '';
      email = '';
      groupId: string | null = null;
      groupName: string | null = null;
      groupDescription: string | null = null;
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

Events come from different streams but are joined based on common identifiers:

* C#

```csharp
  using Cratis.Chronicle.Events;

// User stream events
  [EventType]
  public record DecJoinsUserCreated(string Name, string Email);

[EventType]
  public record DecJoinsUserAssignedToGroup(string UserId, string GroupId);

// Group stream events
  [EventType]
  public record DecJoinsGroupCreated(string Name, string Description);

[EventType]
  public record DecJoinsGroupRenamed(string NewName);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

// User stream events
  @EventType
  data class DecJoinsUserCreated(val name: String, val email: String)

@EventType
  data class DecJoinsUserAssignedToGroup(val userId: String, val groupId: String)

// Group stream events
  @EventType
  data class DecJoinsGroupCreated(val name: String, val description: String)

@EventType
  data class DecJoinsGroupRenamed(val newName: String)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

// User stream events
  @EventType
  record DecJoinsUserCreated(String name, String email) {}

@EventType
  record DecJoinsUserAssignedToGroup(String userId, String groupId) {}

// Group stream events
  @EventType
  record DecJoinsGroupCreated(String name, String description) {}

@EventType
  record DecJoinsGroupRenamed(String newName) {}
  ```

* Elixir

Events

```elixir
  defmodule MyApp.Events.DecJoinsUserCreated do
    use Chronicle.Events.EventType, id: "dec-joins-user-created"

defstruct [:name, :email]
  end

defmodule MyApp.Events.DecJoinsUserAssignedToGroup do
    use Chronicle.Events.EventType, id: "dec-joins-user-assigned-to-group"

defstruct [:user_id, :group_id]
  end

defmodule MyApp.Events.DecJoinsGroupCreated do
    use Chronicle.Events.EventType, id: "dec-joins-group-created"

defstruct [:name, :description]
  end

defmodule MyApp.Events.DecJoinsGroupRenamed do
    use Chronicle.Events.EventType, id: "dec-joins-group-renamed"

defstruct [:new_name]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

// User stream events
  @eventType()
  class DecJoinsUserCreated {
      constructor(readonly name: string, readonly email: string) {}
  }

@eventType()
  class DecJoinsUserAssignedToGroup {
      constructor(readonly userId: string, readonly groupId: string) {}
  }

// Group stream events
  @eventType()
  class DecJoinsGroupCreated {
      constructor(readonly name: string, readonly description: string) {}
  }

@eventType()
  class DecJoinsGroupRenamed {
      constructor(readonly newName: string) {}
  }
  ```

## How joins work

[Section titled “How joins work”](#how-joins-work)

1. **Primary events** establish the read model and may set join keys
2. **Join conditions** specify which property links to other streams
3. **Joined events** update properties when their event source ID matches the join key
4. Join properties are updated whenever relevant events occur
5. **Joined values take precedence** — a joined property is applied over any value a `From` block wrote for the same property, in whichever order the events arrived

## Join scenarios

[Section titled “Join scenarios”](#join-scenarios)

### Setting join keys

[Section titled “Setting join keys”](#setting-join-keys)

Join keys are typically set from events that establish relationships — in the example above, `UserAssignedToGroup` sets `GroupId` to the group’s own event source ID via `.ToEventSourceId()`.

### Joining on the key

[Section titled “Joining on the key”](#joining-on-the-key)

Joins match events based on their event source ID and the join property — `.Join<GroupCreated>(j => j.On(m => m.GroupId))` links in group data whenever a `GroupCreated`/`GroupRenamed` event’s event source ID matches the read model’s `GroupId`.

### Join precedence

[Section titled “Join precedence”](#join-precedence)

When a `From` block and a join write the same property, the joined value wins — regardless of arrival order. Whenever the projection handles a `From` event, Chronicle re-resolves the join against the joined stream’s last stored event and applies the joined properties after the `From` mappings. A `From` block therefore cannot reset or clear a property a join has written; there is no “clear this joined value” operation. If a property must reflect which fact happened most recently, give each fact its own property (for example, two timestamps) and compare them, rather than latching a single flag written from both sides. The [CHR0042](/chronicle/code-analysis/chr0042/) analyzer warns when the same property is written from both sides.

### Multiple joins

[Section titled “Multiple joins”](#multiple-joins)

A projection can join with multiple streams:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecJoinsMultipleEmployeeAssigned(string GroupId, string DepartmentId, string LocationId);

[EventType]
  public record DecJoinsMultipleGroupCreated(string Name);

[EventType]
  public record DecJoinsMultipleDepartmentCreated(string Name);

[EventType]
  public record DecJoinsMultipleLocationUpdated(string Address);

public record DecJoinsMultipleEmployeeSummary(
      string? GroupId,
      string? GroupName,
      string? DepartmentId,
      string? DepartmentName,
      string? LocationId,
      string? LocationAddress);

public class DecJoinsMultipleEmployeeSummaryProjection : IProjectionFor<DecJoinsMultipleEmployeeSummary>
  {
      public void Define(IProjectionBuilderFor<DecJoinsMultipleEmployeeSummary> builder) => builder
          .AutoMap()
          .From<DecJoinsMultipleEmployeeAssigned>()
          .Join<DecJoinsMultipleGroupCreated>(j => j.On(m => m.GroupId))
          .Join<DecJoinsMultipleDepartmentCreated>(j => j.On(m => m.DepartmentId))
          .Join<DecJoinsMultipleLocationUpdated>(j => j.On(m => m.LocationId));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DecJoinsMultipleEmployeeAssigned(val groupId: String, val departmentId: String, val locationId: String)

@EventType
  data class DecJoinsMultipleGroupCreated(val name: String)

@EventType
  data class DecJoinsMultipleDepartmentCreated(val name: String)

@EventType
  data class DecJoinsMultipleLocationUpdated(val address: String)

data class DecJoinsMultipleEmployeeSummary(
      val groupId: String? = null,
      val groupName: String? = null,
      val departmentId: String? = null,
      val departmentName: String? = null,
      val locationId: String? = null,
      val locationAddress: String? = null
  )

class DecJoinsMultipleEmployeeSummaryProjection : IProjectionFor<DecJoinsMultipleEmployeeSummary> {
      override fun define(builder: IProjectionBuilderFor<DecJoinsMultipleEmployeeSummary>) {
          builder
              .from(DecJoinsMultipleEmployeeAssigned::class)
              .join(DecJoinsMultipleGroupCreated::class) { it.on(DecJoinsMultipleEmployeeSummary::groupId) }
              .join(DecJoinsMultipleDepartmentCreated::class) { it.on(DecJoinsMultipleEmployeeSummary::departmentId) }
              .join(DecJoinsMultipleLocationUpdated::class) { it.on(DecJoinsMultipleEmployeeSummary::locationId) }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecJoinsMultipleEmployeeAssigned(String groupId, String departmentId, String locationId) {}

@EventType
  record DecJoinsMultipleGroupCreated(String name) {}

@EventType
  record DecJoinsMultipleDepartmentCreated(String name) {}

@EventType
  record DecJoinsMultipleLocationUpdated(String address) {}

class DecJoinsMultipleEmployeeSummary {
      public String groupId = null;
      public String groupName = null;
      public String departmentId = null;
      public String departmentName = null;
      public String locationId = null;
      public String locationAddress = null;
  }

class DecJoinsMultipleEmployeeSummaryProjection implements IProjectionFor<DecJoinsMultipleEmployeeSummary> {
      @Override
      public void define(IProjectionBuilderFor<DecJoinsMultipleEmployeeSummary> builder) {
          builder
              .from(DecJoinsMultipleEmployeeAssigned.class)
              .join(DecJoinsMultipleGroupCreated.class, jb -> {
                  jb.on("groupId");
              })
              .join(DecJoinsMultipleDepartmentCreated.class, jb -> {
                  jb.on("departmentId");
              })
              .join(DecJoinsMultipleLocationUpdated.class, jb -> {
                  jb.on("locationId");
              });
      }
  }
  ```

* Elixir

Multiple joins

```elixir
  defmodule MyApp.Events.DecJoinsMultipleEmployeeAssigned do
    use Chronicle.Events.EventType, id: "dec-joins-multiple-employee-assigned"

defstruct [:group_id, :department_id, :location_id]
  end

defmodule MyApp.Events.DecJoinsMultipleGroupCreated do
    use Chronicle.Events.EventType, id: "dec-joins-multiple-group-created"

defstruct [:name]
  end

defmodule MyApp.Events.DecJoinsMultipleDepartmentCreated do
    use Chronicle.Events.EventType, id: "dec-joins-multiple-department-created"

defstruct [:name]
  end

defmodule MyApp.Events.DecJoinsMultipleLocationUpdated do
    use Chronicle.Events.EventType, id: "dec-joins-multiple-location-updated"

defstruct [:address]
  end

defmodule MyApp.ReadModels.DecJoinsMultipleEmployeeSummary do
    use Chronicle.ReadModels.ReadModel

defstruct [:group_id, :group_name, :department_id, :department_name, :location_id, :location_address]
  end

defmodule MyApp.Projections.DecJoinsMultipleEmployeeSummaryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecJoinsMultipleEmployeeSummary

alias MyApp.Events.{
      DecJoinsMultipleEmployeeAssigned,
      DecJoinsMultipleGroupCreated,
      DecJoinsMultipleDepartmentCreated,
      DecJoinsMultipleLocationUpdated
    }

from DecJoinsMultipleEmployeeAssigned

join DecJoinsMultipleGroupCreated, on: :group_id
    join DecJoinsMultipleDepartmentCreated, on: :department_id
    join DecJoinsMultipleLocationUpdated, on: :location_id
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecJoinsMultipleEmployeeAssigned {
      groupId = '';
      departmentId = '';
      locationId = '';
  }

@eventType()
  class DecJoinsMultipleGroupCreated {
      name = '';
  }

@eventType()
  class DecJoinsMultipleDepartmentCreated {
      name = '';
  }

@eventType()
  class DecJoinsMultipleLocationUpdated {
      address = '';
  }

class DecJoinsMultipleEmployeeSummary {
      groupId: string | null = null;
      groupName: string | null = null;
      departmentId: string | null = null;
      departmentName: string | null = null;
      locationId: string | null = null;
      locationAddress: string | null = null;
  }

@projection()
  class DecJoinsMultipleEmployeeSummaryProjection implements IProjectionFor<DecJoinsMultipleEmployeeSummary> {
      define(builder: IProjectionBuilderFor<DecJoinsMultipleEmployeeSummary>): void {
          builder
              .autoMap()
              .from(DecJoinsMultipleEmployeeAssigned)
              .join(DecJoinsMultipleGroupCreated, j => j.on(m => m.groupId))
              .join(DecJoinsMultipleDepartmentCreated, j => j.on(m => m.departmentId))
              .join(DecJoinsMultipleLocationUpdated, j => j.on(m => m.locationId));
      }
  }
  ```

### Joining children

[Section titled “Joining children”](#joining-children)

Joins can also be used within child collections:

Client coverage

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecJoinsChildTaskAssigned(string TaskId, string ProjectId);

[EventType]
  public record DecJoinsChildProjectCreated(string Name);

public record DecJoinsChildTask(string TaskId, string ProjectId, string? ProjectName);

public record DecJoinsChildProjectBoard(IEnumerable<DecJoinsChildTask> Tasks);

public class DecJoinsChildProjectBoardProjection : IProjectionFor<DecJoinsChildProjectBoard>
  {
      public void Define(IProjectionBuilderFor<DecJoinsChildProjectBoard> builder) => builder
          .Children(m => m.Tasks, children => children
              .IdentifiedBy(e => e.TaskId)
              .AutoMap()
              .From<DecJoinsChildTaskAssigned>(b => b
                  .UsingKey(e => e.TaskId))
              .Join<DecJoinsChildProjectCreated>(j => j
                  .On(m => m.ProjectId)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `IChildrenBuilderFor` has no `join()` method — joins are only available on the top-level
  `IProjectionBuilderFor<TReadModel>`, not inside a child collection scope.
  ```

* Java

```text
  Java does not support this workflow yet.
  `IChildrenBuilderFor` has no `join()` method — joins are only available on the top-level
  `IProjectionBuilderFor<TReadModel>`, not inside a child collection scope.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecJoinsChildTaskAssigned {
      constructor(readonly taskId: string, readonly projectId: string) {}
  }

@eventType()
  class DecJoinsChildProjectCreated {
      constructor(readonly name: string) {}
  }

class DecJoinsChildTask {
      taskId = '';
      projectId = '';
      projectName: string | null = null;
  }

class DecJoinsChildProjectBoard {
      tasks: DecJoinsChildTask[] = [];
  }

@projection()
  class DecJoinsChildProjectBoardProjection implements IProjectionFor<DecJoinsChildProjectBoard> {
      define(builder: IProjectionBuilderFor<DecJoinsChildProjectBoard>): void {
          builder
              .children<DecJoinsChildTask>(m => m.tasks, children => children
                  .identifiedBy(e => e.taskId)
                  .autoMap()
                  .from(DecJoinsChildTaskAssigned, b => b
                      .usingKey(e => e.taskId))
                  .join(DecJoinsChildProjectCreated, j => j
                      .on(m => m.projectId)));
      }
  }
  ```

## Performance considerations

[Section titled “Performance considerations”](#performance-considerations)

* Joins require Chronicle to track relationships between streams
* The system automatically manages join indexes and updates
* Consider the frequency of joined events when designing projections
* Large numbers of joins may impact projection performance

Joins enable powerful cross-stream read models while maintaining the benefits of event sourcing and proper stream boundaries.

# Projection with a Nested Object

Projections can populate a single nullable child object on a read model using the `Nested()` method. Unlike [children collections](/chronicle/projections/declarative/children/), which manage an array of items identified by a key, `Nested()` targets a scalar nullable property that is set from an event and cleared (set to null) by another event.

Client coverage

Declarative nested-object projections (`Nested()`/`ClearWith()`) are currently a C#-only mechanism. Kotlin and Java have no fluent nested-object API, TypeScript’s builder throws `not implemented yet` for this method, and Elixir has no equivalent nested-object embedding pattern. The examples on this page are shown in C# only until nested projection scopes are implemented for the other clients.

## Defining a nested object projection

[Section titled “Defining a nested object projection”](#defining-a-nested-object-projection)

Use the `Nested()` method with `ClearWith<TEvent>()` to define the nested relationship:

* C#

Nested object projection

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record SliceCreatedForNestedBasic(string Name);

[EventType]
  public record CommandSetForDeclarativeNestedBasic(string Name, string Schema);

[EventType]
  public record CommandClearedForDeclarativeNestedBasic;

public record SliceForNestedBasic(
      string Name,
      CommandItemForNestedBasic? Command);

public record CommandItemForNestedBasic(
      string Name,
      string Schema);

public class SliceProjectionForNestedBasic : IProjectionFor<SliceForNestedBasic>
  {
      public void Define(IProjectionBuilderFor<SliceForNestedBasic> builder) => builder
          .From<SliceCreatedForNestedBasic>()
          .Nested(m => m.Command, nested => nested
              .From<CommandSetForDeclarativeNestedBasic>()
              .ClearWith<CommandClearedForDeclarativeNestedBasic>());
  }
  ```

* Kotlin

Nested object projection

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class SliceCreatedForNestedBasic(val name: String)

@EventType
  data class CommandSetForDeclarativeNestedBasic(val name: String, val schema: String)

@EventType
  data class CommandClearedForDeclarativeNestedBasic(val placeholder: Boolean = true)

data class SliceForNestedBasic(
      val name: String = "",
      val command: CommandItemForNestedBasic? = null
  )

data class CommandItemForNestedBasic(
      val name: String = "",
      val schema: String = ""
  )

class SliceProjectionForNestedBasic : IProjectionFor<SliceForNestedBasic> {
      override fun define(builder: IProjectionBuilderFor<SliceForNestedBasic>) {
          builder
              .from(SliceCreatedForNestedBasic::class)
              .nested(SliceForNestedBasic::command, CommandItemForNestedBasic::class) { nested ->
                  nested
                      .from(CommandSetForDeclarativeNestedBasic::class)
                      .clearWith(CommandClearedForDeclarativeNestedBasic::class)
              }
      }
  }
  ```

* Java

Nested object projection

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record SliceCreatedForNestedBasic(String name) {}

@EventType
  record CommandSetForDeclarativeNestedBasic(String name, String schema) {}

@EventType
  record CommandClearedForDeclarativeNestedBasic() {}

record SliceForNestedBasic(String name, CommandItemForNestedBasic command) {}

record CommandItemForNestedBasic(String name, String schema) {}

class SliceProjectionForNestedBasic implements IProjectionFor<SliceForNestedBasic> {
      @Override
      public void define(IProjectionBuilderFor<SliceForNestedBasic> builder) {
          builder
              .from(SliceCreatedForNestedBasic.class)
              .nested("command", CommandItemForNestedBasic.class, nested -> {
                  nested
                      .from(CommandSetForDeclarativeNestedBasic.class)
                      .clearWith(CommandClearedForDeclarativeNestedBasic.class);
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class SliceCreatedForNestedBasic {
      constructor(readonly name: string) {}
  }

@eventType()
  class CommandSetForDeclarativeNestedBasic {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandClearedForDeclarativeNestedBasic {
  }

class CommandItemForNestedBasic {
      name = '';
      schema = '';
  }

class SliceForNestedBasic {
      name = '';
      command: CommandItemForNestedBasic | null = null;
  }

@projection()
  class SliceProjectionForNestedBasic implements IProjectionFor<SliceForNestedBasic> {
      define(builder: IProjectionBuilderFor<SliceForNestedBasic>): void {
          builder
              .from(SliceCreatedForNestedBasic)
              .nested(m => m.command, nested => nested
                  .from(CommandSetForDeclarativeNestedBasic)
                  .clearWith(CommandClearedForDeclarativeNestedBasic));
      }
  }
  ```

## Read model with a nested property

[Section titled “Read model with a nested property”](#read-model-with-a-nested-property)

The nested property must be nullable on the read model:

* C#

Read model with nested object

```csharp
  public record SliceWithNestedCommand(
      string Name,
      CommandItemForNestedCommand? Command);

public record CommandItemForNestedCommand(
      string Name,
      string Schema);
  ```

* Kotlin

Read model with nested object

```kotlin
  data class SliceWithNestedCommand(
      val name: String = "",
      val command: CommandItemForNestedCommand? = null
  )

data class CommandItemForNestedCommand(
      val name: String = "",
      val schema: String = ""
  )
  ```

* Java

Read model with nested object

```java
  record SliceWithNestedCommand(String name, CommandItemForNestedCommand command) {}

record CommandItemForNestedCommand(String name, String schema) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  class CommandItemForNestedCommand {
      name = '';
      schema = '';
  }

class SliceWithNestedCommand {
      name = '';
      command: CommandItemForNestedCommand | null = null;
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

* C#

Nested object events

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record SliceCreatedForNestedEvents(string Name);

[EventType]
  public record CommandSetForNestedEvents(string Name, string Schema);

[EventType]
  public record CommandClearedForNestedEvents;
  ```

* Kotlin

Nested object events

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class SliceCreatedForNestedEvents(val name: String)

@EventType
  data class CommandSetForNestedEvents(val name: String, val schema: String)

@EventType
  data class CommandClearedForNestedEvents(val placeholder: Boolean = true)
  ```

* Java

Nested object events

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record SliceCreatedForNestedEvents(String name) {}

@EventType
  record CommandSetForNestedEvents(String name, String schema) {}

@EventType
  record CommandClearedForNestedEvents() {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class SliceCreatedForNestedEvents {
      constructor(readonly name: string) {}
  }

@eventType()
  class CommandSetForNestedEvents {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandClearedForNestedEvents {
  }
  ```

## How nested objects work

[Section titled “How nested objects work”](#how-nested-objects-work)

1. When `CommandSetForSlice` is appended the `Command` property is populated on the parent
2. Subsequent `CommandSetForSlice` events replace the nested object with new values
3. When `CommandClearedForSlice` is appended the `Command` property is set to `null`

## Multiple from events

[Section titled “Multiple from events”](#multiple-from-events)

Call `From<TEvent>()` multiple times to update the nested object from several event types:

* C#

Multiple nested events

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record SliceCreatedForNestedUpdates(string Name);

[EventType]
  public record CommandSetForNestedUpdates(string Name, string Schema);

[EventType]
  public record CommandRenamedForNestedUpdates(string NewName);

[EventType]
  public record CommandSchemaUpdatedForNestedUpdates(string UpdatedSchema);

[EventType]
  public record CommandClearedForNestedUpdates;

public record SliceForNestedUpdates(
      string Name,
      CommandItemForNestedUpdates? Command);

public record CommandItemForNestedUpdates(
      string Name,
      string Schema);

public class SliceProjectionForNestedUpdates : IProjectionFor<SliceForNestedUpdates>
  {
      public void Define(IProjectionBuilderFor<SliceForNestedUpdates> builder) => builder
          .From<SliceCreatedForNestedUpdates>()
          .Nested(m => m.Command, nested => nested
              .From<CommandSetForNestedUpdates>()
              .From<CommandRenamedForNestedUpdates>(b => b
                  .Set(m => m.Name).To(e => e.NewName))
              .From<CommandSchemaUpdatedForNestedUpdates>(b => b
                  .Set(m => m.Schema).To(e => e.UpdatedSchema))
              .ClearWith<CommandClearedForNestedUpdates>());
  }
  ```

* Kotlin

Multiple nested events

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class SliceCreatedForNestedUpdates(val name: String)

@EventType
  data class CommandSetForNestedUpdates(val name: String, val schema: String)

@EventType
  data class CommandRenamedForNestedUpdates(val newName: String)

@EventType
  data class CommandSchemaUpdatedForNestedUpdates(val updatedSchema: String)

@EventType
  data class CommandClearedForNestedUpdates(val placeholder: Boolean = true)

data class SliceForNestedUpdates(
      val name: String = "",
      val command: CommandItemForNestedUpdates? = null
  )

data class CommandItemForNestedUpdates(
      val name: String = "",
      val schema: String = ""
  )

class SliceProjectionForNestedUpdates : IProjectionFor<SliceForNestedUpdates> {
      override fun define(builder: IProjectionBuilderFor<SliceForNestedUpdates>) {
          builder
              .from(SliceCreatedForNestedUpdates::class)
              .nested(SliceForNestedUpdates::command, CommandItemForNestedUpdates::class) { nested ->
                  nested
                      .from(CommandSetForNestedUpdates::class)
                      .from(CommandRenamedForNestedUpdates::class) {
                          it.set(CommandItemForNestedUpdates::name).to { e -> e.newName }
                      }
                      .from(CommandSchemaUpdatedForNestedUpdates::class) {
                          it.set(CommandItemForNestedUpdates::schema).to { e -> e.updatedSchema }
                      }
                      .clearWith(CommandClearedForNestedUpdates::class)
              }
      }
  }
  ```

* Java

Multiple nested events

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record SliceCreatedForNestedUpdates(String name) {}

@EventType
  record CommandSetForNestedUpdates(String name, String schema) {}

@EventType
  record CommandRenamedForNestedUpdates(String newName) {}

@EventType
  record CommandSchemaUpdatedForNestedUpdates(String updatedSchema) {}

@EventType
  record CommandClearedForNestedUpdates() {}

record SliceForNestedUpdates(String name, CommandItemForNestedUpdates command) {}

record CommandItemForNestedUpdates(String name, String schema) {}

class SliceProjectionForNestedUpdates implements IProjectionFor<SliceForNestedUpdates> {
      @Override
      public void define(IProjectionBuilderFor<SliceForNestedUpdates> builder) {
          builder
              .from(SliceCreatedForNestedUpdates.class)
              .nested("command", CommandItemForNestedUpdates.class, nested -> {
                  nested
                      .from(CommandSetForNestedUpdates.class)
                      .from(CommandRenamedForNestedUpdates.class, fb -> {
                          fb.<String>set("name").to(e -> e.newName());
                      })
                      .from(CommandSchemaUpdatedForNestedUpdates.class, fb -> {
                          fb.<String>set("schema").to(e -> e.updatedSchema());
                      })
                      .clearWith(CommandClearedForNestedUpdates.class);
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class SliceCreatedForNestedUpdates {
      constructor(readonly name: string) {}
  }

@eventType()
  class CommandSetForNestedUpdates {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandRenamedForNestedUpdates {
      constructor(readonly newName: string) {}
  }

@eventType()
  class CommandSchemaUpdatedForNestedUpdates {
      constructor(readonly updatedSchema: string) {}
  }

@eventType()
  class CommandClearedForNestedUpdates {
  }

class CommandItemForNestedUpdates {
      name = '';
      schema = '';
  }

class SliceForNestedUpdates {
      name = '';
      command: CommandItemForNestedUpdates | null = null;
  }

@projection()
  class SliceProjectionForNestedUpdates implements IProjectionFor<SliceForNestedUpdates> {
      define(builder: IProjectionBuilderFor<SliceForNestedUpdates>): void {
          builder
              .from(SliceCreatedForNestedUpdates)
              .nested<CommandItemForNestedUpdates>(m => m.command, nested => nested
                  .from(CommandSetForNestedUpdates)
                  .from(CommandRenamedForNestedUpdates, b => b
                      .set(m => m.name).to(e => e.newName))
                  .from(CommandSchemaUpdatedForNestedUpdates, b => b
                      .set(m => m.schema).to(e => e.updatedSchema))
                  .clearWith(CommandClearedForNestedUpdates));
      }
  }
  ```

Each `From<TEvent>()` call updates only the properties it explicitly maps or auto-maps — it does not replace the entire nested object.

## AutoMap on nested objects

[Section titled “AutoMap on nested objects”](#automap-on-nested-objects)

AutoMap is enabled on the nested builder and inherits from the parent. Properties on the nested read model that share a name with properties on the event are mapped automatically:

* C#

AutoMap in a nested scope

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record SliceCreatedForNestedAutoMap(string Name);

[EventType]
  public record CommandSetForNestedAutoMap(string Name, string Schema);

[EventType]
  public record CommandUpdatedForNestedAutoMap(string Schema);

[EventType]
  public record CommandClearedForNestedAutoMap;

public record SliceForNestedAutoMap(
      string Name,
      CommandItemForNestedAutoMap? Command);

public record CommandItemForNestedAutoMap(
      string Name,
      string Schema);

public class SliceProjectionForNestedAutoMap : IProjectionFor<SliceForNestedAutoMap>
  {
      public void Define(IProjectionBuilderFor<SliceForNestedAutoMap> builder) => builder
          .From<SliceCreatedForNestedAutoMap>()
          .Nested(m => m.Command, nested => nested
              .From<CommandSetForNestedAutoMap>()
              .From<CommandUpdatedForNestedAutoMap>()
              .ClearWith<CommandClearedForNestedAutoMap>());
  }
  ```

* Kotlin

AutoMap in a nested scope

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class SliceCreatedForNestedAutoMap(val name: String)

@EventType
  data class CommandSetForNestedAutoMap(val name: String, val schema: String)

@EventType
  data class CommandUpdatedForNestedAutoMap(val schema: String)

@EventType
  data class CommandClearedForNestedAutoMap(val placeholder: Boolean = true)

data class SliceForNestedAutoMap(
      val name: String = "",
      val command: CommandItemForNestedAutoMap? = null
  )

data class CommandItemForNestedAutoMap(
      val name: String = "",
      val schema: String = ""
  )

class SliceProjectionForNestedAutoMap : IProjectionFor<SliceForNestedAutoMap> {
      override fun define(builder: IProjectionBuilderFor<SliceForNestedAutoMap>) {
          builder
              .from(SliceCreatedForNestedAutoMap::class)
              .nested(SliceForNestedAutoMap::command, CommandItemForNestedAutoMap::class) { nested ->
                  nested
                      .from(CommandSetForNestedAutoMap::class)
                      .from(CommandUpdatedForNestedAutoMap::class)
                      .clearWith(CommandClearedForNestedAutoMap::class)
              }
      }
  }
  ```

* Java

AutoMap in a nested scope

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record SliceCreatedForNestedAutoMap(String name) {}

@EventType
  record CommandSetForNestedAutoMap(String name, String schema) {}

@EventType
  record CommandUpdatedForNestedAutoMap(String schema) {}

@EventType
  record CommandClearedForNestedAutoMap() {}

record SliceForNestedAutoMap(String name, CommandItemForNestedAutoMap command) {}

record CommandItemForNestedAutoMap(String name, String schema) {}

class SliceProjectionForNestedAutoMap implements IProjectionFor<SliceForNestedAutoMap> {
      @Override
      public void define(IProjectionBuilderFor<SliceForNestedAutoMap> builder) {
          builder
              .from(SliceCreatedForNestedAutoMap.class)
              .nested("command", CommandItemForNestedAutoMap.class, nested -> {
                  nested
                      .from(CommandSetForNestedAutoMap.class)
                      .from(CommandUpdatedForNestedAutoMap.class)
                      .clearWith(CommandClearedForNestedAutoMap.class);
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class SliceCreatedForNestedAutoMap {
      constructor(readonly name: string) {}
  }

@eventType()
  class CommandSetForNestedAutoMap {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandUpdatedForNestedAutoMap {
      constructor(readonly schema: string) {}
  }

@eventType()
  class CommandClearedForNestedAutoMap {
  }

class CommandItemForNestedAutoMap {
      name = '';
      schema = '';
  }

class SliceForNestedAutoMap {
      name = '';
      command: CommandItemForNestedAutoMap | null = null;
  }

@projection()
  class SliceProjectionForNestedAutoMap implements IProjectionFor<SliceForNestedAutoMap> {
      define(builder: IProjectionBuilderFor<SliceForNestedAutoMap>): void {
          builder
              .from(SliceCreatedForNestedAutoMap)
              .nested(m => m.command, nested => nested
                  .from(CommandSetForNestedAutoMap)
                  .from(CommandUpdatedForNestedAutoMap)
                  .clearWith(CommandClearedForNestedAutoMap));
      }
  }
  ```

## Multiple nested objects

[Section titled “Multiple nested objects”](#multiple-nested-objects)

A single projection can have multiple independent nested properties:

* C#

Multiple nested objects

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record SliceCreatedWithMultipleNested(string Name);

[EventType]
  public record CommandSetWithMultipleNested(string Name, string Schema);

[EventType]
  public record CommandClearedWithMultipleNested;

[EventType]
  public record ValidationConfiguredWithMultipleNested(string RuleName);

[EventType]
  public record ValidationRemovedWithMultipleNested;

public record SliceWithMultipleNested(
      string Name,
      CommandItemWithMultipleNested? Command,
      ValidationConfigWithMultipleNested? Validation);

public record CommandItemWithMultipleNested(
      string Name,
      string Schema);

public record ValidationConfigWithMultipleNested(
      string RuleName);

public class SliceProjectionWithMultipleNested : IProjectionFor<SliceWithMultipleNested>
  {
      public void Define(IProjectionBuilderFor<SliceWithMultipleNested> builder) => builder
          .From<SliceCreatedWithMultipleNested>()
          .Nested(m => m.Command, nested => nested
              .From<CommandSetWithMultipleNested>()
              .ClearWith<CommandClearedWithMultipleNested>())
          .Nested(m => m.Validation, nested => nested
              .From<ValidationConfiguredWithMultipleNested>()
              .ClearWith<ValidationRemovedWithMultipleNested>());
  }
  ```

* Kotlin

Multiple nested objects

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class SliceCreatedWithMultipleNested(val name: String)

@EventType
  data class CommandSetWithMultipleNested(val name: String, val schema: String)

@EventType
  data class CommandClearedWithMultipleNested(val placeholder: Boolean = true)

@EventType
  data class ValidationConfiguredWithMultipleNested(val ruleName: String)

@EventType
  data class ValidationRemovedWithMultipleNested(val placeholder: Boolean = true)

data class SliceWithMultipleNested(
      val name: String = "",
      val command: CommandItemWithMultipleNested? = null,
      val validation: ValidationConfigWithMultipleNested? = null
  )

data class CommandItemWithMultipleNested(
      val name: String = "",
      val schema: String = ""
  )

data class ValidationConfigWithMultipleNested(
      val ruleName: String = ""
  )

class SliceProjectionWithMultipleNested : IProjectionFor<SliceWithMultipleNested> {
      override fun define(builder: IProjectionBuilderFor<SliceWithMultipleNested>) {
          builder
              .from(SliceCreatedWithMultipleNested::class)
              .nested(SliceWithMultipleNested::command, CommandItemWithMultipleNested::class) { nested ->
                  nested
                      .from(CommandSetWithMultipleNested::class)
                      .clearWith(CommandClearedWithMultipleNested::class)
              }
              .nested(SliceWithMultipleNested::validation, ValidationConfigWithMultipleNested::class) { nested ->
                  nested
                      .from(ValidationConfiguredWithMultipleNested::class)
                      .clearWith(ValidationRemovedWithMultipleNested::class)
              }
      }
  }
  ```

* Java

Multiple nested objects

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record SliceCreatedWithMultipleNested(String name) {}

@EventType
  record CommandSetWithMultipleNested(String name, String schema) {}

@EventType
  record CommandClearedWithMultipleNested() {}

@EventType
  record ValidationConfiguredWithMultipleNested(String ruleName) {}

@EventType
  record ValidationRemovedWithMultipleNested() {}

record SliceWithMultipleNested(
      String name,
      CommandItemWithMultipleNested command,
      ValidationConfigWithMultipleNested validation) {}

record CommandItemWithMultipleNested(String name, String schema) {}

record ValidationConfigWithMultipleNested(String ruleName) {}

class SliceProjectionWithMultipleNested implements IProjectionFor<SliceWithMultipleNested> {
      @Override
      public void define(IProjectionBuilderFor<SliceWithMultipleNested> builder) {
          builder
              .from(SliceCreatedWithMultipleNested.class)
              .nested("command", CommandItemWithMultipleNested.class, nested -> {
                  nested
                      .from(CommandSetWithMultipleNested.class)
                      .clearWith(CommandClearedWithMultipleNested.class);
              })
              .nested("validation", ValidationConfigWithMultipleNested.class, nested -> {
                  nested
                      .from(ValidationConfiguredWithMultipleNested.class)
                      .clearWith(ValidationRemovedWithMultipleNested.class);
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class SliceCreatedWithMultipleNested {
      constructor(readonly name: string) {}
  }

@eventType()
  class CommandSetWithMultipleNested {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandClearedWithMultipleNested {
  }

@eventType()
  class ValidationConfiguredWithMultipleNested {
      constructor(readonly ruleName: string) {}
  }

@eventType()
  class ValidationRemovedWithMultipleNested {
  }

class CommandItemWithMultipleNested {
      name = '';
      schema = '';
  }

class ValidationConfigWithMultipleNested {
      ruleName = '';
  }

class SliceWithMultipleNested {
      name = '';
      command: CommandItemWithMultipleNested | null = null;
      validation: ValidationConfigWithMultipleNested | null = null;
  }

@projection()
  class SliceProjectionWithMultipleNested implements IProjectionFor<SliceWithMultipleNested> {
      define(builder: IProjectionBuilderFor<SliceWithMultipleNested>): void {
          builder
              .from(SliceCreatedWithMultipleNested)
              .nested(m => m.command, nested => nested
                  .from(CommandSetWithMultipleNested)
                  .clearWith(CommandClearedWithMultipleNested))
              .nested(m => m.validation, nested => nested
                  .from(ValidationConfiguredWithMultipleNested)
                  .clearWith(ValidationRemovedWithMultipleNested));
      }
  }
  ```

## Nested within children

[Section titled “Nested within children”](#nested-within-children)

You can call `Nested()` from within a `Children()` builder to define a nested object on each child item:

* C#

Nested object in children

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record ProjectCreatedWithNestedChildren(string Name);

[EventType]
  public record TaskAddedWithNestedChild(Guid TaskId, string Title);

[EventType]
  public record TaskAssignedWithNestedChild(Guid TaskId, string Name, string Email);

[EventType]
  public record TaskUnassignedWithNestedChild(Guid TaskId);

public record ProjectWithDeclarativeNestedChildren(
      string Name,
      IEnumerable<TaskWithNestedAssignee> Tasks);

public record TaskWithNestedAssignee(
      Guid TaskId,
      string Title,
      AssigneeForNestedChild? Assignee);

public record AssigneeForNestedChild(
      string Name,
      string Email);

public class ProjectProjectionWithDeclarativeNestedChildren : IProjectionFor<ProjectWithDeclarativeNestedChildren>
  {
      public void Define(IProjectionBuilderFor<ProjectWithDeclarativeNestedChildren> builder) => builder
          .From<ProjectCreatedWithNestedChildren>()
          .Children(m => m.Tasks, tasks => tasks
              .IdentifiedBy(m => m.TaskId)
              .From<TaskAddedWithNestedChild>(b => b
                  .UsingKey(e => e.TaskId))
              .Nested(m => m.Assignee, assignee => assignee
                  .From<TaskAssignedWithNestedChild>(b => b
                      .UsingKey(e => e.TaskId))
                  .ClearWith<TaskUnassignedWithNestedChild>()));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `IChildrenBuilderFor`/`IChildFromBuilderFor` have no `nested()` method — `nested()` exists only on
  the top-level `IProjectionBuilderFor<TReadModel>`, so a nested object cannot be declared on a child
  item inside a `children()` scope.
  ```

* Java

```text
  Java does not support this workflow yet.
  `IChildrenBuilderFor`/`IChildFromBuilderFor` have no `nested()` method — `nested()` exists only on
  the top-level `IProjectionBuilderFor<TReadModel>`, so a nested object cannot be declared on a child
  item inside a `children()` scope.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class ProjectCreatedWithNestedChildren {
      constructor(readonly name: string) {}
  }

@eventType()
  class TaskAddedWithNestedChild {
      constructor(readonly taskId: string, readonly title: string) {}
  }

@eventType()
  class TaskAssignedWithNestedChild {
      constructor(readonly taskId: string, readonly name: string, readonly email: string) {}
  }

@eventType()
  class TaskUnassignedWithNestedChild {
      constructor(readonly taskId: string) {}
  }

class AssigneeForNestedChild {
      name = '';
      email = '';
  }

class TaskWithNestedAssignee {
      taskId = '';
      title = '';
      assignee: AssigneeForNestedChild | null = null;
  }

class ProjectWithDeclarativeNestedChildren {
      name = '';
      tasks: TaskWithNestedAssignee[] = [];
  }

@projection()
  class ProjectProjectionWithDeclarativeNestedChildren implements IProjectionFor<ProjectWithDeclarativeNestedChildren> {
      define(builder: IProjectionBuilderFor<ProjectWithDeclarativeNestedChildren>): void {
          builder
              .from(ProjectCreatedWithNestedChildren)
              .children<TaskWithNestedAssignee>(m => m.tasks, tasks => tasks
                  .identifiedBy(m => m.taskId)
                  .from(TaskAddedWithNestedChild, b => b
                      .usingKey(e => e.taskId))
                  .nested(m => m.assignee, assignee => assignee
                      .from(TaskAssignedWithNestedChild, b => b
                          .usingKey(e => e.taskId))
                      .clearWith(TaskUnassignedWithNestedChild)));
      }
  }
  ```

## Examples

[Section titled “Examples”](#examples)

### Employee with optional active contract

[Section titled “Employee with optional active contract”](#employee-with-optional-active-contract)

* C#

Employee contract projection

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record EmployeeHiredWithNestedContract(string Name, string Department);

[EventType]
  public record ContractStartedWithNestedContract(Guid ContractId, DateOnly StartDate, DateOnly EndDate, string Type);

[EventType]
  public record ContractExtendedWithNestedContract(DateOnly NewEndDate);

[EventType]
  public record ContractEndedWithNestedContract;

public record EmployeeWithNestedContract(
      string Name,
      string Department,
      ContractForNestedEmployee? ActiveContract);

public record ContractForNestedEmployee(
      Guid ContractId,
      DateOnly StartDate,
      DateOnly EndDate,
      string Type);

public class EmployeeProjectionWithNestedContract : IProjectionFor<EmployeeWithNestedContract>
  {
      public void Define(IProjectionBuilderFor<EmployeeWithNestedContract> builder) => builder
          .From<EmployeeHiredWithNestedContract>()
          .Nested(m => m.ActiveContract, contract => contract
              .From<ContractStartedWithNestedContract>()
              .From<ContractExtendedWithNestedContract>(b => b
                  .Set(m => m.EndDate).To(e => e.NewEndDate))
              .ClearWith<ContractEndedWithNestedContract>());
  }
  ```

* Kotlin

Employee contract projection

@EventType
  data class EmployeeHiredWithNestedContract(val name: String, val department: String)

@EventType
  data class ContractStartedWithNestedContract(
      val contractId: String,
      val startDate: LocalDate,
      val endDate: LocalDate,
      val type: String
  )

@EventType
  data class ContractExtendedWithNestedContract(val newEndDate: LocalDate)

@EventType
  data class ContractEndedWithNestedContract(val placeholder: Boolean = true)

data class EmployeeWithNestedContract(
      val name: String = "",
      val department: String = "",
      val activeContract: ContractForNestedEmployee? = null
  )

data class ContractForNestedEmployee(
      val contractId: String = "",
      val startDate: LocalDate = LocalDate.MIN,
      val endDate: LocalDate = LocalDate.MIN,
      val type: String = ""
  )

class EmployeeProjectionWithNestedContract : IProjectionFor<EmployeeWithNestedContract> {
      override fun define(builder: IProjectionBuilderFor<EmployeeWithNestedContract>) {
          builder
              .from(EmployeeHiredWithNestedContract::class)
              .nested(EmployeeWithNestedContract::activeContract, ContractForNestedEmployee::class) { contract ->
                  contract
                      .from(ContractStartedWithNestedContract::class)
                      .from(ContractExtendedWithNestedContract::class) {
                          it.set(ContractForNestedEmployee::endDate).to { e -> e.newEndDate }
                      }
                      .clearWith(ContractEndedWithNestedContract::class)
              }
      }
  }
  ```

* Java

Employee contract projection

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.time.LocalDate;

record EmployeeWithNestedContract(String name, String department, ContractForNestedEmployee activeContract) {}

record ContractForNestedEmployee(String contractId, LocalDate startDate, LocalDate endDate, String type) {}

class EmployeeProjectionWithNestedContract implements IProjectionFor<EmployeeWithNestedContract> {
      @Override
      public void define(IProjectionBuilderFor<EmployeeWithNestedContract> builder) {
          builder
              .from(EmployeeHiredForNestedContractEvents.class)
              .nested("activeContract", ContractForNestedEmployee.class, contract -> {
                  contract
                      .from(ContractStartedForNestedContractEvents.class)
                      .from(ContractExtendedForNestedContractEvents.class, fb -> {
                          fb.<LocalDate>set("endDate").to(e -> e.newEndDate());
                      })
                      .clearWith(ContractEndedForNestedContractEvents.class);
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class EmployeeHiredWithNestedContract {
      constructor(readonly name: string, readonly department: string) {}
  }

@eventType()
  class ContractStartedWithNestedContract {
      constructor(
          readonly contractId: string,
          readonly startDate: string,
          readonly endDate: string,
          readonly type: string
      ) {}
  }

@eventType()
  class ContractExtendedWithNestedContract {
      constructor(readonly newEndDate: string) {}
  }

@eventType()
  class ContractEndedWithNestedContract {
  }

class ContractForNestedEmployee {
      contractId = '';
      startDate = '';
      endDate = '';
      type = '';
  }

class EmployeeWithNestedContract {
      name = '';
      department = '';
      activeContract: ContractForNestedEmployee | null = null;
  }

@projection()
  class EmployeeProjectionWithNestedContract implements IProjectionFor<EmployeeWithNestedContract> {
      define(builder: IProjectionBuilderFor<EmployeeWithNestedContract>): void {
          builder
              .from(EmployeeHiredWithNestedContract)
              .nested<ContractForNestedEmployee>(m => m.activeContract, contract => contract
                  .from(ContractStartedWithNestedContract)
                  .from(ContractExtendedWithNestedContract, b => b
                      .set(m => m.endDate).to(e => e.newEndDate))
                  .clearWith(ContractEndedWithNestedContract));
      }
  }
  ```

Events:

* C#

Employee contract events

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record EmployeeHiredForNestedContractEvents(string Name, string Department);

[EventType]
  public record ContractStartedForNestedContractEvents(Guid ContractId, DateOnly StartDate, DateOnly EndDate, string Type);

[EventType]
  public record ContractExtendedForNestedContractEvents(DateOnly NewEndDate);

[EventType]
  public record ContractEndedForNestedContractEvents;
  ```

* Kotlin

Employee contract events

```kotlin
  import io.cratis.chronicle.events.EventType
  import java.time.LocalDate

@EventType
  data class EmployeeHiredForNestedContractEvents(val name: String, val department: String)

@EventType
  data class ContractStartedForNestedContractEvents(
      val contractId: String,
      val startDate: LocalDate,
      val endDate: LocalDate,
      val type: String
  )

@EventType
  data class ContractExtendedForNestedContractEvents(val newEndDate: LocalDate)

@EventType
  data class ContractEndedForNestedContractEvents(val placeholder: Boolean = true)
  ```

* Java

Employee contract events

```java
  import io.cratis.chronicle.events.EventType;

import java.time.LocalDate;

@EventType
  record EmployeeHiredForNestedContractEvents(String name, String department) {}

@EventType
  record ContractStartedForNestedContractEvents(
      String contractId,
      LocalDate startDate,
      LocalDate endDate,
      String type
  ) {}

@EventType
  record ContractExtendedForNestedContractEvents(LocalDate newEndDate) {}

@EventType
  record ContractEndedForNestedContractEvents() {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class EmployeeHiredForNestedContractEvents {
      constructor(readonly name: string, readonly department: string) {}
  }

@eventType()
  class ContractStartedForNestedContractEvents {
      constructor(
          readonly contractId: string,
          readonly startDate: string,
          readonly endDate: string,
          readonly type: string
      ) {}
  }

@eventType()
  class ContractExtendedForNestedContractEvents {
      constructor(readonly newEndDate: string) {}
  }

@eventType()
  class ContractEndedForNestedContractEvents {
  }
  ```

### Product with optional promotion

[Section titled “Product with optional promotion”](#product-with-optional-promotion)

* C#

Product promotion projection

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record ProductListedWithNestedPromotion(string Name, decimal BasePrice);

[EventType]
  public record PromotionAppliedWithNestedPromotion(string Label, int DiscountPercent, DateTimeOffset ValidUntil);

[EventType]
  public record PromotionRemovedWithNestedPromotion;

public record ProductWithNestedPromotion(
      string Name,
      decimal BasePrice,
      PromotionForNestedProduct? Promotion);

public record PromotionForNestedProduct(
      string Label,
      int DiscountPercent,
      DateTimeOffset ValidUntil);

public class ProductProjectionWithNestedPromotion : IProjectionFor<ProductWithNestedPromotion>
  {
      public void Define(IProjectionBuilderFor<ProductWithNestedPromotion> builder) => builder
          .From<ProductListedWithNestedPromotion>()
          .Nested(m => m.Promotion, promotion => promotion
              .From<PromotionAppliedWithNestedPromotion>()
              .ClearWith<PromotionRemovedWithNestedPromotion>());
  }
  ```

* Kotlin

Product promotion projection

@EventType
  data class ProductListedWithNestedPromotion(val name: String, val basePrice: Double)

@EventType
  data class PromotionAppliedWithNestedPromotion(
      val label: String,
      val discountPercent: Int,
      val validUntil: Instant
  )

@EventType
  data class PromotionRemovedWithNestedPromotion(val placeholder: Boolean = true)

data class ProductWithNestedPromotion(
      val name: String = "",
      val basePrice: Double = 0.0,
      val promotion: PromotionForNestedProduct? = null
  )

data class PromotionForNestedProduct(
      val label: String = "",
      val discountPercent: Int = 0,
      val validUntil: Instant = Instant.EPOCH
  )

class ProductProjectionWithNestedPromotion : IProjectionFor<ProductWithNestedPromotion> {
      override fun define(builder: IProjectionBuilderFor<ProductWithNestedPromotion>) {
          builder
              .from(ProductListedWithNestedPromotion::class)
              .nested(ProductWithNestedPromotion::promotion, PromotionForNestedProduct::class) { promotion ->
                  promotion
                      .from(PromotionAppliedWithNestedPromotion::class)
                      .clearWith(PromotionRemovedWithNestedPromotion::class)
              }
      }
  }
  ```

* Java

Product promotion projection

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.time.Instant;

@EventType
  record ProductListedWithNestedPromotion(String name, double basePrice) {}

@EventType
  record PromotionAppliedWithNestedPromotion(String label, int discountPercent, Instant validUntil) {}

@EventType
  record PromotionRemovedWithNestedPromotion() {}

record ProductWithNestedPromotion(String name, double basePrice, PromotionForNestedProduct promotion) {}

record PromotionForNestedProduct(String label, int discountPercent, Instant validUntil) {}

class ProductProjectionWithNestedPromotion implements IProjectionFor<ProductWithNestedPromotion> {
      @Override
      public void define(IProjectionBuilderFor<ProductWithNestedPromotion> builder) {
          builder
              .from(ProductListedWithNestedPromotion.class)
              .nested("promotion", PromotionForNestedProduct.class, promotion -> {
                  promotion
                      .from(PromotionAppliedWithNestedPromotion.class)
                      .clearWith(PromotionRemovedWithNestedPromotion.class);
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class ProductListedWithNestedPromotion {
      constructor(readonly name: string, readonly basePrice: number) {}
  }

@eventType()
  class PromotionAppliedWithNestedPromotion {
      constructor(readonly label: string, readonly discountPercent: number, readonly validUntil: Date) {}
  }

@eventType()
  class PromotionRemovedWithNestedPromotion {
  }

class PromotionForNestedProduct {
      label = '';
      discountPercent = 0;
      validUntil = new Date();
  }

class ProductWithNestedPromotion {
      name = '';
      basePrice = 0;
      promotion: PromotionForNestedProduct | null = null;
  }

@projection()
  class ProductProjectionWithNestedPromotion implements IProjectionFor<ProductWithNestedPromotion> {
      define(builder: IProjectionBuilderFor<ProductWithNestedPromotion>): void {
          builder
              .from(ProductListedWithNestedPromotion)
              .nested(m => m.promotion, promotion => promotion
                  .from(PromotionAppliedWithNestedPromotion)
                  .clearWith(PromotionRemovedWithNestedPromotion));
      }
  }
  ```

## See Also

[Section titled “See Also”](#see-also)

* [Children](/chronicle/projections/declarative/children/) — collections of items managed independently within a parent
* [Simple projection](/chronicle/projections/declarative/simple-projection/) — getting started with projections
* [AutoMap](/chronicle/projections/declarative/auto-map/) — automatic property mapping

# Projection with NotRewindable

The `NotRewindable()` method marks a projection as forward-only, meaning it cannot be replayed or rewound. This is useful for projections that maintain state that should not be recreated from scratch or for performance-critical scenarios where replay is not needed.

Client coverage

Marking a projection as not-rewindable is currently supported in C# and TypeScript only. Kotlin and Java have no fluent API for it, and Elixir’s declarative and model-bound projections always register as rewindable with no way to opt out yet.

## Defining a non-rewindable projection

[Section titled “Defining a non-rewindable projection”](#defining-a-non-rewindable-projection)

Use `NotRewindable()` to mark a projection as forward-only:

* C#

```csharp
  using Cratis.Chronicle.Projections;

public class DecNotRewindableAuditLogProjection : IProjectionFor<DecNotRewindableAuditLogEntry>
  {
      public void Define(IProjectionBuilderFor<DecNotRewindableAuditLogEntry> builder) => builder
          .NotRewindable()
          .AutoMap()
          .FromEvery(_ => _
              .Set(m => m.ProcessedAt).ToEventContextProperty(c => c.Occurred))
          .From<DecNotRewindableUserAction>(_ => _
              .Set(m => m.OccurredAt).ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

class DecNotRewindableAuditLogProjection : IProjectionFor<DecNotRewindableAuditLogEntry> {
      override fun define(builder: IProjectionBuilderFor<DecNotRewindableAuditLogEntry>) {
          builder
              .notRewindable()
              .fromEvery { it.set(DecNotRewindableAuditLogEntry::processedAt).toEventContextProperty("occurred") }
              .from(DecNotRewindableUserAction::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

class DecNotRewindableAuditLogProjection implements IProjectionFor<DecNotRewindableAuditLogEntry> {
      @Override
      public void define(IProjectionBuilderFor<DecNotRewindableAuditLogEntry> builder) {
          builder
              .notRewindable()
              .fromEvery(feb -> {
                  feb.set("processedAt").toEventContextProperty("occurred");
              })
              .from(DecNotRewindableUserAction.class);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.NotRewindableUserAction do
    use Chronicle.Events.EventType, id: "not-rewindable-user-action"

defstruct [:action]
  end

defmodule MyApp.ReadModels.NotRewindableAuditLogEntry do
    use Chronicle.ReadModels.ReadModel, not_rewindable: true

defstruct id: nil, action: nil, processed_at: nil, occurred_at: nil

from_every(set: [processed_at: :occurred])

from MyApp.Events.NotRewindableUserAction,
      set: [id: :event_source_id, action: :action, occurred_at: :occurred]
  end
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecNotRewindableAuditLogProjection implements IProjectionFor<DecNotRewindableAuditLogEntry> {
      define(builder: IProjectionBuilderFor<DecNotRewindableAuditLogEntry>): void {
          builder
              .notRewindable()
              .autoMap()
              .fromEvery(_ => _
                  .set(m => m.processedAt).toEventContextProperty('occurred'))
              .from(DecNotRewindableUserAction, _ => _
                  .set(m => m.occurredAt).toEventContextProperty('occurred'));
      }
  }
  ```

This projection:

* Cannot be replayed or reset
* Processes events only as they arrive in real-time
* Maintains forward-only state progression
* Is optimized for performance and append-only scenarios

## Read model definition

[Section titled “Read model definition”](#read-model-definition)

The read model can include timestamp and audit information:

* C#

```csharp
  public record DecNotRewindableAuditLogEntry(
      string UserId,
      string Action,
      string Details,
      DateTimeOffset OccurredAt,
      DateTimeOffset ProcessedAt,
      long SequenceNumber);
  ```

* Kotlin

```kotlin
  data class DecNotRewindableAuditLogEntry(
      val userId: String = "",
      val action: String = "",
      val details: String = "",
      val processedAt: String = "",
      val sequenceNumber: Long = 0
  )
  ```

* Java

```java
  class DecNotRewindableAuditLogEntry {
      public String userId = "";
      public String action = "";
      public String details = "";
      public String processedAt = "";
      public long sequenceNumber = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.DecNotRewindableAuditLogEntry do
    defstruct [
      :user_id,
      :action,
      :details,
      :occurred_at,
      :processed_at,
      :sequence_number
    ]
  end
  ```

* TypeScript

```typescript
  class DecNotRewindableAuditLogEntry {
      userId = '';
      action = '';
      details = '';
      occurredAt = new Date();
      processedAt = new Date();
      sequenceNumber: bigint = 0n;
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

Events should be designed for forward-only processing:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record DecNotRewindableUserAction(
      string UserId,
      string ActionType,
      string Details);

[EventType]
  public record DecNotRewindableSystemEvent(
      string ComponentName,
      string EventType,
      string Data);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class DecNotRewindableUserAction(
      val userId: String,
      val actionType: String,
      val details: String
  )

@EventType
  data class DecNotRewindableSystemEvent(
      val componentName: String,
      val eventType: String,
      val data: String
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record DecNotRewindableUserAction(
      String userId,
      String actionType,
      String details) {}

@EventType
  record DecNotRewindableSystemEvent(
      String componentName,
      String eventType,
      String data) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.DecNotRewindableUserAction do
    use Chronicle.Events.EventType, id: "dec-not-rewindable-user-action"

defstruct [:user_id, :action_type, :details]
  end

defmodule MyApp.Events.DecNotRewindableSystemEvent do
    use Chronicle.Events.EventType, id: "dec-not-rewindable-system-event"

defstruct [:component_name, :event_type, :data]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class DecNotRewindableUserAction {
      userId = '';
      actionType = '';
      details = '';
  }

@eventType()
  class DecNotRewindableSystemEvent {
      componentName = '';
      eventType = '';
      data = '';
  }
  ```

## How it works

[Section titled “How it works”](#how-it-works)

When a projection is marked as `NotRewindable()`:

1. **No replay capability**: The projection cannot be reset and rebuilt from the beginning
2. **Forward-only processing**: Events are processed only as they arrive in chronological order
3. **Performance optimization**: Chronicle skips replay infrastructure and optimizations
4. **State preservation**: Existing projection state is preserved and cannot be recreated
5. **Error handling**: Failed events may require manual intervention since replay isn’t available

## Use cases for non-rewindable projections

[Section titled “Use cases for non-rewindable projections”](#use-cases-for-non-rewindable-projections)

### Audit and logging projections

[Section titled “Audit and logging projections”](#audit-and-logging-projections)

Perfect for audit logs where you want to preserve the exact timing and sequence:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecNotRewindableUserLoginAttempt(string UserId, bool Succeeded);

[EventType]
  public record DecNotRewindablePermissionChange(string UserId, string Permission);

public record DecNotRewindableSecurityAuditEntry(
      DateTimeOffset AuditedAt,
      long SequenceNumber);

public class DecNotRewindableSecurityAuditProjection : IProjectionFor<DecNotRewindableSecurityAuditEntry>
  {
      public void Define(IProjectionBuilderFor<DecNotRewindableSecurityAuditEntry> builder) => builder
          .NotRewindable()
          .AutoMap()
          .FromEvery(_ => _
              .Set(m => m.AuditedAt).ToEventContextProperty(c => c.Occurred)
              .Set(m => m.SequenceNumber).ToEventContextProperty(c => c.SequenceNumber))
          .From<DecNotRewindableUserLoginAttempt>()
          .From<DecNotRewindablePermissionChange>();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DecNotRewindableUserLoginAttempt(val userId: String, val succeeded: Boolean)

@EventType
  data class DecNotRewindablePermissionChange(val userId: String, val permission: String)

data class DecNotRewindableSecurityAuditEntry(
      val auditedAt: String = "",
      val sequenceNumber: Long = 0
  )

class DecNotRewindableSecurityAuditProjection : IProjectionFor<DecNotRewindableSecurityAuditEntry> {
      override fun define(builder: IProjectionBuilderFor<DecNotRewindableSecurityAuditEntry>) {
          builder
              .notRewindable()
              .fromEvery {
                  it.set(DecNotRewindableSecurityAuditEntry::auditedAt).toEventContextProperty("occurred")
                  it.set(DecNotRewindableSecurityAuditEntry::sequenceNumber).toEventContextProperty("sequenceNumber")
              }
              .from(DecNotRewindableUserLoginAttempt::class)
              .from(DecNotRewindablePermissionChange::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecNotRewindableUserLoginAttempt(String userId, boolean succeeded) {}

@EventType
  record DecNotRewindablePermissionChange(String userId, String permission) {}

class DecNotRewindableSecurityAuditEntry {
      public String auditedAt = "";
      public long sequenceNumber = 0;
  }

class DecNotRewindableSecurityAuditProjection implements IProjectionFor<DecNotRewindableSecurityAuditEntry> {
      @Override
      public void define(IProjectionBuilderFor<DecNotRewindableSecurityAuditEntry> builder) {
          builder
              .notRewindable()
              .fromEvery(feb -> {
                  feb.set("auditedAt").toEventContextProperty("occurred");
                  feb.set("sequenceNumber").toEventContextProperty("sequenceNumber");
              })
              .from(DecNotRewindableUserLoginAttempt.class)
              .from(DecNotRewindablePermissionChange.class);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecNotRewindableUserLoginAttempt {
      userId = '';
      succeeded = false;
  }

@eventType()
  class DecNotRewindablePermissionChange {
      userId = '';
      permission = '';
  }

class DecNotRewindableSecurityAuditEntry {
      auditedAt = new Date();
      sequenceNumber: bigint = 0n;
  }

@projection()
  class DecNotRewindableSecurityAuditProjection implements IProjectionFor<DecNotRewindableSecurityAuditEntry> {
      define(builder: IProjectionBuilderFor<DecNotRewindableSecurityAuditEntry>): void {
          builder
              .notRewindable()
              .autoMap()
              .fromEvery(_ => _
                  .set(m => m.auditedAt).toEventContextProperty('occurred')
                  .set(m => m.sequenceNumber).toEventContextProperty('sequenceNumber'))
              .from(DecNotRewindableUserLoginAttempt)
              .from(DecNotRewindablePermissionChange);
      }
  }
  ```

### Performance monitoring

[Section titled “Performance monitoring”](#performance-monitoring)

For real-time performance metrics that don’t need historical accuracy:

* C#

```csharp
  [EventType]
  public record DecNotRewindableApiRequestCompleted(string Endpoint, int StatusCode, long DurationMilliseconds);

public record DecNotRewindablePerformanceMetric(DateTimeOffset Timestamp);

public class DecNotRewindablePerformanceMetricProjection : IProjectionFor<DecNotRewindablePerformanceMetric>
  {
      public void Define(IProjectionBuilderFor<DecNotRewindablePerformanceMetric> builder) => builder
          .NotRewindable()
          .AutoMap()
          .From<DecNotRewindableApiRequestCompleted>(_ => _
              .Set(m => m.Timestamp).ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DecNotRewindableApiRequestCompleted(val endpoint: String, val statusCode: Int, val durationMilliseconds: Long)

data class DecNotRewindablePerformanceMetric(val timestamp: String = "")

class DecNotRewindablePerformanceMetricProjection : IProjectionFor<DecNotRewindablePerformanceMetric> {
      override fun define(builder: IProjectionBuilderFor<DecNotRewindablePerformanceMetric>) {
          builder
              .notRewindable()
              .autoMap()
              .from(DecNotRewindableApiRequestCompleted::class) {
                  it.set(DecNotRewindablePerformanceMetric::timestamp).toEventContextProperty("occurred")
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecNotRewindableApiRequestCompleted(String endpoint, int statusCode, long durationMilliseconds) {}

class DecNotRewindablePerformanceMetric {
      public String timestamp = "";
  }

class DecNotRewindablePerformanceMetricProjection implements IProjectionFor<DecNotRewindablePerformanceMetric> {
      @Override
      public void define(IProjectionBuilderFor<DecNotRewindablePerformanceMetric> builder) {
          builder
              .notRewindable()
              .autoMap()
              .from(DecNotRewindableApiRequestCompleted.class, fb -> {
                  fb.set("timestamp").toEventContextProperty("occurred");
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecNotRewindableApiRequestCompleted {
      endpoint = '';
      statusCode = 0;
      durationMilliseconds: bigint = 0n;
  }

class DecNotRewindablePerformanceMetric {
      timestamp = new Date();
  }

@projection()
  class DecNotRewindablePerformanceMetricProjection implements IProjectionFor<DecNotRewindablePerformanceMetric> {
      define(builder: IProjectionBuilderFor<DecNotRewindablePerformanceMetric>): void {
          builder
              .notRewindable()
              .autoMap()
              .from(DecNotRewindableApiRequestCompleted, _ => _
                  .set(m => m.timestamp).toEventContextProperty('occurred'));
      }
  }
  ```

### Financial transactions

[Section titled “Financial transactions”](#financial-transactions)

For append-only financial records where replay could cause confusion:

* C#

```csharp
  [EventType]
  public record DecNotRewindablePaymentProcessed(string PaymentId, decimal Amount);

public record DecNotRewindableLedgerEntry(
      DateTimeOffset RecordedAt,
      string TransactionType);

public class DecNotRewindableTransactionLedgerProjection : IProjectionFor<DecNotRewindableLedgerEntry>
  {
      public void Define(IProjectionBuilderFor<DecNotRewindableLedgerEntry> builder) => builder
          .NotRewindable()
          .AutoMap()
          .FromEvery(_ => _
              .Set(m => m.RecordedAt).ToEventContextProperty(c => c.Occurred))
          .From<DecNotRewindablePaymentProcessed>(_ => _
              .Set(m => m.TransactionType).ToValue("PAYMENT"));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class DecNotRewindablePaymentProcessed(val paymentId: String, val amount: Double)

data class DecNotRewindableLedgerEntry(
      val recordedAt: String = ""
  )

class DecNotRewindableTransactionLedgerProjection : IProjectionFor<DecNotRewindableLedgerEntry> {
      override fun define(builder: IProjectionBuilderFor<DecNotRewindableLedgerEntry>) {
          builder
              .notRewindable()
              .fromEvery { it.set(DecNotRewindableLedgerEntry::recordedAt).toEventContextProperty("occurred") }
              .from(DecNotRewindablePaymentProcessed::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record DecNotRewindablePaymentProcessed(String paymentId, double amount) {}

class DecNotRewindableLedgerEntry {
      public String recordedAt = "";
  }

class DecNotRewindableTransactionLedgerProjection implements IProjectionFor<DecNotRewindableLedgerEntry> {
      @Override
      public void define(IProjectionBuilderFor<DecNotRewindableLedgerEntry> builder) {
          builder
              .notRewindable()
              .fromEvery(feb -> {
                  feb.set("recordedAt").toEventContextProperty("occurred");
              })
              .from(DecNotRewindablePaymentProcessed.class);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecNotRewindablePaymentProcessed {
      paymentId = '';
      amount = 0;
  }

class DecNotRewindableLedgerEntry {
      recordedAt = new Date();
      transactionType = '';
  }

@projection()
  class DecNotRewindableTransactionLedgerProjection implements IProjectionFor<DecNotRewindableLedgerEntry> {
      define(builder: IProjectionBuilderFor<DecNotRewindableLedgerEntry>): void {
          builder
              .notRewindable()
              .autoMap()
              .fromEvery(_ => _
                  .set(m => m.recordedAt).toEventContextProperty('occurred'))
              .from(DecNotRewindablePaymentProcessed, _ => _
                  .set(m => m.transactionType).toValue('PAYMENT'));
      }
  }
  ```

## When to use NotRewindable

[Section titled “When to use NotRewindable”](#when-to-use-notrewindable)

Use `NotRewindable()` when:

* **Audit requirements**: You need to preserve exact event timestamps and sequence
* **Performance critical**: The projection handles high-volume events and replay would be expensive
* **Append-only data**: The projection represents data that should never be regenerated
* **Real-time processing**: Only forward, real-time event flow matters — a rebuilt-from-replay history would not reflect current state
* **External integrations**: The projection triggers external actions that shouldn’t be repeated
* **Compliance**: Regulatory requirements prevent data recreation or replay

## When NOT to use NotRewindable

[Section titled “When NOT to use NotRewindable”](#when-not-to-use-notrewindable)

Avoid `NotRewindable()` when:

* **Business logic changes**: You might need to replay events with updated logic
* **Bug fixes**: Errors in projection logic need to be corrected by replay
* **Data migration**: You need to rebuild projections with new schemas
* **Testing**: Development and testing scenarios benefit from replay capability
* **Recovery**: System failures might require rebuilding projection state

## Combining with other features

[Section titled “Combining with other features”](#combining-with-other-features)

NotRewindable can be combined with other projection features:

* C#

```csharp
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecNotRewindableOrderReceived(string OrderId);

[EventType]
  public record DecNotRewindableOrderProcessing(string OrderId);

[EventType]
  public record DecNotRewindableOrderCompleted(string OrderId);

public record DecNotRewindableOrderStatus(
      string Status,
      DateTimeOffset LastUpdatedAt);

public class DecNotRewindableRealTimeOrderStatusProjection : IProjectionFor<DecNotRewindableOrderStatus>
  {
      public void Define(IProjectionBuilderFor<DecNotRewindableOrderStatus> builder) => builder
          .NotRewindable()
          .FromEventSequence("order-processing")
          .Passive()
          .AutoMap()
          .FromEvery(_ => _
              .Set(m => m.LastUpdatedAt).ToEventContextProperty(c => c.Occurred))
          .From<DecNotRewindableOrderReceived>(_ => _
              .Set(m => m.Status).ToValue("RECEIVED"))
          .From<DecNotRewindableOrderProcessing>(_ => _
              .Set(m => m.Status).ToValue("PROCESSING"))
          .From<DecNotRewindableOrderCompleted>(_ => _
              .Set(m => m.Status).ToValue("COMPLETED"));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecNotRewindableOrderReceived {
      orderId = '';
  }

@eventType()
  class DecNotRewindableOrderProcessing {
      orderId = '';
  }

@eventType()
  class DecNotRewindableOrderCompleted {
      orderId = '';
  }

class DecNotRewindableOrderStatus {
      status = '';
      lastUpdatedAt = new Date();
  }

@projection()
  class DecNotRewindableRealTimeOrderStatusProjection implements IProjectionFor<DecNotRewindableOrderStatus> {
      define(builder: IProjectionBuilderFor<DecNotRewindableOrderStatus>): void {
          builder
              .notRewindable()
              .fromEventSequence('order-processing')
              .passive()
              .autoMap()
              .fromEvery(_ => _
                  .set(m => m.lastUpdatedAt).toEventContextProperty('occurred'))
              .from(DecNotRewindableOrderReceived, _ => _
                  .set(m => m.status).toValue('RECEIVED'))
              .from(DecNotRewindableOrderProcessing, _ => _
                  .set(m => m.status).toValue('PROCESSING'))
              .from(DecNotRewindableOrderCompleted, _ => _
                  .set(m => m.status).toValue('COMPLETED'));
      }
  }
  ```

This combines non-rewindable behavior with event sequence specification, passive mode, and event-context timestamp mapping.

## Error handling considerations

[Section titled “Error handling considerations”](#error-handling-considerations)

With non-rewindable projections:

* **Failed events**: Must be handled carefully since replay isn’t available
* **Dead letter queues**: Consider implementing for failed event processing
* **Manual intervention**: May be required to fix projection state
* **Monitoring**: Implement comprehensive monitoring and alerting
* **Backup strategies**: Consider point-in-time snapshots for recovery

## Performance benefits

[Section titled “Performance benefits”](#performance-benefits)

Non-rewindable projections offer several performance advantages:

* **Reduced memory usage**: No need to store replay state or checkpoints
* **Faster startup**: No replay phase during application startup
* **Lower CPU usage**: Eliminates replay processing overhead
* **Simplified infrastructure**: Fewer moving parts in the projection system
* **Better throughput**: All processing power focused on real-time events

# Passive projection

A passive projection is a projection that is not actively materialized to a persistent store but can be queried on-demand for in-memory lookups. This is useful for scenarios where you need to construct read models from events without the overhead of maintaining persistent state.

## Defining a passive projection

[Section titled “Defining a passive projection”](#defining-a-passive-projection)

Use the `.Passive()` method to mark a projection as passive:

* C#

```csharp
  using Cratis.Chronicle.Projections;

public class DecPassiveUserSummaryProjection : IProjectionFor<DecPassiveUserSummary>
  {
      public void Define(IProjectionBuilderFor<DecPassiveUserSummary> builder) => builder
          .Passive()
          .AutoMap()
          .From<DecPassiveUserCreated>()
          .From<DecPassiveUserUpdated>();
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Passive projection

```elixir
  defmodule MyApp.Projections.DecPassiveUserSummaryProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecPassiveUserSummary, passive: true

alias MyApp.Events.{DecPassiveUserCreated, DecPassiveUserUpdated}

from DecPassiveUserCreated
    from DecPassiveUserUpdated
  end
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecPassiveUserSummaryProjection implements IProjectionFor<DecPassiveUserSummary> {
      define(builder: IProjectionBuilderFor<DecPassiveUserSummary>): void {
          builder
              .passive()
              .autoMap()
              .from(DecPassiveUserCreated)
              .from(DecPassiveUserUpdated);
      }
  }
  ```

This projection:

* Will not be actively maintained in persistent storage
* Can be queried on-demand using the `IProjections` service
* Reconstructs the read model from events when requested

## Using passive projections

[Section titled “Using passive projections”](#using-passive-projections)

Passive projections are accessed through the event store’s `ReadModels` using the `GetInstanceById` method:

* C#

```csharp
  using Cratis.Chronicle;

public class DecPassiveUserService(IEventStore eventStore)
  {
      public Task<DecPassiveUserSummary> GetUserSummary(string userId) =>
          eventStore.ReadModels.GetInstanceById<DecPassiveUserSummary>(userId);
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Resolving a passive read model on demand

```elixir
  defmodule MyApp.UserService do
    def get_user_summary(user_id) do
      Chronicle.ReadModels.get_instance_by_id(MyApp.ReadModels.DecPassiveUserSummary, user_id)
    end
  end
  ```

* TypeScript

```typescript
  import { ChronicleClient } from '@cratis/chronicle';

class DecPassiveUserService {
      constructor(private readonly client: ChronicleClient) {}

async getUserSummary(userId: string): Promise<DecPassiveUserSummary> {
          const store = await this.client.getEventStore('MyStore');
          return store.readModels.getInstanceById(DecPassiveUserSummary, userId);
      }
  }
  ```

## Read model definition

[Section titled “Read model definition”](#read-model-definition)

The read model is defined the same way as for regular projections:

* C#

```csharp
  public record DecPassiveUserSummary(
      string Name,
      string Email,
      int LoginCount,
      DateTimeOffset LastLoginAt);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Read model

```elixir
  defmodule MyApp.ReadModels.DecPassiveUserSummary do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, :email, login_count: 0, last_login_at: nil]
  end
  ```

* TypeScript

```typescript
  class DecPassiveUserSummary {
      name = '';
      email = '';
      loginCount = 0;
      lastLoginAt = new Date();
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

Events should match the read model structure or use explicit mapping:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record DecPassiveUserCreated(string Name, string Email);

[EventType]
  public record DecPassiveUserUpdated(string Name, string Email);

[EventType]
  public record DecPassiveUserLoggedIn(DateTimeOffset LoginTime);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Events

```elixir
  defmodule MyApp.Events.DecPassiveUserCreated do
    use Chronicle.Events.EventType, id: "dec-passive-user-created"

defstruct [:name, :email]
  end

defmodule MyApp.Events.DecPassiveUserUpdated do
    use Chronicle.Events.EventType, id: "dec-passive-user-updated"

defstruct [:name, :email]
  end

defmodule MyApp.Events.DecPassiveUserLoggedIn do
    use Chronicle.Events.EventType, id: "dec-passive-user-logged-in"

defstruct [:login_time]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class DecPassiveUserCreated {
      name = '';
      email = '';
  }

@eventType()
  class DecPassiveUserUpdated {
      name = '';
      email = '';
  }

@eventType()
  class DecPassiveUserLoggedIn {
      loginTime = new Date();
  }
  ```

## How it works

[Section titled “How it works”](#how-it-works)

When you call `GetInstanceById` on a passive projection:

1. Chronicle retrieves all relevant events for the specified event source ID
2. The projection logic is applied to reconstruct the read model in memory
3. The resulting read model is returned without being persisted
4. Each call reconstructs the model from scratch, ensuring up-to-date data

## When to use passive projections

[Section titled “When to use passive projections”](#when-to-use-passive-projections)

Passive projections are ideal for:

* **Infrequent queries**: When read models are accessed rarely or sporadically
* **Real-time data**: When you always need the most current state without caching concerns
* **Memory-sensitive scenarios**: When you want to avoid storing projection state
* **Temporary calculations**: For read models that are computed and discarded
* **Testing and debugging**: When you need to inspect event-driven state without persistence

## Performance considerations

[Section titled “Performance considerations”](#performance-considerations)

* Passive projections have higher latency since they reconstruct on each request
* They consume more CPU but less storage compared to active projections
* Consider caching strategies if the same passive projection is accessed frequently
* Use for read models with simple event processing logic to minimize reconstruction time

# Projection with RemoveWithJoin

The `RemovedWithJoin<>()` method allows you to remove child items from collections when events from other streams indicate that related data should be removed. This is particularly useful in scenarios where the removal event occurs on a different stream than the one that originally added the child.

Client coverage

Every example on this page combines declarative child collections with joins, both of which are currently a C#-only mechanism (see [Children](/chronicle/projections/declarative/children/) and [Joins](/chronicle/projections/declarative/joins/)). Kotlin and Java have no fluent child-collection API, TypeScript’s builder throws `not implemented yet` for child collections, and Elixir has no verified, working pattern for embedding a child collection into a parent read model. These examples are shown in C# only until child projection scopes are implemented for the other clients.

## Understanding RemoveWithJoin vs RemovedWith

[Section titled “Understanding RemoveWithJoin vs RemovedWith”](#understanding-removewithjoin-vs-removedwith)

* **`RemovedWith<>()`**: Removes children based on events from the same stream
* **`RemovedWithJoin<>()`**: Removes children based on events from different streams (joins)

## Basic RemoveWithJoin usage

[Section titled “Basic RemoveWithJoin usage”](#basic-removewithjoin-usage)

Use `RemovedWithJoin<>()` in child projections to specify which events should trigger child removal:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecRemoveWithJoinBasicUserCreated(string Name);

[EventType]
  public record DecRemoveWithJoinBasicUserAddedToGroup(string UserId, string GroupId);

[EventType]
  public record DecRemoveWithJoinBasicGroupCreated(string Name);

[EventType]
  public record DecRemoveWithJoinBasicGroupDeleted;

public record DecRemoveWithJoinBasicUserGroup(string GroupId, string Name, DateTimeOffset JoinedAt);

public record DecRemoveWithJoinBasicUser(string Name, IEnumerable<DecRemoveWithJoinBasicUserGroup> Groups);

public class DecRemoveWithJoinBasicUserProjection : IProjectionFor<DecRemoveWithJoinBasicUser>
  {
      public void Define(IProjectionBuilderFor<DecRemoveWithJoinBasicUser> builder) => builder
          .AutoMap()
          .From<DecRemoveWithJoinBasicUserCreated>()
          .Children(m => m.Groups, children => children
              .IdentifiedBy(e => e.GroupId)
              .AutoMap()
              .From<DecRemoveWithJoinBasicUserAddedToGroup>(_ => _
                  .UsingParentKey(e => e.UserId)
                  .Set(m => m.JoinedAt).ToEventContextProperty(c => c.Occurred))
              .Join<DecRemoveWithJoinBasicGroupCreated>(_ => _
                  .On(m => m.GroupId))
              .RemovedWithJoin<DecRemoveWithJoinBasicGroupDeleted>());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `IChildrenBuilderFor`/`IChildFromBuilderFor` have no `removedWithJoin` method — removal via a joined
  event only exists for the whole read model instance (`IProjectionBuilderFor.removedWithJoin`), not
  for a single item inside a `children()` collection.
  ```

* Java

```text
  Java does not support this workflow yet.
  `IChildrenBuilderFor`/`IChildFromBuilderFor` have no `removedWithJoin` method — removal via a joined
  event only exists for the whole read model instance (`IProjectionBuilderFor.removedWithJoin`), not
  for a single item inside a `children()` collection.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecRemoveWithJoinBasicUserCreated {
      constructor(readonly name: string) {}
  }

@eventType()
  class DecRemoveWithJoinBasicUserAddedToGroup {
      constructor(readonly userId: string, readonly groupId: string) {}
  }

@eventType()
  class DecRemoveWithJoinBasicGroupCreated {
      constructor(readonly name: string) {}
  }

@eventType()
  class DecRemoveWithJoinBasicGroupDeleted {
  }

class DecRemoveWithJoinBasicUserGroup {
      groupId = '';
      name = '';
      joinedAt = new Date();
  }

class DecRemoveWithJoinBasicUser {
      name = '';
      groups: DecRemoveWithJoinBasicUserGroup[] = [];
  }

@projection()
  class DecRemoveWithJoinBasicUserProjection implements IProjectionFor<DecRemoveWithJoinBasicUser> {
      define(builder: IProjectionBuilderFor<DecRemoveWithJoinBasicUser>): void {
          builder
              .autoMap()
              .from(DecRemoveWithJoinBasicUserCreated)
              .children<DecRemoveWithJoinBasicUserGroup>(m => m.groups, children => children
                  .identifiedBy(e => e.groupId)
                  .autoMap()
                  .from(DecRemoveWithJoinBasicUserAddedToGroup, _ => _
                      .usingParentKey(e => e.userId)
                      .set(m => m.joinedAt).toEventContextProperty('occurred'))
                  .join(DecRemoveWithJoinBasicGroupCreated, _ => _
                      .on(m => m.groupId))
                  .removedWithJoin(DecRemoveWithJoinBasicGroupDeleted));
      }
  }
  ```

In this example:

* When a `UserAddedToGroup` event occurs, a group is added to the user’s collection
* `UsingParentKey(e => e.UserId)` extracts the parent (user) identifier from the event content
* When a `GroupDeleted` event occurs anywhere in the system, that group is removed from all users
* The removal is based on the group ID that was used to join the data

> **Note**: If you don’t specify `UsingParentKey()`, the framework uses the EventSourceId as the parent identifier by default. Use `UsingParentKey()` when the parent identifier is a property in the event content rather than the EventSourceId.

## How RemoveWithJoin works

[Section titled “How RemoveWithJoin works”](#how-removewithjoin-works)

When using `RemovedWithJoin<>()`:

1. **Event occurs**: The specified event type (e.g., `GroupDeleted`) is processed
2. **Key extraction**: The system extracts the key from the event source ID or specified key expression
3. **Child lookup**: All projections with children joined on that key are found
4. **Removal**: The matching child items are removed from all affected collections

## RemoveWithJoin with explicit keys

[Section titled “RemoveWithJoin with explicit keys”](#removewithjoin-with-explicit-keys)

You can specify which property to use as the key for removal:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record DecRemoveWithJoinExplicitEmployeeHired(string Name);

[EventType]
  public record DecRemoveWithJoinExplicitEmployeeAssignedToProject(string EmployeeId, string ProjectId);

[EventType]
  public record DecRemoveWithJoinExplicitProjectCreated(string Name);

[EventType]
  public record DecRemoveWithJoinExplicitProjectCancelled(string ProjectId);

public record DecRemoveWithJoinExplicitEmployeeProject(string ProjectId, string Name, DateTimeOffset AssignedAt);

public record DecRemoveWithJoinExplicitEmployee(string Name, IEnumerable<DecRemoveWithJoinExplicitEmployeeProject> Projects);

public class DecRemoveWithJoinExplicitEmployeeProjection : IProjectionFor<DecRemoveWithJoinExplicitEmployee>
  {
      public void Define(IProjectionBuilderFor<DecRemoveWithJoinExplicitEmployee> builder) => builder
          .AutoMap()
          .From<DecRemoveWithJoinExplicitEmployeeHired>()
          .Children(m => m.Projects, children => children
              .IdentifiedBy(e => e.ProjectId)
              .AutoMap()
              .From<DecRemoveWithJoinExplicitEmployeeAssignedToProject>(_ => _
                  .UsingParentKey(e => e.EmployeeId)
                  .UsingKey(e => e.ProjectId)
                  .Set(m => m.AssignedAt).ToEventContextProperty(c => c.Occurred))
              .Join<DecRemoveWithJoinExplicitProjectCreated>(_ => _
                  .On(m => m.ProjectId))
              .RemovedWithJoin<DecRemoveWithJoinExplicitProjectCancelled>(_ => _
                  .UsingKey(e => e.ProjectId)));
  }
  ```

* Kotlin

* Java

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class DecRemoveWithJoinExplicitEmployeeHired {
      constructor(readonly name: string) {}
  }

@eventType()
  class DecRemoveWithJoinExplicitEmployeeAssignedToProject {
      constructor(readonly employeeId: string, readonly projectId: string) {}
  }

@eventType()
  class DecRemoveWithJoinExplicitProjectCreated {
      constructor(readonly name: string) {}
  }

@eventType()
  class DecRemoveWithJoinExplicitProjectCancelled {
      constructor(readonly projectId: string) {}
  }

class DecRemoveWithJoinExplicitEmployeeProject {
      projectId = '';
      name = '';
      assignedAt = new Date();
  }

class DecRemoveWithJoinExplicitEmployee {
      name = '';
      projects: DecRemoveWithJoinExplicitEmployeeProject[] = [];
  }

@projection()
  class DecRemoveWithJoinExplicitEmployeeProjection implements IProjectionFor<DecRemoveWithJoinExplicitEmployee> {
      define(builder: IProjectionBuilderFor<DecRemoveWithJoinExplicitEmployee>): void {
          builder
              .autoMap()
              .from(DecRemoveWithJoinExplicitEmployeeHired)
              .children<DecRemoveWithJoinExplicitEmployeeProject>(m => m.projects, children => children
                  .identifiedBy(e => e.projectId)
                  .autoMap()
                  .from(DecRemoveWithJoinExplicitEmployeeAssignedToProject, _ => _
                      .usingParentKey(e => e.employeeId)
                      .usingKey(e => e.projectId)
                      .set(m => m.assignedAt).toEventContextProperty('occurred'))
                  .join(DecRemoveWithJoinExplicitProjectCreated, _ => _
                      .on(m => m.projectId))
                  .removedWithJoin(DecRemoveWithJoinExplicitProjectCancelled, _ => _
                      .usingKey(e => e.projectId)));
      }
  }
  ```

## Real-world example: User groups

[Section titled “Real-world example: User groups”](#real-world-example-user-groups)

Consider a system where users can be members of groups, and groups can be deleted:

* C#

```csharp
  public class DecRemoveWithJoinGroupMembershipProjection : IProjectionFor<DecRemoveWithJoinUserProfile>
  {
      public void Define(IProjectionBuilderFor<DecRemoveWithJoinUserProfile> builder) => builder
          .AutoMap()
          .From<DecRemoveWithJoinUserRegistered>(_ => _
              .Set(m => m.UserId).ToEventSourceId()
              .Set(m => m.RegisteredAt).ToEventContextProperty(c => c.Occurred))
          .Children(m => m.Memberships, children => children
              .IdentifiedBy(e => e.GroupId)
              .AutoMap()
              .From<DecRemoveWithJoinUserJoinedGroup>(_ => _
                  .UsingParentKey(e => e.UserId)
                  .UsingKey(e => e.GroupId)
                  .Set(m => m.JoinedAt).ToEventContextProperty(c => c.Occurred))
              .Join<DecRemoveWithJoinGroupCreated>(_ => _
                  .On(m => m.GroupId))
              .RemovedWith<DecRemoveWithJoinUserLeftGroup>(_ => _
                  .UsingParentKey(e => e.UserId)
                  .UsingKey(e => e.GroupId))
              .RemovedWithJoin<DecRemoveWithJoinGroupDisbanded>());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `IChildrenBuilderFor`/`IChildFromBuilderFor` have no `removedWith`/`removedWithJoin` method — removing
  a single item from a child collection, whether from the same stream or a joined one, is only possible
  today with model-bound `@RemovedWith`/`@RemovedWithJoin` on a `@ChildrenFrom` property.
  ```

* Java

```text
  Java does not support this workflow yet.
  `IChildrenBuilderFor`/`IChildFromBuilderFor` have no `removedWith`/`removedWithJoin` method — removing
  a single item from a child collection, whether from the same stream or a joined one, is only possible
  today with model-bound `@RemovedWith`/`@RemovedWithJoin` on a `@ChildrenFrom` property.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecRemoveWithJoinGroupMembershipProjection implements IProjectionFor<DecRemoveWithJoinUserProfile> {
      define(builder: IProjectionBuilderFor<DecRemoveWithJoinUserProfile>): void {
          builder
              .autoMap()
              .from(DecRemoveWithJoinUserRegistered, _ => _
                  .set(m => m.userId).toEventSourceId()
                  .set(m => m.registeredAt).toEventContextProperty('occurred'))
              .children<DecRemoveWithJoinGroupMembership>(m => m.memberships, children => children
                  .identifiedBy(e => e.groupId)
                  .autoMap()
                  .from(DecRemoveWithJoinUserJoinedGroup, _ => _
                      .usingParentKey(e => e.userId)
                      .usingKey(e => e.groupId)
                      .set(m => m.joinedAt).toEventContextProperty('occurred'))
                  .join(DecRemoveWithJoinGroupCreated, _ => _
                      .on(m => m.groupId))
                  .removedWith(DecRemoveWithJoinUserLeftGroup, _ => _
                      .usingKey(e => e.groupId))
                  .removedWithJoin(DecRemoveWithJoinGroupDisbanded));
      }
  }
  ```

In this example:

* **`RemovedWith<UserLeftGroup>`**: Removes membership when a user explicitly leaves a group
* **`RemovedWithJoin<GroupDisbanded>`**: Removes membership from all users when a group is disbanded

## Complex scenario: Project assignments

[Section titled “Complex scenario: Project assignments”](#complex-scenario-project-assignments)

* C#

```csharp
  public class DecRemoveWithJoinDeveloperProjectsProjection : IProjectionFor<DecRemoveWithJoinDeveloperProfile>
  {
      public void Define(IProjectionBuilderFor<DecRemoveWithJoinDeveloperProfile> builder) => builder
          .AutoMap()
          .From<DecRemoveWithJoinDeveloperOnboarded>(_ => _
              .Set(m => m.DeveloperId).ToEventSourceId()
              .Set(m => m.OnboardedAt).ToEventContextProperty(c => c.Occurred))
          .Children(m => m.CurrentProjects, children => children
              .IdentifiedBy(e => e.ProjectId)
              .AutoMap()
              .From<DecRemoveWithJoinDeveloperAssignedToProject>(_ => _
                  .UsingParentKey(e => e.DeveloperId)
                  .UsingKey(e => e.ProjectId)
                  .Set(m => m.AssignedAt).ToEventContextProperty(c => c.Occurred))
              .Join<DecRemoveWithJoinProjectInitiated>(_ => _
                  .On(m => m.ProjectId))
              .RemovedWith<DecRemoveWithJoinDeveloperUnassignedFromProject>(_ => _
                  .UsingParentKey(e => e.DeveloperId)
                  .UsingKey(e => e.ProjectId))
              .RemovedWithJoin<DecRemoveWithJoinProjectCancelled>()
              .RemovedWithJoin<DecRemoveWithJoinProjectCompleted>());
  }
  ```

* Kotlin

* Java

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecRemoveWithJoinDeveloperProjectsProjection implements IProjectionFor<DecRemoveWithJoinDeveloperProfile> {
      define(builder: IProjectionBuilderFor<DecRemoveWithJoinDeveloperProfile>): void {
          builder
              .autoMap()
              .from(DecRemoveWithJoinDeveloperOnboarded, _ => _
                  .set(m => m.developerId).toEventSourceId()
                  .set(m => m.onboardedAt).toEventContextProperty('occurred'))
              .children<DecRemoveWithJoinProjectAssignment>(m => m.currentProjects, children => children
                  .identifiedBy(e => e.projectId)
                  .autoMap()
                  .from(DecRemoveWithJoinDeveloperAssignedToProject, _ => _
                      .usingParentKey(e => e.developerId)
                      .usingKey(e => e.projectId)
                      .set(m => m.assignedAt).toEventContextProperty('occurred'))
                  .join(DecRemoveWithJoinProjectInitiated, _ => _
                      .on(m => m.projectId))
                  .removedWith(DecRemoveWithJoinDeveloperUnassignedFromProject, _ => _
                      .usingKey(e => e.projectId))
                  .removedWithJoin(DecRemoveWithJoinProjectCancelled)
                  .removedWithJoin(DecRemoveWithJoinProjectCompleted));
      }
  }
  ```

This handles three removal scenarios:

1. **Individual unassignment**: `DeveloperUnassignedFromProject` removes one developer from one project
2. **Project cancellation**: `ProjectCancelled` removes the project from all developers
3. **Project completion**: `ProjectCompleted` removes the project from all developers

## Read model examples

[Section titled “Read model examples”](#read-model-examples)

* C#

```csharp
  public record DecRemoveWithJoinUserProfile(
      string UserId,
      string Username,
      string Email,
      DateTimeOffset RegisteredAt,
      IEnumerable<DecRemoveWithJoinGroupMembership> Memberships);

public record DecRemoveWithJoinGroupMembership(
      string GroupId,
      string GroupName,
      string GroupType,
      DateTimeOffset JoinedAt,
      string Role);

public record DecRemoveWithJoinDeveloperProfile(
      string DeveloperId,
      string Name,
      IEnumerable<string> Skills,
      DateTimeOffset OnboardedAt,
      IEnumerable<DecRemoveWithJoinProjectAssignment> CurrentProjects);

public record DecRemoveWithJoinProjectAssignment(
      string ProjectId,
      string ProjectName,
      string Priority,
      DateTimeOffset Deadline,
      DateTimeOffset AssignedAt,
      string Role,
      int Allocation);
  ```

* Kotlin

```kotlin
  import java.time.Instant

data class DecRemoveWithJoinUserProfile(
      val userId: String = "",
      val username: String = "",
      val email: String = "",
      val registeredAt: Instant = Instant.EPOCH,
      val memberships: List<DecRemoveWithJoinGroupMembership> = emptyList()
  )

data class DecRemoveWithJoinGroupMembership(
      val groupId: String = "",
      val groupName: String = "",
      val groupType: String = "",
      val joinedAt: Instant = Instant.EPOCH,
      val role: String = ""
  )

data class DecRemoveWithJoinDeveloperProfile(
      val developerId: String = "",
      val name: String = "",
      val skills: List<String> = emptyList(),
      val onboardedAt: Instant = Instant.EPOCH,
      val currentProjects: List<DecRemoveWithJoinProjectAssignment> = emptyList()
  )

data class DecRemoveWithJoinProjectAssignment(
      val projectId: String = "",
      val projectName: String = "",
      val priority: String = "",
      val deadline: Instant = Instant.EPOCH,
      val assignedAt: Instant = Instant.EPOCH,
      val role: String = "",
      val allocation: Int = 0
  )
  ```

* Java

```java
  import java.time.Instant;
  import java.util.List;

record DecRemoveWithJoinUserProfile(
      String userId,
      String username,
      String email,
      Instant registeredAt,
      List<DecRemoveWithJoinGroupMembership> memberships
  ) {}

record DecRemoveWithJoinGroupMembership(
      String groupId,
      String groupName,
      String groupType,
      Instant joinedAt,
      String role
  ) {}

record DecRemoveWithJoinDeveloperProfile(
      String developerId,
      String name,
      List<String> skills,
      Instant onboardedAt,
      List<DecRemoveWithJoinProjectAssignment> currentProjects
  ) {}

record DecRemoveWithJoinProjectAssignment(
      String projectId,
      String projectName,
      String priority,
      Instant deadline,
      Instant assignedAt,
      String role,
      int allocation
  ) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  class DecRemoveWithJoinGroupMembership {
      groupId = '';
      groupName = '';
      groupType = '';
      joinedAt = new Date();
      role = '';
  }

class DecRemoveWithJoinUserProfile {
      userId = '';
      username = '';
      email = '';
      registeredAt = new Date();
      memberships: DecRemoveWithJoinGroupMembership[] = [];
  }

class DecRemoveWithJoinProjectAssignment {
      projectId = '';
      projectName = '';
      priority = '';
      deadline = new Date();
      assignedAt = new Date();
      role = '';
      allocation = 0;
  }

class DecRemoveWithJoinDeveloperProfile {
      developerId = '';
      name = '';
      skills: string[] = [];
      onboardedAt = new Date();
      currentProjects: DecRemoveWithJoinProjectAssignment[] = [];
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record DecRemoveWithJoinUserRegistered(string Username, string Email);

[EventType]
  public record DecRemoveWithJoinUserJoinedGroup(string UserId, string GroupId, string Role);

[EventType]
  public record DecRemoveWithJoinUserLeftGroup(string UserId, string GroupId);

[EventType]
  public record DecRemoveWithJoinGroupCreated(string GroupName, string GroupType);

[EventType]
  public record DecRemoveWithJoinGroupDisbanded;

[EventType]
  public record DecRemoveWithJoinDeveloperOnboarded(string Name, IEnumerable<string> Skills);

[EventType]
  public record DecRemoveWithJoinDeveloperAssignedToProject(string DeveloperId, string ProjectId, string Role, int Allocation);

[EventType]
  public record DecRemoveWithJoinDeveloperUnassignedFromProject(string DeveloperId, string ProjectId);

[EventType]
  public record DecRemoveWithJoinProjectInitiated(string ProjectName, string Priority, DateTimeOffset Deadline);

[EventType]
  public record DecRemoveWithJoinProjectCancelled;

[EventType]
  public record DecRemoveWithJoinProjectCompleted;
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class DecRemoveWithJoinUserRegistered(val username: String, val email: String)

@EventType
  data class DecRemoveWithJoinUserJoinedGroup(val userId: String, val groupId: String, val role: String)

@EventType
  data class DecRemoveWithJoinUserLeftGroup(val userId: String, val groupId: String)

@EventType
  data class DecRemoveWithJoinGroupCreated(val groupName: String, val groupType: String)

@EventType
  data class DecRemoveWithJoinGroupDisbanded(val placeholder: Boolean = true)

@EventType
  data class DecRemoveWithJoinDeveloperOnboarded(val name: String, val skills: List<String>)

@EventType
  data class DecRemoveWithJoinDeveloperAssignedToProject(
      val developerId: String,
      val projectId: String,
      val role: String,
      val allocation: Int
  )

@EventType
  data class DecRemoveWithJoinDeveloperUnassignedFromProject(val developerId: String, val projectId: String)

@EventType
  data class DecRemoveWithJoinProjectInitiated(
      val projectName: String,
      val priority: String,
      val deadline: java.time.Instant
  )

@EventType
  data class DecRemoveWithJoinProjectCancelled(val placeholder: Boolean = true)

@EventType
  data class DecRemoveWithJoinProjectCompleted(val placeholder: Boolean = true)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

import java.time.Instant;
  import java.util.List;

@EventType
  record DecRemoveWithJoinUserRegistered(String username, String email) {}

@EventType
  record DecRemoveWithJoinUserJoinedGroup(String userId, String groupId, String role) {}

@EventType
  record DecRemoveWithJoinUserLeftGroup(String userId, String groupId) {}

@EventType
  record DecRemoveWithJoinGroupCreated(String groupName, String groupType) {}

@EventType
  record DecRemoveWithJoinGroupDisbanded() {}

@EventType
  record DecRemoveWithJoinDeveloperOnboarded(String name, List<String> skills) {}

@EventType
  record DecRemoveWithJoinDeveloperAssignedToProject(
      String developerId,
      String projectId,
      String role,
      int allocation
  ) {}

@EventType
  record DecRemoveWithJoinDeveloperUnassignedFromProject(String developerId, String projectId) {}

@EventType
  record DecRemoveWithJoinProjectInitiated(String projectName, String priority, Instant deadline) {}

@EventType
  record DecRemoveWithJoinProjectCancelled() {}

@EventType
  record DecRemoveWithJoinProjectCompleted() {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class DecRemoveWithJoinUserRegistered {
      constructor(readonly username: string, readonly email: string) {}
  }

@eventType()
  class DecRemoveWithJoinUserJoinedGroup {
      constructor(readonly userId: string, readonly groupId: string, readonly role: string) {}
  }

@eventType()
  class DecRemoveWithJoinUserLeftGroup {
      constructor(readonly userId: string, readonly groupId: string) {}
  }

@eventType()
  class DecRemoveWithJoinGroupCreated {
      constructor(readonly groupName: string, readonly groupType: string) {}
  }

@eventType()
  class DecRemoveWithJoinGroupDisbanded {
  }

@eventType()
  class DecRemoveWithJoinDeveloperOnboarded {
      constructor(readonly name: string, readonly skills: string[]) {}
  }

@eventType()
  class DecRemoveWithJoinDeveloperAssignedToProject {
      constructor(
          readonly developerId: string,
          readonly projectId: string,
          readonly role: string,
          readonly allocation: number
      ) {}
  }

@eventType()
  class DecRemoveWithJoinDeveloperUnassignedFromProject {
      constructor(readonly developerId: string, readonly projectId: string) {}
  }

@eventType()
  class DecRemoveWithJoinProjectInitiated {
      constructor(readonly projectName: string, readonly priority: string, readonly deadline: Date) {}
  }

@eventType()
  class DecRemoveWithJoinProjectCancelled {
  }

@eventType()
  class DecRemoveWithJoinProjectCompleted {
  }
  ```

## Best practices

[Section titled “Best practices”](#best-practices)

### Use for cross-stream cleanup

[Section titled “Use for cross-stream cleanup”](#use-for-cross-stream-cleanup)

`RemovedWithJoin<>()` is ideal when:

* Events from one stream should trigger cleanup in projections of other stream
* You need to maintain referential integrity across stream boundaries
* Deletion or deactivation events should cascade to related read models

### Combine with RemovedWith

[Section titled “Combine with RemovedWith”](#combine-with-removedwith)

Often you’ll use both removal methods together:

* `RemovedWith<>()` for explicit removals within the same stream
* `RemovedWithJoin<>()` for cascade removals from related streams

### Consider event ordering

[Section titled “Consider event ordering”](#consider-event-ordering)

Be aware that `RemovedWithJoin<>()` events might be processed before all related `Join<>()` events have completed, so ensure your system handles partial data gracefully.

The `RemovedWithJoin<>()` method provides powerful cross-stream cleanup capabilities, ensuring that your read models stay consistent when related data is removed from other parts of your system.

# Projection with custom properties

When auto-mapping isn’t sufficient, you can explicitly map properties from events to your read model. This gives you full control over how data is transformed and mapped.

## Explicit property mapping

[Section titled “Explicit property mapping”](#explicit-property-mapping)

Instead of using `AutoMap()`, use `Set()` methods to explicitly define property mappings:

* C#

```csharp
  using Cratis.Chronicle.Projections;

public class DecSetPropsAccountProjection : IProjectionFor<DecSetPropsAccount>
  {
      public void Define(IProjectionBuilderFor<DecSetPropsAccount> builder) => builder
          .From<DecSetPropsAccountOpened>(_ => _
              .Set(m => m.AccountNumber).To(e => e.Number)
              .Set(m => m.CustomerName).To(e => e.Owner.Name)
              .Set(m => m.Balance).ToValue(42.0m)
              .Set(m => m.IsActive).ToValue(true)
              .Set(m => m.OpenedAt).To(e => e.Timestamp))
          .From<DecSetPropsMoneyDeposited>(_ => _
              .Set(m => m.Balance).To(e => e.Amount)
              .Set(m => m.LastTransaction).To(e => e.Timestamp));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor
  import java.math.BigDecimal

class DecSetPropsAccountProjection : IProjectionFor<DecSetPropsAccount> {
      override fun define(builder: IProjectionBuilderFor<DecSetPropsAccount>) {
          builder
              .from(DecSetPropsAccountOpened::class) {
                  it.set(DecSetPropsAccount::accountNumber).to { e -> e.number }
                  it.set(DecSetPropsAccount::customerName).to { e -> e.owner.name }
                  it.set(DecSetPropsAccount::balance).to { BigDecimal("42.0") }
                  it.set(DecSetPropsAccount::isActive).to { true }
                  it.set(DecSetPropsAccount::openedAt).to { e -> e.timestamp }
              }
              .from(DecSetPropsMoneyDeposited::class) {
                  it.set(DecSetPropsAccount::balance).to { e -> e.amount }
                  it.set(DecSetPropsAccount::lastTransaction).to { e -> e.timestamp }
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.math.BigDecimal;

class DecSetPropsAccountProjection implements IProjectionFor<DecSetPropsAccount> {
      @Override
      public void define(IProjectionBuilderFor<DecSetPropsAccount> builder) {
          builder
              .from(DecSetPropsAccountOpened.class, fb -> {
                  fb.<String>set("accountNumber").to(e -> e.number());
                  fb.<String>set("customerName").to(e -> e.owner().name());
                  fb.<BigDecimal>set("balance").to(e -> new BigDecimal("42.0"));
                  fb.<Boolean>set("isActive").to(e -> true);
                  fb.<String>set("openedAt").to(e -> e.timestamp());
              })
              .from(DecSetPropsMoneyDeposited.class, fb -> {
                  fb.<Double>set("balance").to(e -> e.amount());
                  fb.<String>set("lastTransaction").to(e -> e.timestamp());
              });
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Projections.DecSetPropsAccountProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecSetPropsAccount

alias MyApp.Events.{DecSetPropsAccountOpened, DecSetPropsMoneyDeposited}

from DecSetPropsAccountOpened,
      set: [
        account_number: :number,
        # `owner` is a nested object on the event — the dot-path expression
        # reaches into it the same way Chronicle's kernel resolves any other
        # nested event property.
        customer_name: "owner.name",
        balance: "$value(42.0)",
        is_active: "$value(true)",
        opened_at: :timestamp
      ]

from DecSetPropsMoneyDeposited,
      set: [
        balance: :amount,
        last_transaction: :timestamp
      ]
  end
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecSetPropsAccountProjection implements IProjectionFor<DecSetPropsAccount> {
      define(builder: IProjectionBuilderFor<DecSetPropsAccount>): void {
          builder
              .from(DecSetPropsAccountOpened, _ => _
                  .set(m => m.accountNumber).to(e => e.number)
                  .set(m => m.customerName).to(e => e.owner.name)
                  .set(m => m.balance).toValue(42.0)
                  .set(m => m.isActive).toValue(true)
                  .set(m => m.openedAt).to(e => e.timestamp))
              .from(DecSetPropsMoneyDeposited, _ => _
                  .set(m => m.balance).to(e => e.amount)
                  .set(m => m.lastTransaction).to(e => e.timestamp));
      }
  }
  ```

## Combining AutoMap with explicit mapping

[Section titled “Combining AutoMap with explicit mapping”](#combining-automap-with-explicit-mapping)

You can use `AutoMap()` at the top level to automatically map matching properties, then add explicit mappings for specific transformations:

* C#

```csharp
  public class DecSetPropsCombinedAccountProjection : IProjectionFor<DecSetPropsAccount>
  {
      public void Define(IProjectionBuilderFor<DecSetPropsAccount> builder) => builder
          .AutoMap()  // Automatically maps matching properties
          .From<DecSetPropsAccountOpened>(_ => _
              .Set(m => m.CustomerName).To(e => e.Owner.Name)  // Custom mapping for nested property
              .Set(m => m.IsActive).ToValue(true))             // Custom mapping for constant
          .From<DecSetPropsMoneyDeposited>();  // Uses AutoMap for all properties
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

class DecSetPropsCombinedAccountProjection : IProjectionFor<DecSetPropsAccount> {
      override fun define(builder: IProjectionBuilderFor<DecSetPropsAccount>) {
          builder
              // AutoMap is on by default; these two properties don't have matching event
              // properties, so they're set explicitly and everything else is left to AutoMap.
              .from(DecSetPropsAccountOpened::class) {
                  it.set(DecSetPropsAccount::customerName).to { e -> e.owner.name }
                  it.set(DecSetPropsAccount::isActive).to { true }
              }
              .from(DecSetPropsMoneyDeposited::class) // Uses AutoMap for all properties
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

class DecSetPropsCombinedAccountProjection implements IProjectionFor<DecSetPropsAccount> {
      @Override
      public void define(IProjectionBuilderFor<DecSetPropsAccount> builder) {
          builder
              // AutoMap is on by default; these two properties don't have matching event
              // properties, so they're set explicitly and everything else is left to AutoMap.
              .from(DecSetPropsAccountOpened.class, fb -> {
                  fb.<String>set("customerName").to(e -> e.owner().name());
                  fb.<Boolean>set("isActive").to(e -> true);
              })
              .from(DecSetPropsMoneyDeposited.class); // Uses AutoMap for all properties
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Projections.DecSetPropsCombinedAccountProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecSetPropsAccount

alias MyApp.Events.{DecSetPropsAccountOpened, DecSetPropsMoneyDeposited}

# AutoMap fills every property whose name matches the event automatically;
    # only the two exceptions below need an explicit set:.
    from DecSetPropsAccountOpened,
      set: [
        customer_name: "owner.name",
        is_active: "$value(true)"
      ]

# Uses AutoMap for every property.
    from DecSetPropsMoneyDeposited
  end
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecSetPropsCombinedAccountProjection implements IProjectionFor<DecSetPropsAccount> {
      define(builder: IProjectionBuilderFor<DecSetPropsAccount>): void {
          builder
              .autoMap()  // Automatically maps matching properties
              .from(DecSetPropsAccountOpened, _ => _
                  .set(m => m.customerName).to(e => e.owner.name)  // Custom mapping for nested property
                  .set(m => m.isActive).toValue(true))             // Custom mapping for constant
              .from(DecSetPropsMoneyDeposited);  // Uses AutoMap for all properties
      }
  }
  ```

`AutoMap()` works recursively, automatically mapping:

* Properties with matching names and compatible types
* Nested objects and their properties
* Collections and arrays

`AutoMap()`/`NoAutoMap()` are set once at the projection level — there is no per-event-type toggle. Add explicit `.Set()` calls inside a specific `.From<TEvent>()` block for the properties that need custom mapping; AutoMap still fills in every other matching property for that event.

## Read model definition

[Section titled “Read model definition”](#read-model-definition)

The read model can have different property names and types than the events:

* C#

```csharp
  public record DecSetPropsAccount(
      string AccountNumber,
      string CustomerName,
      decimal Balance,
      bool IsActive,
      DateTimeOffset OpenedAt,
      DateTimeOffset? LastTransaction);
  ```

* Kotlin

```kotlin
  import java.math.BigDecimal
  import java.time.OffsetDateTime

data class DecSetPropsAccount(
      val accountNumber: String = "",
      val customerName: String = "",
      val balance: BigDecimal = BigDecimal.ZERO,
      val isActive: Boolean = false,
      val openedAt: OffsetDateTime? = null,
      val lastTransaction: OffsetDateTime? = null
  )
  ```

* Java

```java
  class DecSetPropsAccount {
      public String accountNumber = "";
      public String customerName = "";
      public double balance = 0.0;
      public boolean isActive = false;
      public String openedAt = null;
      public String lastTransaction = null;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.DecSetPropsAccount do
    use Chronicle.ReadModels.ReadModel

defstruct [
      :account_number,
      :customer_name,
      :balance,
      :is_active,
      :opened_at,
      :last_transaction
    ]
  end
  ```

* TypeScript

```typescript
  class DecSetPropsAccount {
      accountNumber = '';
      customerName = '';
      balance = 0;
      isActive = false;
      openedAt = new Date();
      lastTransaction: Date | null = null;
  }
  ```

## Event definitions

[Section titled “Event definitions”](#event-definitions)

Events can have different structures than the read model:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record DecSetPropsAccountOpened(
      string Number,
      DecSetPropsCustomer Owner,
      DateTimeOffset Timestamp);

[EventType]
  public record DecSetPropsMoneyDeposited(
      decimal Amount,
      DateTimeOffset Timestamp);

public record DecSetPropsCustomer(string Name, string Email);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import java.math.BigDecimal
  import java.time.OffsetDateTime

data class DecSetPropsCustomer(val name: String, val email: String)

@EventType
  data class DecSetPropsAccountOpened(
      val number: String,
      val owner: DecSetPropsCustomer,
      val timestamp: OffsetDateTime
  )

@EventType
  data class DecSetPropsMoneyDeposited(
      val amount: BigDecimal,
      val timestamp: OffsetDateTime
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

record DecSetPropsCustomer(String name, String email) {}

@EventType
  record DecSetPropsAccountOpened(
      String number,
      DecSetPropsCustomer owner,
      String timestamp) {}

@EventType
  record DecSetPropsMoneyDeposited(
      double amount,
      String timestamp) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.DecSetPropsCustomer do
    defstruct [:name, :email]
  end

defmodule MyApp.Events.DecSetPropsAccountOpened do
    use Chronicle.Events.EventType, id: "dec-set-props-account-opened"

defstruct [:number, :owner, :timestamp]
  end

defmodule MyApp.Events.DecSetPropsMoneyDeposited do
    use Chronicle.Events.EventType, id: "dec-set-props-money-deposited"

defstruct [:amount, :timestamp]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

class DecSetPropsCustomer {
      name = '';
      email = '';
  }

@eventType()
  class DecSetPropsAccountOpened {
      number = '';
      owner = new DecSetPropsCustomer();
      timestamp = new Date();
  }

@eventType()
  class DecSetPropsMoneyDeposited {
      amount = 0;
      timestamp = new Date();
  }
  ```

## Property mapping options

[Section titled “Property mapping options”](#property-mapping-options)

You can map properties in several ways:

* **From event property**: `.Set(m => m.CustomerName).To(e => e.Owner.Name)`
* **From constant value**: `.Set(m => m.IsActive).ToValue(true)`
* **From event context**: `.Set(m => m.OpenedAt).ToEventContextProperty(c => c.Occurred)`
* **From event source ID**: `.Set(m => m.Id).ToEventSourceId()`

Note

`.To(...)` maps a single **event property** — it reads the value straight off the event, it does not run code. It cannot produce a *computed* value: `.To(e => $"{e.FirstName} {e.LastName}")`, `.To(_ => DateTimeOffset.UtcNow)` and similar expressions are not supported, because the builder extracts a property path from the expression rather than executing it. To derive a value, either record it on the event as a fact (compute it in the command’s `Handle()` before appending) or use a [reducer](/chronicle/reducers/), which can run arbitrary logic over the current state and the event.

## Multiple events

[Section titled “Multiple events”](#multiple-events)

A single projection can handle multiple event types, each with its own property mappings. Properties are updated incrementally as events are processed.

In the example above:

* `AccountOpened` sets initial values for all properties
* `MoneyDeposited` only updates `Balance` and `LastTransaction`
* Other properties retain their previous values

This approach gives you precise control over how your read models are built from events.

# Simple projection

A projection in Cratis is a way to create read models from events in the event store. The simplest projection automatically maps event properties to read model properties with matching names using the default AutoMap behavior.

## Defining a simple projection

[Section titled “Defining a simple projection”](#defining-a-simple-projection)

A projection implements `IProjectionFor<TReadModel>` and defines its behavior in the `Define` method:

* C#

```csharp
  using Cratis.Chronicle.Projections;

public class DecSimpleUserProjection : IProjectionFor<DecSimpleUser>
  {
      public void Define(IProjectionBuilderFor<DecSimpleUser> builder) => builder
          .From<DecSimpleUserCreated>();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

class DecSimpleUserProjection : IProjectionFor<DecSimpleUser> {
      override fun define(builder: IProjectionBuilderFor<DecSimpleUser>) {
          builder.from(DecSimpleUserCreated::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

class DecSimpleUserProjection implements IProjectionFor<DecSimpleUser> {
      @Override
      public void define(IProjectionBuilderFor<DecSimpleUser> builder) {
          builder.from(DecSimpleUserCreated.class);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Projections.DecSimpleUserProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.DecSimpleUser

alias MyApp.Events.DecSimpleUserCreated

from DecSimpleUserCreated
  end
  ```

* TypeScript

```typescript
  import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@projection()
  class DecSimpleUserProjection implements IProjectionFor<DecSimpleUser> {
      define(builder: IProjectionBuilderFor<DecSimpleUser>): void {
          builder.from(DecSimpleUserCreated);
      }
  }
  ```

This projection:

* Automatically maps properties from `UserCreated` event to the `User` read model (AutoMap is enabled by default)
* Uses the event source ID as the key for the read model
* Properties with matching names are automatically mapped

> **Note:** AutoMap is enabled by default at the top level. You don’t need to call `.AutoMap()` explicitly unless you want to ensure it’s enabled in contexts where it might be disabled. Read more about [auto mapping](/chronicle/projections/declarative/auto-map/)

## Read model definition

[Section titled “Read model definition”](#read-model-definition)

The read model is a simple record or class representing the projected data:

* C#

```csharp
  public record DecSimpleUser(string Name, string Email, DateTimeOffset CreatedAt);
  ```

* Kotlin

```kotlin
  import java.time.OffsetDateTime

data class DecSimpleUser(
      val name: String = "",
      val email: String = "",
      val createdAt: OffsetDateTime? = null
  )
  ```

* Java

```java
  class DecSimpleUser {
      public String name = "";
      public String email = "";
      public String createdAt = null;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.DecSimpleUser do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, :email, :created_at]
  end
  ```

* TypeScript

```typescript
  class DecSimpleUser {
      name = '';
      email = '';
      createdAt = new Date();
  }
  ```

## Event definition

[Section titled “Event definition”](#event-definition)

The event should match the read model structure for auto-mapping to work:

* C#

```csharp
  using Cratis.Chronicle.Events;

[EventType]
  public record DecSimpleUserCreated(string Name, string Email, DateTimeOffset CreatedAt);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import java.time.OffsetDateTime

@EventType
  data class DecSimpleUserCreated(val name: String, val email: String, val createdAt: OffsetDateTime)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record DecSimpleUserCreated(String name, String email, String createdAt) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.DecSimpleUserCreated do
    use Chronicle.Events.EventType, id: "dec-simple-user-created"

defstruct [:name, :email, :created_at]
  end
  ```

* TypeScript

```typescript
  class DecSimpleUserCreated {
      name = '';
      email = '';
      createdAt = new Date();
  }
  ```

## How it works

[Section titled “How it works”](#how-it-works)

When a `UserCreated` event is appended to the event log:

1. The projection automatically creates or updates a `User` read model
2. The event source ID becomes the key for the read model
3. Properties with matching names are copied from event to read model
4. The read model is stored and can be queried

Auto-mapping works when property names and types match between the event and read model. For more control over the mapping, see [projection with custom properties](/chronicle/projections/declarative/set-properties/).

# Eventual Consistency in Projections

Projections in Chronicle operate under the principle of **eventual consistency**, meaning that read models are updated asynchronously as events are processed. This design provides significant performance benefits but requires understanding of how and when data becomes consistent.

## Understanding Eventual Consistency

[Section titled “Understanding Eventual Consistency”](#understanding-eventual-consistency)

When you append an event to Chronicle, the following sequence occurs:

1. **Event is persisted** to the event store immediately
2. **Event append operation returns** successfully to the caller
3. **Projections are updated asynchronously** in the background
4. **Read models become consistent** after processing completes

This means there’s a brief window where:

* The event has been successfully stored
* But projections may not yet reflect the changes

## Asynchronous Processing

[Section titled “Asynchronous Processing”](#asynchronous-processing)

Chronicle processes events for projections asynchronously to ensure optimal performance and scalability:

### Processing Pipeline

[Section titled “Processing Pipeline”](#processing-pipeline)

```
Event Appended

Event Stored

Append Operation Returns

Background Processor

Projection Updated

Reducer Executed

Observer Notified
```

### Benefits of Asynchronous Processing

[Section titled “Benefits of Asynchronous Processing”](#benefits-of-asynchronous-processing)

* **High Throughput**: Event appends don’t wait for projection updates
* **Scalability**: Projection processing can be scaled independently
* **Resilience**: Failed projection updates don’t affect event persistence
* **Performance**: Read and write operations are optimized separately

## Consistency Guarantees

[Section titled “Consistency Guarantees”](#consistency-guarantees)

### What Chronicle Guarantees

[Section titled “What Chronicle Guarantees”](#what-chronicle-guarantees)

* **Event Ordering**: Events for the same event source are processed in order
* **At-Least-Once Processing**: Every event will be processed (with retries on failure)
* **Partition Consistency**: All projections for a single event source will be eventually consistent

### What Chronicle Does NOT Guarantee

[Section titled “What Chronicle Does NOT Guarantee”](#what-chronicle-does-not-guarantee)

* **Immediate Consistency**: Projections may lag behind events
* **Cross-Partition Ordering**: Events from different event sources may be processed out of relative order
* **Synchronous Updates**: Projection updates are always asynchronous

## Handling Eventual Consistency

[Section titled “Handling Eventual Consistency”](#handling-eventual-consistency)

### 1. Design for Asynchronous Updates

[Section titled “1. Design for Asynchronous Updates”](#1-design-for-asynchronous-updates)

Structure your application to work naturally with eventual consistency:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.ReadModels;

[EventType]
  public record EcBookCreated(string Title, string Author);

public record EcBookInventory(Guid Id, string Title, string Author);

public class EcBookService(IEventLog eventLog, IReadModels readModels)
  {
      // Good — fire and forget: don't wait for the projection before returning
      public async Task<EventSourceId> CreateBook(string title, string author)
      {
          var bookId = EventSourceId.New();
          await eventLog.Append(bookId, new EcBookCreated(title, author));
          return bookId;
      }

// Problematic — expecting immediate consistency
      public async Task<EcBookInventory> CreateBookAndReturn(string title, string author)
      {
          var bookId = EventSourceId.New();
          await eventLog.Append(bookId, new EcBookCreated(title, author));

// The projection may not have run yet — this can return a stale or default instance
          return await readModels.GetInstanceById<EcBookInventory>(bookId);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType
  import java.util.UUID

@EventType
  data class EcBookCreated(val title: String, val author: String)

data class EcBookInventory(val id: String = "", val title: String = "", val author: String = "")

class EcBookService(private val store: IEventStore) {
      // Good — fire and forget: don't wait for the projection before returning
      suspend fun createBook(title: String, author: String): String {
          val bookId = UUID.randomUUID().toString()
          store.eventLog.append(bookId, EcBookCreated(title, author))
          return bookId
      }

// Problematic — expecting immediate consistency
      suspend fun createBookAndReturn(title: String, author: String): EcBookInventory? {
          val bookId = UUID.randomUUID().toString()
          store.eventLog.append(bookId, EcBookCreated(title, author))

// The projection may not have run yet — this can return null or a stale instance
          return store.readModels.getInstanceByKey(EcBookInventory::class, bookId)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.BlockingEventStore;
  import java.util.UUID;

@EventType
  record EcBookCreated(String title, String author) {}

record EcBookInventory(String id, String title, String author) {
      EcBookInventory() {
          this("", "", "");
      }
  }

class EcBookService {
      private final BlockingEventStore store;

EcBookService(IEventStore store) {
          this.store = new BlockingEventStore(store);
      }

// Good — fire and forget: don't wait for the projection before returning
      String createBook(String title, String author) {
          var bookId = UUID.randomUUID().toString();

store.getEventLog().append(bookId, new EcBookCreated(title, author));

return bookId;
      }

// Problematic — expecting immediate consistency
      EcBookInventory createBookAndReturn(String title, String author) {
          var bookId = createBook(title, author);

// The projection may not have run yet — this can return null or a stale instance
          return store.getReadModels().getInstanceByKey(EcBookInventory.class, bookId);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EcBookCreated do
    use Chronicle.Events.EventType, id: "ec-book-created"

defstruct [:title, :author]
  end

defmodule MyApp.ReadModels.EcBookInventory do
    defstruct id: "", title: "", author: ""
  end

defmodule MyApp.EcBookService do
    alias MyApp.Events.EcBookCreated
    alias MyApp.ReadModels.EcBookInventory

# Good — fire and forget: don't wait for the projection before returning
    def create_book(book_id, title, author) do
      Chronicle.append(book_id, %EcBookCreated{title: title, author: author})
      :ok
    end

# Problematic — expecting immediate consistency
    def create_book_and_return(book_id, title, author) do
      create_book(book_id, title, author)

# The projection may not have run yet — this can return nil or a stale instance
      Chronicle.read_model(EcBookInventory, book_id)
    end
  end
  ```

* TypeScript

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

@eventType()
  class EcBookCreated {
      constructor(readonly title: string, readonly author: string) {}
  }

class EcBookInventory {
      id: string = '';
      title: string = '';
      author: string = '';
  }

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

// Good — fire and forget: don't wait for the projection before returning
      async createBook(title: string, author: string): Promise<string> {
          const bookId = Guid.create().toString();
          await this.store.eventLog.append(bookId, new EcBookCreated(title, author));
          return bookId;
      }

// Problematic — expecting immediate consistency
      async createBookAndReturn(title: string, author: string): Promise<EcBookInventory> {
          const bookId = Guid.create().toString();
          await this.store.eventLog.append(bookId, new EcBookCreated(title, author));

// The projection may not have run yet — this can return a stale or default instance
          return this.store.readModels.getInstanceById(EcBookInventory, bookId);
      }
  }
  ```

### 2. Watch Projection Changes

[Section titled “2. Watch Projection Changes”](#2-watch-projection-changes)

Chronicle provides a `.Watch<TReadModel>()` API that allows you to observe projection changes in real-time:

* C#

```csharp
  using System.Reactive.Linq;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.ReadModels;

[EventType]
  public record EcWatchBookCreated(string Title, string Author);

public record EcWatchBookInventory(Guid Id, string Title, string Author);

public class EcWatchBookService(IEventLog eventLog, IReadModels readModels)
  {
      public IObservable<ReadModelChangeset<EcWatchBookInventory>> WatchBookChanges() =>
          readModels.Watch<EcWatchBookInventory>();

public async Task CreateBookAndWatch(string title, string author)
      {
          var bookId = EventSourceId.New();

// Subscribe before appending so the update is observed once the projection catches up
          using var subscription = readModels.Watch<EcWatchBookInventory>()
              .Where(changeset => changeset.ModelKey.Value == bookId.Value)
              .Subscribe(changeset => Console.WriteLine($"Book projection updated: {changeset.ReadModel?.Title}"));

await eventLog.Append(bookId, new EcWatchBookCreated(title, author));
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel
  import kotlinx.coroutines.flow.collect

@ReadModel
  data class WatchAccountInfo(val name: String = "", val balance: Double = 0.0)

suspend fun watchAccountChanges(store: IEventStore) {
      store.readModels.watch(WatchAccountInfo::class).collect { changeset ->
          val label = if (changeset.removed) "removed" else "${changeset.readModel?.name}: ${changeset.readModel?.balance}"
          println("${changeset.modelKey} ${changeset.changeType}: $label")
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;

import io.cratis.chronicle.java.ReadModelsJavaBridge;

@ReadModel
  class WatchAccountInfo {
      private String name = "";
      private double balance = 0.0;

public WatchAccountInfo() {}

public String getName() { return name; }
      public void setName(String name) { this.name = name; }

public double getBalance() { return balance; }
      public void setBalance(double balance) { this.balance = balance; }
  }

class ProjectionsEventualConsistencyWatch {
      void watchAccountChanges(EventStore store) {
          ReadModelsJavaBridge.watch(store.getReadModels(), WatchAccountInfo.class, changeset -> {
              WatchAccountInfo model = changeset.getReadModel();
              String label = changeset.getRemoved() || model == null
                  ? "removed"
                  : model.getName() + ": " + model.getBalance();
              System.out.println(changeset.getModelKey() + " " + changeset.getChangeType() + ": " + label);
          });
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EcWatchBookCreated do
    use Chronicle.Events.EventType, id: "ec-watch-book-created"

defstruct [:title, :author]
  end

defmodule MyApp.ReadModels.EcWatchBookInventory do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.EcWatchBookCreated

defstruct [:id, :title, :author]

from EcWatchBookCreated,
      set: [id: :event_source_id, title: :title, author: :author]
  end

defmodule MyApp.EcWatchBookService do
    alias Chronicle.ReadModels
    alias MyApp.Events.EcWatchBookCreated
    alias MyApp.ReadModels.EcWatchBookInventory

# Subscribes the calling process to live changesets for every instance of
    # EcWatchBookInventory. Chronicle.ReadModels.watch/2 is Elixir's equivalent
    # of the C#/TypeScript clients' Watch<TReadModel>(): instead of an
    # IObservable, the calling process receives
    # {:chronicle_read_model_changed, EcWatchBookInventory, changeset} messages
    # until unwatch/1 is called.
    def watch_book_changes, do: ReadModels.watch(EcWatchBookInventory)

def create_book_and_watch(title, author) do
      book_id = Base.encode16(:crypto.strong_rand_bytes(8), case: :lower)

# Subscribe before appending so the update is observed once the
      # projection catches up.
      {:ok, watcher} = watch_book_changes()

:ok = Chronicle.append(book_id, %EcWatchBookCreated{title: title, author: author})

receive do
        {:chronicle_read_model_changed, EcWatchBookInventory, %{model_key: ^book_id} = changeset} ->
          IO.puts("Book projection updated: #{changeset.read_model && changeset.read_model.title}")
      after
        5_000 -> :timeout
      end

ReadModels.unwatch(watcher)
    end
  end
  ```

* TypeScript

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

@eventType()
  class EcWatchBookCreated {
      constructor(readonly title: string, readonly author: string) {}
  }

class EcWatchBookInventory {
      id: string = '';
      title: string = '';
      author: string = '';
  }

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

watchBookChanges() {
          return this.store.readModels.watch(EcWatchBookInventory);
      }

async createBookAndWatch(title: string, author: string): Promise<void> {
          const bookId = Guid.create().toString();

// Start watching before appending so the update is observed once the projection catches up
          const watchBook = async () => {
              for await (const changeset of this.store.readModels.watch(EcWatchBookInventory)) {
                  if (changeset.key === bookId) {
                      console.log(`Book projection updated: ${changeset.readModel.title}`);
                      break;
                  }
              }
          };
          const watching = watchBook();

await this.store.eventLog.append(bookId, new EcWatchBookCreated(title, author));
          await watching;
      }
  }
  ```

### 3. Monitor Database Changes

[Section titled “3. Monitor Database Changes”](#3-monitor-database-changes)

For applications that need to respond to database changes from external sources, you can:

* **Use database change streams**: Most modern databases (MongoDB, PostgreSQL, SQL Server) provide change stream APIs
* **Implement polling mechanisms**: Periodically check for changes using timestamps or version fields
* **Leverage Chronicle’s watch API**: Use the `.Watch<TReadModel>()` method to observe projection updates regardless of their source

### 4. Use Command-Query Segregation

[Section titled “4. Use Command-Query Segregation”](#4-use-command-query-segregation)

Separate operations that create data from those that read data:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.ReadModels;

[EventType]
  public record EcCqsBookCreated(string Title);

public record EcCqsBook(Guid Id, string Title);

// Commands — fire and forget, never return projected state
  public class EcCqsBookCommandHandler(IEventLog eventLog)
  {
      public Task Create(EventSourceId bookId, string title) =>
          eventLog.Append(bookId, new EcCqsBookCreated(title));
  }

// Queries — always read from projections
  public class EcCqsBookQueryHandler(IReadModels readModels)
  {
      public Task<EcCqsBook> GetBook(EventSourceId bookId) =>
          readModels.GetInstanceById<EcCqsBook>(bookId);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.events.EventType

@EventType
  data class EcCqsBookCreated(val title: String)

data class EcCqsBook(val id: String = "", val title: String = "")

// Commands — fire and forget, never return projected state
  class EcCqsBookCommandHandler(private val store: IEventStore) {
      suspend fun create(bookId: String, title: String) {
          store.eventLog.append(bookId, EcCqsBookCreated(title))
      }
  }

// Queries — always read from projections
  class EcCqsBookQueryHandler(private val store: IEventStore) {
      suspend fun getBook(bookId: String): EcCqsBook? =
          store.readModels.getInstanceByKey(EcCqsBook::class, bookId)
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.java.BlockingEventStore;

@EventType
  record EcCqsBookCreated(String title) {}

record EcCqsBook(String id, String title) {
      EcCqsBook() {
          this("", "");
      }
  }

// Commands — fire and forget, never return projected state
  class EcCqsBookCommandHandler {
      private final BlockingEventStore store;

EcCqsBookCommandHandler(IEventStore store) {
          this.store = new BlockingEventStore(store);
      }

void create(String bookId, String title) {
          store.getEventLog().append(bookId, new EcCqsBookCreated(title));
      }
  }

// Queries — always read from projections
  class EcCqsBookQueryHandler {
      private final BlockingEventStore store;

EcCqsBookQueryHandler(IEventStore store) {
          this.store = new BlockingEventStore(store);
      }

EcCqsBook getBook(String bookId) {
          return store.getReadModels().getInstanceByKey(EcCqsBook.class, bookId);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.EcCqsBookCreated do
    use Chronicle.Events.EventType, id: "ec-cqs-book-created"

defstruct [:title]
  end

defmodule MyApp.ReadModels.EcCqsBook do
    defstruct id: "", title: ""
  end

# Commands — fire and forget, never return projected state
  defmodule MyApp.EcCqsBookCommandHandler do
    alias MyApp.Events.EcCqsBookCreated

def create(book_id, title) do
      Chronicle.append(book_id, %EcCqsBookCreated{title: title})
    end
  end

# Queries — always read from projections
  defmodule MyApp.EcCqsBookQueryHandler do
    alias MyApp.ReadModels.EcCqsBook

def get_book(book_id) do
      Chronicle.read_model(EcCqsBook, book_id)
    end
  end
  ```

* TypeScript

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

@eventType()
  class EcCqsBookCreated {
      constructor(readonly title: string) {}
  }

class EcCqsBook {
      id: string = '';
      title: string = '';
  }

// Commands — fire and forget, never return projected state
  class EcCqsBookCommandHandler {
      constructor(private readonly store: IEventStore) {}

create(bookId: string, title: string): Promise<void> {
          return this.store.eventLog.append(bookId, new EcCqsBookCreated(title)).then(() => undefined);
      }
  }

// Queries — always read from projections
  class EcCqsBookQueryHandler {
      constructor(private readonly store: IEventStore) {}

getBook(bookId: string): Promise<EcCqsBook> {
          return this.store.readModels.getInstanceById(EcCqsBook, bookId);
      }
  }
  ```

## Best Practices

[Section titled “Best Practices”](#best-practices)

### 1. Design for Eventual Consistency

[Section titled “1. Design for Eventual Consistency”](#1-design-for-eventual-consistency)

* Accept that reads may be slightly stale
* Use optimistic UI updates where possible
* Implement retry logic for critical consistency requirements

### 2. Test Eventual Consistency Scenarios

[Section titled “2. Test Eventual Consistency Scenarios”](#2-test-eventual-consistency-scenarios)

* Test your application behavior during projection lag
* Verify retry mechanisms work correctly
* Ensure UI handles missing data gracefully

## Summary

[Section titled “Summary”](#summary)

Eventual consistency in Chronicle projections provides excellent performance and scalability while requiring thoughtful application design. By understanding the asynchronous nature of projection updates and implementing appropriate patterns, you can build robust applications that work naturally with Chronicle’s event-driven architecture.

Remember: eventual consistency is a feature, not a limitation. It enables the high-performance, scalable systems that Chronicle is designed to support.

# Appended event metadata and projections

Projections build read models by mapping events to fields. They observe all events of the types declared in their definition — they do not use `[FilterEventsByTag]`, `[EventSourceType]`, or `[EventStreamType]` to filter incoming events.

## How projections select their input

[Section titled “How projections select their input”](#how-projections-select-their-input)

A projection declares the event types it observes through its event mappings:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record FilteringOrderPlaced(string CustomerId, decimal TotalAmount);

[EventType]
  public record FilteringOrderShipped(DateTimeOffset ShippedAt);

[FromEvent<FilteringOrderPlaced>]
  [FromEvent<FilteringOrderShipped>]
  public record FilteringOrderSummary(
      [Key] string CustomerId,
      decimal TotalAmount,
      DateTimeOffset? ShippedAt);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel
  import java.math.BigDecimal
  import java.time.OffsetDateTime

@EventType
  data class FilteringOrderPlaced(val customerId: String, val totalAmount: BigDecimal)

@EventType
  data class FilteringOrderShipped(val shippedAt: OffsetDateTime)

@ReadModel
  @FromEvent(FilteringOrderPlaced::class)
  @FromEvent(FilteringOrderShipped::class)
  data class FilteringOrderSummary(
      val customerId: String = "",
      val totalAmount: BigDecimal = BigDecimal.ZERO,
      val shippedAt: OffsetDateTime? = null
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;
  import java.math.BigDecimal;
  import java.time.OffsetDateTime;

@EventType
  record FilteringOrderPlaced(String customerId, BigDecimal totalAmount) {}

@EventType
  record FilteringOrderShipped(OffsetDateTime shippedAt) {}

@ReadModel
  @FromEvent(eventType = FilteringOrderPlaced.class)
  @FromEvent(eventType = FilteringOrderShipped.class)
  class FilteringOrderSummary {
      public String customerId = "";
      public BigDecimal totalAmount = BigDecimal.ZERO;
      public OffsetDateTime shippedAt = null;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.FilteringOrderPlaced do
    use Chronicle.Events.EventType, id: "filtering-order-placed"

defstruct [:customer_id, :total_amount]
  end

defmodule MyApp.Events.FilteringOrderShipped do
    use Chronicle.Events.EventType, id: "filtering-order-shipped"

defstruct [:shipped_at]
  end

defmodule MyApp.ReadModels.FilteringOrderSummary do
    use Chronicle.ReadModels.ReadModel

defstruct customer_id: nil, total_amount: nil, shipped_at: nil

from MyApp.Events.FilteringOrderPlaced,
      set: [customer_id: :customer_id, total_amount: :total_amount]

from MyApp.Events.FilteringOrderShipped,
      set: [shipped_at: :shipped_at]
  end
  ```

* TypeScript

```typescript
  import { eventType, fromEvent, readModel } from '@cratis/chronicle';

@eventType()
  class FilteringOrderPlaced {
      customerId = '';
      totalAmount = 0;
  }

@eventType()
  class FilteringOrderShipped {
      shippedAt: Date | null = null;
  }

@readModel()
  @fromEvent(FilteringOrderPlaced)
  @fromEvent(FilteringOrderShipped)
  class FilteringOrderSummary {
      customerId = '';
      totalAmount = 0;
      shippedAt: Date | null = null;
  }
  ```

This projection receives every `OrderPlaced` and `OrderShipped` event regardless of any metadata attached during append. Metadata such as tags or stream type does not affect which events flow into a projection.

## Tagging projections

[Section titled “Tagging projections”](#tagging-projections)

`[Tag]` and `[Tags]` on a projection label the projection definition for organizational purposes. They do not filter incoming events:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Projections;

public record FilteringOrderReport(string CustomerId);

// Labels the projection for discoverability — does not affect which events are received
  [Tag("reporting")]
  public class FilteringOrderReportingProjection : IProjectionFor<FilteringOrderReport>
  {
      public void Define(IProjectionBuilderFor<FilteringOrderReport> builder) =>
          builder.From<FilteringOrderPlaced>(b => b.UsingKey(e => e.CustomerId));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `@Tag` exists, but only labels a reactor or reducer — neither `ProjectionsService.buildDeclarativeDefinition`
  nor `buildModelBoundDefinition` ever reads a `Tag` annotation off a projection class, so tagging a
  projection for discoverability has no effect yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  `@Tag` exists, but only labels a reactor or reducer — neither `ProjectionsService.buildDeclarativeDefinition`
  nor `buildModelBoundDefinition` ever reads a `Tag` annotation off a projection class, so tagging a
  projection for discoverability has no effect yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Client coverage

Labeling a **projection** is currently C#-only. Kotlin and Java have the equivalents for a **reactor or reducer** — `@Tag`, `@FilterEventsByTag`, `@EventSourceType`, and `@EventStreamType` — but nothing on projection registration. Elixir and TypeScript have no tag or filter mechanism on any of the three.

## Combining a projection with metadata-based filtering

[Section titled “Combining a projection with metadata-based filtering”](#combining-a-projection-with-metadata-based-filtering)

When you need a side effect or secondary read model that reacts only to a subset of events based on appended metadata, pair the projection with a reactor or reducer that carries the appropriate filter attributes.

The following example shows an `OrderSummaryProjection` that builds the full read model for all orders, alongside a `PremiumOrderNotifier` reactor that fires only when an order is appended with the `premium` tag:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record FilteringWithReactorOrderPlaced(string CustomerId, decimal TotalAmount);

// --- Append call ---
  // Carries the "premium" tag for orders that qualify
  // eventLog.Append(orderId, new FilteringWithReactorOrderPlaced(customerId, total), tags: ["premium"]);

// --- Projection: receives every OrderPlaced ---
  [FromEvent<FilteringWithReactorOrderPlaced>]
  public record FilteringWithReactorOrderSummary(
      [Key] string CustomerId,
      decimal TotalAmount);

// --- Reactor: receives only premium-tagged OrderPlaced ---
  [FilterEventsByTag("premium")]
  public class FilteringWithReactorPremiumOrderNotifier : IReactor
  {
      public Task Placed(FilteringWithReactorOrderPlaced @event, EventContext context) =>
          Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.FilterEventsByTag
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class FilteringWithReactorOrderPlaced(val customerId: String, val totalAmount: Double)

// --- Append call ---
  // Carries the "premium" tag for orders that qualify
  // eventStore.eventLog.append(orderId, FilteringWithReactorOrderPlaced(customerId, total), AppendOptions(tags = listOf("premium")))

// --- Projection: receives every OrderPlaced ---
  @ReadModel
  @FromEvent(FilteringWithReactorOrderPlaced::class)
  data class FilteringWithReactorOrderSummary(
      val customerId: String = "",
      val totalAmount: Double = 0.0
  )

// --- Reactor: receives only premium-tagged OrderPlaced ---
  @Reactor
  @FilterEventsByTag("premium")
  class FilteringWithReactorPremiumOrderNotifier {
      fun placed(event: FilteringWithReactorOrderPlaced, context: EventContext) {
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.FilterEventsByTag;
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record FilteringWithReactorOrderPlaced(String customerId, double totalAmount) {}

// --- Append call ---
  // Carries the "premium" tag for orders that qualify
  // EventLogJavaBridge.append(eventStore.getEventLog(), orderId,
  //     new FilteringWithReactorOrderPlaced(customerId, total),
  //     new AppendOptionsBuilder().tag("premium").build());

// --- Projection: receives every OrderPlaced ---
  @ReadModel
  @FromEvent(eventType = FilteringWithReactorOrderPlaced.class)
  record FilteringWithReactorOrderSummary(String customerId, double totalAmount) {}

// --- Reactor: receives only premium-tagged OrderPlaced ---
  @Reactor
  @FilterEventsByTag("premium")
  class FilteringWithReactorPremiumOrderNotifier {
      void placed(FilteringWithReactorOrderPlaced event, EventContext context) {
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The same pattern works with a reducer instead of a reactor:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

public record FilteringPremiumOrderTotals(int Count, decimal Total);

[FilterEventsByTag("premium")]
  public class FilteringPremiumOrderTotalsReducer : IReducerFor<FilteringPremiumOrderTotals>
  {
      public FilteringPremiumOrderTotals Placed(FilteringWithReactorOrderPlaced @event, FilteringPremiumOrderTotals? current, EventContext context) =>
          new((current?.Count ?? 0) + 1, (current?.Total ?? 0m) + @event.TotalAmount);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.observation.FilterEventsByTag
  import io.cratis.chronicle.observation.Reducer

data class FilteringPremiumOrderTotals(val count: Int = 0, val total: Double = 0.0)

@Reducer
  @FilterEventsByTag("premium")
  class FilteringPremiumOrderTotalsReducer {
      fun placed(
          event: FilteringWithReactorOrderPlaced,
          current: FilteringPremiumOrderTotals?,
          context: EventContext
      ): FilteringPremiumOrderTotals =
          FilteringPremiumOrderTotals(
              count = (current?.count ?: 0) + 1,
              total = (current?.total ?: 0.0) + event.totalAmount
          )
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.observation.FilterEventsByTag;
  import io.cratis.chronicle.observation.Reducer;

record FilteringPremiumOrderTotals(int count, double total) {}

@Reducer
  @FilterEventsByTag("premium")
  class FilteringPremiumOrderTotalsReducer {
      FilteringPremiumOrderTotals placed(
          FilteringWithReactorOrderPlaced event,
          FilteringPremiumOrderTotals current,
          EventContext context
      ) {
          int count = current == null ? 0 : current.count();
          double total = current == null ? 0.0 : current.total();
          return new FilteringPremiumOrderTotals(count + 1, total + event.totalAmount());
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Use this pattern whenever you need both a projection-based read model (covering all events) and a metadata-filtered view or side effect (covering a subset).

## Appending with metadata

[Section titled “Appending with metadata”](#appending-with-metadata)

The metadata you provide at append time drives the filters on any accompanying reducers or reactors:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

public class FilteringAppendService(IEventLog eventLog)
  {
      public async Task AppendOrders(string customerId)
      {
          // Appends to all observers — no extra metadata
          await eventLog.Append(EventSourceId.New(), new FilteringWithReactorOrderPlaced(customerId, 42m));

// Appends to all observers; additionally dispatched to observers filtering on "premium"
          await eventLog.Append(EventSourceId.New(), new FilteringWithReactorOrderPlaced(customerId, 299m), tags: ["premium"]);

// Appends with stream type; dispatched to observers filtering on "wholesale" stream type
          await eventLog.Append(EventSourceId.New(), new FilteringWithReactorOrderPlaced(customerId, 1500m), eventStreamType: "wholesale");
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.AppendOptions
  import java.util.UUID

class FilteringAppendService(private val eventStore: IEventStore) {
      suspend fun appendOrders(customerId: String) {
          // Appends to all observers — no extra metadata
          eventStore.eventLog.append(
              UUID.randomUUID().toString(),
              FilteringWithReactorOrderPlaced(customerId, 42.0)
          )

// Appends to all observers; additionally dispatched to observers filtering on "premium"
          eventStore.eventLog.append(
              UUID.randomUUID().toString(),
              FilteringWithReactorOrderPlaced(customerId, 299.0),
              AppendOptions(tags = listOf("premium"))
          )

// Appends with stream type; dispatched to observers filtering on "wholesale" stream type
          eventStore.eventLog.append(
              UUID.randomUUID().toString(),
              FilteringWithReactorOrderPlaced(customerId, 1500.0),
              AppendOptions(eventStreamType = "wholesale")
          )
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.AppendOptionsBuilder;
  import io.cratis.chronicle.java.BlockingEventStore;

import java.util.UUID;

class FilteringAppendService {
      private final BlockingEventStore eventStore;

FilteringAppendService(IEventStore eventStore) {
          this.eventStore = new BlockingEventStore(eventStore);
      }

void appendOrders(String customerId) {
          // Appends to all observers — no extra metadata
          eventStore.getEventLog().append(
              UUID.randomUUID().toString(),
              new FilteringWithReactorOrderPlaced(customerId, 42.0));

// Appends to all observers; additionally dispatched to observers filtering on "premium"
          var premiumOptions = new AppendOptionsBuilder().tag("premium").build();
          eventStore.getEventLog().append(
              UUID.randomUUID().toString(),
              new FilteringWithReactorOrderPlaced(customerId, 299.0),
              premiumOptions);

// Appends with stream type; dispatched to observers filtering on "wholesale" stream type
          var wholesaleOptions = new AppendOptionsBuilder().eventStreamType("wholesale").build();
          eventStore.getEventLog().append(
              UUID.randomUUID().toString(),
              new FilteringWithReactorOrderPlaced(customerId, 1500.0),
              wholesaleOptions);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.FilteringMetadataOrderPlaced do
    use Chronicle.Events.EventType, id: "filtering-metadata-order-placed"

defstruct [:customer_id, :total_amount]
  end

defmodule MyApp.FilteringAppendService do
    alias MyApp.Events.FilteringMetadataOrderPlaced

def append_orders(order_id, customer_id) do
      # Appends to all observers — no extra metadata
      Chronicle.append(order_id, %FilteringMetadataOrderPlaced{customer_id: customer_id, total_amount: 42})

# Appends to all observers; additionally dispatched to observers filtering on "premium"
      Chronicle.append(
        order_id,
        %FilteringMetadataOrderPlaced{customer_id: customer_id, total_amount: 299},
        tags: ["premium"]
      )

# Appends with stream type; dispatched to observers filtering on "wholesale" stream type
      Chronicle.append(
        order_id,
        %FilteringMetadataOrderPlaced{customer_id: customer_id, total_amount: 1500},
        event_stream_type: "wholesale"
      )
    end
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  `AppendOptions` only carries `correlationId`, `eventSourceId`, and `concurrencyScope` —
  there is no way to attach tags or a custom event stream type when appending from
  TypeScript. Track the client SDK issue before relying on metadata-filtered
  observers from TypeScript.
  ```

## See also

[Section titled “See also”](#see-also)

* [Filter reactors by appended event metadata](/chronicle/reactors/filtering/)
* [Filter reducers by appended event metadata](/chronicle/reducers/filtering/)
* [Tagging Projections](/chronicle/projections/tagging-projections/)

# Immediate Projections

> **Status**: This documentation is in progress and will be updated soon.

Immediate projections allow you to work with projections that provide strong consistency by processing events synchronously during the event append operation.

## Overview

[Section titled “Overview”](#overview)

While most projections in Chronicle operate with eventual consistency, immediate projections process events synchronously, ensuring that the read model is updated before the event append operation completes.

## When to Use Immediate Projections

[Section titled “When to Use Immediate Projections”](#when-to-use-immediate-projections)

Immediate projections are useful when:

* You need strong consistency guarantees
* The read model must be immediately available after an event
* You’re building critical business flows that require synchronous state updates

## Performance Considerations

[Section titled “Performance Considerations”](#performance-considerations)

Because immediate projections run synchronously, they can impact the performance of your event append operations. Use them judiciously and only when strong consistency is required.

## See Also

[Section titled “See Also”](#see-also)

* [Eventual Consistency](/chronicle/projections/eventual-consistency/) - Learn about eventual consistency in projections
* [Model-Bound Projections](/chronicle/projections/model-bound/) - How to work with model-bound projections

# Model-Bound Projections

Model-bound projections let the read model describe how it is built. Instead of creating a separate `IProjectionFor<T>` class, you put the projection metadata directly on the read model type and Chronicle builds the projection definition from those attributes.

## Overview

[Section titled “Overview”](#overview)

Start with convention-based mapping and add explicit attributes only where the event and read model use different names. That keeps the common case small while still making the exceptions visible.

## Basic Example

[Section titled “Basic Example”](#basic-example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbIndexAccountOpened(string Name, decimal InitialBalance);

[FromEvent<MbIndexAccountOpened>]
  public record MbIndexAccountInfo(
      [Key]
      Guid Id,

string Name,

[SetFrom<MbIndexAccountOpened>(nameof(MbIndexAccountOpened.InitialBalance))]
      decimal Balance);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class IndexAccountOpened(
      val name: String,
      val initialBalance: Double
  )

@ReadModel
  @FromEvent(IndexAccountOpened::class)
  data class IndexAccountInfo(
      val name: String = "",

@SetFrom("initialBalance")
      val balance: Double = 0.0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record IndexAccountOpened(String name, double initialBalance) {}

@ReadModel
  @FromEvent(eventType = IndexAccountOpened.class)
  class IndexAccountInfo {
      public String name = "";

@SetFrom(propertyPath = "initialBalance")
      public double balance = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.IndexAccountOpened do
    use Chronicle.Events.EventType, id: "index-account-opened-v1"

defstruct [:name, :initial_balance]
  end

defmodule MyApp.ReadModels.IndexAccountInfo do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.IndexAccountOpened

defstruct [:id, :name, balance: 0]

from IndexAccountOpened,
      set: [id: :event_source_id, name: :name, balance: :initial_balance]
  end
  ```

* TypeScript

```typescript
  import { eventType, fromEvent, Guid, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbIndexAccountOpened {
      name = '';
      initialBalance = 0;
  }

@readModel()
  @fromEvent(MbIndexAccountOpened)
  class MbIndexAccountInfo {
      id: Guid = Guid.empty;
      name = '';

@setFrom(MbIndexAccountOpened, 'initialBalance')
      balance = 0;
  }
  ```

In this example:

* `[FromEvent<AccountOpened>]` creates or updates an `AccountInfo` instance when an `AccountOpened` event is processed
* `[Key]` marks the read model identifier
* `Name` maps by convention because both the event and the read model use the same property name
* `Balance` uses `[SetFrom<TEvent>]` because the event property is called `InitialBalance`

## Discovery

[Section titled “Discovery”](#discovery)

Types are automatically discovered by the presence of:

* Any class/record level projection mapping attributes (FromEvent, Passive, NotRewindable, etc.)
* Any projection mapping attribute (SetFrom, AddFrom, Join, etc.)

No explicit marker attribute is required on the type itself.

## Key Features

[Section titled “Key Features”](#key-features)

Model-bound projections support all projection engine capabilities:

* **Property Mapping**: SetFrom, AddFrom, SubtractFrom, SetFromContext
* **FromEvery**: Set properties from all events
* **Counters**: Increment, Decrement, Count
* **Relationships**: Join, Children (with unlimited nesting depth)
* **Removal**: RemovedWith, RemovedWithJoin
* **Convention-based**: FromEvent for automatic property matching
* **Configuration**: FromEventSequence, NotRewindable, Passive
* **Fully Recursive**: All attributes work at any nesting level - children, grandchildren, and beyond

See the following pages for detailed information on each feature:

* [Basic Mapping](/chronicle/projections/model-bound/basic-mapping/) - SetFrom, AddFrom, SubtractFrom, SetFromContext
* [Set Constant Value](/chronicle/projections/model-bound/set-value/) - Set a property to a fixed value with SetValue
* [Clearing Values](/chronicle/projections/model-bound/clearing/) - Take a value away with ClearWith or a null SetValue
* [Convention-Based](/chronicle/projections/model-bound/convention-based/) - Automatic property mapping with FromEvent (equivalent to AutoMap)
* [FromEvery](/chronicle/projections/model-bound/from-every/) - Update properties from all events
* [FromAll](/chronicle/projections/model-bound/from-all/) - Subscribe to all event types without filtering
* [Counters](/chronicle/projections/model-bound/counters/) - Increment, Decrement, Count
* [Children](/chronicle/projections/model-bound/children/) - Managing child collections
* [Removal](/chronicle/projections/model-bound/removal/) - Removing read models and children with RemovedWith, RemovedWithJoin
* [Joins](/chronicle/projections/model-bound/joins/) - Joining with other events
* [Event Sequence Source](/chronicle/projections/model-bound/event-sequence-source/) - Reading from specific event sequences
* [Not Rewindable](/chronicle/projections/model-bound/not-rewindable/) - Forward-only projections
* [Passive](/chronicle/projections/model-bound/passive/) - On-demand projections

## When to Use

[Section titled “When to Use”](#when-to-use)

Prefer model-bound projections by default:

* They keep projection metadata next to the read model
* They cover the common Chronicle projection capabilities without a separate class
* They make the happy path concise and consistent across features

Use fluent projections (`IProjectionFor<T>`) as a fallback when the projection cannot be expressed cleanly with model-bound attributes:

* You need projection construction that is more dynamic or procedural
* You intentionally want to separate the read model from the projection definition
* You need specialized builder features that do not map naturally to attributes

## Comparison with Fluent Projections

[Section titled “Comparison with Fluent Projections”](#comparison-with-fluent-projections)

### Explicit Property Mapping

[Section titled “Explicit Property Mapping”](#explicit-property-mapping)

**Fluent Projection:**

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record MbIndexExplicitAccountOpened(string Name, decimal InitialBalance);

public class MbIndexExplicitAccountProjection : IProjectionFor<MbIndexExplicitAccountInfo>
  {
      public void Define(IProjectionBuilderFor<MbIndexExplicitAccountInfo> builder) => builder
          .From<MbIndexExplicitAccountOpened>(_ => _
              .Set(m => m.Name).To(e => e.Name)
              .Set(m => m.Balance).To(e => e.InitialBalance));
  }

public class MbIndexExplicitAccountInfo
  {
      public string Name { get; set; } = string.Empty;
      public decimal Balance { get; set; }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class IndexExplicitAccountOpened(
      val name: String,
      val initialBalance: Double
  )

data class IndexExplicitAccountInfo(
      val name: String = "",
      val balance: Double = 0.0
  )

class IndexExplicitAccountProjection : IProjectionFor<IndexExplicitAccountInfo> {
      override fun define(builder: IProjectionBuilderFor<IndexExplicitAccountInfo>) {
          builder.from(IndexExplicitAccountOpened::class) {
              it.set(IndexExplicitAccountInfo::name).toProperty("name")
              it.set(IndexExplicitAccountInfo::balance).toProperty("initialBalance")
          }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;
  import io.cratis.chronicle.readModels.ReadModel;

@ReadModel
  record IndexExplicitAccountInfo(String name, double balance) {
  }

class IndexExplicitAccountProjection implements IProjectionFor<IndexExplicitAccountInfo> {
      @Override
      public void define(IProjectionBuilderFor<IndexExplicitAccountInfo> builder) {
          builder.from(IndexExplicitAccountOpened.class, from -> {
              from.set("name").toProperty("name");
              from.set("balance").toProperty("initialBalance");
          });
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.IndexExplicitAccountOpened do
    use Chronicle.Events.EventType, id: "index-explicit-account-opened-v1"

defstruct [:name, :initial_balance]
  end

defmodule MyApp.ReadModels.IndexExplicitAccountInfo do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, balance: 0]
  end

defmodule MyApp.Projections.IndexExplicitAccountProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.IndexExplicitAccountInfo

alias MyApp.Events.IndexExplicitAccountOpened

from IndexExplicitAccountOpened,
      set: [name: :name, balance: :initial_balance]
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class MbIndexExplicitAccountOpened {
      name = '';
      initialBalance = 0;
  }

@projection()
  class MbIndexExplicitAccountProjection implements IProjectionFor<MbIndexExplicitAccountInfo> {
      define(builder: IProjectionBuilderFor<MbIndexExplicitAccountInfo>): void {
          builder.from(MbIndexExplicitAccountOpened, _ => _
              .set(m => m.name).to(e => e.name)
              .set(m => m.balance).to(e => e.initialBalance));
      }
  }

class MbIndexExplicitAccountInfo {
      name = '';
      balance = 0;
  }
  ```

**Model-Bound Projection:**

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

public record MbIndexExplicitMbAccountInfo(
      [Key] Guid Id,
      [SetFrom<MbIndexExplicitAccountOpened>(nameof(MbIndexExplicitAccountOpened.Name))] string Name,
      [SetFrom<MbIndexExplicitAccountOpened>(nameof(MbIndexExplicitAccountOpened.InitialBalance))] decimal Balance);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.SetFrom

data class IndexExplicitMbAccountInfo(
      @SetFrom("name", IndexExplicitAccountOpened::class)
      val name: String = "",

@SetFrom("initialBalance", IndexExplicitAccountOpened::class)
      val balance: Double = 0.0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.SetFrom;

@EventType
  record IndexExplicitAccountOpened(String name, double initialBalance) {}

class IndexExplicitMbAccountInfo {
      @SetFrom(propertyPath = "name", eventType = IndexExplicitAccountOpened.class)
      public String name = "";

@SetFrom(propertyPath = "initialBalance", eventType = IndexExplicitAccountOpened.class)
      public double balance = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.IndexExplicitMbAccountInfo do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.IndexExplicitAccountOpened

defstruct [:name, balance: 0]

from IndexExplicitAccountOpened,
      set: [name: :name, balance: :initial_balance]
  end
  ```

* TypeScript

```typescript
  import { Guid, setFrom } from '@cratis/chronicle';

class MbIndexExplicitMbAccountInfo {
      id: Guid = Guid.empty;

@setFrom(MbIndexExplicitAccountOpened, 'name')
      name = '';

@setFrom(MbIndexExplicitAccountOpened, 'initialBalance')
      balance = 0;
  }
  ```

### Automatic Property Mapping

[Section titled “Automatic Property Mapping”](#automatic-property-mapping)

**Fluent Projection with AutoMap:**

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record MbIndexAutoMapAccountOpened(string Name, decimal Balance);

public class MbIndexAutoMapAccountProjection : IProjectionFor<MbIndexAutoMapAccountInfo>
  {
      public void Define(IProjectionBuilderFor<MbIndexAutoMapAccountInfo> builder) => builder
          .AutoMap()
          .From<MbIndexAutoMapAccountOpened>();
  }

public class MbIndexAutoMapAccountInfo
  {
      public string Name { get; set; } = string.Empty;
      public decimal Balance { get; set; }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class IndexAutoMapAccountOpened(
      val name: String,
      val balance: Double
  )

data class IndexAutoMapAccountInfo(
      val name: String = "",
      val balance: Double = 0.0
  )

class IndexAutoMapAccountProjection : IProjectionFor<IndexAutoMapAccountInfo> {
      override fun define(builder: IProjectionBuilderFor<IndexAutoMapAccountInfo>) {
          // No configure block — matching properties are mapped automatically.
          builder.from(IndexAutoMapAccountOpened::class)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record IndexAutoMapAccountOpened(String name, double balance) {}

class IndexAutoMapAccountInfo {
      public String name = "";
      public double balance = 0;
  }

class IndexAutoMapAccountProjection implements IProjectionFor<IndexAutoMapAccountInfo> {
      @Override
      public void define(IProjectionBuilderFor<IndexAutoMapAccountInfo> builder) {
          // No configure block — matching properties are mapped automatically.
          builder.from(IndexAutoMapAccountOpened.class);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.IndexAutoMapAccountOpened do
    use Chronicle.Events.EventType, id: "index-automap-account-opened-v1"

defstruct [:name, :balance]
  end

defmodule MyApp.ReadModels.IndexAutoMapAccountInfo do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, balance: 0]
  end

defmodule MyApp.Projections.IndexAutoMapAccountProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.IndexAutoMapAccountInfo

alias MyApp.Events.IndexAutoMapAccountOpened

# No `set:` list — matching properties are mapped automatically.
    from IndexAutoMapAccountOpened
  end
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class MbIndexAutoMapAccountOpened {
      name = '';
      balance = 0;
  }

@projection()
  class MbIndexAutoMapAccountProjection implements IProjectionFor<MbIndexAutoMapAccountInfo> {
      define(builder: IProjectionBuilderFor<MbIndexAutoMapAccountInfo>): void {
          builder.autoMap().from(MbIndexAutoMapAccountOpened);
      }
  }

class MbIndexAutoMapAccountInfo {
      name = '';
      balance = 0;
  }
  ```

**Model-Bound Projection with FromEvent:**

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[FromEvent<MbIndexAutoMapAccountOpened>]
  public record MbIndexAutoMapMbAccountInfo(
      [Key] Guid Id,
      string Name,        // Automatically mapped from MbIndexAutoMapAccountOpened.Name
      decimal Balance);   // Automatically mapped from MbIndexAutoMapAccountOpened.Balance
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  @FromEvent(IndexAutoMapAccountOpened::class)
  data class IndexAutoMapMbAccountInfo(
      val name: String = "",     // Automatically mapped from IndexAutoMapAccountOpened.name
      val balance: Double = 0.0  // Automatically mapped from IndexAutoMapAccountOpened.balance
  )
  ```

* Java

```java
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;

@ReadModel
  @FromEvent(eventType = IndexAutoMapAccountOpened.class)
  class IndexAutoMapMbAccountInfo {
      public String name = "";    // Automatically mapped from IndexAutoMapAccountOpened.name
      public double balance = 0;  // Automatically mapped from IndexAutoMapAccountOpened.balance
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.IndexAutoMapMbAccountInfo do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.IndexAutoMapAccountOpened

# `name` and `balance` are mapped automatically from the matching event
    # fields — no `set:` list needed.
    defstruct [:name, balance: 0]

from IndexAutoMapAccountOpened
  end
  ```

* TypeScript

```typescript
  import { fromEvent, Guid, readModel } from '@cratis/chronicle';

@readModel()
  @fromEvent(MbIndexAutoMapAccountOpened)
  class MbIndexAutoMapMbAccountInfo {
      id: Guid = Guid.empty;
      name = '';        // Automatically mapped from MbIndexAutoMapAccountOpened.name
      balance = 0;       // Automatically mapped from MbIndexAutoMapAccountOpened.balance
  }
  ```

Both approaches produce the same result. Model-bound projections with `FromEvent` are particularly concise when property names match between events and read models, providing the same automatic mapping benefits as `.AutoMap()` in fluent projections.

## Reading Your Model-Bound Projections

[Section titled “Reading Your Model-Bound Projections”](#reading-your-model-bound-projections)

Once you’ve defined a model-bound projection, you can retrieve and observe the resulting read models using the `IReadModels` API:

# Basic Property Mapping

Model-bound projections map event data to read model properties close to the read model definition. Use them when each event property maps directly to a read model property, when a property should accumulate numeric values, or when event metadata belongs in the read model.

The exact syntax belongs to each client. The projection definition sent to Chronicle still has the same shape: event type, read model key, and property mappings.

## Set A Property From An Event

[Section titled “Set A Property From An Event”](#set-a-property-from-an-event)

Set mappings copy a value from an event into the read model. This is the most common model-bound operation.

* C#

Model-bound set mapping

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record UserRegisteredForContact(string Name, string Email);

public record UserContact(
      [Key] Guid Id,

[SetFrom<UserRegisteredForContact>(nameof(UserRegisteredForContact.Email))]
      string Email,

[SetFrom<UserRegisteredForContact>(nameof(UserRegisteredForContact.Name))]
      string Name);
  ```

* Kotlin

Model-bound set mapping

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class UserRegisteredForContact(
      val name: String,
      val email: String
  )

@ReadModel
  @FromEvent(UserRegisteredForContact::class)
  data class UserContact(
      @SetFrom("email", UserRegisteredForContact::class)
      val email: String = "",

@SetFrom("name", UserRegisteredForContact::class)
      val name: String = ""
  )
  ```

* Java

Model-bound set mapping

@EventType
  record UserRegisteredForContact(String name, String email) {}

@ReadModel
  @FromEvent(eventType = UserRegisteredForContact.class)
  class UserContact {
      @SetFrom(propertyPath = "email", eventType = UserRegisteredForContact.class)
      public String email = "";

@SetFrom(propertyPath = "name", eventType = UserRegisteredForContact.class)
      public String name = "";
  }
  ```

* Elixir

Model-bound set mapping

```elixir
  defmodule MyApp.Events.UserRegisteredForContact do
    use Chronicle.Events.EventType, id: "user-registered-for-contact-v1"

defstruct [:name, :email]
  end

defmodule MyApp.ReadModels.UserContact do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.UserRegisteredForContact

defstruct [:id, :name, :email]

from UserRegisteredForContact,
      set: [
        id: :event_source_id,
        email: :email,
        name: :name
      ]
  end
  ```

* TypeScript

Model-bound set mapping

```typescript
  import { eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class UserRegisteredForContact {
      constructor(readonly name: string, readonly email: string) {}
  }

@readModel()
  @fromEvent(UserRegisteredForContact)
  class UserContact {
      @setFrom(UserRegisteredForContact, 'email')
      email = '';

@setFrom(UserRegisteredForContact, 'name')
      name = '';
  }
  ```

When the event property and read model property have the same name, the client can use its convention-based form instead of repeating the property name.

* C#

Convention-based set mapping

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record UserRegisteredForProfile(string Name, string Email);

[FromEvent<UserRegisteredForProfile>]
  public record UserProfile(
      [Key] Guid Id,
      string Name,
      string Email);
  ```

* Kotlin

Convention-based set mapping

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class UserRegisteredForProfile(
      val name: String,
      val email: String
  )

@ReadModel
  @FromEvent(UserRegisteredForProfile::class)
  data class UserProfile(
      @SetFrom
      val name: String = "",

@SetFrom
      val email: String = ""
  )
  ```

* Java

Convention-based set mapping

@EventType
  record UserRegisteredForProfile(String name, String email) {}

@ReadModel
  @FromEvent(eventType = UserRegisteredForProfile.class)
  class UserProfile {
      @SetFrom
      public String name = "";

@SetFrom
      public String email = "";
  }
  ```

* Elixir

Convention-based set mapping

```elixir
  defmodule MyApp.Events.UserRegisteredForProfile do
    use Chronicle.Events.EventType, id: "user-registered-for-profile"

defstruct [:name, :email]
  end

defmodule MyApp.ReadModels.UserProfile do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.UserRegisteredForProfile

defstruct [:id, :name, :email]

# `name` and `email` are mapped automatically from the matching event
    # fields by convention — only the key/id needs to be told where to come
    # from.
    from UserRegisteredForProfile, set: [id: :event_source_id]
  end
  ```

* TypeScript

Convention-based set mapping

```typescript
  import { eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class UserRegisteredForProfile {
      constructor(readonly name: string, readonly email: string) {}
  }

@readModel()
  @fromEvent(UserRegisteredForProfile)
  class UserProfile {
      @setFrom(UserRegisteredForProfile)
      name = '';

@setFrom(UserRegisteredForProfile)
      email = '';
  }
  ```

Use multiple set mappings when different events can update the same read model property.

* C#

Multiple set mappings

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record AccountOpenedForRename(string AccountName);

[EventType]
  public record AccountRenamedForRename(string NewName);

public record RenameableAccount(
      [Key] Guid Id,

[SetFrom<AccountOpenedForRename>(nameof(AccountOpenedForRename.AccountName))]
      [SetFrom<AccountRenamedForRename>(nameof(AccountRenamedForRename.NewName))]
      string Name);
  ```

* Kotlin

Multiple set mappings

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class AccountOpenedForRename(
      val accountName: String
  )

@EventType
  data class AccountRenamedForRename(
      val newName: String
  )

@ReadModel
  @FromEvent(AccountOpenedForRename::class)
  @FromEvent(AccountRenamedForRename::class)
  data class RenameableAccount(
      @SetFrom("accountName", AccountOpenedForRename::class)
      @SetFrom("newName", AccountRenamedForRename::class)
      val name: String = ""
  )
  ```

* Java

Multiple set mappings

@EventType
  record AccountOpenedForRename(String accountName) {}

@EventType
  record AccountRenamedForRename(String newName) {}

@ReadModel
  @FromEvent(eventType = AccountOpenedForRename.class)
  @FromEvent(eventType = AccountRenamedForRename.class)
  class RenameableAccount {
      @SetFrom(propertyPath = "accountName", eventType = AccountOpenedForRename.class)
      @SetFrom(propertyPath = "newName", eventType = AccountRenamedForRename.class)
      public String name = "";
  }
  ```

* Elixir

Multiple set mappings

```elixir
  defmodule MyApp.Events.AccountOpenedForRename do
    use Chronicle.Events.EventType, id: "account-opened-for-rename-v1"

defstruct [:account_name]
  end

defmodule MyApp.Events.AccountRenamedForRename do
    use Chronicle.Events.EventType, id: "account-renamed-for-rename-v1"

defstruct [:new_name]
  end

defmodule MyApp.ReadModels.RenameableAccount do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{AccountOpenedForRename, AccountRenamedForRename}

defstruct [:id, :name]

from AccountOpenedForRename,
      set: [
        id: :event_source_id,
        name: :account_name
      ]

from AccountRenamedForRename,
      set: [name: :new_name]
  end
  ```

* TypeScript

Multiple set mappings

```typescript
  import { eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

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

@eventType()
  class AccountRenamedForRename {
      constructor(readonly newName: string) {}
  }

@readModel()
  @fromEvent(AccountOpenedForRename)
  @fromEvent(AccountRenamedForRename)
  class RenameableAccount {
      @setFrom(AccountOpenedForRename, 'accountName')
      @setFrom(AccountRenamedForRename, 'newName')
      name = '';
  }
  ```

## Add And Subtract Values

[Section titled “Add And Subtract Values”](#add-and-subtract-values)

Add mappings increase a numeric read model property by a value from an event. They are useful for balances, totals, counters, and other accumulated values.

* C#

Add from an event

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record AccountOpenedForDeposits(decimal InitialBalance);

[EventType]
  public record DepositMadeForBalance(decimal Amount);

public record DepositAccount(
      [Key] Guid Id,

[SetFrom<AccountOpenedForDeposits>(nameof(AccountOpenedForDeposits.InitialBalance))]
      [AddFrom<DepositMadeForBalance>(nameof(DepositMadeForBalance.Amount))]
      decimal Balance);
  ```

* Kotlin

Add from an event

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.AddFrom
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class AccountOpenedForDeposits(val initialBalance: Double)

@EventType
  data class DepositMadeForBalance(val amount: Double)

@ReadModel
  @FromEvent(AccountOpenedForDeposits::class)
  @FromEvent(DepositMadeForBalance::class)
  data class DepositAccount(
      @SetFrom("initialBalance", AccountOpenedForDeposits::class)
      @AddFrom(DepositMadeForBalance::class, "amount")
      val balance: Double = 0.0
  )
  ```

* Java

Add from an event

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.AddFrom;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record AccountOpenedForDeposits(double initialBalance) {}

@EventType
  record DepositMadeForBalance(double amount) {}

@ReadModel
  @FromEvent(eventType = AccountOpenedForDeposits.class)
  @FromEvent(eventType = DepositMadeForBalance.class)
  class DepositAccount {
      @SetFrom(propertyPath = "initialBalance", eventType = AccountOpenedForDeposits.class)
      @AddFrom(eventType = DepositMadeForBalance.class, eventPropertyName = "amount")
      public double balance = 0.0;
  }
  ```

* Elixir

Add from an event

```elixir
  defmodule MyApp.Events.AccountOpenedForDeposits do
    use Chronicle.Events.EventType, id: "account-opened-for-deposits-v1"

defstruct [:initial_balance]
  end

defmodule MyApp.Events.DepositMadeForBalance do
    use Chronicle.Events.EventType, id: "deposit-made-for-balance-v1"

defstruct [:amount]
  end

defmodule MyApp.ReadModels.DepositAccount do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{AccountOpenedForDeposits, DepositMadeForBalance}

defstruct [:id, balance: 0]

from AccountOpenedForDeposits,
      set: [
        id: :event_source_id,
        balance: :initial_balance
      ]

from DepositMadeForBalance,
      add: [balance: :amount]
  end
  ```

* TypeScript

Add from an event

```typescript
  import { addFrom, eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class AccountOpenedForDeposits {
      constructor(readonly initialBalance: number) {}
  }

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

@readModel()
  @fromEvent(AccountOpenedForDeposits)
  @fromEvent(DepositMadeForBalance)
  class DepositAccount {
      @setFrom(AccountOpenedForDeposits, 'initialBalance')
      @addFrom(DepositMadeForBalance, 'amount')
      balance = 0;
  }
  ```

Subtract mappings decrease a numeric read model property by a value from an event. Combine add and subtract mappings when the read model should track a net value.

* C#

Subtract from an event

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record BalanceAccountOpened(decimal InitialBalance);

[EventType]
  public record BalanceDepositMade(decimal Amount);

[EventType]
  public record BalanceWithdrawalMade(decimal Amount);

public record BalanceAccount(
      [Key] Guid Id,

[SetFrom<BalanceAccountOpened>(nameof(BalanceAccountOpened.InitialBalance))]
      [AddFrom<BalanceDepositMade>(nameof(BalanceDepositMade.Amount))]
      [SubtractFrom<BalanceWithdrawalMade>(nameof(BalanceWithdrawalMade.Amount))]
      decimal Balance);
  ```

* Kotlin

Subtract from an event

@EventType
  data class BalanceAccountOpened(val initialBalance: Double)

@EventType
  data class BalanceDepositMade(val amount: Double)

@EventType
  data class BalanceWithdrawalMade(val amount: Double)

@ReadModel
  @FromEvent(BalanceAccountOpened::class)
  @FromEvent(BalanceDepositMade::class)
  @FromEvent(BalanceWithdrawalMade::class)
  data class BalanceAccount(
      @SetFrom("initialBalance", BalanceAccountOpened::class)
      @AddFrom(BalanceDepositMade::class, "amount")
      @SubtractFrom(BalanceWithdrawalMade::class, "amount")
      val balance: Double = 0.0
  )
  ```

* Java

Subtract from an event

@EventType
  record BalanceAccountOpened(double initialBalance) {}

@EventType
  record BalanceDepositMade(double amount) {}

@EventType
  record BalanceWithdrawalMade(double amount) {}

@ReadModel
  @FromEvent(eventType = BalanceAccountOpened.class)
  @FromEvent(eventType = BalanceDepositMade.class)
  @FromEvent(eventType = BalanceWithdrawalMade.class)
  class BalanceAccount {
      @SetFrom(propertyPath = "initialBalance", eventType = BalanceAccountOpened.class)
      @AddFrom(eventType = BalanceDepositMade.class, eventPropertyName = "amount")
      @SubtractFrom(eventType = BalanceWithdrawalMade.class, eventPropertyName = "amount")
      public double balance = 0.0;
  }
  ```

* Elixir

Subtract from an event

```elixir
  defmodule MyApp.Events.BalanceAccountOpened do
    use Chronicle.Events.EventType, id: "balance-account-opened-v1"

defstruct [:initial_balance]
  end

defmodule MyApp.Events.BalanceDepositMade do
    use Chronicle.Events.EventType, id: "balance-deposit-made-v1"

defstruct [:amount]
  end

defmodule MyApp.Events.BalanceWithdrawalMade do
    use Chronicle.Events.EventType, id: "balance-withdrawal-made-v1"

defstruct [:amount]
  end

defmodule MyApp.ReadModels.BalanceAccount do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{BalanceAccountOpened, BalanceDepositMade, BalanceWithdrawalMade}

defstruct [:id, balance: 0]

from BalanceAccountOpened,
      set: [
        id: :event_source_id,
        balance: :initial_balance
      ]

from BalanceDepositMade,
      add: [balance: :amount]

from BalanceWithdrawalMade,
      subtract: [balance: :amount]
  end
  ```

* TypeScript

Subtract from an event

```typescript
  import { addFrom, eventType, fromEvent, readModel, setFrom, subtractFrom } from '@cratis/chronicle';

@eventType()
  class BalanceAccountOpened {
      constructor(readonly initialBalance: number) {}
  }

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

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

@readModel()
  @fromEvent(BalanceAccountOpened)
  @fromEvent(BalanceDepositMade)
  @fromEvent(BalanceWithdrawalMade)
  class BalanceAccount {
      @setFrom(BalanceAccountOpened, 'initialBalance')
      @addFrom(BalanceDepositMade, 'amount')
      @subtractFrom(BalanceWithdrawalMade, 'amount')
      balance = 0;
  }
  ```

The event flow for a balance-style read model is:

1. The opening event sets the initial balance.
2. Deposit events add to the balance.
3. Withdrawal events subtract from the balance.
4. Rename or profile events update descriptive properties without changing the balance.

* C#

Complete balance projection

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record BankAccountOpened(string AccountName, decimal InitialBalance);

[EventType]
  public record BankAccountRenamed(string NewName);

[EventType]
  public record FundsDeposited(decimal Amount);

[EventType]
  public record FundsWithdrawn(decimal Amount);

public record BankAccount(
      [Key] Guid Id,

[SetFrom<BankAccountOpened>(nameof(BankAccountOpened.AccountName))]
      [SetFrom<BankAccountRenamed>(nameof(BankAccountRenamed.NewName))]
      string Name,

[SetFrom<BankAccountOpened>(nameof(BankAccountOpened.InitialBalance))]
      [AddFrom<FundsDeposited>(nameof(FundsDeposited.Amount))]
      [SubtractFrom<FundsWithdrawn>(nameof(FundsWithdrawn.Amount))]
      decimal Balance);
  ```

* Kotlin

Complete balance projection

@EventType
  data class BankAccountOpened(val accountName: String, val initialBalance: Double)

@EventType
  data class BankAccountRenamed(val newName: String)

@EventType
  data class FundsDeposited(val amount: Double)

@EventType
  data class FundsWithdrawn(val amount: Double)

@ReadModel
  @FromEvent(BankAccountOpened::class)
  @FromEvent(BankAccountRenamed::class)
  @FromEvent(FundsDeposited::class)
  @FromEvent(FundsWithdrawn::class)
  data class BankAccount(
      @SetFrom("accountName", BankAccountOpened::class)
      @SetFrom("newName", BankAccountRenamed::class)
      val name: String = "",

@SetFrom("initialBalance", BankAccountOpened::class)
      @AddFrom(FundsDeposited::class, "amount")
      @SubtractFrom(FundsWithdrawn::class, "amount")
      val balance: Double = 0.0
  )
  ```

* Java

Complete balance projection

@EventType
  record BankAccountOpened(String accountName, double initialBalance) {}

@EventType
  record BankAccountRenamed(String newName) {}

@EventType
  record FundsDeposited(double amount) {}

@EventType
  record FundsWithdrawn(double amount) {}

@ReadModel
  @FromEvent(eventType = BankAccountOpened.class)
  @FromEvent(eventType = BankAccountRenamed.class)
  @FromEvent(eventType = FundsDeposited.class)
  @FromEvent(eventType = FundsWithdrawn.class)
  class BankAccount {
      @SetFrom(propertyPath = "accountName", eventType = BankAccountOpened.class)
      @SetFrom(propertyPath = "newName", eventType = BankAccountRenamed.class)
      public String name = "";

@SetFrom(propertyPath = "initialBalance", eventType = BankAccountOpened.class)
      @AddFrom(eventType = FundsDeposited.class, eventPropertyName = "amount")
      @SubtractFrom(eventType = FundsWithdrawn.class, eventPropertyName = "amount")
      public double balance = 0.0;
  }
  ```

* Elixir

Complete balance projection

```elixir
  defmodule MyApp.Events.BankAccountOpened do
    use Chronicle.Events.EventType, id: "bank-account-opened-v1"

defstruct [:account_name, :initial_balance]
  end

defmodule MyApp.Events.BankAccountRenamed do
    use Chronicle.Events.EventType, id: "bank-account-renamed-v1"

defstruct [:new_name]
  end

defmodule MyApp.Events.FundsDeposited do
    use Chronicle.Events.EventType, id: "funds-deposited-v1"

defstruct [:amount]
  end

defmodule MyApp.Events.FundsWithdrawn do
    use Chronicle.Events.EventType, id: "funds-withdrawn-v1"

defstruct [:amount]
  end

defmodule MyApp.ReadModels.BankAccount do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{BankAccountOpened, BankAccountRenamed, FundsDeposited, FundsWithdrawn}

defstruct [:id, :name, balance: 0]

from BankAccountOpened,
      set: [
        id: :event_source_id,
        name: :account_name,
        balance: :initial_balance
      ]

from BankAccountRenamed,
      set: [name: :new_name]

from FundsDeposited,
      add: [balance: :amount]

from FundsWithdrawn,
      subtract: [balance: :amount]
  end
  ```

* TypeScript

Complete balance projection

```typescript
  import { addFrom, eventType, fromEvent, readModel, setFrom, subtractFrom } from '@cratis/chronicle';

@eventType()
  class BankAccountOpened {
      constructor(readonly accountName: string, readonly initialBalance: number) {}
  }

@eventType()
  class BankAccountRenamed {
      constructor(readonly newName: string) {}
  }

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

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

@readModel()
  @fromEvent(BankAccountOpened)
  @fromEvent(BankAccountRenamed)
  @fromEvent(FundsDeposited)
  @fromEvent(FundsWithdrawn)
  class BankAccount {
      @setFrom(BankAccountOpened, 'accountName')
      @setFrom(BankAccountRenamed, 'newName')
      name = '';

@setFrom(BankAccountOpened, 'initialBalance')
      @addFrom(FundsDeposited, 'amount')
      @subtractFrom(FundsWithdrawn, 'amount')
      balance = 0;
  }
  ```

## Set A Property From Event Context

[Section titled “Set A Property From Event Context”](#set-a-property-from-event-context)

Event context contains metadata such as when the event occurred, which event source it belongs to, sequence information, and correlation metadata. Map context fields when the read model needs audit or lifecycle information.

* C#

Map event context

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record OrderPlacedForAudit(string CustomerName);

public record AuditedOrder(
      [Key] Guid Id,

[SetFrom<OrderPlacedForAudit>(nameof(OrderPlacedForAudit.CustomerName))]
      string CustomerName,

[SetFromContext<OrderPlacedForAudit>(nameof(EventContext.Occurred))]
      DateTimeOffset OrderedAt);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.projections.SetFromContext
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class OrderPlacedForAudit(val customerName: String)

@ReadModel
  @FromEvent(OrderPlacedForAudit::class)
  data class AuditedOrder(
      @SetFrom("customerName", OrderPlacedForAudit::class)
      val customerName: String = "",

@SetFromContext(OrderPlacedForAudit::class, contextProperty = "occurred")
      val orderedAt: String = ""
  )
  ```

* Java

@EventType
  record OrderPlacedForAudit(String customerName) {}

@ReadModel
  @FromEvent(eventType = OrderPlacedForAudit.class)
  class AuditedOrder {
      @SetFrom(propertyPath = "customerName", eventType = OrderPlacedForAudit.class)
      public String customerName = "";

@SetFromContext(eventType = OrderPlacedForAudit.class, contextProperty = "occurred")
      public String orderedAt = "";
  }
  ```

* Elixir

Map event context

```elixir
  defmodule MyApp.Events.OrderPlacedForAudit do
    use Chronicle.Events.EventType, id: "order-placed-for-audit-v1"

defstruct [:customer_name]
  end

defmodule MyApp.ReadModels.AuditedOrder do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.OrderPlacedForAudit

defstruct [:id, :customer_name, :ordered_at]

from OrderPlacedForAudit,
      set: [
        id: :event_source_id,
        customer_name: :customer_name,
        ordered_at: :occurred
      ]
  end
  ```

* TypeScript

Map event context

```typescript
  import { eventType, fromEvent, readModel, setFrom, setFromContext } from '@cratis/chronicle';

@eventType()
  class OrderPlacedForAudit {
      constructor(readonly customerName: string) {}
  }

@readModel()
  @fromEvent(OrderPlacedForAudit)
  class AuditedOrder {
      @setFrom(OrderPlacedForAudit, 'customerName')
      customerName = '';

@setFromContext(OrderPlacedForAudit, 'occurred')
      orderedAt = new Date();
  }
  ```

Use an every-event mapping when a read model property should reflect the latest event that affected the projection, rather than one specific event type.

* C#

Specific context vs every event

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record OrderPlacedForLifecycle(string CustomerName);

[EventType]
  public record OrderShippedForLifecycle(string TrackingNumber);

public record OrderLifecycle(
      [Key] Guid Id,

[SetFromContext<OrderPlacedForLifecycle>(nameof(EventContext.Occurred))]
      DateTimeOffset PlacedAt,

[SetFromContext<OrderShippedForLifecycle>(nameof(EventContext.Occurred))]
      DateTimeOffset? ShippedAt,

[FromEvery(contextProperty: nameof(EventContext.Occurred))]
      DateTimeOffset LastModified);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

Specific context vs every event

```elixir
  defmodule MyApp.Events.OrderPlacedForLifecycle do
    use Chronicle.Events.EventType, id: "order-placed-for-lifecycle-v1"

defstruct [:customer_name]
  end

defmodule MyApp.Events.OrderShippedForLifecycle do
    use Chronicle.Events.EventType, id: "order-shipped-for-lifecycle-v1"

defstruct [:tracking_number]
  end

defmodule MyApp.ReadModels.OrderLifecycle do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{OrderPlacedForLifecycle, OrderShippedForLifecycle}

defstruct [:id, :placed_at, :shipped_at, :last_modified]

from OrderPlacedForLifecycle,
      set: [
        id: :event_source_id,
        placed_at: :occurred
      ]

from OrderShippedForLifecycle,
      set: [shipped_at: :occurred]

from_every set: [last_modified: :occurred]
  end
  ```

* TypeScript

Specific context vs every event

```typescript
  import { eventType, fromEvent, fromEvery, readModel, setFromContext } from '@cratis/chronicle';

@eventType()
  class OrderPlacedForLifecycle {
      constructor(readonly customerName: string) {}
  }

@eventType()
  class OrderShippedForLifecycle {
      constructor(readonly trackingNumber: string) {}
  }

@readModel()
  @fromEvent(OrderPlacedForLifecycle)
  @fromEvent(OrderShippedForLifecycle)
  class OrderLifecycle {
      @setFromContext(OrderPlacedForLifecycle, 'occurred')
      placedAt = new Date();

@setFromContext(OrderShippedForLifecycle, 'occurred')
      shippedAt?: Date;

@fromEvery(undefined, 'occurred')
      lastModified = new Date();
  }
  ```

## Choosing The Mapping

[Section titled “Choosing The Mapping”](#choosing-the-mapping)

| Mapping     | Use it when                                                         |
| ----------- | ------------------------------------------------------------------- |
| Set         | A read model property should take a value from a specific event.    |
| Add         | A numeric property should increase when an event occurs.            |
| Subtract    | A numeric property should decrease when an event occurs.            |
| Context     | A read model property should come from event metadata.              |
| Every event | A property should update for any event that affects the projection. |

Prefer the most direct mapping that expresses the read model. If the read model needs branching, state-dependent logic, or calculations that are clearer as code, use a [reducer](/chronicle/reducers/) instead.

# Children Collections

Model-bound projections support child collections through the `ChildrenFrom` attribute, allowing you to build hierarchical read models with parent-child relationships.

## Basic Children

[Section titled “Basic Children”](#basic-children)

The `ChildrenFrom` attribute defines how child entities are added to a collection:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbChildrenLineItemAdded(
      Guid ItemId,
      string ProductName,
      int Quantity,
      decimal Price);

public record MbChildrenOrder(
      [Key]
      Guid OrderId,

[ChildrenFrom<MbChildrenLineItemAdded>(key: nameof(MbChildrenLineItemAdded.ItemId))]
      IEnumerable<MbChildrenLineItem> Items);

public record MbChildrenLineItem(
      [Key] Guid Id,  // Chronicle automatically discovers this as the key
      string ProductName,
      int Quantity,
      decimal Price);
  ```

* Kotlin

@EventType
  data class MbChildrenLineItemAdded(
      val itemId: String,
      val productName: String,
      val quantity: Int,
      val price: Double
  )

@ReadModel
  @FromEvent(MbChildrenLineItemAdded::class)
  data class MbChildrenOrder(
      @ChildrenFrom(MbChildrenLineItemAdded::class, key = "itemId", identifiedBy = "itemId")
      val items: List<MbChildrenLineItem> = emptyList()
  )

data class MbChildrenLineItem(
      val itemId: String = "",  // Chronicle automatically discovers this as the key, via identifiedBy
      val productName: String = "",
      val quantity: Int = 0,
      val price: Double = 0.0
  )
  ```

* Java

import java.util.Collections;
  import java.util.List;

@EventType
  record MbChildrenLineItemAdded(
      String itemId,
      String productName,
      int quantity,
      double price) {}

@ReadModel
  @FromEvent(eventType = MbChildrenLineItemAdded.class)
  class MbChildrenOrder {
      @ChildrenFrom(eventType = MbChildrenLineItemAdded.class, key = "itemId", identifiedBy = "itemId")
      public List<MbChildrenLineItem> items = Collections.emptyList();
  }

class MbChildrenLineItem {
      public String itemId = "";  // Chronicle automatically discovers this as the key, via identifiedBy
      public String productName = "";
      public int quantity = 0;
      public double price = 0.0;
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, readModel } from '@cratis/chronicle';

@eventType()
  class MbChildrenLineItemAdded {
      itemId: Guid = Guid.empty;
      productName = '';
      quantity = 0;
      price = 0;
  }

@readModel()
  class MbChildrenOrder {
      id: Guid = Guid.empty;

@childrenFrom(MbChildrenLineItemAdded, 'itemId')
      items: MbChildrenLineItem[] = [];
  }

// The `id` property is automatically discovered as the child's key
  class MbChildrenLineItem {
      id: Guid = Guid.empty;
      productName = '';
      quantity = 0;
      price = 0;
  }
  ```

In this example, the `[Key]` attribute on the `LineItem.Id` property is automatically discovered by Chronicle, so you don’t need to specify `identifiedBy` explicitly in the `ChildrenFrom` attribute.

### Parameters

[Section titled “Parameters”](#parameters)

* **key** (optional): Property on the event that identifies the child. Defaults to `EventSourceId`

* **identifiedBy** (optional): Property on the child model that identifies it. If not specified, Chronicle will:

1. Look for a property with the `[Key]` attribute
  2. Look for a property named `Id` (case-insensitive)
  3. Fall back to `EventSourceId` if neither is found

* **parentKey** (optional): Property that identifies the parent. Defaults to `EventSourceId`

* Use this when the parent identifier is a property in the event content rather than the EventSourceId
  * Example: `parentKey: nameof(LineItemAdded.OrderId)` when OrderId is in the event

Auto-mapping is enabled by default. To disable it for a child model, apply the `[NoAutoMap]` attribute on the child type.

> **Note**: With automatic key discovery, you typically don’t need to specify `identifiedBy` explicitly. Just mark your child model’s key property with `[Key]` attribute, or name it `Id`, and Chronicle will automatically discover it.

### Auto-Mapping

[Section titled “Auto-Mapping”](#auto-mapping)

By default, `ChildrenFrom` automatically maps properties from the event to the child model when property names match. This behavior is similar to the `FromEvent` attribute:

* C#

```csharp
  [EventType]
  public record MbChildrenAutoMapLineItemAdded(
      Guid ItemId,
      string ProductName,
      int Quantity,
      decimal Price);

public record MbChildrenAutoMapOrder(
      [Key]
      Guid OrderId,

[ChildrenFrom<MbChildrenAutoMapLineItemAdded>(key: nameof(MbChildrenAutoMapLineItemAdded.ItemId))]
      IEnumerable<MbChildrenAutoMapLineItem> Items);

public record MbChildrenAutoMapLineItem(
      [Key] Guid Id,
      string ProductName,  // Automatically mapped from MbChildrenAutoMapLineItemAdded.ProductName
      int Quantity,        // Automatically mapped from MbChildrenAutoMapLineItemAdded.Quantity
      decimal Price);      // Automatically mapped from MbChildrenAutoMapLineItemAdded.Price
  ```

* Kotlin

@EventType
  data class MbChildrenAutoMapLineItemAdded(
      val itemId: String,
      val productName: String,
      val quantity: Int,
      val price: Double
  )

@ReadModel
  @FromEvent(MbChildrenAutoMapLineItemAdded::class)
  data class MbChildrenAutoMapOrder(
      @ChildrenFrom(MbChildrenAutoMapLineItemAdded::class, key = "itemId", identifiedBy = "itemId")
      val items: List<MbChildrenAutoMapLineItem> = emptyList()
  )

data class MbChildrenAutoMapLineItem(
      val itemId: String = "",
      val productName: String = "",  // Automatically mapped from MbChildrenAutoMapLineItemAdded.productName
      val quantity: Int = 0,          // Automatically mapped from MbChildrenAutoMapLineItemAdded.quantity
      val price: Double = 0.0         // Automatically mapped from MbChildrenAutoMapLineItemAdded.price
  )
  ```

* Java

import java.util.Collections;
  import java.util.List;

@EventType
  record MbChildrenAutoMapLineItemAdded(
      String itemId,
      String productName,
      int quantity,
      double price) {}

@ReadModel
  @FromEvent(eventType = MbChildrenAutoMapLineItemAdded.class)
  class MbChildrenAutoMapOrder {
      @ChildrenFrom(eventType = MbChildrenAutoMapLineItemAdded.class, key = "itemId", identifiedBy = "itemId")
      public List<MbChildrenAutoMapLineItem> items = Collections.emptyList();
  }

class MbChildrenAutoMapLineItem {
      public String itemId = "";
      public String productName = "";  // Automatically mapped from MbChildrenAutoMapLineItemAdded.productName
      public int quantity = 0;          // Automatically mapped from MbChildrenAutoMapLineItemAdded.quantity
      public double price = 0.0;        // Automatically mapped from MbChildrenAutoMapLineItemAdded.price
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class MbChildrenAutoMapLineItemAdded {
      itemId: Guid = Guid.empty;
      productName = '';
      quantity = 0;
      price = 0;
  }

@readModel()
  class MbChildrenAutoMapOrder {
      id: Guid = Guid.empty;

@childrenFrom(MbChildrenAutoMapLineItemAdded, 'itemId')
      items: MbChildrenAutoMapLineItem[] = [];
  }

class MbChildrenAutoMapLineItem {
      id: Guid = Guid.empty;
      productName = '';   // Automatically mapped from MbChildrenAutoMapLineItemAdded.productName
      quantity = 0;        // Automatically mapped from MbChildrenAutoMapLineItemAdded.quantity
      price = 0;            // Automatically mapped from MbChildrenAutoMapLineItemAdded.price
  }
  ```

You can disable auto-mapping if you want to control property mapping explicitly:

* C#

```csharp
  using Cratis.Chronicle.Projections;

[EventType]
  public record MbChildrenNoAutoMapLineItemAdded(
      Guid ItemId,
      string ProductName,
      int Quantity,
      decimal Price);

public record MbChildrenNoAutoMapOrder(
      [Key]
      Guid OrderId,

[ChildrenFrom<MbChildrenNoAutoMapLineItemAdded>(key: nameof(MbChildrenNoAutoMapLineItemAdded.ItemId))]
      IEnumerable<MbChildrenNoAutoMapLineItem> Items);

[NoAutoMap]
  public record MbChildrenNoAutoMapLineItem(
      [Key] Guid Id,

// Now you must use SetFrom for each property
      [SetFrom<MbChildrenNoAutoMapLineItemAdded>(nameof(MbChildrenNoAutoMapLineItemAdded.ProductName))]
      string ProductName,

[SetFrom<MbChildrenNoAutoMapLineItemAdded>(nameof(MbChildrenNoAutoMapLineItemAdded.Quantity))]
      int Quantity,

[SetFrom<MbChildrenNoAutoMapLineItemAdded>(nameof(MbChildrenNoAutoMapLineItemAdded.Price))]
      decimal Price);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ChildrenFrom
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.NoAutoMap
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbChildrenNoAutoMapOrderPlaced(val orderId: String)

@EventType
  data class MbChildrenNoAutoMapLineItemAdded(
      val itemId: String,
      val productName: String,
      val quantity: Int,
      val price: Double
  )

@ReadModel
  @FromEvent(MbChildrenNoAutoMapOrderPlaced::class)
  data class MbChildrenNoAutoMapOrder(
      @ChildrenFrom(MbChildrenNoAutoMapLineItemAdded::class, key = "itemId")
      val items: List<MbChildrenNoAutoMapLineItem> = emptyList()
  )

// Now you must use @SetFrom for each property
  @NoAutoMap
  data class MbChildrenNoAutoMapLineItem(
      @SetFrom("productName", MbChildrenNoAutoMapLineItemAdded::class)
      val productName: String = "",

@SetFrom("quantity", MbChildrenNoAutoMapLineItemAdded::class)
      val quantity: Int = 0,

@SetFrom("price", MbChildrenNoAutoMapLineItemAdded::class)
      val price: Double = 0.0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ChildrenFrom;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.NoAutoMap;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;

@EventType
  record MbChildrenNoAutoMapOrderPlaced(String orderId) {}

@EventType
  record MbChildrenNoAutoMapLineItemAdded(
      String itemId,
      String productName,
      int quantity,
      double price
  ) {}

@ReadModel
  @FromEvent(eventType = MbChildrenNoAutoMapOrderPlaced.class)
  record MbChildrenNoAutoMapOrder(
      @ChildrenFrom(eventType = MbChildrenNoAutoMapLineItemAdded.class, key = "itemId")
      List<MbChildrenNoAutoMapLineItem> items
  ) {}

// Now you must use @SetFrom for each property
  @NoAutoMap
  record MbChildrenNoAutoMapLineItem(
      @SetFrom(propertyPath = "productName", eventType = MbChildrenNoAutoMapLineItemAdded.class)
      String productName,

@SetFrom(propertyPath = "quantity", eventType = MbChildrenNoAutoMapLineItemAdded.class)
      int quantity,

@SetFrom(propertyPath = "price", eventType = MbChildrenNoAutoMapLineItemAdded.class)
      double price
  ) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Client coverage

Disabling auto-mapping for a child type is a .NET-only mechanism today — Kotlin, Java, Elixir, and TypeScript model-bound child collections do not expose a `NoAutoMap`-equivalent switch.

## Recursive Attribute Processing

[Section titled “Recursive Attribute Processing”](#recursive-attribute-processing)

All projection attributes work recursively on child types. The child type’s properties are automatically scanned for projection attributes:

* C#

```csharp
  [EventType]
  public record MbChildrenCountersItemAddedToCart(Guid ItemId, string ProductName, decimal Price, int InitialQuantity);

[EventType]
  public record MbChildrenCountersQuantityIncreased(Guid ItemId);

[EventType]
  public record MbChildrenCountersQuantityDecreased(Guid ItemId);

public record MbChildrenCountersShoppingCart(
      [Key]
      Guid CartId,

[ChildrenFrom<MbChildrenCountersItemAddedToCart>(
          key: nameof(MbChildrenCountersItemAddedToCart.ItemId))]
      IEnumerable<MbChildrenCountersCartItem> Items);

// Child type with its own projection attributes
  public record MbChildrenCountersCartItem(
      [Key] Guid Id,

[SetFrom<MbChildrenCountersItemAddedToCart>(nameof(MbChildrenCountersItemAddedToCart.ProductName))]
      string ProductName,

[SetFrom<MbChildrenCountersItemAddedToCart>(nameof(MbChildrenCountersItemAddedToCart.Price))]
      decimal Price,

[SetFrom<MbChildrenCountersItemAddedToCart>(nameof(MbChildrenCountersItemAddedToCart.InitialQuantity))]
      [Increment<MbChildrenCountersQuantityIncreased>]
      [Decrement<MbChildrenCountersQuantityDecreased>]
      int Quantity);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ChildrenFrom
  import io.cratis.chronicle.projections.Decrement
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.Increment
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbChildrenCountersItemAddedToCart(
      val itemId: String,
      val productName: String,
      val price: Double,
      val initialQuantity: Int
  )

@EventType
  data class MbChildrenCountersQuantityIncreased(val itemId: String)

@EventType
  data class MbChildrenCountersQuantityDecreased(val itemId: String)

@ReadModel
  @FromEvent(MbChildrenCountersItemAddedToCart::class)
  data class MbChildrenCountersShoppingCart(
      @ChildrenFrom(MbChildrenCountersItemAddedToCart::class, key = "itemId", identifiedBy = "itemId")
      @ChildrenFrom(MbChildrenCountersQuantityIncreased::class, key = "itemId", identifiedBy = "itemId")
      @ChildrenFrom(MbChildrenCountersQuantityDecreased::class, key = "itemId", identifiedBy = "itemId")
      val items: List<MbChildrenCountersCartItem> = emptyList()
  )

// Child type with its own projection attributes
  data class MbChildrenCountersCartItem(
      val itemId: String = "",

@SetFrom("productName", MbChildrenCountersItemAddedToCart::class)
      val productName: String = "",

@SetFrom("price", MbChildrenCountersItemAddedToCart::class)
      val price: Double = 0.0,

@SetFrom("initialQuantity", MbChildrenCountersItemAddedToCart::class)
      @Increment(MbChildrenCountersQuantityIncreased::class)
      @Decrement(MbChildrenCountersQuantityDecreased::class)
      val quantity: Int = 0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ChildrenFrom;
  import io.cratis.chronicle.projections.Decrement;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.Increment;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.Collections;
  import java.util.List;

@EventType
  record MbChildrenCountersItemAddedToCart(
      String itemId,
      String productName,
      double price,
      int initialQuantity) {}

@EventType
  record MbChildrenCountersQuantityIncreased(String itemId) {}

@EventType
  record MbChildrenCountersQuantityDecreased(String itemId) {}

@ReadModel
  @FromEvent(eventType = MbChildrenCountersItemAddedToCart.class)
  class MbChildrenCountersShoppingCart {
      @ChildrenFrom(eventType = MbChildrenCountersItemAddedToCart.class, key = "itemId", identifiedBy = "itemId")
      @ChildrenFrom(eventType = MbChildrenCountersQuantityIncreased.class, key = "itemId", identifiedBy = "itemId")
      @ChildrenFrom(eventType = MbChildrenCountersQuantityDecreased.class, key = "itemId", identifiedBy = "itemId")
      public List<MbChildrenCountersCartItem> items = Collections.emptyList();
  }

// Child type with its own projection attributes
  class MbChildrenCountersCartItem {
      public String itemId = "";

@SetFrom(propertyPath = "productName", eventType = MbChildrenCountersItemAddedToCart.class)
      public String productName = "";

@SetFrom(propertyPath = "price", eventType = MbChildrenCountersItemAddedToCart.class)
      public double price = 0.0;

@SetFrom(propertyPath = "initialQuantity", eventType = MbChildrenCountersItemAddedToCart.class)
      @Increment(eventType = MbChildrenCountersQuantityIncreased.class)
      @Decrement(eventType = MbChildrenCountersQuantityDecreased.class)
      public int quantity = 0;
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, decrement, eventType, Guid, increment, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbChildrenCountersItemAddedToCart {
      itemId: Guid = Guid.empty;
      productName = '';
      price = 0;
      initialQuantity = 0;
  }

@eventType()
  class MbChildrenCountersQuantityIncreased {
      itemId: Guid = Guid.empty;
  }

@eventType()
  class MbChildrenCountersQuantityDecreased {
      itemId: Guid = Guid.empty;
  }

@readModel()
  class MbChildrenCountersShoppingCart {
      id: Guid = Guid.empty;

@childrenFrom(MbChildrenCountersItemAddedToCart, 'itemId')
      items: MbChildrenCountersCartItem[] = [];
  }

// Child type with its own projection decorators
  class MbChildrenCountersCartItem {
      id: Guid = Guid.empty;

@setFrom(MbChildrenCountersItemAddedToCart, 'productName')
      productName = '';

@setFrom(MbChildrenCountersItemAddedToCart, 'price')
      price = 0;

@setFrom(MbChildrenCountersItemAddedToCart, 'initialQuantity')
      @increment(MbChildrenCountersQuantityIncreased)
      @decrement(MbChildrenCountersQuantityDecreased)
      quantity = 0;
  }
  ```

When an `ItemAddedToCart` event occurs:

1. A new `CartItem` is added to the collection
2. Properties are mapped from the event to the child
3. The child’s own attributes are processed

When a `QuantityIncreased` event occurs later:

* The projection finds the matching child by ID
* Increments the `Quantity` on that specific child

## Class-Level `FromEvent` on Child Types

[Section titled “Class-Level FromEvent on Child Types”](#class-level-fromevent-on-child-types)

Use a class-level `FromEvent` on the child type when later child events should auto-map into the existing child instance. If those events come from the child’s own event source, specify `parentKey` so Chronicle can still resolve the parent document:

* C#

```csharp
  [EventType]
  public record MbChildrenChildFromEventConfigurationAdded(Guid DashboardId, Guid ConfigurationId, string Name);

[EventType]
  public record MbChildrenChildFromEventConfigurationRenamed(Guid DashboardId, Guid Id, string Name);

public record MbChildrenChildFromEventDashboard(
      [Key] Guid Id,
      string Name,

[ChildrenFrom<MbChildrenChildFromEventConfigurationAdded>(
          key: nameof(MbChildrenChildFromEventConfigurationAdded.ConfigurationId),
          parentKey: nameof(MbChildrenChildFromEventConfigurationAdded.DashboardId))]
      IEnumerable<MbChildrenChildFromEventConfiguration> Configurations);

[FromEvent<MbChildrenChildFromEventConfigurationRenamed>(parentKey: nameof(MbChildrenChildFromEventConfigurationRenamed.DashboardId))]
  public record MbChildrenChildFromEventConfiguration(
      [Key] Guid Id,
      string Name);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, fromEvent, Guid, readModel } from '@cratis/chronicle';

@eventType()
  class MbChildrenChildFromEventConfigurationAdded {
      dashboardId: Guid = Guid.empty;
      configurationId: Guid = Guid.empty;
      name = '';
  }

@eventType()
  class MbChildrenChildFromEventConfigurationRenamed {
      dashboardId: Guid = Guid.empty;
      id: Guid = Guid.empty;
      name = '';
  }

@readModel()
  class MbChildrenChildFromEventDashboard {
      id: Guid = Guid.empty;
      name = '';

@childrenFrom(MbChildrenChildFromEventConfigurationAdded, 'configurationId', undefined, 'dashboardId')
      configurations: MbChildrenChildFromEventConfiguration[] = [];
  }

@fromEvent(MbChildrenChildFromEventConfigurationRenamed, { parentKey: 'dashboardId' })
  class MbChildrenChildFromEventConfiguration {
      id: Guid = Guid.empty;
      name = '';
  }
  ```

`ChildrenFrom` handles how the child is first added to the collection. The child type’s own `FromEvent` handles later updates, and `parentKey` is the equivalent of `.UsingParentKey(...)` in a fluent child projection. You do not need `identifiedBy` here because `Configuration.Id` is marked with `[Key]`.

## Removing Children

[Section titled “Removing Children”](#removing-children)

Use `RemovedWith` to remove children from collections. You can apply it either on the collection property or on the child type class:

### Property-Level Removal

[Section titled “Property-Level Removal”](#property-level-removal)

* C#

```csharp
  [EventType]
  public record MbChildrenRemovalPropertyLineItemAdded(Guid ItemId, string Description);

[EventType]
  public record MbChildrenRemovalPropertyLineItemRemoved(Guid ItemId);

public record MbChildrenRemovalPropertyOrder(
      [Key] Guid Id,

[ChildrenFrom<MbChildrenRemovalPropertyLineItemAdded>(key: nameof(MbChildrenRemovalPropertyLineItemAdded.ItemId))]
      [RemovedWith<MbChildrenRemovalPropertyLineItemRemoved>(key: nameof(MbChildrenRemovalPropertyLineItemRemoved.ItemId))]
      IEnumerable<MbChildrenRemovalPropertyOrderLine> Lines);

public record MbChildrenRemovalPropertyOrderLine(
      [Key] Guid Id,
      string Description);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ChildrenFrom
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWith
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbChildrenRemovalPropertyLineItemAdded(val itemId: String, val description: String)

@EventType
  data class MbChildrenRemovalPropertyLineItemRemoved(val itemId: String)

@ReadModel
  @FromEvent(MbChildrenRemovalPropertyLineItemAdded::class)
  data class MbChildrenRemovalPropertyOrder(
      @ChildrenFrom(MbChildrenRemovalPropertyLineItemAdded::class, key = "itemId", identifiedBy = "itemId")
      @RemovedWith(MbChildrenRemovalPropertyLineItemRemoved::class, key = "itemId")
      val lines: List<MbChildrenRemovalPropertyOrderLine> = emptyList()
  )

data class MbChildrenRemovalPropertyOrderLine(
      val itemId: String = "",

@SetFrom("description", MbChildrenRemovalPropertyLineItemAdded::class)
      val description: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ChildrenFrom;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWith;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.Collections;
  import java.util.List;

@EventType
  record MbChildrenRemovalPropertyLineItemAdded(String itemId, String description) {}

@EventType
  record MbChildrenRemovalPropertyLineItemRemoved(String itemId) {}

@ReadModel
  @FromEvent(eventType = MbChildrenRemovalPropertyLineItemAdded.class)
  class MbChildrenRemovalPropertyOrder {
      @ChildrenFrom(eventType = MbChildrenRemovalPropertyLineItemAdded.class, key = "itemId", identifiedBy = "itemId")
      @RemovedWith(eventType = MbChildrenRemovalPropertyLineItemRemoved.class, key = "itemId")
      public List<MbChildrenRemovalPropertyOrderLine> lines = Collections.emptyList();
  }

class MbChildrenRemovalPropertyOrderLine {
      public String itemId = "";

@SetFrom(propertyPath = "description", eventType = MbChildrenRemovalPropertyLineItemAdded.class)
      public String description = "";
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, readModel, removedWith } from '@cratis/chronicle';

@eventType()
  class MbChildrenRemovalPropertyLineItemAdded {
      itemId: Guid = Guid.empty;
      description = '';
  }

@eventType()
  class MbChildrenRemovalPropertyLineItemRemoved {
      itemId: Guid = Guid.empty;
  }

@readModel()
  class MbChildrenRemovalPropertyOrder {
      id: Guid = Guid.empty;

@childrenFrom(MbChildrenRemovalPropertyLineItemAdded, 'itemId')
      @removedWith(MbChildrenRemovalPropertyLineItemRemoved, 'itemId')
      lines: MbChildrenRemovalPropertyOrderLine[] = [];
  }

class MbChildrenRemovalPropertyOrderLine {
      id: Guid = Guid.empty;
      description = '';
  }
  ```

### Class-Level Removal

[Section titled “Class-Level Removal”](#class-level-removal)

Apply `RemovedWith` directly on the child type for better separation of concerns:

* C#

```csharp
  [EventType]
  public record MbChildrenRemovalClassLineItemAdded(Guid ItemId, string Description);

[EventType]
  public record MbChildrenRemovalClassLineItemRemoved(Guid OrderId, Guid ItemId);

public record MbChildrenRemovalClassOrder(
      [Key] Guid Id,

[ChildrenFrom<MbChildrenRemovalClassLineItemAdded>(key: nameof(MbChildrenRemovalClassLineItemAdded.ItemId))]
      IEnumerable<MbChildrenRemovalClassOrderLine> Lines);

[RemovedWith<MbChildrenRemovalClassLineItemRemoved>(
      key: nameof(MbChildrenRemovalClassLineItemRemoved.ItemId),
      parentKey: nameof(MbChildrenRemovalClassLineItemRemoved.OrderId))]
  public record MbChildrenRemovalClassOrderLine(
      [Key] Guid Id,
      string Description);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, readModel, removedWith } from '@cratis/chronicle';

@eventType()
  class MbChildrenRemovalClassLineItemAdded {
      itemId: Guid = Guid.empty;
      description = '';
  }

@eventType()
  class MbChildrenRemovalClassLineItemRemoved {
      orderId: Guid = Guid.empty;
      itemId: Guid = Guid.empty;
  }

@readModel()
  class MbChildrenRemovalClassOrder {
      id: Guid = Guid.empty;

@childrenFrom(MbChildrenRemovalClassLineItemAdded, 'itemId')
      lines: MbChildrenRemovalClassOrderLine[] = [];
  }

@removedWith(MbChildrenRemovalClassLineItemRemoved, 'itemId', 'orderId')
  class MbChildrenRemovalClassOrderLine {
      id: Guid = Guid.empty;
      description = '';
  }
  ```

### RemovedWithJoin

[Section titled “RemovedWithJoin”](#removedwithjoin)

For removal based on events from different streams (joins), use `RemovedWithJoin` on the collection property (it also works at the child type’s class level, the same way `RemovedWith` does above):

* C#

```csharp
  [EventType]
  public record MbChildrenRemovedFeatureActivated(Guid FeatureId, string Name);

[EventType]
  public record MbChildrenRemovedFeatureDeactivated(Guid FeatureId);

public record MbChildrenRemovedSubscription(
      [Key]
      Guid SubscriptionId,

[ChildrenFrom<MbChildrenRemovedFeatureActivated>(key: nameof(MbChildrenRemovedFeatureActivated.FeatureId))]
      [RemovedWithJoin<MbChildrenRemovedFeatureDeactivated>(key: nameof(MbChildrenRemovedFeatureDeactivated.FeatureId))]
      IEnumerable<MbChildrenRemovedFeature> Features);

public record MbChildrenRemovedFeature(
      [Key] Guid FeatureId,
      string Name);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ChildrenFrom
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWithJoin
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbChildrenRemovedFeatureActivated(val featureId: String, val name: String)

@EventType
  data class MbChildrenRemovedFeatureDeactivated(val featureId: String)

@ReadModel
  @FromEvent(MbChildrenRemovedFeatureActivated::class)
  data class MbChildrenRemovedSubscription(
      @ChildrenFrom(MbChildrenRemovedFeatureActivated::class, key = "featureId", identifiedBy = "featureId")
      @RemovedWithJoin(MbChildrenRemovedFeatureDeactivated::class, key = "featureId")
      val features: List<MbChildrenRemovedFeature> = emptyList()
  )

data class MbChildrenRemovedFeature(
      val featureId: String = "",

@SetFrom("name", MbChildrenRemovedFeatureActivated::class)
      val name: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ChildrenFrom;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWithJoin;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.Collections;
  import java.util.List;

@EventType
  record MbChildrenRemovedFeatureActivated(String featureId, String name) {}

@EventType
  record MbChildrenRemovedFeatureDeactivated(String featureId) {}

@ReadModel
  @FromEvent(eventType = MbChildrenRemovedFeatureActivated.class)
  class MbChildrenRemovedSubscription {
      @ChildrenFrom(eventType = MbChildrenRemovedFeatureActivated.class, key = "featureId", identifiedBy = "featureId")
      @RemovedWithJoin(eventType = MbChildrenRemovedFeatureDeactivated.class, key = "featureId")
      public List<MbChildrenRemovedFeature> features = Collections.emptyList();
  }

class MbChildrenRemovedFeature {
      public String featureId = "";

@SetFrom(propertyPath = "name", eventType = MbChildrenRemovedFeatureActivated.class)
      public String name = "";
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, readModel, removedWithJoin } from '@cratis/chronicle';

@eventType()
  class MbChildrenRemovedFeatureActivated {
      featureId: Guid = Guid.empty;
      name = '';
  }

@eventType()
  class MbChildrenRemovedFeatureDeactivated {
      featureId: Guid = Guid.empty;
  }

@readModel()
  class MbChildrenRemovedSubscription {
      id: Guid = Guid.empty;

@childrenFrom(MbChildrenRemovedFeatureActivated, 'featureId', 'featureId')
      @removedWithJoin(MbChildrenRemovedFeatureDeactivated, 'featureId')
      features: MbChildrenRemovedFeature[] = [];
  }

class MbChildrenRemovedFeature {
      featureId: Guid = Guid.empty;
      name = '';
  }
  ```

> **Note**: For comprehensive documentation on removal options including removing root read models, see [Removal](/chronicle/projections/model-bound/removal/).

## Complete Example

[Section titled “Complete Example”](#complete-example)

Here’s a comprehensive example showing children with full attribute support:

* C#

```csharp
  // Events
  [EventType]
  public record MbChildrenFullOrderCreated(string CustomerName);

[EventType]
  public record MbChildrenFullLineItemAdded(
      Guid ItemId,
      string ProductName,
      int InitialQuantity,
      decimal UnitPrice);

[EventType]
  public record MbChildrenFullQuantityAdjusted(Guid ItemId, int NewQuantity);

[EventType]
  public record MbChildrenFullLineItemRemoved(Guid ItemId);

// Read Models
  public record MbChildrenFullOrder(
      [Key]
      Guid Id,

[SetFrom<MbChildrenFullOrderCreated>(nameof(MbChildrenFullOrderCreated.CustomerName))]
      string Customer,

[ChildrenFrom<MbChildrenFullLineItemAdded>(key: nameof(MbChildrenFullLineItemAdded.ItemId))]
      [RemovedWith<MbChildrenFullLineItemRemoved>(key: nameof(MbChildrenFullLineItemRemoved.ItemId))]
      IEnumerable<MbChildrenFullOrderLine> Lines);

public record MbChildrenFullOrderLine(
      [Key] Guid Id,

[SetFrom<MbChildrenFullLineItemAdded>(nameof(MbChildrenFullLineItemAdded.ProductName))]
      string Product,

[SetFrom<MbChildrenFullLineItemAdded>(nameof(MbChildrenFullLineItemAdded.InitialQuantity))]
      [SetFrom<MbChildrenFullQuantityAdjusted>(nameof(MbChildrenFullQuantityAdjusted.NewQuantity))]
      int Quantity,

[SetFrom<MbChildrenFullLineItemAdded>(nameof(MbChildrenFullLineItemAdded.UnitPrice))]
      decimal UnitPrice);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ChildrenFrom
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWith
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

// Events
  @EventType
  data class MbChildrenFullOrderCreated(val customerName: String)

@EventType
  data class MbChildrenFullLineItemAdded(
      val itemId: String,
      val productName: String,
      val initialQuantity: Int,
      val unitPrice: Double
  )

@EventType
  data class MbChildrenFullQuantityAdjusted(val itemId: String, val newQuantity: Int)

@EventType
  data class MbChildrenFullLineItemRemoved(val itemId: String)

// Read Models
  @ReadModel
  @FromEvent(MbChildrenFullOrderCreated::class)
  data class MbChildrenFullOrder(
      @SetFrom("customerName", MbChildrenFullOrderCreated::class)
      val customer: String = "",

@ChildrenFrom(MbChildrenFullLineItemAdded::class, key = "itemId", identifiedBy = "itemId")
      @ChildrenFrom(MbChildrenFullQuantityAdjusted::class, key = "itemId", identifiedBy = "itemId")
      @RemovedWith(MbChildrenFullLineItemRemoved::class, key = "itemId")
      val lines: List<MbChildrenFullOrderLine> = emptyList()
  )

data class MbChildrenFullOrderLine(
      val itemId: String = "",

@SetFrom("productName", MbChildrenFullLineItemAdded::class)
      val product: String = "",

@SetFrom("initialQuantity", MbChildrenFullLineItemAdded::class)
      @SetFrom("newQuantity", MbChildrenFullQuantityAdjusted::class)
      val quantity: Int = 0,

@SetFrom("unitPrice", MbChildrenFullLineItemAdded::class)
      val unitPrice: Double = 0.0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ChildrenFrom;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWith;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.Collections;
  import java.util.List;

// Events
  @EventType
  record MbChildrenFullOrderCreated(String customerName) {}

@EventType
  record MbChildrenFullLineItemAdded(
      String itemId,
      String productName,
      int initialQuantity,
      double unitPrice) {}

@EventType
  record MbChildrenFullQuantityAdjusted(String itemId, int newQuantity) {}

@EventType
  record MbChildrenFullLineItemRemoved(String itemId) {}

// Read Models
  @ReadModel
  @FromEvent(eventType = MbChildrenFullOrderCreated.class)
  class MbChildrenFullOrder {
      @SetFrom(propertyPath = "customerName", eventType = MbChildrenFullOrderCreated.class)
      public String customer = "";

@ChildrenFrom(eventType = MbChildrenFullLineItemAdded.class, key = "itemId", identifiedBy = "itemId")
      @ChildrenFrom(eventType = MbChildrenFullQuantityAdjusted.class, key = "itemId", identifiedBy = "itemId")
      @RemovedWith(eventType = MbChildrenFullLineItemRemoved.class, key = "itemId")
      public List<MbChildrenFullOrderLine> lines = Collections.emptyList();
  }

class MbChildrenFullOrderLine {
      public String itemId = "";

@SetFrom(propertyPath = "productName", eventType = MbChildrenFullLineItemAdded.class)
      public String product = "";

@SetFrom(propertyPath = "initialQuantity", eventType = MbChildrenFullLineItemAdded.class)
      @SetFrom(propertyPath = "newQuantity", eventType = MbChildrenFullQuantityAdjusted.class)
      public int quantity = 0;

@SetFrom(propertyPath = "unitPrice", eventType = MbChildrenFullLineItemAdded.class)
      public double unitPrice = 0.0;
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, readModel, removedWith, setFrom } from '@cratis/chronicle';

// Events
  @eventType()
  class MbChildrenFullOrderCreated {
      customerName = '';
  }

@eventType()
  class MbChildrenFullLineItemAdded {
      itemId: Guid = Guid.empty;
      productName = '';
      initialQuantity = 0;
      unitPrice = 0;
  }

@eventType()
  class MbChildrenFullQuantityAdjusted {
      itemId: Guid = Guid.empty;
      newQuantity = 0;
  }

@eventType()
  class MbChildrenFullLineItemRemoved {
      itemId: Guid = Guid.empty;
  }

// Read Models
  @readModel()
  class MbChildrenFullOrder {
      id: Guid = Guid.empty;

@setFrom(MbChildrenFullOrderCreated, 'customerName')
      customer = '';

@childrenFrom(MbChildrenFullLineItemAdded, 'itemId')
      @removedWith(MbChildrenFullLineItemRemoved, 'itemId')
      lines: MbChildrenFullOrderLine[] = [];
  }

class MbChildrenFullOrderLine {
      id: Guid = Guid.empty;

@setFrom(MbChildrenFullLineItemAdded, 'productName')
      product = '';

@setFrom(MbChildrenFullLineItemAdded, 'initialQuantity')
      @setFrom(MbChildrenFullQuantityAdjusted, 'newQuantity')
      quantity = 0;

@setFrom(MbChildrenFullLineItemAdded, 'unitPrice')
      unitPrice = 0;
  }
  ```

## Event Processing Flow

[Section titled “Event Processing Flow”](#event-processing-flow)

1. **OrderCreated** - Creates the parent Order with customer name
2. **LineItemAdded** - Adds a new OrderLine to the collection with initial values
3. **QuantityAdjusted** - Updates the Quantity on the matching OrderLine
4. **LineItemRemoved** - Removes the OrderLine from the collection

## Nested Children

[Section titled “Nested Children”](#nested-children)

Children can have their own children, creating deeply nested structures. All projection attributes (joins, removal, counters, context mapping, etc.) work recursively at every level:

* C#

```csharp
  // Events
  [EventType]
  public record MbChildrenNestedOrganizationCreated(string Name);

[EventType]
  public record MbChildrenNestedDepartmentAdded(Guid Id, string Name);

[EventType]
  public record MbChildrenNestedDepartmentRenamed(Guid Id, string NewName);

[EventType]
  public record MbChildrenNestedTeamAdded(Guid Id, Guid DepartmentId, string Name);

[EventType]
  public record MbChildrenNestedTeamRenamed(Guid Id, string NewName);

// Read Models - all attributes work at every nesting level
  public record MbChildrenNestedOrganization(
      [Key] Guid Id,

[SetFrom<MbChildrenNestedOrganizationCreated>]
      string Name,

[ChildrenFrom<MbChildrenNestedDepartmentAdded>(
          key: nameof(MbChildrenNestedDepartmentAdded.Id),
          identifiedBy: nameof(MbChildrenNestedDepartment.Id))]
      IEnumerable<MbChildrenNestedDepartment> Departments);

public record MbChildrenNestedDepartment(
      [Key] Guid Id,

[SetFrom<MbChildrenNestedDepartmentAdded>]
      [Join<MbChildrenNestedDepartmentRenamed>(eventPropertyName: nameof(MbChildrenNestedDepartmentRenamed.NewName))] // Joins work on children
      string Name,

[ChildrenFrom<MbChildrenNestedTeamAdded>(
          key: nameof(MbChildrenNestedTeamAdded.Id),
          identifiedBy: nameof(MbChildrenNestedTeam.Id),
          parentKey: nameof(MbChildrenNestedTeamAdded.DepartmentId))] // Nested children
      IEnumerable<MbChildrenNestedTeam> Teams);

public record MbChildrenNestedTeam(
      [Key] Guid Id,

[SetFrom<MbChildrenNestedTeamAdded>]
      [Join<MbChildrenNestedTeamRenamed>(eventPropertyName: nameof(MbChildrenNestedTeamRenamed.NewName))] // Joins work on nested children too
      string Name);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, join, readModel, setFrom } from '@cratis/chronicle';

// Events
  @eventType()
  class MbChildrenNestedOrganizationCreated {
      name = '';
  }

@eventType()
  class MbChildrenNestedDepartmentAdded {
      id: Guid = Guid.empty;
      name = '';
  }

@eventType()
  class MbChildrenNestedDepartmentRenamed {
      id: Guid = Guid.empty;
      newName = '';
  }

@eventType()
  class MbChildrenNestedTeamAdded {
      id: Guid = Guid.empty;
      departmentId: Guid = Guid.empty;
      name = '';
  }

@eventType()
  class MbChildrenNestedTeamRenamed {
      id: Guid = Guid.empty;
      newName = '';
  }

// Read Models - all decorators work at every nesting level
  @readModel()
  class MbChildrenNestedOrganization {
      id: Guid = Guid.empty;

@setFrom(MbChildrenNestedOrganizationCreated, 'name')
      name = '';

@childrenFrom(MbChildrenNestedDepartmentAdded, 'id', 'id')
      departments: MbChildrenNestedDepartment[] = [];
  }

class MbChildrenNestedDepartment {
      id: Guid = Guid.empty;

@setFrom(MbChildrenNestedDepartmentAdded, 'name')
      @join(MbChildrenNestedDepartmentRenamed, undefined, 'newName') // Joins work on children
      name = '';

@childrenFrom(MbChildrenNestedTeamAdded, 'id', 'id', 'departmentId') // Nested children
      teams: MbChildrenNestedTeam[] = [];
  }

class MbChildrenNestedTeam {
      id: Guid = Guid.empty;

@setFrom(MbChildrenNestedTeamAdded, 'name')
      @join(MbChildrenNestedTeamRenamed, undefined, 'newName') // Joins work on nested children too
      name = '';
  }
  ```

### What Works Recursively

[Section titled “What Works Recursively”](#what-works-recursively)

All projection attributes are fully supported on child types at any nesting level:

| Attribute                           | Works on Children |
| ----------------------------------- | ----------------- |
| `SetFrom`                           | ✓                 |
| `AddFrom` / `SubtractFrom`          | ✓                 |
| `SetFromContext`                    | ✓                 |
| `Join`                              | ✓                 |
| `Increment` / `Decrement` / `Count` | ✓                 |
| `ChildrenFrom` (nested children)    | ✓                 |
| `RemovedWith` / `RemovedWithJoin`   | ✓                 |
| `FromEvent` (class-level)           | ✓                 |

This means you can build arbitrarily deep hierarchies with full projection capabilities at every level.

## Collections with no children

[Section titled “Collections with no children”](#collections-with-no-children)

Until a child event arrives the collection has no children, and Chronicle stores that as an absent field rather than as `[]` — so that a parallel replay cannot erase a child a sibling event already added. How you declare the property decides what you read back: non-nullable materializes as an empty collection, nullable stays `null` so you can tell “no children yet” apart from “an empty list”. See [Empty child collections](/chronicle/read-models/empty-child-collections/).

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Always use Key attribute** on child types to identify them uniquely
2. **Leverage recursive attributes** to build complex child projections without duplication
3. **Use RemovedWith** to maintain collection integrity when items are removed
4. **Consider performance** with large collections - deeply nested structures can impact query performance

# Clearing Values

Some facts take a value away without putting anything in its place. A note is deleted, a due date is dropped, a shift is released. `ClearWith` declares which event does that, and the projection writes the member back to `null` every time the event is observed — including when the read model is rebuilt from the beginning of the stream.

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

Put `ClearWith` on the member the event empties. The member has to be nullable.

* C#

Clear a scalar member

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbClearingProjectNoted(string Note);

[EventType]
  public record MbClearingProjectNoteCleared;

[FromEvent<MbClearingProjectNoted>]
  public record MbClearingProjectNotes(
      [Key]
      Guid Id,

[ClearWith<MbClearingProjectNoteCleared>]
      string? Note);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.projections.SetValue
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbClearingProjectNoted(val note: String)

@EventType
  data class MbClearingProjectNoteCleared(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(MbClearingProjectNoted::class)
  data class MbClearingProjectNotes(
      @SetFrom("note", MbClearingProjectNoted::class)
      @SetValue(MbClearingProjectNoteCleared::class, clear = true)
      val note: String? = null
  )
  ```

* Java

@EventType
  record MbClearingProjectNoted(String note) {}

@EventType
  record MbClearingProjectNoteCleared() {}

@ReadModel
  @FromEvent(eventType = MbClearingProjectNoted.class)
  class MbClearingProjectNotes {
      @SetFrom(propertyPath = "note", eventType = MbClearingProjectNoted.class)
      @SetValue(eventType = MbClearingProjectNoteCleared.class, clear = true)
      public String note;
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

Clear a scalar member

```typescript
  import { clearWith, eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbClearingProjectNoted {
      note = '';
  }

@eventType()
  class MbClearingProjectNoteCleared {}

@readModel()
  @fromEvent(MbClearingProjectNoted)
  class MbClearingProjectNotes {
      @setFrom(MbClearingProjectNoted, 'note')
      @clearWith(MbClearingProjectNoteCleared)
      note: string | undefined = undefined;
  }
  ```

When `MbClearingProjectNoted` occurs, `Note` is populated. When `MbClearingProjectNoteCleared` occurs, `Note` goes back to `null`. A later `MbClearingProjectNoted` sets it again — a clear is a value written at a point in the stream, not a terminal state for the member.

## The Same Clear as a Null SetValue

[Section titled “The Same Clear as a Null SetValue”](#the-same-clear-as-a-null-setvalue)

`SetValue` with `null` means exactly the same thing and builds exactly the same mapping. Reach for whichever reads better where you are: `ClearWith` states the intent, and `SetValue(null)` sits naturally alongside the other `SetValue` declarations on a member.

* C#

The same clear, written as a null SetValue

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbClearingInvoiceIssued(string Reference);

[EventType]
  public record MbClearingInvoiceVoided;

[FromEvent<MbClearingInvoiceIssued>]
  public record MbClearingInvoice(
      [Key]
      Guid Id,

[SetValue<MbClearingInvoiceVoided>(null)]
      string? Reference);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetValue
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbClearingInvoiceIssued(val reference: String)

@EventType
  data class MbClearingInvoiceVoided(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(MbClearingInvoiceIssued::class)
  data class MbClearingInvoice(
      // AutoMap sets this from the matching "reference" property on MbClearingInvoiceIssued; SetValue
      // with clear = true is the only way to null it back out - @ClearWith targets CLASS only, so it
      // cannot sit on a plain scalar property the way the .NET client's [ClearWith<T>] can.
      @SetValue(MbClearingInvoiceVoided::class, clear = true)
      val reference: String? = null
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.SetValue;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record MbClearingInvoiceIssued(String reference) {}

@EventType
  record MbClearingInvoiceVoided() {}

@ReadModel
  @FromEvent(eventType = MbClearingInvoiceIssued.class)
  class MbClearingInvoice {
      // AutoMap sets this from the matching "reference" field on MbClearingInvoiceIssued; SetValue with
      // clear = true is the only way to null it back out - @ClearWith targets CLASS only, so it cannot
      // sit on a plain scalar field the way the .NET client's [ClearWith<T>] can.
      @SetValue(eventType = MbClearingInvoiceVoided.class, clear = true)
      public String reference;
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, fromEvent, Guid, readModel, setValue } from '@cratis/chronicle';

@eventType()
  class MbClearingInvoiceIssued {
      constructor(readonly reference: string) {}
  }

@eventType()
  class MbClearingInvoiceVoided {
  }

@readModel()
  @fromEvent(MbClearingInvoiceIssued)
  class MbClearingInvoice {
      id: Guid = Guid.empty;

@setValue(MbClearingInvoiceVoided, null)
      reference: string | null = null;
  }
  ```

## The Member Must Be Able to Hold No Value

[Section titled “The Member Must Be Able to Hold No Value”](#the-member-must-be-able-to-hold-no-value)

Clearing means returning a member to *no value*, so the member must have that state. A non-nullable member does not, and the declaration is refused: [CHR0048](/chronicle/code-analysis/chr0048/) reports it as a build warning — scheduled to become an error in the next major — and building the projection throws `CannotClearNonNullableMember`, so an unaddressed warning fails at startup.

* C#

A member has to be able to hold no value

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbClearingShiftPlanned(string Assignee, int Hours);

[EventType]
  public record MbClearingShiftReleased;

[FromEvent<MbClearingShiftPlanned>]
  public record MbClearingShift(
      [Key]
      Guid Id,

// Nullable, so "nobody is assigned" is a state the member can actually hold.
      [ClearWith<MbClearingShiftReleased>]
      string? Assignee,

// Nullable value type, for the same reason: 0 hours is a number of hours, not the absence of one.
      [ClearWith<MbClearingShiftReleased>]
      int? Hours);
  ```

* Kotlin

@EventType
  data class MbClearingShiftPlanned(val assignee: String, val hours: Int)

@EventType
  data class MbClearingShiftReleased(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(MbClearingShiftPlanned::class)
  data class MbClearingShift(
      // Nullable, so "nobody is assigned" is a state the property can actually hold.
      @SetValue(MbClearingShiftReleased::class, clear = true)
      val assignee: String? = null,

// Nullable numeric type, for the same reason: 0 hours is a number of hours, not the absence of one.
      @SetValue(MbClearingShiftReleased::class, clear = true)
      val hours: Int? = null
  )
  ```

* Java

@EventType
  record MbClearingShiftPlanned(String assignee, int hours) {}

@EventType
  record MbClearingShiftReleased() {}

@ReadModel
  @FromEvent(eventType = MbClearingShiftPlanned.class)
  class MbClearingShift {
      // A reference type, so "nobody is assigned" is a state the field can actually hold.
      @SetValue(eventType = MbClearingShiftReleased.class, clear = true)
      public String assignee;

// Boxed Integer, for the same reason: 0 hours is a number of hours, not the absence of one. A
      // primitive int could never be cleared this way.
      @SetValue(eventType = MbClearingShiftReleased.class, clear = true)
      public Integer hours;
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

A member has to be able to hold no value

```typescript
  import { clearWith, eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbClearingShiftPlanned {
      constructor(
          readonly assignee: string,
          readonly hours: number
      ) {}
  }

@eventType()
  class MbClearingShiftReleased {}

@readModel()
  @fromEvent(MbClearingShiftPlanned)
  class MbClearingShift {
      // Optional, so "nobody is assigned" is a state the member can actually hold.
      @setFrom(MbClearingShiftPlanned, 'assignee')
      @clearWith(MbClearingShiftReleased)
      assignee: string | undefined = undefined;

// Optional for the same reason: 0 hours is a number of hours, not the absence of one.
      @setFrom(MbClearingShiftPlanned, 'hours')
      @clearWith(MbClearingShiftReleased)
      hours: number | undefined = undefined;
  }
  ```

This is deliberate rather than a limitation to work around. The only value a projection could write to a non-nullable member is its type default — `""`, `0`, `DateTimeOffset.MinValue` — and that is a *different fact*. A reader seeing an empty string cannot tell whether the value was cleared or was genuinely empty, which is exactly the ambiguity a type-specific “not set” sentinel introduces.

So decide which you mean:

| You mean                                             | Declare                                              |
| ---------------------------------------------------- | ---------------------------------------------------- |
| No value at all                                      | A nullable member plus `[ClearWith<TEvent>]`         |
| A specific value that happens to be the type default | `[SetValue<TEvent>("")]`, `[SetValue<TEvent>(0)]`, … |

## Child Items

[Section titled “Child Items”](#child-items)

A member of a child collection item clears the same way. The clearing event has to reach the child, so it needs its own `ChildrenFrom` with the key that identifies which item to clear.

* C#

Clear a member of a child item

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbClearingTaskListStarted(string Name);

[EventType]
  public record MbClearingTaskAdded(Guid ListId, Guid TaskId, string Title, string Due);

[EventType]
  public record MbClearingTaskDeferred(Guid ListId, Guid TaskId);

public record MbClearingTask(
      [Key] Guid Id,
      [SetFrom<MbClearingTaskAdded>(nameof(MbClearingTaskAdded.Title))] string Title,
      [SetFrom<MbClearingTaskAdded>(nameof(MbClearingTaskAdded.Due))]
      [ClearWith<MbClearingTaskDeferred>]
      string? Due);

[FromEvent<MbClearingTaskListStarted>]
  public record MbClearingTaskList(
      [Key] Guid Id,

[ChildrenFrom<MbClearingTaskAdded>(key: nameof(MbClearingTaskAdded.TaskId), parentKey: nameof(MbClearingTaskAdded.ListId), identifiedBy: nameof(MbClearingTask.Id))]
      [ChildrenFrom<MbClearingTaskDeferred>(key: nameof(MbClearingTaskDeferred.TaskId), parentKey: nameof(MbClearingTaskDeferred.ListId), identifiedBy: nameof(MbClearingTask.Id))]
      IReadOnlyList<MbClearingTask> Tasks);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ChildrenFrom
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.projections.SetValue
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbClearingTaskListStarted(val name: String)

@EventType
  data class MbClearingTaskAdded(val listId: String, val taskId: String, val title: String, val due: String)

@EventType
  data class MbClearingTaskDeferred(val listId: String, val taskId: String)

data class MbClearingTask(
      val taskId: String = "",

@SetFrom("title", MbClearingTaskAdded::class)
      val title: String = "",

@SetFrom("due", MbClearingTaskAdded::class)
      @SetValue(MbClearingTaskDeferred::class, clear = true)
      val due: String? = null
  )

@ReadModel
  @FromEvent(MbClearingTaskListStarted::class)
  data class MbClearingTaskList(
      @ChildrenFrom(MbClearingTaskAdded::class, key = "taskId", identifiedBy = "taskId", parentKey = "listId")
      @ChildrenFrom(MbClearingTaskDeferred::class, key = "taskId", identifiedBy = "taskId", parentKey = "listId")
      val tasks: List<MbClearingTask> = emptyList()
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ChildrenFrom;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.projections.SetValue;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.Collections;
  import java.util.List;

@EventType
  record MbClearingTaskListStarted(String name) {}

@EventType
  record MbClearingTaskAdded(String listId, String taskId, String title, String due) {}

@EventType
  record MbClearingTaskDeferred(String listId, String taskId) {}

class MbClearingTask {
      public String taskId = "";

@SetFrom(propertyPath = "title", eventType = MbClearingTaskAdded.class)
      public String title = "";

@SetFrom(propertyPath = "due", eventType = MbClearingTaskAdded.class)
      @SetValue(eventType = MbClearingTaskDeferred.class, clear = true)
      public String due;
  }

@ReadModel
  @FromEvent(eventType = MbClearingTaskListStarted.class)
  class MbClearingTaskList {
      @ChildrenFrom(eventType = MbClearingTaskAdded.class, key = "taskId", identifiedBy = "taskId", parentKey = "listId")
      @ChildrenFrom(eventType = MbClearingTaskDeferred.class, key = "taskId", identifiedBy = "taskId", parentKey = "listId")
      public List<MbClearingTask> tasks = Collections.emptyList();
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Nested Objects

[Section titled “Nested Objects”](#nested-objects)

`ClearWith` on a member *of* a nested type clears that member and leaves the object standing. `ClearWith` on the `Nested` member itself — or on the nested type, as described in [Nested Objects](/chronicle/projections/model-bound/nested/) — clears the whole object back to `null`.

* C#

Clear one member of a nested object, or the whole object

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbClearingContractSigned(string Title, string NoticeGiven);

[EventType]
  public record MbClearingNoticeWithdrawn;

[EventType]
  public record MbClearingContractEnded;

[FromEvent<MbClearingContractSigned>]
  public record MbClearingContract(
      string Title,

// Clears this member of the nested object; the object itself stays.
      [ClearWith<MbClearingNoticeWithdrawn>]
      string? NoticeGiven);

public record MbClearingEmployee(
      [Key] Guid Id,

// Clears the whole nested object back to null.
      [Nested]
      [ClearWith<MbClearingContractEnded>]
      MbClearingContract? Contract);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ClearWith
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.Nested
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.projections.SetValue
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbClearingContractSigned(val title: String, val noticeGiven: String)

@EventType
  data class MbClearingNoticeWithdrawn(val placeholder: Boolean = true)

@EventType
  data class MbClearingContractEnded(val placeholder: Boolean = true)

@EventType
  data class MbClearingEmployeeHired(val placeholder: Boolean = true)

@FromEvent(MbClearingContractSigned::class)
  @ClearWith(MbClearingContractEnded::class)
  data class MbClearingContract(
      @SetFrom("title", MbClearingContractSigned::class)
      val title: String = "",

// Clears this property of the nested object; the object itself stays.
      @SetFrom("noticeGiven", MbClearingContractSigned::class)
      @SetValue(MbClearingNoticeWithdrawn::class, clear = true)
      val noticeGiven: String? = null
  )

// The Kotlin client only recognizes a model-bound read model once it carries at least one root
  // @FromEvent - MbClearingContract's own @FromEvent above still drives the nested object.
  @ReadModel
  @FromEvent(MbClearingEmployeeHired::class)
  data class MbClearingEmployee(
      @Nested
      val contract: MbClearingContract? = null
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ClearWith;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.Nested;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.projections.SetValue;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record MbClearingContractSigned(String title, String noticeGiven) {}

@EventType
  record MbClearingNoticeWithdrawn() {}

@EventType
  record MbClearingContractEnded() {}

@EventType
  record MbClearingEmployeeHired() {}

@FromEvent(eventType = MbClearingContractSigned.class)
  @ClearWith(eventType = MbClearingContractEnded.class)
  class MbClearingContract {
      @SetFrom(propertyPath = "title", eventType = MbClearingContractSigned.class)
      public String title = "";

// Clears this field of the nested object; the object itself stays.
      @SetFrom(propertyPath = "noticeGiven", eventType = MbClearingContractSigned.class)
      @SetValue(eventType = MbClearingNoticeWithdrawn.class, clear = true)
      public String noticeGiven;
  }

// The Kotlin client only recognizes a model-bound read model once it carries at least one root
  // @FromEvent - MbClearingContract's own @FromEvent above still drives the nested object.
  @ReadModel
  @FromEvent(eventType = MbClearingEmployeeHired.class)
  class MbClearingEmployee {
      @Nested
      public MbClearingContract contract;
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Declaring it on the holding member rather than on the nested type is worth preferring when the nested type is shared: the owner names the event that ends *its* relationship, and the nested type does not have to know about it.

## When This Is the Wrong Fit

[Section titled “When This Is the Wrong Fit”](#when-this-is-the-wrong-fit)

* **Emptying a collection.** `ClearWith` on a `ChildrenFrom` collection is not a supported way to remove every item; use `RemovedWith` on the child, described in [Removal](/chronicle/projections/model-bound/removal/).
* **Deleting the whole read model.** That is a root-level `RemovedWith`, not a clear.
* **A member that should fall back to a default rather than to nothing.** Say so with `SetValue`; the declaration then records the value on purpose instead of leaving a reader to guess.

## In the Projection Declaration Language

[Section titled “In the Projection Declaration Language”](#in-the-projection-declaration-language)

`clear` is a statement of its own, alongside `increment`, `decrement` and `count`. It names the member the event empties:

```text
projection Notes => MbClearingProjectNotes
    from MbClearingProjectNoted
        note = note
    from MbClearingProjectNoteCleared
        clear note
```

A clear reaches a member of a nested object through its path — the same clear the `MbClearingContract` example above declares with an attribute:

```text
projection Employees => MbClearingEmployee
    from MbClearingNoticeWithdrawn
        clear contract.noticeGiven
```

`note = null` compiles to exactly the same mapping and keeps working, so existing declarations need no change. Prefer `clear` in new ones: assigning a value and taking one away are different acts, and spelling both with `=` hides that. It is also what you get back — when Chronicle generates a declaration from a projection definition it writes `clear`, whichever spelling the declaration was authored in. See the [Projection Declaration Language](/chronicle/projections/projection-declaration-language/) for the rest of the syntax.

## In the Fluent API

[Section titled “In the Fluent API”](#in-the-fluent-api)

`Clear` is an operation in its own right, alongside `Set`, `Increment` and `Count`. It is available everywhere `Set` is — at the root, inside `Children`, and inside `Nested`.

* C#

Clear at the root, on a child and inside a nested object

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections;

[EventType]
  public record MbClearingFluentNoted(string Note);

[EventType]
  public record MbClearingFluentNoteCleared;

[EventType]
  public record MbClearingFluentSummarised(string Headline, string Note);

[EventType]
  public record MbClearingFluentSummaryNoteCleared;

[EventType]
  public record MbClearingFluentTaskAdded(Guid TaskId, string Title, string Note);

[EventType]
  public record MbClearingFluentTaskNoteCleared(Guid TaskId);

public record MbClearingFluentSummary(string Headline, string? Note);

public record MbClearingFluentTask([Key] Guid Id, string Title, string? Note);

public record MbClearingFluentProject(
      [Key] Guid Id,
      string? Note,
      MbClearingFluentSummary? Summary,
      IReadOnlyList<MbClearingFluentTask> Tasks);

public class MbClearingFluentProjectProjection : IProjectionFor<MbClearingFluentProject>
  {
      public void Define(IProjectionBuilderFor<MbClearingFluentProject> builder) => builder
          .From<MbClearingFluentNoted>(_ => _
              .Set(m => m.Note).To(e => e.Note))
          .From<MbClearingFluentNoteCleared>(_ => _
              .Clear(m => m.Note))
          .Nested(m => m.Summary, summary => summary
              .From<MbClearingFluentSummarised>(_ => _
                  .Set(m => m.Headline).To(e => e.Headline)
                  .Set(m => m.Note).To(e => e.Note))
              .From<MbClearingFluentSummaryNoteCleared>(_ => _
                  .Clear(m => m.Note)))
          .Children(m => m.Tasks, tasks => tasks
              .IdentifiedBy(_ => _.Id)
              .From<MbClearingFluentTaskAdded>(_ => _
                  .UsingKey(e => e.TaskId)
                  .Set(m => m.Title).To(e => e.Title)
                  .Set(m => m.Note).To(e => e.Note))
              .From<MbClearingFluentTaskNoteCleared>(_ => _
                  .UsingKey(e => e.TaskId)
                  .Clear(m => m.Note)));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `IFromBuilderFor`/`IChildFromBuilderFor` have no `clear()` method at all — the only clearing operation
  in the fluent builder is `INestedBuilderFor.clearWith()`, which clears an entire nested object, not a
  single member of the root, a nested object, or a child item.
  ```

* Java

```text
  Java does not support this workflow yet.
  `IFromBuilderFor`/`IChildFromBuilderFor` have no `clear()` method at all — the only clearing operation
  in the fluent builder is `INestedBuilderFor.clearWith()`, which clears an entire nested object, not a
  single member of the root, a nested object, or a child item.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`Set(...).ToValue(null)` means the same thing and keeps working, so existing projections need no change. Prefer `Clear` in new code: it names the operation instead of spelling it as a set of a value that happens to be absent, and it reads the same as the `ClearWith` attribute.

`Clear` carries a default implementation that throws `ClearNotSupported`, so adding it to the builder interface does not break an implementation written outside Chronicle: such a builder keeps compiling and only fails if it is actually asked to clear something, which it could not have been before the member existed.

The nullable rule is enforced here too. C# cannot express “a nullable-annotated reference type” as a generic constraint — a non-nullable argument converts to a nullable parameter without complaint — so `Clear` cannot refuse a non-nullable member at its signature. Building the projection refuses it instead, throwing `CannotClearNonNullableMember`, and [CHR0048](/chronicle/code-analysis/chr0048/) reports both `Clear` and `ToValue(null)` at build time.

# Constant Keys

A constant key fixes the read model key to a literal string value, so all events of a given type accumulate into a **single** read model instance regardless of which event source they come from.

## FromEvent with ConstantKey

[Section titled “FromEvent with ConstantKey”](#fromevent-with-constantkey)

Use `ConstantKey` on the `[FromEvent]` attribute at the class level to route all matching events to a fixed read model instance:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbConstantKeyOrderPlaced(string CustomerName, DateTimeOffset PlacedAt);

[FromEvent<MbConstantKeyOrderPlaced>(ConstantKey = "global")]
  public record MbConstantKeyGlobalOrderSummary(
      [SetFrom<MbConstantKeyOrderPlaced>(nameof(MbConstantKeyOrderPlaced.CustomerName))]
      string LastCustomer,

[SetFrom<MbConstantKeyOrderPlaced>(nameof(MbConstantKeyOrderPlaced.PlacedAt))]
      DateTimeOffset LastOrderDate);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstantKeyOrderPlaced do
    use Chronicle.Events.EventType, id: "constant-key-order-placed-v1"

defstruct [:customer_name, :placed_at]
  end

defmodule MyApp.ReadModels.GlobalOrderSummary do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.ConstantKeyOrderPlaced

defstruct [:last_customer, :last_order_date]

# A literal `$value(...)` key expression routes every event to the same
    # instance, regardless of which event source produced it.
    from ConstantKeyOrderPlaced,
      key: "$value(global)",
      set: [last_customer: :customer_name, last_order_date: :placed_at]
  end
  ```

* TypeScript

```typescript
  import { eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbConstantKeyOrderPlaced {
      customerName = '';
      placedAt = new Date();
  }

@readModel()
  @fromEvent(MbConstantKeyOrderPlaced, { constantKey: 'global' })
  class MbConstantKeyGlobalOrderSummary {
      @setFrom(MbConstantKeyOrderPlaced, 'customerName')
      lastCustomer = '';

@setFrom(MbConstantKeyOrderPlaced, 'placedAt')
      lastOrderDate = new Date();
  }
  ```

Every `OrderPlaced` event from every event source updates the same `GlobalOrderSummary` instance.

## Count, Increment, and Decrement with ConstantKey

[Section titled “Count, Increment, and Decrement with ConstantKey”](#count-increment-and-decrement-with-constantkey)

`Count`, `Increment`, and `Decrement` attributes also support `ConstantKey` for collecting events from all event sources into a single document:

* C#

```csharp
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbConstantKeyOrderPlacedForMetrics;

[EventType]
  public record MbConstantKeyUserLoggedIn;

[EventType]
  public record MbConstantKeyUserLoggedOut;

[EventType]
  public record MbConstantKeyErrorOccurred;

public record MbConstantKeySystemMetrics(
      [Count<MbConstantKeyOrderPlacedForMetrics>(ConstantKey = "metrics")]
      int TotalOrders,

[Increment<MbConstantKeyUserLoggedIn>(ConstantKey = "metrics")]
      [Decrement<MbConstantKeyUserLoggedOut>(ConstantKey = "metrics")]
      int ActiveSessions,

[Count<MbConstantKeyErrorOccurred>(ConstantKey = "metrics")]
      int TotalErrors);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.Count
  import io.cratis.chronicle.projections.Decrement
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.Increment
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  class MbConstantKeyOrderPlacedForMetrics

@EventType
  class MbConstantKeyUserLoggedIn

@EventType
  class MbConstantKeyUserLoggedOut

@EventType
  class MbConstantKeyErrorOccurred

@ReadModel
  @FromEvent(MbConstantKeyOrderPlacedForMetrics::class)
  @FromEvent(MbConstantKeyUserLoggedIn::class)
  @FromEvent(MbConstantKeyUserLoggedOut::class)
  @FromEvent(MbConstantKeyErrorOccurred::class)
  data class MbConstantKeySystemMetrics(
      @Count(MbConstantKeyOrderPlacedForMetrics::class, constantKey = "metrics")
      val totalOrders: Int = 0,

@Increment(MbConstantKeyUserLoggedIn::class, constantKey = "metrics")
      @Decrement(MbConstantKeyUserLoggedOut::class, constantKey = "metrics")
      val activeSessions: Int = 0,

@Count(MbConstantKeyErrorOccurred::class, constantKey = "metrics")
      val totalErrors: Int = 0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.Count;
  import io.cratis.chronicle.projections.Decrement;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.Increment;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  class MbConstantKeyOrderPlacedForMetrics {}

@EventType
  class MbConstantKeyUserLoggedIn {}

@EventType
  class MbConstantKeyUserLoggedOut {}

@EventType
  class MbConstantKeyErrorOccurred {}

@ReadModel
  @FromEvent(eventType = MbConstantKeyOrderPlacedForMetrics.class)
  @FromEvent(eventType = MbConstantKeyUserLoggedIn.class)
  @FromEvent(eventType = MbConstantKeyUserLoggedOut.class)
  @FromEvent(eventType = MbConstantKeyErrorOccurred.class)
  class MbConstantKeySystemMetrics {
      @Count(eventType = MbConstantKeyOrderPlacedForMetrics.class, constantKey = "metrics")
      public int totalOrders = 0;

@Increment(eventType = MbConstantKeyUserLoggedIn.class, constantKey = "metrics")
      @Decrement(eventType = MbConstantKeyUserLoggedOut.class, constantKey = "metrics")
      public int activeSessions = 0;

@Count(eventType = MbConstantKeyErrorOccurred.class, constantKey = "metrics")
      public int totalErrors = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstantKeyOrderPlacedForMetrics do
    use Chronicle.Events.EventType, id: "constant-key-order-placed-for-metrics-v1"

defstruct []
  end

defmodule MyApp.Events.ConstantKeyUserLoggedIn do
    use Chronicle.Events.EventType, id: "constant-key-user-logged-in-v1"

defstruct []
  end

defmodule MyApp.Events.ConstantKeyUserLoggedOut do
    use Chronicle.Events.EventType, id: "constant-key-user-logged-out-v1"

defstruct []
  end

defmodule MyApp.Events.ConstantKeyErrorOccurred do
    use Chronicle.Events.EventType, id: "constant-key-error-occurred-v1"

defstruct []
  end

defmodule MyApp.ReadModels.SystemMetrics do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{
      ConstantKeyOrderPlacedForMetrics,
      ConstantKeyUserLoggedIn,
      ConstantKeyUserLoggedOut,
      ConstantKeyErrorOccurred
    }

defstruct total_orders: 0, active_sessions: 0, total_errors: 0

from ConstantKeyOrderPlacedForMetrics,
      key: "$value(metrics)",
      count: :total_orders

from ConstantKeyUserLoggedIn,
      key: "$value(metrics)",
      add: [active_sessions: 1]

from ConstantKeyUserLoggedOut,
      key: "$value(metrics)",
      subtract: [active_sessions: 1]

from ConstantKeyErrorOccurred,
      key: "$value(metrics)",
      count: :total_errors
  end
  ```

* TypeScript

```typescript
  import { count, decrement, eventType, increment, readModel } from '@cratis/chronicle';

@eventType()
  class MbConstantKeyOrderPlacedForMetrics {
  }

@eventType()
  class MbConstantKeyUserLoggedIn {
  }

@eventType()
  class MbConstantKeyUserLoggedOut {
  }

@eventType()
  class MbConstantKeyErrorOccurred {
  }

@readModel()
  class MbConstantKeySystemMetrics {
      @count(MbConstantKeyOrderPlacedForMetrics, 'metrics')
      totalOrders = 0;

@increment(MbConstantKeyUserLoggedIn, 'metrics')
      @decrement(MbConstantKeyUserLoggedOut, 'metrics')
      activeSessions = 0;

@count(MbConstantKeyErrorOccurred, 'metrics')
      totalErrors = 0;
  }
  ```

All three properties converge on the `"metrics"` document regardless of which user or order they come from.

## Mixing event source key and constant key

[Section titled “Mixing event source key and constant key”](#mixing-event-source-key-and-constant-key)

You can mix regular key-based events with constant key events on the same read model:

* C#

```csharp
  [EventType]
  public record MbConstantKeyUserRegistered;

[EventType]
  public record MbConstantKeyOrderPlacedGlobal;

[FromEvent<MbConstantKeyUserRegistered>]
  public record MbConstantKeyUserDashboard(
      [Key]
      Guid UserId,

string Name,

// A per-instance property alongside a constant-keyed one on the same read model
      [Count<MbConstantKeyOrderPlacedGlobal>(ConstantKey = "global-stats")]
      int PlatformTotalOrders);
  ```

* Kotlin

@EventType
  class MbConstantKeyUserRegistered

@EventType
  class MbConstantKeyOrderPlacedGlobal

@ReadModel
  @FromEvent(MbConstantKeyUserRegistered::class)
  @FromEvent(MbConstantKeyOrderPlacedGlobal::class)
  data class MbConstantKeyUserDashboard(
      val name: String = "",

// A per-instance property alongside a constant-keyed one on the same read model
      @Count(MbConstantKeyOrderPlacedGlobal::class, constantKey = "global-stats")
      val platformTotalOrders: Int = 0
  )
  ```

* Java

@EventType
  class MbConstantKeyUserRegistered {}

@EventType
  class MbConstantKeyOrderPlacedGlobal {}

@ReadModel
  @FromEvent(eventType = MbConstantKeyUserRegistered.class)
  @FromEvent(eventType = MbConstantKeyOrderPlacedGlobal.class)
  class MbConstantKeyUserDashboard {
      public String name = "";

// A per-instance property alongside a constant-keyed one on the same read model
      @Count(eventType = MbConstantKeyOrderPlacedGlobal.class, constantKey = "global-stats")
      public int platformTotalOrders = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstantKeyUserRegistered do
    use Chronicle.Events.EventType, id: "constant-key-user-registered-v1"

defstruct [:name]
  end

defmodule MyApp.Events.ConstantKeyOrderPlacedGlobal do
    use Chronicle.Events.EventType, id: "constant-key-order-placed-global-v1"

defstruct []
  end

defmodule MyApp.ReadModels.UserDashboard do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{ConstantKeyUserRegistered, ConstantKeyOrderPlacedGlobal}

defstruct [:user_id, :name, platform_total_orders: 0]

# Regular, per-instance key — one document per user.
    from ConstantKeyUserRegistered,
      set: [user_id: :event_source_id, name: :name]

# A literal key routes this counter to a single shared document instead —
    # "global-stats", not the per-user instance above.
    from ConstantKeyOrderPlacedGlobal,
      key: "$value(global-stats)",
      count: :platform_total_orders
  end
  ```

* TypeScript

```typescript
  import { count, eventType, fromEvent, Guid, readModel } from '@cratis/chronicle';

@eventType()
  class MbConstantKeyUserRegistered {
  }

@eventType()
  class MbConstantKeyOrderPlacedGlobal {
  }

@readModel()
  @fromEvent(MbConstantKeyUserRegistered)
  class MbConstantKeyUserDashboard {
      id: Guid = Guid.empty;
      name = '';

// A per-instance property alongside a constant-keyed one on the same read model
      @count(MbConstantKeyOrderPlacedGlobal, 'global-stats')
      platformTotalOrders = 0;
  }
  ```

> **Note:** When `ConstantKey` is set on a counter attribute, it affects *which read model instance the counter updates* — not the key of the read model the attribute belongs to. In this example, `PlatformTotalOrders` would update the document with key `"global-stats"`, not the `UserDashboard` instance.

## Complete example

[Section titled “Complete example”](#complete-example)

* C#

```csharp
  // Events
  [EventType]
  public record MbConstantKeyProductPurchased(string ProductId, decimal Amount);

[EventType]
  public record MbConstantKeyProductReturned(string ProductId, decimal Amount);

[EventType]
  public record MbConstantKeyPageViewed(string PageUrl);

// Global read model
  public record MbConstantKeyStoreMetrics(
      [Count<MbConstantKeyProductPurchased>(ConstantKey = "store")]
      int TotalPurchases,

[Count<MbConstantKeyProductReturned>(ConstantKey = "store")]
      int TotalReturns,

[Increment<MbConstantKeyProductPurchased>(ConstantKey = "store")]
      [Decrement<MbConstantKeyProductReturned>(ConstantKey = "store")]
      int NetTransactions,

[Count<MbConstantKeyPageViewed>(ConstantKey = "store")]
      int TotalPageViews);
  ```

* Kotlin

// Events
  @EventType
  data class MbConstantKeyProductPurchased(val productId: String, val amount: Double)

@EventType
  data class MbConstantKeyProductReturned(val productId: String, val amount: Double)

@EventType
  data class MbConstantKeyPageViewed(val pageUrl: String)

// Global read model
  @ReadModel
  @FromEvent(MbConstantKeyProductPurchased::class)
  @FromEvent(MbConstantKeyProductReturned::class)
  @FromEvent(MbConstantKeyPageViewed::class)
  data class MbConstantKeyStoreMetrics(
      @Count(MbConstantKeyProductPurchased::class, constantKey = "store")
      val totalPurchases: Int = 0,

@Count(MbConstantKeyProductReturned::class, constantKey = "store")
      val totalReturns: Int = 0,

@Increment(MbConstantKeyProductPurchased::class, constantKey = "store")
      @Decrement(MbConstantKeyProductReturned::class, constantKey = "store")
      val netTransactions: Int = 0,

@Count(MbConstantKeyPageViewed::class, constantKey = "store")
      val totalPageViews: Int = 0
  )
  ```

* Java

// Events
  @EventType
  record MbConstantKeyProductPurchased(String productId, double amount) {}

@EventType
  record MbConstantKeyProductReturned(String productId, double amount) {}

@EventType
  record MbConstantKeyPageViewed(String pageUrl) {}

// Global read model
  @ReadModel
  @FromEvent(eventType = MbConstantKeyProductPurchased.class)
  @FromEvent(eventType = MbConstantKeyProductReturned.class)
  @FromEvent(eventType = MbConstantKeyPageViewed.class)
  class MbConstantKeyStoreMetrics {
      @Count(eventType = MbConstantKeyProductPurchased.class, constantKey = "store")
      public int totalPurchases = 0;

@Count(eventType = MbConstantKeyProductReturned.class, constantKey = "store")
      public int totalReturns = 0;

@Increment(eventType = MbConstantKeyProductPurchased.class, constantKey = "store")
      @Decrement(eventType = MbConstantKeyProductReturned.class, constantKey = "store")
      public int netTransactions = 0;

@Count(eventType = MbConstantKeyPageViewed.class, constantKey = "store")
      public int totalPageViews = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ConstantKeyProductPurchased do
    use Chronicle.Events.EventType, id: "constant-key-product-purchased-v1"

defstruct [:product_id, :amount]
  end

defmodule MyApp.Events.ConstantKeyProductReturned do
    use Chronicle.Events.EventType, id: "constant-key-product-returned-v1"

defstruct [:product_id, :amount]
  end

defmodule MyApp.Events.ConstantKeyPageViewed do
    use Chronicle.Events.EventType, id: "constant-key-page-viewed-v1"

defstruct [:page_url]
  end

defmodule MyApp.ReadModels.StoreMetrics do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{
      ConstantKeyProductPurchased,
      ConstantKeyProductReturned,
      ConstantKeyPageViewed
    }

defstruct total_purchases: 0, total_returns: 0, net_transactions: 0, total_page_views: 0

from ConstantKeyProductPurchased,
      key: "$value(store)",
      count: :total_purchases,
      add: [net_transactions: 1]

from ConstantKeyProductReturned,
      key: "$value(store)",
      count: :total_returns,
      subtract: [net_transactions: 1]

from ConstantKeyPageViewed,
      key: "$value(store)",
      count: :total_page_views
  end
  ```

* TypeScript

```typescript
  import { count, decrement, eventType, increment, readModel } from '@cratis/chronicle';

// Events
  @eventType()
  class MbConstantKeyProductPurchased {
      productId = '';
      amount = 0;
  }

@eventType()
  class MbConstantKeyProductReturned {
      productId = '';
      amount = 0;
  }

@eventType()
  class MbConstantKeyPageViewed {
      pageUrl = '';
  }

// Global read model
  @readModel()
  class MbConstantKeyStoreMetrics {
      @count(MbConstantKeyProductPurchased, 'store')
      totalPurchases = 0;

@count(MbConstantKeyProductReturned, 'store')
      totalReturns = 0;

@increment(MbConstantKeyProductPurchased, 'store')
      @decrement(MbConstantKeyProductReturned, 'store')
      netTransactions = 0;

@count(MbConstantKeyPageViewed, 'store')
      totalPageViews = 0;
  }
  ```

All events from all users and products accumulate into the single `StoreMetrics` document with key `"store"`.

# Convention-Based Mapping

Convention-based model-bound mapping lets a client say: “this read model is projected from this event, and matching property names should map automatically.” It is the model-bound counterpart to AutoMap in a declarative projection.

Use it when event properties and read model properties share names and compatible shapes. Add explicit mappings only for the properties that need a different source name, a context value, or a different operation.

## How It Works

[Section titled “How It Works”](#how-it-works)

Convention-based mapping follows the same projection rules as AutoMap:

1. The event and read model property names must match.
2. The property types must be compatible.
3. Nested objects can be mapped when their internal property names match.
4. Collections can be mapped when the element shape is compatible.
5. Properties that do not exist on the event are skipped for that event.

The client syntax differs, but the Chronicle projection definition still contains the event type, key expression, read model, and AutoMap behavior.

## Basic Convention Mapping

[Section titled “Basic Convention Mapping”](#basic-convention-mapping)

Apply the client’s model-bound “from event” marker at the read model level. Matching properties are then mapped without per-property set mappings.

* C#

Convention-based mapping

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record ConventionUserRegistered(
      string Name,
      string Email,
      DateTimeOffset RegisteredAt);

[FromEvent<ConventionUserRegistered>]
  public record ConventionUser(
      [Key] Guid Id,
      string Name,
      string Email,
      DateTimeOffset RegisteredAt);
  ```

* Kotlin

Convention-based mapping

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class ConventionUserRegistered(
      val name: String,
      val email: String,
      val registeredAt: String
  )

@ReadModel
  @FromEvent(ConventionUserRegistered::class)
  data class ConventionUser(
      val name: String = "",
      val email: String = "",
      val registeredAt: String = ""
  )
  ```

* Java

Convention-based mapping

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record ConventionUserRegistered(String name, String email, String registeredAt) {}

@ReadModel
  @FromEvent(eventType = ConventionUserRegistered.class)
  class ConventionUser {
      public String name = "";
      public String email = "";
      public String registeredAt = "";
  }
  ```

* Elixir

Convention-based mapping

```elixir
  defmodule MyApp.Events.ConventionUserRegistered do
    use Chronicle.Events.EventType, id: "convention-user-registered-v1"

defstruct [:name, :email, :registered_at]
  end

defmodule MyApp.ReadModels.ConventionUser do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.ConventionUserRegistered

defstruct [:name, :email, :registered_at]

# No `set:` list — matching field names are mapped automatically.
    from ConventionUserRegistered
  end
  ```

* TypeScript

Convention-based mapping

```typescript
  import { eventType, fromEvent, readModel } from '@cratis/chronicle';

@eventType()
  class ConventionUserRegistered {
      constructor(
          readonly name: string,
          readonly email: string,
          readonly registeredAt: Date
      ) {}
  }

@readModel()
  @fromEvent(ConventionUserRegistered)
  class ConventionUser {
      name = '';
      email = '';
      registeredAt = new Date();
  }
  ```

This is equivalent to writing explicit set mappings for every property:

* C#

Equivalent explicit mappings

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record ExplicitConventionUserRegistered(
      string Name,
      string Email,
      DateTimeOffset RegisteredAt);

public record ExplicitConventionUser(
      [Key] Guid Id,

[SetFrom<ExplicitConventionUserRegistered>(nameof(ExplicitConventionUserRegistered.Name))]
      string Name,

[SetFrom<ExplicitConventionUserRegistered>(nameof(ExplicitConventionUserRegistered.Email))]
      string Email,

[SetFrom<ExplicitConventionUserRegistered>(nameof(ExplicitConventionUserRegistered.RegisteredAt))]
      DateTimeOffset RegisteredAt);
  ```

* Kotlin

Equivalent explicit mappings

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class ExplicitConventionUserRegistered(
      val name: String,
      val email: String,
      val registeredAt: String
  )

@ReadModel
  @FromEvent(ExplicitConventionUserRegistered::class)
  data class ExplicitConventionUser(
      @SetFrom("name")
      val name: String = "",

@SetFrom("email")
      val email: String = "",

@SetFrom("registeredAt")
      val registeredAt: String = ""
  )
  ```

* Java

Equivalent explicit mappings

@EventType
  record ExplicitConventionUserRegistered(String name, String email, String registeredAt) {}

@ReadModel
  @FromEvent(eventType = ExplicitConventionUserRegistered.class)
  class ExplicitConventionUser {
      @SetFrom(propertyPath = "name")
      public String name = "";

@SetFrom(propertyPath = "email")
      public String email = "";

@SetFrom(propertyPath = "registeredAt")
      public String registeredAt = "";
  }
  ```

* Elixir

Equivalent explicit mappings

```elixir
  defmodule MyApp.Events.ExplicitConventionUserRegistered do
    use Chronicle.Events.EventType, id: "explicit-convention-user-registered-v1"

defstruct [:name, :email, :registered_at]
  end

defmodule MyApp.ReadModels.ExplicitConventionUser do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.ExplicitConventionUserRegistered

defstruct [:name, :email, :registered_at]

from ExplicitConventionUserRegistered,
      set: [name: :name, email: :email, registered_at: :registered_at]
  end
  ```

* TypeScript

Equivalent explicit mappings

```typescript
  import { eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class ExplicitConventionUserRegistered {
      constructor(
          readonly name: string,
          readonly email: string,
          readonly registeredAt: Date
      ) {}
  }

@readModel()
  @fromEvent(ExplicitConventionUserRegistered)
  class ExplicitConventionUser {
      @setFrom(ExplicitConventionUserRegistered, 'name')
      name = '';

@setFrom(ExplicitConventionUserRegistered, 'email')
      email = '';

@setFrom(ExplicitConventionUserRegistered, 'registeredAt')
      registeredAt = new Date();
  }
  ```

## Multiple Events

[Section titled “Multiple Events”](#multiple-events)

A read model can use convention mapping from more than one event type. Each event updates the matching properties it contains and leaves the rest unchanged.

* C#

Multiple convention events

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record ConventionUserProfileCreated(string Name, string Email);

[EventType]
  public record ConventionUserProfileUpdated(string Name, string Email, string Phone);

[FromEvent<ConventionUserProfileCreated>]
  [FromEvent<ConventionUserProfileUpdated>]
  public record ConventionUserProfile(
      [Key] Guid Id,
      string Name,
      string Email,
      string Phone);
  ```

* Kotlin

Multiple convention events

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class ConventionUserProfileCreated(
      val name: String,
      val email: String
  )

@EventType
  data class ConventionUserProfileUpdated(
      val name: String,
      val email: String,
      val phone: String
  )

@ReadModel
  @FromEvent(ConventionUserProfileCreated::class)
  @FromEvent(ConventionUserProfileUpdated::class)
  data class ConventionUserProfile(
      val name: String = "",
      val email: String = "",
      val phone: String = ""
  )
  ```

* Java

Multiple convention events

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record ConventionUserProfileCreated(String name, String email) {}

@EventType
  record ConventionUserProfileUpdated(String name, String email, String phone) {}

@ReadModel
  @FromEvent(eventType = ConventionUserProfileCreated.class)
  @FromEvent(eventType = ConventionUserProfileUpdated.class)
  class ConventionUserProfile {
      public String name = "";
      public String email = "";
      public String phone = "";
  }
  ```

* Elixir

Multiple convention events

```elixir
  defmodule MyApp.Events.ConventionUserProfileCreated do
    use Chronicle.Events.EventType, id: "convention-user-profile-created-v1"

defstruct [:name, :email]
  end

defmodule MyApp.Events.ConventionUserProfileUpdated do
    use Chronicle.Events.EventType, id: "convention-user-profile-updated-v1"

defstruct [:name, :email, :phone]
  end

defmodule MyApp.ReadModels.ConventionUserProfile do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{ConventionUserProfileCreated, ConventionUserProfileUpdated}

defstruct [:name, :email, :phone]

from ConventionUserProfileCreated
    from ConventionUserProfileUpdated
  end
  ```

* TypeScript

Multiple convention events

```typescript
  import { eventType, fromEvent, readModel } from '@cratis/chronicle';

@eventType()
  class ConventionUserProfileCreated {
      constructor(readonly name: string, readonly email: string) {}
  }

@eventType()
  class ConventionUserProfileUpdated {
      constructor(
          readonly name: string,
          readonly email: string,
          readonly phone: string
      ) {}
  }

@readModel()
  @fromEvent(ConventionUserProfileCreated)
  @fromEvent(ConventionUserProfileUpdated)
  class ConventionUserProfile {
      name = '';
      email = '';
      phone = '';
  }
  ```

## Custom Keys

[Section titled “Custom Keys”](#custom-keys)

By default, convention-based mappings use the event source id as the read model key. Use a custom key when the event carries the identifier of the read model instance in its content.

* C#

Custom key

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record ConventionUserRegisteredWithKey(
      Guid UserId,
      string Name,
      string Email);

[FromEvent<ConventionUserRegisteredWithKey>(key: nameof(ConventionUserRegisteredWithKey.UserId))]
  public record ConventionUserById(
      [Key] Guid Id,
      string Name,
      string Email);
  ```

* Kotlin

Custom key

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class ConventionUserRegisteredWithKey(
      val userId: String,
      val name: String,
      val email: String
  )

@ReadModel
  @FromEvent(ConventionUserRegisteredWithKey::class, key = "userId")
  data class ConventionUserById(
      val name: String = "",
      val email: String = ""
  )
  ```

* Java

Custom key

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record ConventionUserRegisteredWithKey(String userId, String name, String email) {}

@ReadModel
  @FromEvent(eventType = ConventionUserRegisteredWithKey.class, key = "userId")
  class ConventionUserById {
      public String name = "";
      public String email = "";
  }
  ```

* Elixir

Custom key

```elixir
  defmodule MyApp.Events.ConventionUserRegisteredWithKey do
    use Chronicle.Events.EventType, id: "convention-user-registered-with-key-v1"

defstruct [:user_id, :name, :email]
  end

defmodule MyApp.ReadModels.ConventionUserById do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.ConventionUserRegisteredWithKey

defstruct [:name, :email]

from ConventionUserRegisteredWithKey, key: :user_id
  end
  ```

* TypeScript

Custom key

```typescript
  import { eventType, fromEvent, readModel } from '@cratis/chronicle';

@eventType()
  class ConventionUserRegisteredWithKey {
      constructor(
          readonly userId: string,
          readonly name: string,
          readonly email: string
      ) {}
  }

@readModel()
  @fromEvent(ConventionUserRegisteredWithKey, { key: 'userId' })
  class ConventionUserById {
      name = '';
      email = '';
  }
  ```

Custom keys are useful when:

* the event source id is not the read model id
* one event source can update multiple read model instances
* an event from one source updates a cross-source or cross-aggregate view

## Relationship To Declarative AutoMap

[Section titled “Relationship To Declarative AutoMap”](#relationship-to-declarative-automap)

Convention-based model-bound mapping and declarative AutoMap describe the same mapping behavior through different APIs.

* C#

Model-bound and declarative AutoMap

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record ConventionEquivalentUserRegistered(string Name, string Email);

[FromEvent<ConventionEquivalentUserRegistered>]
  public record ConventionEquivalentUser(
      [Key] Guid Id,
      string Name,
      string Email);

public class ConventionEquivalentProjection : IProjectionFor<ConventionEquivalentUser>
  {
      public void Define(IProjectionBuilderFor<ConventionEquivalentUser> builder) =>
          builder.From<ConventionEquivalentUserRegistered>();
  }
  ```

* Kotlin

Model-bound and declarative AutoMap

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class ConventionEquivalentUserRegistered(
      val name: String,
      val email: String
  )

@ReadModel
  @FromEvent(ConventionEquivalentUserRegistered::class)
  data class ConventionEquivalentUser(
      val name: String = "",
      val email: String = ""
  )

class ConventionEquivalentProjection : IProjectionFor<ConventionEquivalentUser> {
      override fun define(builder: IProjectionBuilderFor<ConventionEquivalentUser>) {
          builder.from(ConventionEquivalentUserRegistered::class)
      }
  }
  ```

* Java

Model-bound and declarative AutoMap

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record ConventionEquivalentUserRegistered(String name, String email) {}

@ReadModel
  @FromEvent(eventType = ConventionEquivalentUserRegistered.class)
  class ConventionEquivalentUser {
      public String name = "";
      public String email = "";
  }

class ConventionEquivalentProjection implements IProjectionFor<ConventionEquivalentUser> {
      @Override
      public void define(IProjectionBuilderFor<ConventionEquivalentUser> builder) {
          builder.from(ConventionEquivalentUserRegistered.class);
      }
  }
  ```

* Elixir

Model-bound and declarative AutoMap

```elixir
  defmodule MyApp.Events.ConventionEquivalentUserRegistered do
    use Chronicle.Events.EventType, id: "convention-equivalent-user-registered-v1"

defstruct [:name, :email]
  end

defmodule MyApp.ReadModels.ConventionEquivalentUser do
    use Chronicle.ReadModels.ReadModel

defstruct [:name, :email]
  end

defmodule MyApp.Projections.ConventionEquivalentProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.ConventionEquivalentUser

alias MyApp.Events.ConventionEquivalentUserRegistered

# No `set:` list — matching field names are mapped automatically, the same
    # way the model-bound `from` declaration on the read model itself would.
    from ConventionEquivalentUserRegistered
  end
  ```

* TypeScript

Model-bound and declarative AutoMap

```typescript
  import { eventType, fromEvent, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class ConventionEquivalentUserRegistered {
      constructor(readonly name: string, readonly email: string) {}
  }

@readModel()
  @fromEvent(ConventionEquivalentUserRegistered)
  class ConventionEquivalentUser {
      name = '';
      email = '';
  }

@projection('', ConventionEquivalentUser)
  class ConventionEquivalentProjection implements IProjectionFor<ConventionEquivalentUser> {
      define(builder: IProjectionBuilderFor<ConventionEquivalentUser>): void {
          builder.from(ConventionEquivalentUserRegistered);
      }
  }
  ```

Use the model-bound form when the mapping belongs naturally on the read model. Use a declarative projection when you need joins, richer key selection, or a projection definition that should stay separate from the read model shape.

## Matching Structures

[Section titled “Matching Structures”](#matching-structures)

Convention mapping also works for nested values and collections when the names and shapes match.

* C#

Matching nested structures and collections

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

public record ConventionAddress(string Street, string City, string PostalCode);

public record ConventionLineItem(string ProductName, decimal UnitPrice, int Quantity);

[EventType]
  public record ConventionCustomerRegistered(
      string FirstName,
      string LastName,
      ConventionAddress BillingAddress,
      ConventionAddress ShippingAddress);

[EventType]
  public record ConventionOrderCreated(
      string CustomerEmail,
      ConventionLineItem[] Items,
      string[] Tags);

[FromEvent<ConventionCustomerRegistered>]
  public record ConventionCustomer(
      [Key] Guid Id,
      string FirstName,
      string LastName,
      ConventionAddress BillingAddress,
      ConventionAddress ShippingAddress);

[FromEvent<ConventionOrderCreated>]
  public record ConventionOrder(
      [Key] Guid Id,
      string CustomerEmail,
      ConventionLineItem[] Items,
      string[] Tags);
  ```

* Kotlin

Matching nested structures and collections

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

data class ConventionAddress(
      val street: String = "",
      val city: String = "",
      val postalCode: String = ""
  )

data class ConventionLineItem(
      val productName: String = "",
      val unitPrice: Double = 0.0,
      val quantity: Int = 0
  )

@EventType
  data class ConventionCustomerRegistered(
      val firstName: String,
      val lastName: String,
      val billingAddress: ConventionAddress,
      val shippingAddress: ConventionAddress
  )

@EventType
  data class ConventionOrderCreated(
      val customerEmail: String,
      val items: List<ConventionLineItem>,
      val tags: List<String>
  )

@ReadModel
  @FromEvent(ConventionCustomerRegistered::class)
  data class ConventionCustomer(
      val firstName: String = "",
      val lastName: String = "",
      val billingAddress: ConventionAddress = ConventionAddress(),
      val shippingAddress: ConventionAddress = ConventionAddress()
  )

@ReadModel
  @FromEvent(ConventionOrderCreated::class)
  data class ConventionOrder(
      val customerEmail: String = "",
      val items: List<ConventionLineItem> = emptyList(),
      val tags: List<String> = emptyList()
  )
  ```

* Java

Matching nested structures and collections

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;
  import java.util.List;

record ConventionAddress(String street, String city, String postalCode) {}

record ConventionLineItem(String productName, double unitPrice, int quantity) {}

@EventType
  record ConventionCustomerRegistered(
      String firstName,
      String lastName,
      ConventionAddress billingAddress,
      ConventionAddress shippingAddress) {}

@EventType
  record ConventionOrderCreated(String customerEmail, List<ConventionLineItem> items, List<String> tags) {}

@ReadModel
  @FromEvent(eventType = ConventionCustomerRegistered.class)
  class ConventionCustomer {
      public String firstName = "";
      public String lastName = "";
      public ConventionAddress billingAddress;
      public ConventionAddress shippingAddress;
  }

@ReadModel
  @FromEvent(eventType = ConventionOrderCreated.class)
  class ConventionOrder {
      public String customerEmail = "";
      public List<ConventionLineItem> items = List.of();
      public List<String> tags = List.of();
  }
  ```

* Elixir

Matching nested structures and collections

```elixir
  defmodule MyApp.Events.ConventionCustomerRegistered do
    use Chronicle.Events.EventType, id: "convention-customer-registered-v1"

defstruct [:first_name, :last_name, :billing_address, :shipping_address]
  end

defmodule MyApp.Events.ConventionOrderCreated do
    use Chronicle.Events.EventType, id: "convention-order-created-v1"

defstruct [:customer_email, :items, :tags]
  end

defmodule MyApp.ReadModels.ConventionCustomer do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.ConventionCustomerRegistered

# Nested maps and lists are plain Elixir terms — matching field names on the
    # event are copied across as-is, structure and all.
    defstruct [:first_name, :last_name, :billing_address, :shipping_address]

from ConventionCustomerRegistered
  end

defmodule MyApp.ReadModels.ConventionOrder do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.ConventionOrderCreated

defstruct [:customer_email, :items, :tags]

from ConventionOrderCreated
  end
  ```

* TypeScript

Matching nested structures and collections

```typescript
  import { eventType, fromEvent, readModel } from '@cratis/chronicle';

class ConventionAddress {
      street = '';
      city = '';
      postalCode = '';
  }

class ConventionLineItem {
      productName = '';
      unitPrice = 0;
      quantity = 0;
  }

@eventType()
  class ConventionCustomerRegistered {
      constructor(
          readonly firstName: string,
          readonly lastName: string,
          readonly billingAddress: ConventionAddress,
          readonly shippingAddress: ConventionAddress
      ) {}
  }

@eventType()
  class ConventionOrderCreated {
      constructor(
          readonly customerEmail: string,
          readonly items: ConventionLineItem[],
          readonly tags: string[]
      ) {}
  }

@readModel()
  @fromEvent(ConventionCustomerRegistered)
  class ConventionCustomer {
      firstName = '';
      lastName = '';
      billingAddress = new ConventionAddress();
      shippingAddress = new ConventionAddress();
  }

@readModel()
  @fromEvent(ConventionOrderCreated)
  class ConventionOrder {
      customerEmail = '';
      items: ConventionLineItem[] = [];
      tags: string[] = [];
  }
  ```

## Partial Events

[Section titled “Partial Events”](#partial-events)

Events do not need to contain every read model property. Chronicle maps the properties that exist on each event.

* C#

Partial event shapes

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record ConventionPartialUserRegistered(string Email);

[EventType]
  public record ConventionPartialUserCompleted(
      string FirstName,
      string LastName,
      string Phone);

[FromEvent<ConventionPartialUserRegistered>]
  [FromEvent<ConventionPartialUserCompleted>]
  public record ConventionPartialUser(
      [Key] Guid Id,
      string Email,
      string FirstName,
      string LastName,
      string Phone);
  ```

* Kotlin

Partial event shapes

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class ConventionPartialUserRegistered(
      val email: String
  )

@EventType
  data class ConventionPartialUserCompleted(
      val firstName: String,
      val lastName: String,
      val phone: String
  )

@ReadModel
  @FromEvent(ConventionPartialUserRegistered::class)
  @FromEvent(ConventionPartialUserCompleted::class)
  data class ConventionPartialUser(
      val email: String = "",
      val firstName: String = "",
      val lastName: String = "",
      val phone: String = ""
  )
  ```

* Java

Partial event shapes

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record ConventionPartialUserRegistered(String email) {}

@EventType
  record ConventionPartialUserCompleted(String firstName, String lastName, String phone) {}

@ReadModel
  @FromEvent(eventType = ConventionPartialUserRegistered.class)
  @FromEvent(eventType = ConventionPartialUserCompleted.class)
  class ConventionPartialUser {
      public String email = "";
      public String firstName = "";
      public String lastName = "";
      public String phone = "";
  }
  ```

* Elixir

Partial event shapes

```elixir
  defmodule MyApp.Events.ConventionPartialUserRegistered do
    use Chronicle.Events.EventType, id: "convention-partial-user-registered-v1"

defstruct [:email]
  end

defmodule MyApp.Events.ConventionPartialUserCompleted do
    use Chronicle.Events.EventType, id: "convention-partial-user-completed-v1"

defstruct [:first_name, :last_name, :phone]
  end

defmodule MyApp.ReadModels.ConventionPartialUser do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{ConventionPartialUserRegistered, ConventionPartialUserCompleted}

defstruct [:email, :first_name, :last_name, :phone]

from ConventionPartialUserRegistered
    from ConventionPartialUserCompleted
  end
  ```

* TypeScript

Partial event shapes

```typescript
  import { eventType, fromEvent, readModel } from '@cratis/chronicle';

@eventType()
  class ConventionPartialUserRegistered {
      constructor(readonly email: string) {}
  }

@eventType()
  class ConventionPartialUserCompleted {
      constructor(
          readonly firstName: string,
          readonly lastName: string,
          readonly phone: string
      ) {}
  }

@readModel()
  @fromEvent(ConventionPartialUserRegistered)
  @fromEvent(ConventionPartialUserCompleted)
  class ConventionPartialUser {
      email = '';
      firstName = '';
      lastName = '';
      phone = '';
  }
  ```

## Excluding A Property From Mapping

[Section titled “Excluding A Property From Mapping”](#excluding-a-property-from-mapping)

Convention mapping applies to every event the read model subscribes to — including an event pulled in only to `[Count]`, `[Increment]`, or `[Join]`. If such an event carries a property whose name matches one you set explicitly, convention mapping would otherwise overwrite your value with the unrelated event’s. Chronicle handles the common form of this automatically and gives you an attribute for the rest.

### Aggregate-Only Events

[Section titled “Aggregate-Only Events”](#aggregate-only-events)

An event a read model subscribes to **only to aggregate** — `[Count]`, `[Increment]`, `[Decrement]`, `[Add]`, or `[Subtract]` — does not contribute its other properties to convention mapping. Counting an event does not copy its unrelated fields onto the read model, so a same-named property on it cannot overwrite an explicit value. No annotation is needed.

* C#

Aggregating an event does not map its other properties

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record AggOnlyArrangementSet(string Location);

[EventType]
  public record AggOnlyCandidateSubmitted(string Name, string Location);

[FromEvent<AggOnlyArrangementSet>]
  public record AggOnlyAssignmentSummary(
      [Key]
      Guid Id,

// AggOnlyCandidateSubmitted is subscribed only to be counted, so its identically named
      // Location is not auto-mapped over the value sourced from AggOnlyArrangementSet.
      [SetFrom<AggOnlyArrangementSet>(nameof(AggOnlyArrangementSet.Location))]
      string Location,

[Count<AggOnlyCandidateSubmitted>]
      int CandidateCount);
  ```

* Kotlin

Aggregating an event does not map its other properties

@EventType
  data class AggOnlyArrangementSet(val location: String)

@EventType
  data class AggOnlyCandidateSubmitted(val name: String, val location: String)

@ReadModel
  @FromEvent(AggOnlyArrangementSet::class)
  data class AggOnlyAssignmentSummary(
      // AggOnlyCandidateSubmitted is subscribed only to be counted, so its identically named
      // location is not auto-mapped over the value sourced from AggOnlyArrangementSet.
      @SetFrom("location", AggOnlyArrangementSet::class)
      val location: String = "",

@Count(AggOnlyCandidateSubmitted::class)
      val candidateCount: Int = 0
  )
  ```

* Java

Aggregating an event does not map its other properties

@EventType
  record AggOnlyArrangementSet(String location) {}

@EventType
  record AggOnlyCandidateSubmitted(String name, String location) {}

@ReadModel
  @FromEvent(eventType = AggOnlyArrangementSet.class)
  record AggOnlyAssignmentSummary(
      // AggOnlyCandidateSubmitted is subscribed only to be counted, so its identically named
      // location is not auto-mapped over the value sourced from AggOnlyArrangementSet.
      @SetFrom(propertyPath = "location", eventType = AggOnlyArrangementSet.class)
      String location,

@Count(eventType = AggOnlyCandidateSubmitted.class)
      int candidateCount
  ) {}
  ```

* Elixir

Aggregating an event does not map its other properties

```elixir
  defmodule MyApp.Events.AggOnlyArrangementSet do
    use Chronicle.Events.EventType, id: "agg-only-arrangement-set-v1"

defstruct [:location]
  end

defmodule MyApp.Events.AggOnlyCandidateSubmitted do
    use Chronicle.Events.EventType, id: "agg-only-candidate-submitted-v1"

defstruct [:name, :location]
  end

defmodule MyApp.ReadModels.AggOnlyAssignmentSummary do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{AggOnlyArrangementSet, AggOnlyCandidateSubmitted}

defstruct [:location, candidate_count: 0]

from AggOnlyArrangementSet

# AggOnlyCandidateSubmitted is subscribed only to be counted, so its own
    # `location` field is never mapped over the value set from
    # AggOnlyArrangementSet.
    from AggOnlyCandidateSubmitted, count: :candidate_count
  end
  ```

* TypeScript

```typescript
  import { count, eventType, fromEvent, Guid, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class AggOnlyArrangementSet {
      constructor(readonly location: string) {}
  }

@eventType()
  class AggOnlyCandidateSubmitted {
      constructor(readonly name: string, readonly location: string) {}
  }

// AggOnlyCandidateSubmitted is subscribed only to be counted, so its identically named
  // location is not auto-mapped over the value sourced from AggOnlyArrangementSet.
  @readModel()
  @fromEvent(AggOnlyArrangementSet)
  class AggOnlyAssignmentSummary {
      id: Guid = Guid.empty;

@setFrom(AggOnlyArrangementSet, 'location')
      location = '';

@count(AggOnlyCandidateSubmitted)
      candidateCount = 0;
  }
  ```

### `[NoAutoMap]` On A Property

[Section titled “\[NoAutoMap\] On A Property”](#noautomap-on-a-property)

For the collisions Chronicle cannot infer — a value-mapped (`[SetFrom]`) or `[Join]`ed event that carries an identically named property — apply `[NoAutoMap]` to the read model property (or record parameter). That property is then set only from its explicit source; convention mapping never touches it, while every other property keeps mapping.

* C#

Exclude a single property from convention mapping

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record NoAutoMapWorkArrangementSet(string Location, int WorkMode);

[EventType]
  public record NoAutoMapCandidateSubmitted(string Name, string Location);

[FromEvent<NoAutoMapWorkArrangementSet>]
  public record NoAutoMapAssignmentSummary(
      [Key]
      Guid Id,

// Location is sourced only from NoAutoMapWorkArrangementSet. NoAutoMapCandidateSubmitted is
      // value-mapped (for CandidateName) and also carries a Location; [NoAutoMap] stops that Location
      // from being auto-mapped over the explicit value, while every other property keeps mapping.
      [SetFrom<NoAutoMapWorkArrangementSet>(nameof(NoAutoMapWorkArrangementSet.Location))]
      [NoAutoMap]
      string Location,

[SetFrom<NoAutoMapCandidateSubmitted>(nameof(NoAutoMapCandidateSubmitted.Name))]
      string CandidateName);
  ```

* Kotlin

Exclude a single property from convention mapping

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.NoAutoMap
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class NoAutoMapWorkArrangementSet(val location: String, val workMode: Int)

@EventType
  data class NoAutoMapCandidateSubmitted(val name: String, val location: String)

@ReadModel
  @FromEvent(NoAutoMapWorkArrangementSet::class)
  data class NoAutoMapAssignmentSummary(
      // location is sourced only from NoAutoMapWorkArrangementSet. NoAutoMapCandidateSubmitted is
      // value-mapped (for candidateName) and also carries a location; @NoAutoMap stops that location
      // from being auto-mapped over the explicit value, while every other property keeps mapping.
      @SetFrom("location", NoAutoMapWorkArrangementSet::class)
      @NoAutoMap
      val location: String = "",

@SetFrom("name", NoAutoMapCandidateSubmitted::class)
      val candidateName: String = ""
  )
  ```

* Java

Exclude a single property from convention mapping

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.NoAutoMap;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record NoAutoMapWorkArrangementSet(String location, int workMode) {}

@EventType
  record NoAutoMapCandidateSubmitted(String name, String location) {}

@ReadModel
  @FromEvent(eventType = NoAutoMapWorkArrangementSet.class)
  record NoAutoMapAssignmentSummary(
      // location is sourced only from NoAutoMapWorkArrangementSet. NoAutoMapCandidateSubmitted is
      // value-mapped (for candidateName) and also carries a location; @NoAutoMap stops that location
      // from being auto-mapped over the explicit value, while every other property keeps mapping.
      @SetFrom(propertyPath = "location", eventType = NoAutoMapWorkArrangementSet.class)
      @NoAutoMap
      String location,

@SetFrom(propertyPath = "name", eventType = NoAutoMapCandidateSubmitted.class)
      String candidateName
  ) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

Exclude a single property from convention mapping

```typescript
  import { eventType, fromEvent, noAutoMap, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class NoAutoMapWorkArrangementSet {
      constructor(
          readonly location: string,
          readonly workMode: number
      ) {}
  }

@eventType()
  class NoAutoMapCandidateSubmitted {
      constructor(
          readonly name: string,
          readonly location: string
      ) {}
  }

@readModel()
  @fromEvent(NoAutoMapWorkArrangementSet)
  class NoAutoMapAssignmentSummary {
      // location is sourced only from NoAutoMapWorkArrangementSet. NoAutoMapCandidateSubmitted is
      // value-mapped (for candidateName) and also carries a location; @noAutoMap stops that location
      // from being auto-mapped over the explicit value, while every other property keeps mapping.
      @setFrom(NoAutoMapWorkArrangementSet, 'location')
      @noAutoMap
      location = '';

@setFrom(NoAutoMapCandidateSubmitted, 'name')
      candidateName = '';
  }
  ```

`[NoAutoMap]` also works at the read model (class) level to disable convention mapping for the whole read model. Use the property form when you only need to protect a single property and want convention mapping everywhere else.

## When To Use It

[Section titled “When To Use It”](#when-to-use-it)

Use convention-based mapping when:

* the event and read model use consistent names
* most properties are simple set mappings
* the read model is easiest to understand next to its event mappings
* you want to keep explicit attributes or decorators for the exceptions only

Use explicit mappings when:

* names differ between the event and read model
* the property comes from event context
* the property needs add, subtract, count, or another operation
* the mapping needs a custom key for only one event
* being explicit is clearer than relying on naming

Convention-based mapping is evaluated when the projection definition is built. Event processing uses the compiled projection definition, so there is no per-event reflection penalty compared with explicit set mappings.

# Counters

Model-bound projections provide three counter operations for tracking occurrences and quantities: Increment, Decrement, and Count.

## Increment

[Section titled “Increment”](#increment)

The `Increment` attribute increments a numeric property when an event occurs. This is useful for tracking counters that increase with specific events.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbCountersUserLoggedIn;

public record MbCountersUserStatistics(
      [Key]
      Guid UserId,

[Increment<MbCountersUserLoggedIn>]
      int LoginCount);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.Increment
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  class MbCountersUserLoggedIn

@ReadModel
  @FromEvent(MbCountersUserLoggedIn::class)
  data class MbCountersUserStatistics(
      @Increment(MbCountersUserLoggedIn::class)
      val loginCount: Int = 0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.Increment;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  class MbCountersUserLoggedIn {}

@ReadModel
  @FromEvent(eventType = MbCountersUserLoggedIn.class)
  class MbCountersUserStatistics {
      @Increment(eventType = MbCountersUserLoggedIn.class)
      public int loginCount = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.CountersUserLoggedIn do
    use Chronicle.Events.EventType, id: "counters-user-logged-in-v1"

defstruct []
  end

defmodule MyApp.ReadModels.CountersUserStatistics do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.CountersUserLoggedIn

defstruct [:user_id, login_count: 0]

from CountersUserLoggedIn,
      set: [user_id: :event_source_id],
      add: [login_count: 1]
  end
  ```

* TypeScript

```typescript
  import { eventType, Guid, increment, readModel } from '@cratis/chronicle';

@eventType()
  class MbCountersUserLoggedIn {
  }

@readModel()
  class MbCountersUserStatistics {
      id: Guid = Guid.empty;

@increment(MbCountersUserLoggedIn)
      loginCount = 0;
  }
  ```

Each time a `UserLoggedIn` event occurs, `LoginCount` is incremented by 1.

## Decrement

[Section titled “Decrement”](#decrement)

The `Decrement` attribute decrements a numeric property when an event occurs. This is useful for tracking decreasing counters.

* C#

```csharp
  [EventType]
  public record MbCountersUserConnected;

[EventType]
  public record MbCountersUserDisconnected;

public record MbCountersServerStatistics(
      [Key]
      Guid ServerId,

[Increment<MbCountersUserConnected>]
      [Decrement<MbCountersUserDisconnected>]
      int ActiveConnections);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.Decrement
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.Increment
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  class MbCountersUserConnected

@EventType
  class MbCountersUserDisconnected

@ReadModel
  @FromEvent(MbCountersUserConnected::class)
  @FromEvent(MbCountersUserDisconnected::class)
  data class MbCountersServerStatistics(
      @Increment(MbCountersUserConnected::class)
      @Decrement(MbCountersUserDisconnected::class)
      val activeConnections: Int = 0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.Decrement;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.Increment;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  class MbCountersUserConnected {}

@EventType
  class MbCountersUserDisconnected {}

@ReadModel
  @FromEvent(eventType = MbCountersUserConnected.class)
  @FromEvent(eventType = MbCountersUserDisconnected.class)
  class MbCountersServerStatistics {
      @Increment(eventType = MbCountersUserConnected.class)
      @Decrement(eventType = MbCountersUserDisconnected.class)
      public int activeConnections = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.CountersUserConnected do
    use Chronicle.Events.EventType, id: "counters-user-connected-v1"

defstruct []
  end

defmodule MyApp.Events.CountersUserDisconnected do
    use Chronicle.Events.EventType, id: "counters-user-disconnected-v1"

defstruct []
  end

defmodule MyApp.ReadModels.CountersServerStatistics do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{CountersUserConnected, CountersUserDisconnected}

defstruct [:server_id, active_connections: 0]

from CountersUserConnected,
      set: [server_id: :event_source_id],
      add: [active_connections: 1]

from CountersUserDisconnected,
      subtract: [active_connections: 1]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class MbCountersUserConnected {
  }

@eventType()
  class MbCountersUserDisconnected {
  }

@readModel()
  class MbCountersServerStatistics {
      id: Guid = Guid.empty;

@increment(MbCountersUserConnected)
      @decrement(MbCountersUserDisconnected)
      activeConnections = 0;
  }
  ```

When a `UserConnected` event occurs, `ActiveConnections` increases by 1. When a `UserDisconnected` event occurs, it decreases by 1.

## Count

[Section titled “Count”](#count)

The `Count` attribute counts the total number of times an event occurs. Unlike Increment, Count doesn’t increment from a current value—it maintains an absolute count.

* C#

```csharp
  [EventType]
  public record MbCountersOrderPlaced;

[EventType]
  public record MbCountersOrderCancelled;

public record MbCountersEventMetrics(
      [Key]
      Guid Id,

[Count<MbCountersOrderPlaced>]
      int TotalOrders,

[Count<MbCountersOrderCancelled>]
      int CancelledOrders);
  ```

* Kotlin

@EventType
  class MbCountersOrderPlaced

@EventType
  class MbCountersOrderCancelled

@ReadModel
  @FromEvent(MbCountersOrderPlaced::class)
  @FromEvent(MbCountersOrderCancelled::class)
  data class MbCountersEventMetrics(
      @Count(MbCountersOrderPlaced::class)
      val totalOrders: Int = 0,

@Count(MbCountersOrderCancelled::class)
      val cancelledOrders: Int = 0
  )
  ```

* Java

@EventType
  class MbCountersOrderPlaced {}

@EventType
  class MbCountersOrderCancelled {}

@ReadModel
  @FromEvent(eventType = MbCountersOrderPlaced.class)
  @FromEvent(eventType = MbCountersOrderCancelled.class)
  class MbCountersEventMetrics {
      @Count(eventType = MbCountersOrderPlaced.class)
      public int totalOrders = 0;

@Count(eventType = MbCountersOrderCancelled.class)
      public int cancelledOrders = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.CountersOrderPlaced do
    use Chronicle.Events.EventType, id: "counters-order-placed-v1"

defstruct []
  end

defmodule MyApp.Events.CountersOrderCancelled do
    use Chronicle.Events.EventType, id: "counters-order-cancelled-v1"

defstruct []
  end

defmodule MyApp.ReadModels.CountersEventMetrics do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{CountersOrderPlaced, CountersOrderCancelled}

defstruct [:id, total_orders: 0, cancelled_orders: 0]

from CountersOrderPlaced,
      set: [id: :event_source_id],
      count: :total_orders

from CountersOrderCancelled,
      count: :cancelled_orders
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class MbCountersOrderPlaced {
  }

@eventType()
  class MbCountersOrderCancelled {
  }

@readModel()
  class MbCountersEventMetrics {
      id: Guid = Guid.empty;

@count(MbCountersOrderPlaced)
      totalOrders = 0;

@count(MbCountersOrderCancelled)
      cancelledOrders = 0;
  }
  ```

## Multiple Events

[Section titled “Multiple Events”](#multiple-events)

You can use multiple attributes on the same property to respond to different events:

* C#

```csharp
  [EventType]
  public record MbCountersItemCreated(string Name, int InitialQuantity);

[EventType]
  public record MbCountersItemRestocked;

[EventType]
  public record MbCountersItemSold;

public record MbCountersInventoryItem(
      [Key]
      Guid ItemId,

[SetFrom<MbCountersItemCreated>(nameof(MbCountersItemCreated.Name))]
      string Name,

[SetFrom<MbCountersItemCreated>(nameof(MbCountersItemCreated.InitialQuantity))]
      [Increment<MbCountersItemRestocked>]
      [Decrement<MbCountersItemSold>]
      int Quantity,

[Count<MbCountersItemRestocked>]
      int RestockCount,

[Count<MbCountersItemSold>]
      int SalesCount);
  ```

* Kotlin

@EventType
  data class MbCountersItemCreated(val name: String, val initialQuantity: Int)

@EventType
  class MbCountersItemRestocked

@EventType
  class MbCountersItemSold

@ReadModel
  @FromEvent(MbCountersItemCreated::class)
  @FromEvent(MbCountersItemRestocked::class)
  @FromEvent(MbCountersItemSold::class)
  data class MbCountersInventoryItem(
      @SetFrom("name", MbCountersItemCreated::class)
      val name: String = "",

@SetFrom("initialQuantity", MbCountersItemCreated::class)
      @Increment(MbCountersItemRestocked::class)
      @Decrement(MbCountersItemSold::class)
      val quantity: Int = 0,

@Count(MbCountersItemRestocked::class)
      val restockCount: Int = 0,

@Count(MbCountersItemSold::class)
      val salesCount: Int = 0
  )
  ```

* Java

@EventType
  record MbCountersItemCreated(String name, int initialQuantity) {}

@EventType
  class MbCountersItemRestocked {}

@EventType
  class MbCountersItemSold {}

@ReadModel
  @FromEvent(eventType = MbCountersItemCreated.class)
  @FromEvent(eventType = MbCountersItemRestocked.class)
  @FromEvent(eventType = MbCountersItemSold.class)
  class MbCountersInventoryItem {
      @SetFrom(propertyPath = "name", eventType = MbCountersItemCreated.class)
      public String name = "";

@SetFrom(propertyPath = "initialQuantity", eventType = MbCountersItemCreated.class)
      @Increment(eventType = MbCountersItemRestocked.class)
      @Decrement(eventType = MbCountersItemSold.class)
      public int quantity = 0;

@Count(eventType = MbCountersItemRestocked.class)
      public int restockCount = 0;

@Count(eventType = MbCountersItemSold.class)
      public int salesCount = 0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.CountersItemCreated do
    use Chronicle.Events.EventType, id: "counters-item-created-v1"

defstruct [:name, :initial_quantity]
  end

defmodule MyApp.Events.CountersItemRestocked do
    use Chronicle.Events.EventType, id: "counters-item-restocked-v1"

defstruct []
  end

defmodule MyApp.Events.CountersItemSold do
    use Chronicle.Events.EventType, id: "counters-item-sold-v1"

defstruct []
  end

defmodule MyApp.ReadModels.CountersInventoryItem do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{CountersItemCreated, CountersItemRestocked, CountersItemSold}

defstruct [:item_id, :name, quantity: 0, restock_count: 0, sales_count: 0]

from CountersItemCreated,
      set: [item_id: :event_source_id, name: :name, quantity: :initial_quantity]

from CountersItemRestocked,
      add: [quantity: 1],
      count: :restock_count

from CountersItemSold,
      subtract: [quantity: 1],
      count: :sales_count
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class MbCountersItemCreated {
      name = '';
      initialQuantity = 0;
  }

@eventType()
  class MbCountersItemRestocked {
  }

@eventType()
  class MbCountersItemSold {
  }

@readModel()
  class MbCountersInventoryItem {
      id: Guid = Guid.empty;

@setFrom(MbCountersItemCreated, 'name')
      name = '';

@setFrom(MbCountersItemCreated, 'initialQuantity')
      @increment(MbCountersItemRestocked)
      @decrement(MbCountersItemSold)
      quantity = 0;

@count(MbCountersItemRestocked)
      restockCount = 0;

@count(MbCountersItemSold)
      salesCount = 0;
  }
  ```

## Complete Example

[Section titled “Complete Example”](#complete-example)

Here’s a complete example tracking various metrics:

* C#

```csharp
  // Events
  [EventType]
  public record MbCountersUserLoggedInFull(DateTimeOffset Timestamp);

[EventType]
  public record MbCountersUserLoggedOutFull(DateTimeOffset Timestamp);

[EventType]
  public record MbCountersPurchaseMade(decimal Amount);

[EventType]
  public record MbCountersRefundIssued(decimal Amount);

// Read Model
  public record MbCountersUserActivity(
      [Key]
      Guid UserId,

// Track login/logout counts
      [Count<MbCountersUserLoggedInFull>]
      int TotalLogins,

[Count<MbCountersUserLoggedOutFull>]
      int TotalLogouts,

// Track active sessions
      [Increment<MbCountersUserLoggedInFull>]
      [Decrement<MbCountersUserLoggedOutFull>]
      int ActiveSessions,

// Track transaction counts
      [Count<MbCountersPurchaseMade>]
      int PurchaseCount,

[Count<MbCountersRefundIssued>]
      int RefundCount,

// Track transaction values
      [AddFrom<MbCountersPurchaseMade>(nameof(MbCountersPurchaseMade.Amount))]
      [SubtractFrom<MbCountersRefundIssued>(nameof(MbCountersRefundIssued.Amount))]
      decimal NetSpent);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.AddFrom
  import io.cratis.chronicle.projections.Count
  import io.cratis.chronicle.projections.Decrement
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.Increment
  import io.cratis.chronicle.projections.SubtractFrom
  import io.cratis.chronicle.readModels.ReadModel
  import java.time.Instant

// Events
  @EventType
  data class MbCountersUserLoggedInFull(val timestamp: Instant)

@EventType
  data class MbCountersUserLoggedOutFull(val timestamp: Instant)

@EventType
  data class MbCountersPurchaseMade(val amount: Double)

@EventType
  data class MbCountersRefundIssued(val amount: Double)

// Read Model
  @ReadModel
  @FromEvent(MbCountersUserLoggedInFull::class)
  @FromEvent(MbCountersUserLoggedOutFull::class)
  @FromEvent(MbCountersPurchaseMade::class)
  @FromEvent(MbCountersRefundIssued::class)
  data class MbCountersUserActivity(
      // Track login/logout counts
      @Count(MbCountersUserLoggedInFull::class)
      val totalLogins: Int = 0,

@Count(MbCountersUserLoggedOutFull::class)
      val totalLogouts: Int = 0,

// Track active sessions
      @Increment(MbCountersUserLoggedInFull::class)
      @Decrement(MbCountersUserLoggedOutFull::class)
      val activeSessions: Int = 0,

// Track transaction counts
      @Count(MbCountersPurchaseMade::class)
      val purchaseCount: Int = 0,

@Count(MbCountersRefundIssued::class)
      val refundCount: Int = 0,

// Track transaction values
      @AddFrom(MbCountersPurchaseMade::class, "amount")
      @SubtractFrom(MbCountersRefundIssued::class, "amount")
      val netSpent: Double = 0.0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.AddFrom;
  import io.cratis.chronicle.projections.Count;
  import io.cratis.chronicle.projections.Decrement;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.Increment;
  import io.cratis.chronicle.projections.SubtractFrom;
  import io.cratis.chronicle.readModels.ReadModel;

import java.time.Instant;

// Events
  @EventType
  record MbCountersUserLoggedInFull(Instant timestamp) {}

@EventType
  record MbCountersUserLoggedOutFull(Instant timestamp) {}

@EventType
  record MbCountersPurchaseMade(double amount) {}

@EventType
  record MbCountersRefundIssued(double amount) {}

// Read Model
  @ReadModel
  @FromEvent(eventType = MbCountersUserLoggedInFull.class)
  @FromEvent(eventType = MbCountersUserLoggedOutFull.class)
  @FromEvent(eventType = MbCountersPurchaseMade.class)
  @FromEvent(eventType = MbCountersRefundIssued.class)
  class MbCountersUserActivity {
      // Track login/logout counts
      @Count(eventType = MbCountersUserLoggedInFull.class)
      public int totalLogins = 0;

@Count(eventType = MbCountersUserLoggedOutFull.class)
      public int totalLogouts = 0;

// Track active sessions
      @Increment(eventType = MbCountersUserLoggedInFull.class)
      @Decrement(eventType = MbCountersUserLoggedOutFull.class)
      public int activeSessions = 0;

// Track transaction counts
      @Count(eventType = MbCountersPurchaseMade.class)
      public int purchaseCount = 0;

@Count(eventType = MbCountersRefundIssued.class)
      public int refundCount = 0;

// Track transaction values
      @AddFrom(eventType = MbCountersPurchaseMade.class, eventPropertyName = "amount")
      @SubtractFrom(eventType = MbCountersRefundIssued.class, eventPropertyName = "amount")
      public double netSpent = 0.0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.CountersUserLoggedInFull do
    use Chronicle.Events.EventType, id: "counters-user-logged-in-full-v1"

defstruct [:timestamp]
  end

defmodule MyApp.Events.CountersUserLoggedOutFull do
    use Chronicle.Events.EventType, id: "counters-user-logged-out-full-v1"

defstruct [:timestamp]
  end

defmodule MyApp.Events.CountersPurchaseMade do
    use Chronicle.Events.EventType, id: "counters-purchase-made-v1"

defstruct [:amount]
  end

defmodule MyApp.Events.CountersRefundIssued do
    use Chronicle.Events.EventType, id: "counters-refund-issued-v1"

defstruct [:amount]
  end

defmodule MyApp.ReadModels.CountersUserActivity do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{
      CountersUserLoggedInFull,
      CountersUserLoggedOutFull,
      CountersPurchaseMade,
      CountersRefundIssued
    }

defstruct [
      :user_id,
      total_logins: 0,
      total_logouts: 0,
      active_sessions: 0,
      purchase_count: 0,
      refund_count: 0,
      net_spent: 0
    ]

# Track login/logout counts and active sessions
    from CountersUserLoggedInFull,
      set: [user_id: :event_source_id],
      count: :total_logins,
      add: [active_sessions: 1]

from CountersUserLoggedOutFull,
      count: :total_logouts,
      subtract: [active_sessions: 1]

# Track transaction counts and net value
    from CountersPurchaseMade,
      count: :purchase_count,
      add: [net_spent: :amount]

from CountersRefundIssued,
      count: :refund_count,
      subtract: [net_spent: :amount]
  end
  ```

* TypeScript

```typescript
  import { addFrom, count, decrement, eventType, Guid, increment, readModel, subtractFrom } from '@cratis/chronicle';

// Events
  @eventType()
  class MbCountersUserLoggedInFull {
      timestamp = new Date();
  }

@eventType()
  class MbCountersUserLoggedOutFull {
      timestamp = new Date();
  }

@eventType()
  class MbCountersPurchaseMade {
      amount = 0;
  }

@eventType()
  class MbCountersRefundIssued {
      amount = 0;
  }

// Read Model
  @readModel()
  class MbCountersUserActivity {
      id: Guid = Guid.empty;

// Track login/logout counts
      @count(MbCountersUserLoggedInFull)
      totalLogins = 0;

@count(MbCountersUserLoggedOutFull)
      totalLogouts = 0;

// Track active sessions
      @increment(MbCountersUserLoggedInFull)
      @decrement(MbCountersUserLoggedOutFull)
      activeSessions = 0;

// Track transaction counts
      @count(MbCountersPurchaseMade)
      purchaseCount = 0;

@count(MbCountersRefundIssued)
      refundCount = 0;

// Track transaction values
      @addFrom(MbCountersPurchaseMade, 'amount')
      @subtractFrom(MbCountersRefundIssued, 'amount')
      netSpent = 0;
  }
  ```

## Counter vs Count

[Section titled “Counter vs Count”](#counter-vs-count)

**Increment/Decrement:**

* Modifies the current value
* Useful for tracking active states (sessions, connections)
* Can be combined with SetFrom to establish initial values
* Changes are relative to current value

**Count:**

* Maintains absolute count of event occurrences
* Useful for analytics and reporting
* Independent of other operations
* Always represents total occurrences

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Use Increment/Decrement** for tracking active/current states that change over time
2. **Use Count** for analytics and metrics that track total occurrences
3. **Combine operations** on the same property when tracking both current state and history
4. **Initialize counters** with SetFrom when you have an initial value from a creation event

# Event Sequence Source

By default, model-bound projections read from the event log. Use `[EventSequence]` to specify a different event sequence:

* C#

```csharp
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbEventSeqOrderPlaced(decimal Amount);

[EventSequence("custom-sequence")]
  public record MbEventSeqOrderSummary(
      [Key]
      Guid Id,

[SetFrom<MbEventSeqOrderPlaced>(nameof(MbEventSeqOrderPlaced.Amount))]
      decimal TotalAmount);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.EventSequence
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbEventSeqOrderPlaced(val amount: Double)

@ReadModel
  @EventSequence("custom-sequence")
  @FromEvent(MbEventSeqOrderPlaced::class)
  data class MbEventSeqOrderSummary(
      @SetFrom("amount", MbEventSeqOrderPlaced::class)
      val totalAmount: Double = 0.0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.EventSequence;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record MbEventSeqOrderPlaced(double amount) {}

@ReadModel
  @EventSequence("custom-sequence")
  @FromEvent(eventType = MbEventSeqOrderPlaced.class)
  record MbEventSeqOrderSummary(
      @SetFrom(propertyPath = "amount", eventType = MbEventSeqOrderPlaced.class)
      double totalAmount
  ) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventSequence, eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbEventSeqOrderPlaced {
      amount = 0;
  }

@readModel()
  @fromEvent(MbEventSeqOrderPlaced)
  @eventSequence('custom-sequence')
  class MbEventSeqOrderSummary {
      @setFrom(MbEventSeqOrderPlaced, 'amount')
      totalAmount = 0;
  }
  ```

This corresponds to the fluent API for declarative projections:

* C#

```csharp
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Projections;

[EventType]
  public record MbEventSeqFluentOrderPlaced(decimal Amount);

public class MbEventSeqFluentOrderProjection : IProjectionFor<MbEventSeqFluentOrderSummary>
  {
      public void Define(IProjectionBuilderFor<MbEventSeqFluentOrderSummary> builder) => builder
          .FromEventSequence(new EventSequenceId("custom-sequence"))
          .From<MbEventSeqFluentOrderPlaced>(_ => _
              .Set(m => m.TotalAmount).To(e => e.Amount));
  }

public class MbEventSeqFluentOrderSummary
  {
      public decimal TotalAmount { get; set; }
  }
  ```

* Kotlin

@EventType
  data class MbEventSeqFluentOrderPlaced(val amount: Double)

data class MbEventSeqFluentOrderSummary(val totalAmount: Double = 0.0)

@Projection(eventSequence = "custom-sequence")
  class MbEventSeqFluentOrderProjection : IProjectionFor<MbEventSeqFluentOrderSummary> {
      override fun define(builder: IProjectionBuilderFor<MbEventSeqFluentOrderSummary>) {
          builder.from(MbEventSeqFluentOrderPlaced::class) {
              it.set(MbEventSeqFluentOrderSummary::totalAmount).to { e -> e.amount }
          }
      }
  }
  ```

* Java

@EventType
  record MbEventSeqFluentOrderPlaced(double amount) {
  }

class MbEventSeqFluentOrderSummary {
      public double totalAmount = 0;
  }

@Projection(eventSequence = "custom-sequence")
  class MbEventSeqFluentOrderProjection implements IProjectionFor<MbEventSeqFluentOrderSummary> {
      @Override
      public void define(IProjectionBuilderFor<MbEventSeqFluentOrderSummary> builder) {
          builder.from(MbEventSeqFluentOrderPlaced.class,
              from -> from.<Double>set("totalAmount").to(MbEventSeqFluentOrderPlaced::amount));
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class MbEventSeqFluentOrderPlaced {
      amount = 0;
  }

// The event sequence is configured on the decorator rather than the builder
  @projection('', undefined, 'custom-sequence')
  class MbEventSeqFluentOrderProjection implements IProjectionFor<MbEventSeqFluentOrderSummary> {
      define(builder: IProjectionBuilderFor<MbEventSeqFluentOrderSummary>): void {
          builder.from(MbEventSeqFluentOrderPlaced, _ => _
              .set(m => m.totalAmount).to(e => e.amount));
      }
  }

class MbEventSeqFluentOrderSummary {
      totalAmount = 0;
  }
  ```

Client coverage

Explicitly overriding the event sequence a projection reads from is a .NET and TypeScript mechanism today — Kotlin, Java, and Elixir client projections always register against the event log and do not yet expose an `[EventSequence]`-equivalent override.

## Convenience: `[EventLog]`

[Section titled “Convenience: \[EventLog\]”](#convenience-eventlog)

Use `[EventLog]` when you want to be explicit that the projection reads from the default event log, even when other event types in the assembly carry a `[EventStore]` attribute:

* C#

```csharp
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Keys;

[EventType]
  public record MbEventSeqLocalEvent(string Data);

[EventLog]
  public record MbEventSeqLocalSnapshot(
      [Key]
      Guid Id,

[SetFrom<MbEventSeqLocalEvent>(nameof(MbEventSeqLocalEvent.Data))]
      string Data);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbEventSeqLocalEvent(val data: String)

// No @EventSequence needed — an observer with no event sequence specified observes the event log.
  @ReadModel
  @FromEvent(MbEventSeqLocalEvent::class)
  data class MbEventSeqLocalSnapshot(
      @SetFrom("data", MbEventSeqLocalEvent::class)
      val data: String = ""
  )
  ```

* Java

@EventType
  record MbEventSeqLocalEvent(String data) {}

// No @EventSequence needed — an observer with no event sequence specified observes the event log.
  @ReadModel
  @FromEvent(eventType = MbEventSeqLocalEvent.class)
  record MbEventSeqLocalSnapshot(
      @SetFrom(propertyPath = "data", eventType = MbEventSeqLocalEvent.class)
      String data
  ) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventLog, eventType, fromEvent, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbEventSeqLocalEvent {
      data = '';
  }

@readModel()
  @fromEvent(MbEventSeqLocalEvent)
  @eventLog
  class MbEventSeqLocalSnapshot {
      @setFrom(MbEventSeqLocalEvent, 'data')
      data = '';
  }
  ```

## Automatic Inbox Routing

[Section titled “Automatic Inbox Routing”](#automatic-inbox-routing)

When the event types used in a model-bound projection carry a `[EventStore]` attribute pointing to a **different** event store than the one the projection is registered in, Chronicle automatically routes the projection to the corresponding inbox sequence — no `[EventSequence]` annotation needed.

When the `[EventStore]` attribute points to the **same** event store as the current one, Chronicle routes to the event log instead.

## When to use `[EventSequence]` explicitly

[Section titled “When to use \[EventSequence\] explicitly”](#when-to-use-eventsequence-explicitly)

* When you need to read from a specific sequence other than the inferred one
* To suppress automatic inbox routing for a projection that handles foreign events
* For projections that target a specialized or partitioned event stream

> **Note:** The old `[FromEventSequence]` attribute has been removed. Use `[EventSequence]` instead.

# From All

`FromAll` is the .NET client name for a projection-wide every-event mapping. Other clients expose the same Chronicle definition through their every-event APIs, so use [From Every Event](/chronicle/projections/model-bound/from-every/) for the portable, multi-client concept.

Use `FromAll` in .NET when you want a property mapping to apply across the event types considered by the projection, especially when defining the projection with the fluent API.

## Fluent .NET Projection

[Section titled “Fluent .NET Projection”](#fluent-net-projection)

The fluent `.FromAll(...)` API maps read model properties from event context for all events in the projection definition.

* C#

Fluent FromAll mapping

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections;

[EventType]
  public record InventoryRegisteredFromAll(string ProductName);

[EventType]
  public record InventoryAdjustedFromAll(int Quantity);

public record InventoryStatusFromAll(
      [property: Key] Guid Id,
      string ProductName,
      DateTimeOffset LastUpdated);

public class InventoryStatusFromAllProjection : IProjectionFor<InventoryStatusFromAll>
  {
      public void Define(IProjectionBuilderFor<InventoryStatusFromAll> builder) => builder
          .From<InventoryRegisteredFromAll>()
          .From<InventoryAdjustedFromAll>()
          .FromAll(_ => _
              .Set(m => m.LastUpdated)
              .ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

Fluent FromAll mapping

@EventType
  data class InventoryRegisteredFromAll(val productName: String)

@EventType
  data class InventoryAdjustedFromAll(val quantity: Int)

data class InventoryStatusFromAll(
      val productName: String = "",
      val lastUpdated: Instant = Instant.EPOCH
  )

class InventoryStatusFromAllProjection : IProjectionFor<InventoryStatusFromAll> {
      override fun define(builder: IProjectionBuilderFor<InventoryStatusFromAll>) {
          builder
              .from(InventoryRegisteredFromAll::class)
              .from(InventoryAdjustedFromAll::class)
              .fromAll { it.set(InventoryStatusFromAll::lastUpdated).toEventContextProperty("occurred") }
      }
  }
  ```

* Java

Fluent FromAll mapping

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

import java.time.Instant;

@EventType
  record InventoryRegisteredFromAll(String productName) {
  }

@EventType
  record InventoryAdjustedFromAll(int quantity) {
  }

class InventoryStatusFromAll {
      public String productName = "";
      public Instant lastUpdated = Instant.EPOCH;
  }

class InventoryStatusFromAllProjection implements IProjectionFor<InventoryStatusFromAll> {
      @Override
      public void define(IProjectionBuilderFor<InventoryStatusFromAll> builder) {
          builder
              .from(InventoryRegisteredFromAll.class)
              .from(InventoryAdjustedFromAll.class)
              .fromAll(all -> {
                  all.set("lastUpdated").toEventContextProperty("occurred");
              });
      }
  }
  ```

* Elixir

Set a property from event context on every event

```elixir
  defmodule MyApp.Events.InventoryRegisteredFromAll do
    use Chronicle.Events.EventType, id: "inventory-registered-from-all-v1"

defstruct [:product_name]
  end

defmodule MyApp.Events.InventoryAdjustedFromAll do
    use Chronicle.Events.EventType, id: "inventory-adjusted-from-all-v1"

defstruct [:quantity]
  end

defmodule MyApp.ReadModels.InventoryStatusFromAll do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{InventoryAdjustedFromAll, InventoryRegisteredFromAll}

defstruct [:id, :product_name, :last_updated]

from InventoryRegisteredFromAll,
      set: [id: :event_source_id, product_name: :product_name]

from InventoryAdjustedFromAll

from_every set: [last_updated: :occurred]
  end
  ```

* TypeScript

```typescript
  import { eventType, Guid, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class InventoryRegisteredFromAll {
      constructor(readonly productName: string) {}
  }

@eventType()
  class InventoryAdjustedFromAll {
      constructor(readonly quantity: number) {}
  }

class InventoryStatusFromAll {
      id: Guid = Guid.empty;
      productName = '';
      lastUpdated = new Date();
  }

@projection()
  class InventoryStatusFromAllProjection implements IProjectionFor<InventoryStatusFromAll> {
      define(builder: IProjectionBuilderFor<InventoryStatusFromAll>): void {
          builder
              .from(InventoryRegisteredFromAll)
              .from(InventoryAdjustedFromAll)
              .fromEvery(_ => _
                  .set(m => m.lastUpdated)
                  .toEventContextProperty('occurred'));
      }
  }
  ```

## Model-Bound Attribute

[Section titled “Model-Bound Attribute”](#model-bound-attribute)

The `[FromAll]` attribute is also available in the .NET model-bound API. Use the no-argument form when the read model property name matches the event payload property name by convention.

* C#

Convention-based FromAll attribute

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record ProductRenamedFromAllConvention(string Name, int Version);

[EventType]
  public record ProductPriceChangedFromAllConvention(decimal Price, int Version);

[FromEvent<ProductRenamedFromAllConvention>]
  [FromEvent<ProductPriceChangedFromAllConvention>]
  public record ProductVersionFromAllConvention
  {
      [Key]
      public Guid Id { get; init; }

public string Name { get; init; } = string.Empty;

public decimal Price { get; init; }

[FromAll]
      public int Version { get; init; }
  }
  ```

* Kotlin

Convention-based FromAll attribute

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromAll
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class ProductRenamedFromAllConvention(val name: String, val version: Int)

@EventType
  data class ProductPriceChangedFromAllConvention(val price: Double, val version: Int)

@ReadModel
  @FromEvent(ProductRenamedFromAllConvention::class)
  @FromEvent(ProductPriceChangedFromAllConvention::class)
  data class ProductVersionFromAllConvention(
      val name: String = "",
      val price: Double = 0.0,

@FromAll
      val version: Int = 0
  )
  ```

* Java

Convention-based FromAll attribute

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromAll;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record ProductRenamedFromAllConvention(String name, int version) {}

@EventType
  record ProductPriceChangedFromAllConvention(double price, int version) {}

@ReadModel
  @FromEvent(eventType = ProductRenamedFromAllConvention.class)
  @FromEvent(eventType = ProductPriceChangedFromAllConvention.class)
  record ProductVersionFromAllConvention(
      String name,
      double price,

@FromAll
      int version
  ) {}
  ```

* Elixir

Every-event mapping alongside per-event convention mapping

```elixir
  defmodule MyApp.Events.ProductRenamedFromAllConvention do
    use Chronicle.Events.EventType, id: "product-renamed-from-all-convention-v1"

defstruct [:name, :version]
  end

defmodule MyApp.Events.ProductPriceChangedFromAllConvention do
    use Chronicle.Events.EventType, id: "product-price-changed-from-all-convention-v1"

defstruct [:price, :version]
  end

defmodule MyApp.ReadModels.ProductVersionFromAllConvention do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{ProductPriceChangedFromAllConvention, ProductRenamedFromAllConvention}

defstruct [:id, :name, :price, :version]

from ProductRenamedFromAllConvention,
      set: [id: :event_source_id, name: :name]

from ProductPriceChangedFromAllConvention,
      set: [id: :event_source_id, price: :price]

# `version` is carried by every event in this projection, so it is mapped
    # once for all of them instead of being repeated in each `from`.
    from_every set: [version: :version]
  end
  ```

* TypeScript

Convention-based fromAll property

```typescript
  import { eventType, fromAll, fromEvent, readModel } from '@cratis/chronicle';

@eventType()
  class ProductRenamedFromAllConvention {
      constructor(
          readonly name: string,
          readonly version: number
      ) {}
  }

@eventType()
  class ProductPriceChangedFromAllConvention {
      constructor(
          readonly price: number,
          readonly version: number
      ) {}
  }

@readModel()
  @fromEvent(ProductRenamedFromAllConvention)
  @fromEvent(ProductPriceChangedFromAllConvention)
  class ProductVersionFromAllConvention {
      name = '';
      price = 0;

@fromAll()
      version = 0;
  }
  ```

For explicit model-bound event payload or event context mappings, prefer `[FromEvery(...)]`. It creates the same every-event projection definition while making the source kind explicit. See [From Every Event](/chronicle/projections/model-bound/from-every/) for examples.

## Choosing Between FromAll And FromEvery

[Section titled “Choosing Between FromAll And FromEvery”](#choosing-between-fromall-and-fromevery)

| API                            | Use it when                                                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `.FromAll(...)`                | You are using the .NET fluent projection API and want to define an all-events mapping in the projection class.           |
| `[FromAll]`                    | You are using .NET model-bound projections and convention-based payload mapping is enough.                               |
| `[FromEvery(...)]`             | You are using .NET model-bound projections and need to name an event payload or event context source explicitly.         |
| Other clients’ every-event API | You are writing Kotlin, Elixir, TypeScript, or another client and the client exposes the concept under a different name. |

## Limitations

[Section titled “Limitations”](#limitations)

* `FromAll` is a .NET client API name, not the portable name used by every client.
* The model-bound `[FromAll]` attribute is best kept to the convention-based form.
* Use an event-specific mapping when a property should update only for selected event types.

# From Every Event

Use an every-event mapping when a read model property should update whenever any event in the projection is processed. This is usually audit metadata such as the last modification time, the latest event sequence number, or the correlation id of the operation that last touched the read model.

Every-event mappings are different from event-specific mappings. A set mapping applies only when its event type is processed. An every-event mapping applies after any event that belongs to the projection.

## Map Event Context

[Section titled “Map Event Context”](#map-event-context)

Event context is the most common source for every-event mappings because every event has the same context shape. This keeps audit fields independent from the event payloads.

* C#

Update an audit timestamp from every event

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record InventoryProductRegisteredForEvery(string ProductName);

[EventType]
  public record InventoryItemsAdjustedForEvery(int Quantity);

[FromEvent<InventoryProductRegisteredForEvery>]
  [FromEvent<InventoryItemsAdjustedForEvery>]
  public record InventoryStatusFromEvery(
      [Key] Guid Id,
      string ProductName,
      [FromEvery(contextProperty: nameof(EventContext.Occurred))]
      DateTimeOffset LastUpdated);
  ```

* Kotlin

Update an audit timestamp from every event

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.FromEvery
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class InventoryProductRegisteredForEvery(val productName: String)

@EventType
  data class InventoryItemsAdjustedForEvery(val quantity: Int)

@ReadModel
  @FromEvent(InventoryProductRegisteredForEvery::class)
  @FromEvent(InventoryItemsAdjustedForEvery::class)
  data class InventoryStatusFromEvery(
      val productName: String = "",

@FromEvery(contextProperty = "occurred")
      val lastUpdated: String = ""
  )
  ```

* Java

Update an audit timestamp from every event

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.FromEvery;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record InventoryProductRegisteredForEvery(String productName) {}

@EventType
  record InventoryItemsAdjustedForEvery(int quantity) {}

@ReadModel
  @FromEvent(eventType = InventoryProductRegisteredForEvery.class)
  @FromEvent(eventType = InventoryItemsAdjustedForEvery.class)
  class InventoryStatusFromEvery {
      public String productName = "";

@FromEvery(contextProperty = "occurred")
      public String lastUpdated = "";
  }
  ```

* Elixir

Update an audit timestamp from every event

```elixir
  defmodule MyApp.Events.InventoryProductRegisteredForEvery do
    use Chronicle.Events.EventType, id: "inventory-product-registered-for-every-v1"

defstruct [:product_name]
  end

defmodule MyApp.Events.InventoryItemsAdjustedForEvery do
    use Chronicle.Events.EventType, id: "inventory-items-adjusted-for-every-v1"

defstruct [:quantity]
  end

defmodule MyApp.ReadModels.InventoryStatusFromEvery do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{InventoryItemsAdjustedForEvery, InventoryProductRegisteredForEvery}

defstruct [:id, :product_name, :last_updated]

from InventoryProductRegisteredForEvery,
      set: [
        id: :event_source_id,
        product_name: :product_name
      ]

from InventoryItemsAdjustedForEvery

from_every set: [last_updated: :occurred]
  end
  ```

* TypeScript

Update an audit timestamp from every event

```typescript
  import { eventType, fromEvent, fromEvery, readModel } from '@cratis/chronicle';

@eventType()
  class InventoryProductRegisteredForEvery {
      constructor(readonly productName: string) {}
  }

@eventType()
  class InventoryItemsAdjustedForEvery {
      constructor(readonly quantity: number) {}
  }

@readModel()
  @fromEvent(InventoryProductRegisteredForEvery)
  @fromEvent(InventoryItemsAdjustedForEvery)
  class InventoryStatusFromEvery {
      productName = '';

@fromEvery(undefined, 'occurred')
      lastUpdated = new Date();
  }
  ```

You can map multiple context fields when the read model needs a small audit trail.

* C#

Track audit metadata from every event

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record AuditableInventoryChangedForEvery(string Reason);

[FromEvent<AuditableInventoryChangedForEvery>]
  public record AuditableInventoryStatusFromEvery(
      [Key] Guid Id,
      [FromEvery(contextProperty: nameof(EventContext.Occurred))]
      DateTimeOffset LastModified,
      [FromEvery(contextProperty: nameof(EventContext.SequenceNumber))]
      EventSequenceNumber LastEventSequence,
      [FromEvery(contextProperty: nameof(EventContext.CorrelationId))]
      string LastCorrelationId);
  ```

* Kotlin

Track audit metadata from every event

@EventType
  data class AuditableInventoryChangedForEvery(val reason: String)

@ReadModel
  @FromEvent(AuditableInventoryChangedForEvery::class)
  data class AuditableInventoryStatusFromEvery(
      @FromEvery(contextProperty = "occurred")
      val lastModified: String = "",

@FromEvery(contextProperty = "sequenceNumber")
      val lastEventSequence: String = "",

@FromEvery(contextProperty = "correlationId")
      val lastCorrelationId: String = ""
  )
  ```

* Java

Track audit metadata from every event

@EventType
  record AuditableInventoryChangedForEvery(String reason) {}

@ReadModel
  @FromEvent(eventType = AuditableInventoryChangedForEvery.class)
  class AuditableInventoryStatusFromEvery {
      @FromEvery(contextProperty = "occurred")
      public String lastModified = "";

@FromEvery(contextProperty = "sequenceNumber")
      public String lastEventSequence = "";

@FromEvery(contextProperty = "correlationId")
      public String lastCorrelationId = "";
  }
  ```

* Elixir

Track audit metadata from every event

```elixir
  defmodule MyApp.Events.AuditableInventoryChangedForEvery do
    use Chronicle.Events.EventType, id: "auditable-inventory-changed-for-every-v1"

defstruct [:reason]
  end

defmodule MyApp.ReadModels.AuditableInventoryStatusFromEvery do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.AuditableInventoryChangedForEvery

defstruct [:id, :last_modified, :last_event_sequence, :last_correlation_id]

from AuditableInventoryChangedForEvery,
      set: [id: :event_source_id]

from_every set: [
      last_modified: :occurred,
      last_event_sequence: "$context.sequenceNumber",
      last_correlation_id: "$context.correlationId"
    ]
  end
  ```

* TypeScript

Track audit metadata from every event

```typescript
  import { eventType, fromEvent, fromEvery, readModel } from '@cratis/chronicle';

@eventType()
  class AuditableInventoryChangedForEvery {
      constructor(readonly reason: string) {}
  }

@readModel()
  @fromEvent(AuditableInventoryChangedForEvery)
  class AuditableInventoryStatusFromEvery {
      @fromEvery(undefined, 'occurred')
      lastModified = new Date();

@fromEvery(undefined, 'sequenceNumber')
      lastEventSequence = 0n;

@fromEvery(undefined, 'correlationId')
      lastCorrelationId = '';
  }
  ```

## Map Event Payload Properties

[Section titled “Map Event Payload Properties”](#map-event-payload-properties)

Every-event mappings can also read from event payload properties. Use this only when each event in the projection carries the same property name and compatible value type.

* C#

Read a shared event property from every event

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

public enum OrderStateFromEvery
  {
      New,
      Confirmed,
      Shipped
  }

[EventType]
  public record OrderConfirmedForEvery(OrderStateFromEvery Status);

[EventType]
  public record OrderShippedForEvery(OrderStateFromEvery Status);

[FromEvent<OrderConfirmedForEvery>]
  [FromEvent<OrderShippedForEvery>]
  public record OrderStatusFromEvery(
      [Key] Guid Id,
      [FromEvery(property: nameof(OrderConfirmedForEvery.Status))]
      OrderStateFromEvery CurrentStatus);
  ```

* Kotlin

Read a shared event property from every event

enum class OrderStateFromEvery {
      New,
      Confirmed,
      Shipped
  }

@EventType
  data class OrderConfirmedForEvery(val status: OrderStateFromEvery)

@EventType
  data class OrderShippedForEvery(val status: OrderStateFromEvery)

@ReadModel
  @FromEvent(OrderConfirmedForEvery::class)
  @FromEvent(OrderShippedForEvery::class)
  data class OrderStatusFromEvery(
      @FromEvery(property = "status")
      val currentStatus: OrderStateFromEvery = OrderStateFromEvery.New
  )
  ```

* Java

Read a shared event property from every event

enum OrderStateFromEvery {
      New,
      Confirmed,
      Shipped
  }

@EventType
  record OrderConfirmedForEvery(OrderStateFromEvery status) {}

@EventType
  record OrderShippedForEvery(OrderStateFromEvery status) {}

@ReadModel
  @FromEvent(eventType = OrderConfirmedForEvery.class)
  @FromEvent(eventType = OrderShippedForEvery.class)
  class OrderStatusFromEvery {
      @FromEvery(property = "status")
      public OrderStateFromEvery currentStatus = OrderStateFromEvery.New;
  }
  ```

* Elixir

Read a shared event property from every event

```elixir
  defmodule MyApp.Events.OrderConfirmedForEvery do
    use Chronicle.Events.EventType, id: "order-confirmed-for-every-v1"

defstruct [:status]
  end

defmodule MyApp.Events.OrderShippedForEvery do
    use Chronicle.Events.EventType, id: "order-shipped-for-every-v1"

defstruct [:status]
  end

defmodule MyApp.ReadModels.OrderStatusFromEvery do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{OrderConfirmedForEvery, OrderShippedForEvery}

defstruct [:id, :current_status]

from OrderConfirmedForEvery,
      set: [id: :event_source_id]

from OrderShippedForEvery

from_every set: [current_status: :status]
  end
  ```

* TypeScript

Read a shared event property from every event

```typescript
  import { eventType, fromEvent, fromEvery, readModel } from '@cratis/chronicle';

enum OrderStateFromEvery {
      New = 'New',
      Confirmed = 'Confirmed',
      Shipped = 'Shipped'
  }

@eventType()
  class OrderConfirmedForEvery {
      constructor(readonly status: OrderStateFromEvery) {}
  }

@eventType()
  class OrderShippedForEvery {
      constructor(readonly status: OrderStateFromEvery) {}
  }

@readModel()
  @fromEvent(OrderConfirmedForEvery)
  @fromEvent(OrderShippedForEvery)
  class OrderStatusFromEvery {
      @fromEvery('status')
      currentStatus = OrderStateFromEvery.New;
  }
  ```

If a client supports convention-based property mapping, omitting the source property uses the read model property name.

* C#

Use the read model property name by convention

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record ProductRenamedForEveryConvention(string Name, int Version);

[EventType]
  public record ProductPriceChangedForEveryConvention(decimal Price, int Version);

[FromEvent<ProductRenamedForEveryConvention>]
  [FromEvent<ProductPriceChangedForEveryConvention>]
  public record ProductVersionFromEveryConvention(
      [Key] Guid Id,
      string Name,
      decimal Price,
      [FromEvery]
      int Version);
  ```

* Kotlin

Use the read model property name by convention

@EventType
  data class ProductRenamedForEveryConvention(val name: String, val version: Int)

@EventType
  data class ProductPriceChangedForEveryConvention(val price: Double, val version: Int)

@ReadModel
  @FromEvent(ProductRenamedForEveryConvention::class)
  @FromEvent(ProductPriceChangedForEveryConvention::class)
  data class ProductVersionFromEveryConvention(
      val name: String = "",
      val price: Double = 0.0,

@FromEvery
      val version: Int = 0
  )
  ```

* Java

Use the read model property name by convention

@EventType
  record ProductRenamedForEveryConvention(String name, int version) {}

@EventType
  record ProductPriceChangedForEveryConvention(double price, int version) {}

@ReadModel
  @FromEvent(eventType = ProductRenamedForEveryConvention.class)
  @FromEvent(eventType = ProductPriceChangedForEveryConvention.class)
  class ProductVersionFromEveryConvention {
      public String name = "";
      public double price = 0.0;

@FromEvery
      public int version = 0;
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

Use the read model property name by convention

```typescript
  import { eventType, fromEvent, fromEvery, readModel } from '@cratis/chronicle';

@eventType()
  class ProductRenamedForEveryConvention {
      constructor(readonly name: string, readonly version: number) {}
  }

@eventType()
  class ProductPriceChangedForEveryConvention {
      constructor(readonly price: number, readonly version: number) {}
  }

@readModel()
  @fromEvent(ProductRenamedForEveryConvention)
  @fromEvent(ProductPriceChangedForEveryConvention)
  class ProductVersionFromEveryConvention {
      name = '';
      price = 0;

@fromEvery()
      version = 0;
  }
  ```

## Combine With Event-Specific Mappings

[Section titled “Combine With Event-Specific Mappings”](#combine-with-event-specific-mappings)

When an event is processed, Chronicle applies the event-specific mappings for that event and the every-event mappings for the projection. This lets the read model update business fields and audit metadata in the same event pass.

* C#

Combine specific mappings with every-event metadata

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record UserRegisteredForEvery(string Name, string Email);

[EventType]
  public record UserNameChangedForEvery(string NewName);

[EventType]
  public record UserEmailChangedForEvery(string NewEmail);

[FromEvent<UserRegisteredForEvery>]
  [FromEvent<UserNameChangedForEvery>]
  [FromEvent<UserEmailChangedForEvery>]
  public record UserProfileFromEvery(
      [Key] Guid Id,
      [SetFrom<UserRegisteredForEvery>(nameof(UserRegisteredForEvery.Name))]
      [SetFrom<UserNameChangedForEvery>(nameof(UserNameChangedForEvery.NewName))]
      string Name,
      [SetFrom<UserRegisteredForEvery>(nameof(UserRegisteredForEvery.Email))]
      [SetFrom<UserEmailChangedForEvery>(nameof(UserEmailChangedForEvery.NewEmail))]
      string Email,
      [FromEvery(contextProperty: nameof(EventContext.Occurred))]
      DateTimeOffset LastUpdated);
  ```

* Kotlin

Combine specific mappings with every-event metadata

@EventType
  data class UserRegisteredForEvery(val name: String, val email: String)

@EventType
  data class UserNameChangedForEvery(val newName: String)

@EventType
  data class UserEmailChangedForEvery(val newEmail: String)

@ReadModel
  @FromEvent(UserRegisteredForEvery::class)
  @FromEvent(UserNameChangedForEvery::class)
  @FromEvent(UserEmailChangedForEvery::class)
  data class UserProfileFromEvery(
      @SetFrom("name", UserRegisteredForEvery::class)
      @SetFrom("newName", UserNameChangedForEvery::class)
      val name: String = "",

@SetFrom("email", UserRegisteredForEvery::class)
      @SetFrom("newEmail", UserEmailChangedForEvery::class)
      val email: String = "",

@FromEvery(contextProperty = "occurred")
      val lastUpdated: String = ""
  )
  ```

* Java

Combine specific mappings with every-event metadata

@EventType
  record UserRegisteredForEvery(String name, String email) {}

@EventType
  record UserNameChangedForEvery(String newName) {}

@EventType
  record UserEmailChangedForEvery(String newEmail) {}

@ReadModel
  @FromEvent(eventType = UserRegisteredForEvery.class)
  @FromEvent(eventType = UserNameChangedForEvery.class)
  @FromEvent(eventType = UserEmailChangedForEvery.class)
  class UserProfileFromEvery {
      @SetFrom(propertyPath = "name", eventType = UserRegisteredForEvery.class)
      @SetFrom(propertyPath = "newName", eventType = UserNameChangedForEvery.class)
      public String name = "";

@SetFrom(propertyPath = "email", eventType = UserRegisteredForEvery.class)
      @SetFrom(propertyPath = "newEmail", eventType = UserEmailChangedForEvery.class)
      public String email = "";

@FromEvery(contextProperty = "occurred")
      public String lastUpdated = "";
  }
  ```

* Elixir

Combine specific mappings with every-event metadata

```elixir
  defmodule MyApp.Events.UserRegisteredForEvery do
    use Chronicle.Events.EventType, id: "user-registered-for-every-v1"

defstruct [:name, :email]
  end

defmodule MyApp.Events.UserNameChangedForEvery do
    use Chronicle.Events.EventType, id: "user-name-changed-for-every-v1"

defstruct [:new_name]
  end

defmodule MyApp.Events.UserEmailChangedForEvery do
    use Chronicle.Events.EventType, id: "user-email-changed-for-every-v1"

defstruct [:new_email]
  end

defmodule MyApp.ReadModels.UserProfileFromEvery do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{UserEmailChangedForEvery, UserNameChangedForEvery, UserRegisteredForEvery}

defstruct [:id, :name, :email, :last_updated]

from UserRegisteredForEvery,
      set: [
        id: :event_source_id,
        name: :name,
        email: :email
      ]

from UserNameChangedForEvery,
      set: [name: :new_name]

from UserEmailChangedForEvery,
      set: [email: :new_email]

from_every set: [last_updated: :occurred]
  end
  ```

* TypeScript

Combine specific mappings with every-event metadata

```typescript
  import { eventType, fromEvent, fromEvery, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class UserRegisteredForEvery {
      constructor(readonly name: string, readonly email: string) {}
  }

@eventType()
  class UserNameChangedForEvery {
      constructor(readonly newName: string) {}
  }

@eventType()
  class UserEmailChangedForEvery {
      constructor(readonly newEmail: string) {}
  }

@readModel()
  @fromEvent(UserRegisteredForEvery)
  @fromEvent(UserNameChangedForEvery)
  @fromEvent(UserEmailChangedForEvery)
  class UserProfileFromEvery {
      @setFrom(UserRegisteredForEvery, 'name')
      @setFrom(UserNameChangedForEvery, 'newName')
      name = '';

@setFrom(UserRegisteredForEvery, 'email')
      @setFrom(UserEmailChangedForEvery, 'newEmail')
      email = '';

@fromEvery(undefined, 'occurred')
      lastUpdated = new Date();
  }
  ```

For example, when the name-change event in the examples above is processed:

1. The name mapping updates the read model’s name.
2. The every-event mapping updates the last-modified field from the event context.

## Declarative Equivalent

[Section titled “Declarative Equivalent”](#declarative-equivalent)

Every-event mappings are part of the projection definition Chronicle receives. Clients that expose both model-bound and standalone projection definitions send the same kind of every-event definition to Chronicle.

* C#

Declarative projection with every-event metadata

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections;

[EventType]
  public record InventoryRegisteredDeclarativeForEvery(string ProductName);

[EventType]
  public record InventoryAdjustedDeclarativeForEvery(int Quantity);

public record InventoryStatusDeclarativeFromEvery(
      [property: Key] Guid Id,
      string ProductName,
      DateTimeOffset LastUpdated);

public class InventoryStatusDeclarativeProjection : IProjectionFor<InventoryStatusDeclarativeFromEvery>
  {
      public void Define(IProjectionBuilderFor<InventoryStatusDeclarativeFromEvery> builder) => builder
          .From<InventoryRegisteredDeclarativeForEvery>()
          .From<InventoryAdjustedDeclarativeForEvery>()
          .FromEvery(_ => _
              .Set(m => m.LastUpdated)
              .ToEventContextProperty(c => c.Occurred));
  }
  ```

* Kotlin

Declarative projection with every-event metadata

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class InventoryRegisteredDeclarativeForEvery(val productName: String)

@EventType
  data class InventoryAdjustedDeclarativeForEvery(val quantity: Int)

data class InventoryStatusDeclarativeFromEvery(
      val productName: String = "",
      val lastUpdated: String = ""
  )

class InventoryStatusDeclarativeProjection : IProjectionFor<InventoryStatusDeclarativeFromEvery> {
      override fun define(builder: IProjectionBuilderFor<InventoryStatusDeclarativeFromEvery>) {
          builder
              .from(InventoryRegisteredDeclarativeForEvery::class)
              .from(InventoryAdjustedDeclarativeForEvery::class)
              .fromEvery { it ->
                  it.set(InventoryStatusDeclarativeFromEvery::lastUpdated).toEventContextProperty("occurred")
              }
      }
  }
  ```

* Java

Declarative projection with every-event metadata

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record InventoryRegisteredDeclarativeForEvery(String productName) {
  }

@EventType
  record InventoryAdjustedDeclarativeForEvery(int quantity) {
  }

class InventoryStatusDeclarativeFromEvery {
      public String productName = "";
      public String lastUpdated = "";
  }

class InventoryStatusDeclarativeProjection implements IProjectionFor<InventoryStatusDeclarativeFromEvery> {
      @Override
      public void define(IProjectionBuilderFor<InventoryStatusDeclarativeFromEvery> builder) {
          builder
              .from(InventoryRegisteredDeclarativeForEvery.class)
              .from(InventoryAdjustedDeclarativeForEvery.class)
              .fromEvery(every -> {
                  every.set("lastUpdated").toEventContextProperty("occurred");
              });
      }
  }
  ```

* Elixir

Declarative projection with every-event metadata

```elixir
  defmodule MyApp.Events.InventoryRegisteredDeclarativeForEvery do
    use Chronicle.Events.EventType, id: "inventory-registered-declarative-for-every-v1"

defstruct [:product_name]
  end

defmodule MyApp.Events.InventoryAdjustedDeclarativeForEvery do
    use Chronicle.Events.EventType, id: "inventory-adjusted-declarative-for-every-v1"

defstruct [:quantity]
  end

defmodule MyApp.ReadModels.InventoryStatusDeclarativeFromEvery do
    use Chronicle.ReadModels.ReadModel

defstruct [:id, :product_name, :last_updated]
  end

defmodule MyApp.Projections.InventoryStatusDeclarativeProjection do
    use Chronicle.Projections.Projection, model: MyApp.ReadModels.InventoryStatusDeclarativeFromEvery

alias MyApp.Events.{InventoryAdjustedDeclarativeForEvery, InventoryRegisteredDeclarativeForEvery}

from InventoryRegisteredDeclarativeForEvery,
      set: [
        id: :event_source_id,
        product_name: :product_name
      ]

from InventoryAdjustedDeclarativeForEvery

from_every set: [last_updated: :occurred]
  end
  ```

* TypeScript

Declarative projection with every-event metadata

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

@eventType()
  class InventoryRegisteredDeclarativeForEvery {
      constructor(readonly productName: string) {}
  }

@eventType()
  class InventoryAdjustedDeclarativeForEvery {
      constructor(readonly quantity: number) {}
  }

@readModel()
  class InventoryStatusDeclarativeFromEvery {
      productName = '';
      lastUpdated = new Date();
  }

@projection('', InventoryStatusDeclarativeFromEvery)
  class InventoryStatusDeclarativeProjection implements IProjectionFor<InventoryStatusDeclarativeFromEvery> {
      define(builder: IProjectionBuilderFor<InventoryStatusDeclarativeFromEvery>): void {
          builder
              .from(InventoryRegisteredDeclarativeForEvery)
              .from(InventoryAdjustedDeclarativeForEvery)
              .fromEvery(_ => _
                  .set(m => m.lastUpdated)
                  .toEventContextProperty('occurred'));
      }
  }
  ```

## Use Cases

[Section titled “Use Cases”](#use-cases)

| Use case                            | Typical source                |
| ----------------------------------- | ----------------------------- |
| Last modification time              | Event context occurrence time |
| Last event sequence                 | Event context sequence number |
| Last operation id                   | Event context correlation id  |
| Current status shared by all events | Event payload property        |

Prefer context properties for audit metadata. Use payload properties only when the event contracts are intentionally consistent. If a property should update only for selected event types, use an event-specific mapping instead.

## Limitations

[Section titled “Limitations”](#limitations)

* Only one every-event mapping can target the same read model property.
* Payload-property mappings are skipped for events that do not carry the source property.
* Child-projection inclusion is client-specific; check the client-specific projection API if you need every-event mappings to include or exclude child projections.

# Joins

Model-bound projections support joining data from different events using the `Join` attribute. This allows you to enrich your read models with data from related events.

## Basic Join

[Section titled “Basic Join”](#basic-join)

The `Join` attribute maps properties from events that are related through a common key:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbJoinsOrderPlaced(Guid CustomerId, decimal Amount);

[EventType]
  public record MbJoinsCustomerCreated(string Name);

public record MbJoinsOrderSummary(
      [Key]
      Guid OrderId,

[SetFrom<MbJoinsOrderPlaced>]
      decimal Amount,

[SetFrom<MbJoinsOrderPlaced>]
      Guid CustomerId,

[Join<MbJoinsCustomerCreated>(
          on: nameof(CustomerId),
          eventPropertyName: nameof(MbJoinsCustomerCreated.Name))]
      string CustomerName);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.Join
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbJoinsOrderPlaced(val customerId: String, val amount: Double)

@EventType
  data class MbJoinsCustomerCreated(val name: String)

@ReadModel
  @FromEvent(MbJoinsOrderPlaced::class)
  data class MbJoinsOrderSummary(
      @SetFrom("amount", MbJoinsOrderPlaced::class)
      val amount: Double = 0.0,

@SetFrom("customerId", MbJoinsOrderPlaced::class)
      val customerId: String = "",

@Join(MbJoinsCustomerCreated::class, on = "customerId", eventPropertyName = "name")
      val customerName: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.Join;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record MbJoinsOrderPlaced(String customerId, double amount) {}

@EventType
  record MbJoinsCustomerCreated(String name) {}

@ReadModel
  @FromEvent(eventType = MbJoinsOrderPlaced.class)
  class MbJoinsOrderSummary {
      @SetFrom(propertyPath = "amount", eventType = MbJoinsOrderPlaced.class)
      public double amount = 0.0;

@SetFrom(propertyPath = "customerId", eventType = MbJoinsOrderPlaced.class)
      public String customerId = "";

@Join(eventType = MbJoinsCustomerCreated.class, on = "customerId", eventPropertyName = "name")
      public String customerName = "";
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.JoinsOrderPlaced do
    use Chronicle.Events.EventType, id: "joins-order-placed-v1"

defstruct [:customer_id, :amount]
  end

defmodule MyApp.Events.JoinsCustomerCreated do
    use Chronicle.Events.EventType, id: "joins-customer-created-v1"

defstruct [:name]
  end

defmodule MyApp.ReadModels.JoinsOrderSummary do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{JoinsOrderPlaced, JoinsCustomerCreated}

defstruct [:order_id, :amount, :customer_id, :customer_name]

from JoinsOrderPlaced,
      set: [order_id: :event_source_id, amount: :amount, customer_id: :customer_id]

join JoinsCustomerCreated,
      on: "customer_id",
      set: [customer_name: :name]
  end
  ```

* TypeScript

```typescript
  import { eventType, Guid, join, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbJoinsOrderPlaced {
      customerId: Guid = Guid.empty;
      amount = 0;
  }

@eventType()
  class MbJoinsCustomerCreated {
      name = '';
  }

@readModel()
  class MbJoinsOrderSummary {
      id: Guid = Guid.empty;

@setFrom(MbJoinsOrderPlaced, 'amount')
      amount = 0;

@setFrom(MbJoinsOrderPlaced, 'customerId')
      customerId: Guid = Guid.empty;

@join(MbJoinsCustomerCreated, 'customerId', 'name')
      customerName = '';
  }
  ```

### Parameters

[Section titled “Parameters”](#parameters)

* **on** (optional): Property on the read model to join on. For root projections, this is typically required unless joining within children
* **eventPropertyName** (optional): Property name on the event. If not specified, uses the read model property name

## Join in Children

[Section titled “Join in Children”](#join-in-children)

Joins work within child collections. When used in children, the `on` parameter is optional if the child has an `identifiedBy` property:

* C#

```csharp
  [EventType]
  public record MbJoinsLineItemAdded(Guid ProductId, int Quantity);

[EventType]
  public record MbJoinsProductUpdated(string ProductName, decimal CurrentPrice);

public record MbJoinsOrder(
      [Key]
      Guid OrderId,

[ChildrenFrom<MbJoinsLineItemAdded>(key: nameof(MbJoinsLineItemAdded.ProductId))]
      IEnumerable<MbJoinsOrderLine> Lines);

// The line's key is the product id, so the join to ProductUpdated (raised on that
  // same product's event source) resolves implicitly through the child's own key.
  public record MbJoinsOrderLine(
      [Key] Guid ProductId,

[SetFrom<MbJoinsLineItemAdded>]
      int Quantity,

[Join<MbJoinsProductUpdated>(eventPropertyName: nameof(MbJoinsProductUpdated.ProductName))]
      string ProductName,

[Join<MbJoinsProductUpdated>(eventPropertyName: nameof(MbJoinsProductUpdated.CurrentPrice))]
      decimal Price);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, join, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbJoinsLineItemAdded {
      productId: Guid = Guid.empty;
      quantity = 0;
  }

@eventType()
  class MbJoinsProductUpdated {
      productName = '';
      currentPrice = 0;
  }

@readModel()
  class MbJoinsOrder {
      id: Guid = Guid.empty;

@childrenFrom(MbJoinsLineItemAdded, 'productId')
      lines: MbJoinsOrderLine[] = [];
  }

// The line's key is the product id, so the join to ProductUpdated (raised on that
  // same product's event source) resolves implicitly through the child's own key.
  class MbJoinsOrderLine {
      id: Guid = Guid.empty;

@setFrom(MbJoinsLineItemAdded, 'quantity')
      quantity = 0;

@join(MbJoinsProductUpdated, undefined, 'productName')
      productName = '';

@join(MbJoinsProductUpdated, undefined, 'currentPrice')
      price = 0;
  }
  ```

## Multiple Joins

[Section titled “Multiple Joins”](#multiple-joins)

You can join with multiple different events:

* C#

```csharp
  [EventType]
  public record MbJoinsMultipleOrderPlaced(Guid CustomerId);

[EventType]
  public record MbJoinsMultipleCustomerCreated(string Name);

[EventType]
  public record MbJoinsCustomerUpdated(string Email);

[EventType]
  public record MbJoinsShippingAddressSet(string Address);

public record MbJoinsEnrichedOrder(
      [Key]
      Guid OrderId,

[SetFrom<MbJoinsMultipleOrderPlaced>]
      Guid CustomerId,

[Join<MbJoinsMultipleCustomerCreated>(on: nameof(CustomerId))]
      string CustomerName,

[Join<MbJoinsCustomerUpdated>(on: nameof(CustomerId))]
      string CustomerEmail,

// ShippingAddressSet is raised on the order's own event source, so it joins on the
      // read model's own key rather than a separate correlating property.
      [Join<MbJoinsShippingAddressSet>(on: nameof(OrderId))]
      string ShippingAddress);
  ```

* Kotlin

@EventType
  data class MbJoinsMultipleOrderPlaced(val customerId: String)

@EventType
  data class MbJoinsMultipleCustomerCreated(val name: String)

@EventType
  data class MbJoinsCustomerUpdated(val email: String)

@EventType
  data class MbJoinsShippingAddressSet(val address: String)

@ReadModel
  @FromEvent(MbJoinsMultipleOrderPlaced::class)
  data class MbJoinsEnrichedOrder(
      @SetFrom("customerId", MbJoinsMultipleOrderPlaced::class)
      val customerId: String = "",

@Join(MbJoinsMultipleCustomerCreated::class, on = "customerId")
      val customerName: String = "",

@Join(MbJoinsCustomerUpdated::class, on = "customerId")
      val customerEmail: String = "",

// ShippingAddressSet is raised on the order's own event source, so it joins on the
      // read model's own event source id rather than a separate correlating property.
      @Join(MbJoinsShippingAddressSet::class)
      val shippingAddress: String = ""
  )
  ```

* Java

@EventType
  record MbJoinsMultipleOrderPlaced(String customerId) {}

@EventType
  record MbJoinsMultipleCustomerCreated(String name) {}

@EventType
  record MbJoinsCustomerUpdated(String email) {}

@EventType
  record MbJoinsShippingAddressSet(String address) {}

@ReadModel
  @FromEvent(eventType = MbJoinsMultipleOrderPlaced.class)
  class MbJoinsEnrichedOrder {
      @SetFrom(propertyPath = "customerId", eventType = MbJoinsMultipleOrderPlaced.class)
      public String customerId = "";

@Join(eventType = MbJoinsMultipleCustomerCreated.class, on = "customerId")
      public String customerName = "";

@Join(eventType = MbJoinsCustomerUpdated.class, on = "customerId")
      public String customerEmail = "";

// ShippingAddressSet is raised on the order's own event source, so it joins on the
      // read model's own event source id rather than a separate correlating property.
      @Join(eventType = MbJoinsShippingAddressSet.class)
      public String shippingAddress = "";
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.JoinsMultipleOrderPlaced do
    use Chronicle.Events.EventType, id: "joins-multiple-order-placed-v1"

defstruct [:customer_id]
  end

defmodule MyApp.Events.JoinsMultipleCustomerCreated do
    use Chronicle.Events.EventType, id: "joins-multiple-customer-created-v1"

defstruct [:name]
  end

defmodule MyApp.Events.JoinsCustomerUpdated do
    use Chronicle.Events.EventType, id: "joins-customer-updated-v1"

defstruct [:email]
  end

defmodule MyApp.Events.JoinsShippingAddressSet do
    use Chronicle.Events.EventType, id: "joins-shipping-address-set-v1"

defstruct [:address]
  end

defmodule MyApp.ReadModels.JoinsEnrichedOrder do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{
      JoinsMultipleOrderPlaced,
      JoinsMultipleCustomerCreated,
      JoinsCustomerUpdated,
      JoinsShippingAddressSet
    }

defstruct [:order_id, :customer_id, :customer_name, :customer_email, :shipping_address]

from JoinsMultipleOrderPlaced,
      set: [order_id: :event_source_id, customer_id: :customer_id]

join JoinsMultipleCustomerCreated,
      on: "customer_id",
      set: [customer_name: :name]

join JoinsCustomerUpdated,
      on: "customer_id",
      set: [customer_email: :email]

# Raised on the order's own event source, so it joins on the read model's
    # own key rather than a separate correlating property.
    join JoinsShippingAddressSet,
      on: "order_id",
      set: [shipping_address: :address]
  end
  ```

* TypeScript

```typescript
  import { eventType, Guid, join, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbJoinsMultipleOrderPlaced {
      customerId: Guid = Guid.empty;
  }

@eventType()
  class MbJoinsMultipleCustomerCreated {
      name = '';
  }

@eventType()
  class MbJoinsCustomerUpdated {
      email = '';
  }

@eventType()
  class MbJoinsShippingAddressSet {
      address = '';
  }

@readModel()
  class MbJoinsEnrichedOrder {
      id: Guid = Guid.empty;

@setFrom(MbJoinsMultipleOrderPlaced, 'customerId')
      customerId: Guid = Guid.empty;

@join(MbJoinsMultipleCustomerCreated, 'customerId', 'name')
      customerName = '';

@join(MbJoinsCustomerUpdated, 'customerId', 'email')
      customerEmail = '';

// ShippingAddressSet is raised on the order's own event source, so it joins on the
      // read model's own key rather than a separate correlating property.
      @join(MbJoinsShippingAddressSet, 'id', 'address')
      shippingAddress = '';
  }
  ```

## Recursive Join Processing

[Section titled “Recursive Join Processing”](#recursive-join-processing)

Join attributes on related types are processed recursively:

* C#

```csharp
  [EventType]
  public record MbJoinsSourcesLineItemAdded(Guid ProductId);

[EventType]
  public record MbJoinsSourcesProductCatalogUpdated(string Name, string Description);

[EventType]
  public record MbJoinsSourcesPricingUpdated(decimal CurrentPrice);

public record MbJoinsSourcesOrder(
      [Key]
      Guid OrderId,

[ChildrenFrom<MbJoinsSourcesLineItemAdded>(key: nameof(MbJoinsSourcesLineItemAdded.ProductId))]
      IEnumerable<MbJoinsSourcesOrderLine> Lines);

// Keyed by product id, so both joins below resolve implicitly through the child's own key.
  public record MbJoinsSourcesOrderLine(
      [Key] Guid ProductId,

[Join<MbJoinsSourcesProductCatalogUpdated>(eventPropertyName: nameof(MbJoinsSourcesProductCatalogUpdated.Name))]
      string ProductName,

[Join<MbJoinsSourcesProductCatalogUpdated>(eventPropertyName: nameof(MbJoinsSourcesProductCatalogUpdated.Description))]
      string Description,

[Join<MbJoinsSourcesPricingUpdated>(eventPropertyName: nameof(MbJoinsSourcesPricingUpdated.CurrentPrice))]
      decimal UnitPrice);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, join, readModel } from '@cratis/chronicle';

@eventType()
  class MbJoinsSourcesLineItemAdded {
      productId: Guid = Guid.empty;
  }

@eventType()
  class MbJoinsSourcesProductCatalogUpdated {
      name = '';
      description = '';
  }

@eventType()
  class MbJoinsSourcesPricingUpdated {
      currentPrice = 0;
  }

@readModel()
  class MbJoinsSourcesOrder {
      id: Guid = Guid.empty;

@childrenFrom(MbJoinsSourcesLineItemAdded, 'productId')
      lines: MbJoinsSourcesOrderLine[] = [];
  }

// Keyed by product id, so both joins below resolve implicitly through the child's own key.
  class MbJoinsSourcesOrderLine {
      id: Guid = Guid.empty;

@join(MbJoinsSourcesProductCatalogUpdated, undefined, 'name')
      productName = '';

@join(MbJoinsSourcesProductCatalogUpdated, undefined, 'description')
      description = '';

@join(MbJoinsSourcesPricingUpdated, undefined, 'currentPrice')
      unitPrice = 0;
  }
  ```

## Complete Example

[Section titled “Complete Example”](#complete-example)

Here’s a comprehensive example showing joins at multiple levels:

* C#

```csharp
  // Events
  [EventType]
  public record MbJoinsFullOrderPlaced(Guid CustomerId, DateTimeOffset PlacedAt);

[EventType]
  public record MbJoinsFullCustomerRegistered(string Name, string Email);

[EventType]
  public record MbJoinsFullCustomerProfileUpdated(string PhoneNumber);

[EventType]
  public record MbJoinsFullLineItemAdded(Guid ProductId, int Quantity);

[EventType]
  public record MbJoinsFullProductCreated(string Name, decimal Price);

[EventType]
  public record MbJoinsFullProductPriceChanged(decimal NewPrice);

// Read Models
  public record MbJoinsFullOrderDetails(
      [Key]
      Guid OrderId,

[SetFrom<MbJoinsFullOrderPlaced>]
      DateTimeOffset PlacedAt,

[SetFrom<MbJoinsFullOrderPlaced>]
      Guid CustomerId,

// Join customer information
      [Join<MbJoinsFullCustomerRegistered>(
          on: nameof(CustomerId),
          eventPropertyName: nameof(MbJoinsFullCustomerRegistered.Name))]
      string CustomerName,

[Join<MbJoinsFullCustomerRegistered>(
          on: nameof(CustomerId),
          eventPropertyName: nameof(MbJoinsFullCustomerRegistered.Email))]
      string CustomerEmail,

[Join<MbJoinsFullCustomerProfileUpdated>(
          on: nameof(CustomerId),
          eventPropertyName: nameof(MbJoinsFullCustomerProfileUpdated.PhoneNumber))]
      string CustomerPhone,

[ChildrenFrom<MbJoinsFullLineItemAdded>(key: nameof(MbJoinsFullLineItemAdded.ProductId))]
      IEnumerable<MbJoinsFullLineItemDetails> Items);

// Keyed by product id, so the joins below resolve implicitly through the child's own key.
  public record MbJoinsFullLineItemDetails(
      [Key] Guid ProductId,

[SetFrom<MbJoinsFullLineItemAdded>]
      int Quantity,

// Join product information
      [Join<MbJoinsFullProductCreated>(eventPropertyName: nameof(MbJoinsFullProductCreated.Name))]
      string ProductName,

[Join<MbJoinsFullProductCreated>(eventPropertyName: nameof(MbJoinsFullProductCreated.Price))]
      [Join<MbJoinsFullProductPriceChanged>(eventPropertyName: nameof(MbJoinsFullProductPriceChanged.NewPrice))]
      decimal Price);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, join, readModel, setFrom } from '@cratis/chronicle';

// Events
  @eventType()
  class MbJoinsFullOrderPlaced {
      customerId: Guid = Guid.empty;
      placedAt = new Date();
  }

@eventType()
  class MbJoinsFullCustomerRegistered {
      name = '';
      email = '';
  }

@eventType()
  class MbJoinsFullCustomerProfileUpdated {
      phoneNumber = '';
  }

@eventType()
  class MbJoinsFullLineItemAdded {
      productId: Guid = Guid.empty;
      quantity = 0;
  }

@eventType()
  class MbJoinsFullProductCreated {
      name = '';
      price = 0;
  }

@eventType()
  class MbJoinsFullProductPriceChanged {
      newPrice = 0;
  }

// Read Models
  @readModel()
  class MbJoinsFullOrderDetails {
      id: Guid = Guid.empty;

@setFrom(MbJoinsFullOrderPlaced, 'placedAt')
      placedAt = new Date();

@setFrom(MbJoinsFullOrderPlaced, 'customerId')
      customerId: Guid = Guid.empty;

// Join customer information
      @join(MbJoinsFullCustomerRegistered, 'customerId', 'name')
      customerName = '';

@join(MbJoinsFullCustomerRegistered, 'customerId', 'email')
      customerEmail = '';

@join(MbJoinsFullCustomerProfileUpdated, 'customerId', 'phoneNumber')
      customerPhone = '';

@childrenFrom(MbJoinsFullLineItemAdded, 'productId')
      items: MbJoinsFullLineItemDetails[] = [];
  }

// Keyed by product id, so the joins below resolve implicitly through the child's own key.
  class MbJoinsFullLineItemDetails {
      id: Guid = Guid.empty;

@setFrom(MbJoinsFullLineItemAdded, 'quantity')
      quantity = 0;

// Join product information
      @join(MbJoinsFullProductCreated, undefined, 'name')
      productName = '';

@join(MbJoinsFullProductCreated, undefined, 'price')
      @join(MbJoinsFullProductPriceChanged, undefined, 'newPrice')
      price = 0;
  }
  ```

## Event Processing Flow

[Section titled “Event Processing Flow”](#event-processing-flow)

1. **CustomerRegistered** - Customer data becomes available for joining
2. **ProductCreated** - Product data becomes available for joining
3. **OrderPlaced** - Order is created, joins pull in customer data
4. **LineItemAdded** - Line item is added, joins pull in product data
5. **ProductPriceChanged** - Updates price on all relevant line items through join
6. **CustomerProfileUpdated** - Updates phone number on all relevant orders through join

## Join vs SetFrom

[Section titled “Join vs SetFrom”](#join-vs-setfrom)

**SetFrom:**

* Maps properties from events directly related to the entity
* Event is “about” the entity (same event source ID)
* Direct parent-child relationship

**Join:**

* Maps properties from events about related entities
* Event is about a different entity but shares a common key
* Used for enrichment and denormalization

## Join Precedence

[Section titled “Join Precedence”](#join-precedence)

When a `Join` and a local mapping — `SetFrom`, or an AutoMapped `FromEvent` property — target the same property, **the joined value wins, regardless of the order the events arrive**. Every time the projection handles one of the read model’s own events, Chronicle re-resolves the join against the last stored event of the joined stream and applies the joined properties *after* the local mappings. Only while the joined stream has no matching event yet does a locally written value stay in place.

Caution

A local mapping cannot reset or clear a property a join has written — there is no “clear this joined value” operation. A `bool` latch that a local event sets and a joined event clears will silently stick on the joined value, even when the local event is the most recent one. If a property must reflect which fact happened most recently, give each fact its own property (for example, two timestamps) and compare them in the query instead. The [CHR0042](/chronicle/code-analysis/chr0042/) analyzer warns when a property is written from both sides.

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Use meaningful join keys** - Ensure the `on` parameter clearly identifies the relationship
2. **Handle missing data** - Joins may not find matching data; consider nullable properties
3. **Be mindful of updates** - Joined data updates when the source event changes
4. **Avoid circular joins** - Don’t create circular dependencies between projections
5. **Consider cardinality** - Joins work best for one-to-one and many-to-one relationships

# Nested Objects

Nested model-bound projections populate a single nullable child object on a read model. Use them when an event should set, update, or clear one scalar object inside the parent, rather than managing a collection of child items.

The current model-bound nested API is available in the .NET client. TypeScript currently rejects `@nested` during projection registration, and the Kotlin and Elixir clients do not expose an equivalent model-bound nested API.

## Basic Lifecycle

[Section titled “Basic Lifecycle”](#basic-lifecycle)

Mark the nullable parent property as nested. The nested type declares the events that populate it and, optionally, the events that clear it.

* C#

Nested object lifecycle

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record CommandSetForNestedBasic(string Name, string Schema);

[EventType]
  public record CommandClearedForNestedBasic;

[FromEvent<CommandSetForNestedBasic>]
  public record SliceWithNestedCommandBasic(
      [Key] Guid Id,
      string Name,
      [Nested] CommandItemNestedBasic? Command);

[FromEvent<CommandSetForNestedBasic>]
  [ClearWith<CommandClearedForNestedBasic>]
  public record CommandItemNestedBasic(
      string Name,
      string Schema);
  ```

* Kotlin

Nested object lifecycle

@EventType
  data class CommandSetForNestedBasic(val name: String, val schema: String)

@EventType
  data class CommandClearedForNestedBasic(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(CommandSetForNestedBasic::class)
  data class SliceWithNestedCommandBasic(
      val name: String = "",

@Nested
      val command: CommandItemNestedBasic? = null
  )

@FromEvent(CommandSetForNestedBasic::class)
  @ClearWith(CommandClearedForNestedBasic::class)
  data class CommandItemNestedBasic(
      val name: String = "",
      val schema: String = ""
  )
  ```

* Java

Nested object lifecycle

@EventType
  record CommandSetForNestedBasic(String name, String schema) {}

@EventType
  record CommandClearedForNestedBasic() {}

@ReadModel
  @FromEvent(eventType = CommandSetForNestedBasic.class)
  record SliceWithNestedCommandBasic(
      String name,

@Nested
      CommandItemNestedBasic command
  ) {}

@FromEvent(eventType = CommandSetForNestedBasic.class)
  @ClearWith(eventType = CommandClearedForNestedBasic.class)
  record CommandItemNestedBasic(String name, String schema) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { clearWith, eventType, fromEvent, Guid, nested, readModel } from '@cratis/chronicle';

@eventType()
  class CommandSetForNestedBasic {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandClearedForNestedBasic {
  }

@fromEvent(CommandSetForNestedBasic)
  @clearWith(CommandClearedForNestedBasic)
  class CommandItemNestedBasic {
      name = '';
      schema = '';
  }

@readModel()
  @fromEvent(CommandSetForNestedBasic)
  class SliceWithNestedCommandBasic {
      id: Guid = Guid.empty;
      name = '';

@nested
      command: CommandItemNestedBasic | null = null;
  }
  ```

The lifecycle is:

1. The first populate event creates the nested object.
2. Later populate events update the existing nested object.
3. A clear event sets the parent property back to `null`.

## Parent Property

[Section titled “Parent Property”](#parent-property)

The nested marker belongs on the single nullable property that holds the child object.

* C#

Nested property on the parent

```csharp
  using Cratis.Chronicle.Projections.ModelBound;

public record ParentWithNestedProperty(
      [Nested] NestedPropertyChild? Child);

public record NestedPropertyChild(
      string Name,
      string Description);
  ```

* Kotlin

Nested property on the parent

```kotlin
  import io.cratis.chronicle.projections.Nested

data class ParentWithNestedProperty(
      @Nested
      val child: NestedPropertyChild? = null
  )

data class NestedPropertyChild(
      val name: String = "",
      val description: String = ""
  )
  ```

* Java

Nested property on the parent

```java
  import io.cratis.chronicle.projections.Nested;

record ParentWithNestedProperty(
      @Nested
      NestedPropertyChild child
  ) {}

record NestedPropertyChild(String name, String description) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { nested } from '@cratis/chronicle';

class NestedPropertyChild {
      name = '';
      description = '';
  }

class ParentWithNestedProperty {
      @nested
      child: NestedPropertyChild | null = null;
  }
  ```

The nested type is scanned for its own model-bound projection annotations, including `FromEvent`, `ClearWith`, and property mappings.

## Clearing Nested Objects

[Section titled “Clearing Nested Objects”](#clearing-nested-objects)

Apply a clear annotation to the nested type when one event should remove the nested object from the parent.

* C#

Clear a nested object

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record CommandSetForNestedClear(string Name, string Schema);

[EventType]
  public record CommandClearedForNestedClear;

[FromEvent<CommandSetForNestedClear>]
  [ClearWith<CommandClearedForNestedClear>]
  public record CommandItemNestedClear(
      string Name,
      string Schema);
  ```

* Kotlin

Clear a nested object

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ClearWith
  import io.cratis.chronicle.projections.FromEvent

@EventType
  data class CommandSetForNestedClear(val name: String, val schema: String)

@EventType
  data class CommandClearedForNestedClear(val placeholder: Boolean = true)

@FromEvent(CommandSetForNestedClear::class)
  @ClearWith(CommandClearedForNestedClear::class)
  data class CommandItemNestedClear(
      val name: String = "",
      val schema: String = ""
  )
  ```

* Java

Clear a nested object

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ClearWith;
  import io.cratis.chronicle.projections.FromEvent;

@EventType
  record CommandSetForNestedClear(String name, String schema) {}

@EventType
  record CommandClearedForNestedClear() {}

@FromEvent(eventType = CommandSetForNestedClear.class)
  @ClearWith(eventType = CommandClearedForNestedClear.class)
  record CommandItemNestedClear(String name, String schema) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { clearWith, eventType, fromEvent } from '@cratis/chronicle';

@eventType()
  class CommandSetForNestedClear {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandClearedForNestedClear {
  }

@fromEvent(CommandSetForNestedClear)
  @clearWith(CommandClearedForNestedClear)
  class CommandItemNestedClear {
      name = '';
      schema = '';
  }
  ```

Use multiple clear annotations when more than one event should clear the same nested object.

* C#

Clear a nested object from multiple events

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record CommandSetForNestedMultipleClear(string Name, string Schema);

[EventType]
  public record CommandClearedForNestedMultipleClear;

[EventType]
  public record SliceArchivedForNestedMultipleClear;

[FromEvent<CommandSetForNestedMultipleClear>]
  [ClearWith<CommandClearedForNestedMultipleClear>]
  [ClearWith<SliceArchivedForNestedMultipleClear>]
  public record CommandItemNestedMultipleClear(
      string Name,
      string Schema);
  ```

* Kotlin

Clear a nested object from multiple events

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ClearWith
  import io.cratis.chronicle.projections.FromEvent

@EventType
  data class CommandSetForNestedMultipleClear(val name: String, val schema: String)

@EventType
  data class CommandClearedForNestedMultipleClear(val placeholder: Boolean = true)

@EventType
  data class SliceArchivedForNestedMultipleClear(val placeholder: Boolean = true)

@FromEvent(CommandSetForNestedMultipleClear::class)
  @ClearWith(CommandClearedForNestedMultipleClear::class)
  @ClearWith(SliceArchivedForNestedMultipleClear::class)
  data class CommandItemNestedMultipleClear(
      val name: String = "",
      val schema: String = ""
  )
  ```

* Java

Clear a nested object from multiple events

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ClearWith;
  import io.cratis.chronicle.projections.FromEvent;

@EventType
  record CommandSetForNestedMultipleClear(String name, String schema) {}

@EventType
  record CommandClearedForNestedMultipleClear() {}

@EventType
  record SliceArchivedForNestedMultipleClear() {}

@FromEvent(eventType = CommandSetForNestedMultipleClear.class)
  @ClearWith(eventType = CommandClearedForNestedMultipleClear.class)
  @ClearWith(eventType = SliceArchivedForNestedMultipleClear.class)
  record CommandItemNestedMultipleClear(String name, String schema) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { clearWith, eventType, fromEvent } from '@cratis/chronicle';

@eventType()
  class CommandSetForNestedMultipleClear {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandClearedForNestedMultipleClear {
  }

@eventType()
  class SliceArchivedForNestedMultipleClear {
  }

@fromEvent(CommandSetForNestedMultipleClear)
  @clearWith(CommandClearedForNestedMultipleClear)
  @clearWith(SliceArchivedForNestedMultipleClear)
  class CommandItemNestedMultipleClear {
      name = '';
      schema = '';
  }
  ```

The same annotation on the *parent property* clears the same nested object. Prefer it when the nested type is shared, so the owner names the event that ends its own relationship and the nested type does not have to know about it. To clear a single member of the nested object rather than the whole object, put the annotation on that member — see [Clearing Values](/chronicle/projections/model-bound/clearing/).

## Updating From Multiple Events

[Section titled “Updating From Multiple Events”](#updating-from-multiple-events)

A nested type can be populated or updated by several events. Matching property names are auto-mapped by default.

* C#

Update a nested object from multiple events

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record CommandSetForNestedMultipleFrom(string Name, string Schema);

[EventType]
  public record CommandRenamedForNestedMultipleFrom(string Name);

[EventType]
  public record CommandSchemaUpdatedForNestedMultipleFrom(string Schema);

[EventType]
  public record CommandClearedForNestedMultipleFrom;

[FromEvent<CommandSetForNestedMultipleFrom>]
  [FromEvent<CommandRenamedForNestedMultipleFrom>]
  [FromEvent<CommandSchemaUpdatedForNestedMultipleFrom>]
  [ClearWith<CommandClearedForNestedMultipleFrom>]
  public record CommandItemNestedMultipleFrom(
      string Name,
      string Schema);
  ```

* Kotlin

Update a nested object from multiple events

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ClearWith
  import io.cratis.chronicle.projections.FromEvent

@EventType
  data class CommandSetForNestedMultipleFrom(val name: String, val schema: String)

@EventType
  data class CommandRenamedForNestedMultipleFrom(val name: String)

@EventType
  data class CommandSchemaUpdatedForNestedMultipleFrom(val schema: String)

@EventType
  data class CommandClearedForNestedMultipleFrom(val placeholder: Boolean = true)

@FromEvent(CommandSetForNestedMultipleFrom::class)
  @FromEvent(CommandRenamedForNestedMultipleFrom::class)
  @FromEvent(CommandSchemaUpdatedForNestedMultipleFrom::class)
  @ClearWith(CommandClearedForNestedMultipleFrom::class)
  data class CommandItemNestedMultipleFrom(
      val name: String = "",
      val schema: String = ""
  )
  ```

* Java

Update a nested object from multiple events

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ClearWith;
  import io.cratis.chronicle.projections.FromEvent;

@EventType
  record CommandSetForNestedMultipleFrom(String name, String schema) {}

@EventType
  record CommandRenamedForNestedMultipleFrom(String name) {}

@EventType
  record CommandSchemaUpdatedForNestedMultipleFrom(String schema) {}

@EventType
  record CommandClearedForNestedMultipleFrom() {}

@FromEvent(eventType = CommandSetForNestedMultipleFrom.class)
  @FromEvent(eventType = CommandRenamedForNestedMultipleFrom.class)
  @FromEvent(eventType = CommandSchemaUpdatedForNestedMultipleFrom.class)
  @ClearWith(eventType = CommandClearedForNestedMultipleFrom.class)
  record CommandItemNestedMultipleFrom(String name, String schema) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { clearWith, eventType, fromEvent } from '@cratis/chronicle';

@eventType()
  class CommandSetForNestedMultipleFrom {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandRenamedForNestedMultipleFrom {
      constructor(readonly name: string) {}
  }

@eventType()
  class CommandSchemaUpdatedForNestedMultipleFrom {
      constructor(readonly schema: string) {}
  }

@eventType()
  class CommandClearedForNestedMultipleFrom {
  }

@fromEvent(CommandSetForNestedMultipleFrom)
  @fromEvent(CommandRenamedForNestedMultipleFrom)
  @fromEvent(CommandSchemaUpdatedForNestedMultipleFrom)
  @clearWith(CommandClearedForNestedMultipleFrom)
  class CommandItemNestedMultipleFrom {
      name = '';
      schema = '';
  }
  ```

When event property names differ from nested object property names, add explicit property mappings to the nested type.

* C#

Explicit mappings on a nested type

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record CommandSetForNestedExplicit(string CommandName, string JsonSchema);

[EventType]
  public record CommandSchemaUpdatedForNestedExplicit(string UpdatedSchema);

[EventType]
  public record CommandClearedForNestedExplicit;

[FromEvent<CommandSetForNestedExplicit>]
  [FromEvent<CommandSchemaUpdatedForNestedExplicit>]
  [ClearWith<CommandClearedForNestedExplicit>]
  public record CommandItemNestedExplicit(
      [SetFrom<CommandSetForNestedExplicit>(nameof(CommandSetForNestedExplicit.CommandName))]
      string Name,
      [SetFrom<CommandSetForNestedExplicit>(nameof(CommandSetForNestedExplicit.JsonSchema))]
      [SetFrom<CommandSchemaUpdatedForNestedExplicit>(nameof(CommandSchemaUpdatedForNestedExplicit.UpdatedSchema))]
      string Schema);
  ```

* Kotlin

Explicit mappings on a nested type

@EventType
  data class CommandSetForNestedExplicit(val commandName: String, val jsonSchema: String)

@EventType
  data class CommandSchemaUpdatedForNestedExplicit(val updatedSchema: String)

@EventType
  data class CommandClearedForNestedExplicit(val placeholder: Boolean = true)

@FromEvent(CommandSetForNestedExplicit::class)
  @FromEvent(CommandSchemaUpdatedForNestedExplicit::class)
  @ClearWith(CommandClearedForNestedExplicit::class)
  data class CommandItemNestedExplicit(
      @SetFrom("commandName", CommandSetForNestedExplicit::class)
      val name: String = "",

@SetFrom("jsonSchema", CommandSetForNestedExplicit::class)
      @SetFrom("updatedSchema", CommandSchemaUpdatedForNestedExplicit::class)
      val schema: String = ""
  )
  ```

* Java

Explicit mappings on a nested type

@EventType
  record CommandSetForNestedExplicit(String commandName, String jsonSchema) {}

@EventType
  record CommandSchemaUpdatedForNestedExplicit(String updatedSchema) {}

@EventType
  record CommandClearedForNestedExplicit() {}

@FromEvent(eventType = CommandSetForNestedExplicit.class)
  @FromEvent(eventType = CommandSchemaUpdatedForNestedExplicit.class)
  @ClearWith(eventType = CommandClearedForNestedExplicit.class)
  record CommandItemNestedExplicit(
      @SetFrom(propertyPath = "commandName", eventType = CommandSetForNestedExplicit.class)
      String name,

@SetFrom(propertyPath = "jsonSchema", eventType = CommandSetForNestedExplicit.class)
      @SetFrom(propertyPath = "updatedSchema", eventType = CommandSchemaUpdatedForNestedExplicit.class)
      String schema
  ) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { clearWith, eventType, fromEvent, setFrom } from '@cratis/chronicle';

@eventType()
  class CommandSetForNestedExplicit {
      constructor(readonly commandName: string, readonly jsonSchema: string) {}
  }

@eventType()
  class CommandSchemaUpdatedForNestedExplicit {
      constructor(readonly updatedSchema: string) {}
  }

@eventType()
  class CommandClearedForNestedExplicit {
  }

@fromEvent(CommandSetForNestedExplicit)
  @fromEvent(CommandSchemaUpdatedForNestedExplicit)
  @clearWith(CommandClearedForNestedExplicit)
  class CommandItemNestedExplicit {
      @setFrom(CommandSetForNestedExplicit, 'commandName')
      name = '';

@setFrom(CommandSetForNestedExplicit, 'jsonSchema')
      @setFrom(CommandSchemaUpdatedForNestedExplicit, 'updatedSchema')
      schema = '';
  }
  ```

## Auto-Mapping

[Section titled “Auto-Mapping”](#auto-mapping)

AutoMap is enabled by default for nested types. Disable it on the nested type when every property should be mapped explicitly.

* C#

Disable AutoMap on a nested type

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record CommandSetForNestedNoAutoMap(string CommandName, string Schema);

[EventType]
  public record CommandClearedForNestedNoAutoMap;

[FromEvent<CommandSetForNestedNoAutoMap>]
  [ClearWith<CommandClearedForNestedNoAutoMap>]
  [NoAutoMap]
  public record CommandItemNestedNoAutoMap(
      [SetFrom<CommandSetForNestedNoAutoMap>(nameof(CommandSetForNestedNoAutoMap.CommandName))]
      string Name,
      [SetFrom<CommandSetForNestedNoAutoMap>(nameof(CommandSetForNestedNoAutoMap.Schema))]
      string Schema);
  ```

* Kotlin

Disable AutoMap on a nested type

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ClearWith
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.NoAutoMap
  import io.cratis.chronicle.projections.SetFrom

@EventType
  data class CommandSetForNestedNoAutoMap(val commandName: String, val schema: String)

@EventType
  data class CommandClearedForNestedNoAutoMap(val placeholder: Boolean = true)

@FromEvent(CommandSetForNestedNoAutoMap::class)
  @ClearWith(CommandClearedForNestedNoAutoMap::class)
  @NoAutoMap
  data class CommandItemNestedNoAutoMap(
      @SetFrom("commandName", CommandSetForNestedNoAutoMap::class)
      val name: String = "",

@SetFrom("schema", CommandSetForNestedNoAutoMap::class)
      val schema: String = ""
  )
  ```

* Java

Disable AutoMap on a nested type

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ClearWith;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.NoAutoMap;
  import io.cratis.chronicle.projections.SetFrom;

@EventType
  record CommandSetForNestedNoAutoMap(String commandName, String schema) {}

@EventType
  record CommandClearedForNestedNoAutoMap() {}

@FromEvent(eventType = CommandSetForNestedNoAutoMap.class)
  @ClearWith(eventType = CommandClearedForNestedNoAutoMap.class)
  @NoAutoMap
  record CommandItemNestedNoAutoMap(
      @SetFrom(propertyPath = "commandName", eventType = CommandSetForNestedNoAutoMap.class)
      String name,

@SetFrom(propertyPath = "schema", eventType = CommandSetForNestedNoAutoMap.class)
      String schema
  ) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Multiple Nested Objects

[Section titled “Multiple Nested Objects”](#multiple-nested-objects)

A parent can hold more than one nested object. Each nested property points to a type with its own event lifecycle.

* C#

Multiple nested objects on one parent

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record CommandSetForNestedMultiple(string Name, string Schema);

[EventType]
  public record CommandClearedForNestedMultiple;

[EventType]
  public record ValidationConfiguredForNestedMultiple(string Rules, bool IsStrict);

[EventType]
  public record ValidationRemovedForNestedMultiple;

public record SliceWithMultipleNestedObjects(
      string Name,
      [Nested] CommandItemNestedMultiple? Command,
      [Nested] ValidationConfigNestedMultiple? Validation);

[FromEvent<CommandSetForNestedMultiple>]
  [ClearWith<CommandClearedForNestedMultiple>]
  public record CommandItemNestedMultiple(string Name, string Schema);

[FromEvent<ValidationConfiguredForNestedMultiple>]
  [ClearWith<ValidationRemovedForNestedMultiple>]
  public record ValidationConfigNestedMultiple(string Rules, bool IsStrict);
  ```

* Kotlin

Multiple nested objects on one parent

@EventType
  data class SliceCreatedForNestedMultiple(val name: String)

@EventType
  data class CommandSetForNestedMultiple(val name: String, val schema: String)

@EventType
  data class CommandClearedForNestedMultiple(val placeholder: Boolean = true)

@EventType
  data class ValidationConfiguredForNestedMultiple(val rules: String, val isStrict: Boolean)

@EventType
  data class ValidationRemovedForNestedMultiple(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(SliceCreatedForNestedMultiple::class)
  data class SliceWithMultipleNestedObjects(
      val name: String = "",

@Nested
      val command: CommandItemNestedMultiple? = null,

@Nested
      val validation: ValidationConfigNestedMultiple? = null
  )

@FromEvent(CommandSetForNestedMultiple::class)
  @ClearWith(CommandClearedForNestedMultiple::class)
  data class CommandItemNestedMultiple(val name: String = "", val schema: String = "")

@FromEvent(ValidationConfiguredForNestedMultiple::class)
  @ClearWith(ValidationRemovedForNestedMultiple::class)
  data class ValidationConfigNestedMultiple(val rules: String = "", val isStrict: Boolean = false)
  ```

* Java

Multiple nested objects on one parent

@EventType
  record SliceCreatedForNestedMultiple(String name) {}

@EventType
  record CommandSetForNestedMultiple(String name, String schema) {}

@EventType
  record CommandClearedForNestedMultiple() {}

@EventType
  record ValidationConfiguredForNestedMultiple(String rules, boolean isStrict) {}

@EventType
  record ValidationRemovedForNestedMultiple() {}

@ReadModel
  @FromEvent(eventType = SliceCreatedForNestedMultiple.class)
  record SliceWithMultipleNestedObjects(
      String name,

@Nested
      CommandItemNestedMultiple command,

@Nested
      ValidationConfigNestedMultiple validation
  ) {}

@FromEvent(eventType = CommandSetForNestedMultiple.class)
  @ClearWith(eventType = CommandClearedForNestedMultiple.class)
  record CommandItemNestedMultiple(String name, String schema) {}

@FromEvent(eventType = ValidationConfiguredForNestedMultiple.class)
  @ClearWith(eventType = ValidationRemovedForNestedMultiple.class)
  record ValidationConfigNestedMultiple(String rules, boolean isStrict) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { clearWith, eventType, fromEvent, nested } from '@cratis/chronicle';

@eventType()
  class CommandSetForNestedMultiple {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class CommandClearedForNestedMultiple {
  }

@eventType()
  class ValidationConfiguredForNestedMultiple {
      constructor(readonly rules: string, readonly isStrict: boolean) {}
  }

@eventType()
  class ValidationRemovedForNestedMultiple {
  }

@fromEvent(CommandSetForNestedMultiple)
  @clearWith(CommandClearedForNestedMultiple)
  class CommandItemNestedMultiple {
      name = '';
      schema = '';
  }

@fromEvent(ValidationConfiguredForNestedMultiple)
  @clearWith(ValidationRemovedForNestedMultiple)
  class ValidationConfigNestedMultiple {
      rules = '';
      isStrict = false;
  }

class SliceWithMultipleNestedObjects {
      name = '';

@nested
      command: CommandItemNestedMultiple | null = null;

@nested
      validation: ValidationConfigNestedMultiple | null = null;
  }
  ```

## Nested Objects Inside Children

[Section titled “Nested Objects Inside Children”](#nested-objects-inside-children)

Nested objects can also appear inside child collection items.

* C#

Nested object inside child collection items

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record TaskAddedForNestedChildren(Guid TaskId, string Title);

[EventType]
  public record TaskAssignedForNestedChildren(Guid TaskId, string Name, string Email);

[EventType]
  public record TaskUnassignedForNestedChildren(Guid TaskId);

public record ProjectWithNestedChildren(
      [Key] Guid Id,
      string Name,
      [ChildrenFrom<TaskAddedForNestedChildren>(key: nameof(TaskAddedForNestedChildren.TaskId))]
      IEnumerable<ProjectTaskWithNestedAssignee> Tasks);

public record ProjectTaskWithNestedAssignee(
      [Key] Guid TaskId,
      string Title,
      [Nested] TaskAssigneeNestedChild? Assignee);

[FromEvent<TaskAssignedForNestedChildren>]
  [ClearWith<TaskUnassignedForNestedChildren>]
  public record TaskAssigneeNestedChild(
      string Name,
      string Email);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `ProjectionsService.collectChildrenMap` only reads `@FromEvent`/`@SetFrom`/aggregate annotations off
  the child element type — it never recurses into a `@Nested` property declared on that child type, so a
  nested object inside a child collection item is never wired up.
  ```

* Java

```text
  Java does not support this workflow yet.
  `ProjectionsService.collectChildrenMap` only reads `@FromEvent`/`@SetFrom`/aggregate annotations off
  the child element type — it never recurses into a `@Nested` property declared on that child type, so a
  nested object inside a child collection item is never wired up.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, clearWith, eventType, fromEvent, Guid, nested } from '@cratis/chronicle';

@eventType()
  class TaskAddedForNestedChildren {
      constructor(readonly taskId: Guid, readonly title: string) {}
  }

@eventType()
  class TaskAssignedForNestedChildren {
      constructor(readonly taskId: Guid, readonly name: string, readonly email: string) {}
  }

@eventType()
  class TaskUnassignedForNestedChildren {
      constructor(readonly taskId: Guid) {}
  }

@fromEvent(TaskAssignedForNestedChildren)
  @clearWith(TaskUnassignedForNestedChildren)
  class TaskAssigneeNestedChild {
      name = '';
      email = '';
  }

class ProjectTaskWithNestedAssignee {
      taskId: Guid = Guid.empty;
      title = '';

@nested
      assignee: TaskAssigneeNestedChild | null = null;
  }

class ProjectWithNestedChildren {
      id: Guid = Guid.empty;
      name = '';

@childrenFrom(TaskAddedForNestedChildren, 'taskId')
      tasks: ProjectTaskWithNestedAssignee[] = [];
  }
  ```

## Complete Example

[Section titled “Complete Example”](#complete-example)

This example shows a parent read model with a command definition that can be set, renamed, updated, and cleared.

* C#

Complete nested object projection

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record SliceCreatedForNestedComplete(string Name);

[EventType]
  public record CommandSetForNestedComplete(
      Guid CommandId,
      string Name,
      string Schema,
      string Rules,
      string StateSchema);

[EventType]
  public record CommandRenamedForNestedComplete(Guid CommandId, string Name);

[EventType]
  public record CommandDefinitionUpdatedForNestedComplete(
      Guid CommandId,
      string Schema,
      string Rules,
      string StateSchema);

[EventType]
  public record CommandClearedForNestedComplete;

[FromEvent<SliceCreatedForNestedComplete>]
  public record SliceNestedComplete(
      [Key] Guid Id,
      string Name,
      [Nested] CommandItemNestedComplete? Command);

[FromEvent<CommandSetForNestedComplete>]
  [FromEvent<CommandRenamedForNestedComplete>]
  [FromEvent<CommandDefinitionUpdatedForNestedComplete>]
  [ClearWith<CommandClearedForNestedComplete>]
  public record CommandItemNestedComplete(
      [SetFrom<CommandSetForNestedComplete>(nameof(CommandSetForNestedComplete.CommandId))]
      Guid Id,
      [SetFrom<CommandSetForNestedComplete>(nameof(CommandSetForNestedComplete.Name))]
      [SetFrom<CommandRenamedForNestedComplete>(nameof(CommandRenamedForNestedComplete.Name))]
      string Name,
      [SetFrom<CommandSetForNestedComplete>(nameof(CommandSetForNestedComplete.Schema))]
      [SetFrom<CommandDefinitionUpdatedForNestedComplete>(nameof(CommandDefinitionUpdatedForNestedComplete.Schema))]
      string Schema,
      [SetFrom<CommandSetForNestedComplete>(nameof(CommandSetForNestedComplete.Rules))]
      [SetFrom<CommandDefinitionUpdatedForNestedComplete>(nameof(CommandDefinitionUpdatedForNestedComplete.Rules))]
      string Rules,
      [SetFrom<CommandSetForNestedComplete>(nameof(CommandSetForNestedComplete.StateSchema))]
      [SetFrom<CommandDefinitionUpdatedForNestedComplete>(nameof(CommandDefinitionUpdatedForNestedComplete.StateSchema))]
      string StateSchema);
  ```

* Kotlin

Complete nested object projection

@EventType
  data class SliceCreatedForNestedComplete(val name: String)

@EventType
  data class CommandSetForNestedComplete(
      val commandId: String,
      val name: String,
      val schema: String,
      val rules: String,
      val stateSchema: String
  )

@EventType
  data class CommandRenamedForNestedComplete(val commandId: String, val name: String)

@EventType
  data class CommandDefinitionUpdatedForNestedComplete(
      val commandId: String,
      val schema: String,
      val rules: String,
      val stateSchema: String
  )

@EventType
  data class CommandClearedForNestedComplete(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(SliceCreatedForNestedComplete::class)
  data class SliceNestedComplete(
      val name: String = "",

@Nested
      val command: CommandItemNestedComplete? = null
  )

@FromEvent(CommandSetForNestedComplete::class)
  @FromEvent(CommandRenamedForNestedComplete::class)
  @FromEvent(CommandDefinitionUpdatedForNestedComplete::class)
  @ClearWith(CommandClearedForNestedComplete::class)
  data class CommandItemNestedComplete(
      @SetFrom("commandId", CommandSetForNestedComplete::class)
      val id: String = "",

@SetFrom("name", CommandSetForNestedComplete::class)
      @SetFrom("name", CommandRenamedForNestedComplete::class)
      val name: String = "",

@SetFrom("schema", CommandSetForNestedComplete::class)
      @SetFrom("schema", CommandDefinitionUpdatedForNestedComplete::class)
      val schema: String = "",

@SetFrom("rules", CommandSetForNestedComplete::class)
      @SetFrom("rules", CommandDefinitionUpdatedForNestedComplete::class)
      val rules: String = "",

@SetFrom("stateSchema", CommandSetForNestedComplete::class)
      @SetFrom("stateSchema", CommandDefinitionUpdatedForNestedComplete::class)
      val stateSchema: String = ""
  )
  ```

* Java

Complete nested object projection

@EventType
  record SliceCreatedForNestedComplete(String name) {}

@EventType
  record CommandSetForNestedComplete(
      String commandId,
      String name,
      String schema,
      String rules,
      String stateSchema
  ) {}

@EventType
  record CommandRenamedForNestedComplete(String commandId, String name) {}

@EventType
  record CommandDefinitionUpdatedForNestedComplete(
      String commandId,
      String schema,
      String rules,
      String stateSchema
  ) {}

@EventType
  record CommandClearedForNestedComplete() {}

@ReadModel
  @FromEvent(eventType = SliceCreatedForNestedComplete.class)
  record SliceNestedComplete(
      String name,

@Nested
      CommandItemNestedComplete command
  ) {}

@FromEvent(eventType = CommandSetForNestedComplete.class)
  @FromEvent(eventType = CommandRenamedForNestedComplete.class)
  @FromEvent(eventType = CommandDefinitionUpdatedForNestedComplete.class)
  @ClearWith(eventType = CommandClearedForNestedComplete.class)
  record CommandItemNestedComplete(
      @SetFrom(propertyPath = "commandId", eventType = CommandSetForNestedComplete.class)
      String id,

@SetFrom(propertyPath = "name", eventType = CommandSetForNestedComplete.class)
      @SetFrom(propertyPath = "name", eventType = CommandRenamedForNestedComplete.class)
      String name,

@SetFrom(propertyPath = "schema", eventType = CommandSetForNestedComplete.class)
      @SetFrom(propertyPath = "schema", eventType = CommandDefinitionUpdatedForNestedComplete.class)
      String schema,

@SetFrom(propertyPath = "rules", eventType = CommandSetForNestedComplete.class)
      @SetFrom(propertyPath = "rules", eventType = CommandDefinitionUpdatedForNestedComplete.class)
      String rules,

@SetFrom(propertyPath = "stateSchema", eventType = CommandSetForNestedComplete.class)
      @SetFrom(propertyPath = "stateSchema", eventType = CommandDefinitionUpdatedForNestedComplete.class)
      String stateSchema
  ) {}
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { clearWith, eventType, fromEvent, Guid, nested, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class SliceCreatedForNestedComplete {
      constructor(readonly name: string) {}
  }

@eventType()
  class CommandSetForNestedComplete {
      constructor(
          readonly commandId: Guid,
          readonly name: string,
          readonly schema: string,
          readonly rules: string,
          readonly stateSchema: string
      ) {}
  }

@eventType()
  class CommandRenamedForNestedComplete {
      constructor(readonly commandId: Guid, readonly name: string) {}
  }

@eventType()
  class CommandDefinitionUpdatedForNestedComplete {
      constructor(
          readonly commandId: Guid,
          readonly schema: string,
          readonly rules: string,
          readonly stateSchema: string
      ) {}
  }

@eventType()
  class CommandClearedForNestedComplete {
  }

@fromEvent(CommandSetForNestedComplete)
  @fromEvent(CommandRenamedForNestedComplete)
  @fromEvent(CommandDefinitionUpdatedForNestedComplete)
  @clearWith(CommandClearedForNestedComplete)
  class CommandItemNestedComplete {
      @setFrom(CommandSetForNestedComplete, 'commandId')
      id: Guid = Guid.empty;

@setFrom(CommandSetForNestedComplete, 'name')
      @setFrom(CommandRenamedForNestedComplete, 'name')
      name = '';

@setFrom(CommandSetForNestedComplete, 'schema')
      @setFrom(CommandDefinitionUpdatedForNestedComplete, 'schema')
      schema = '';

@setFrom(CommandSetForNestedComplete, 'rules')
      @setFrom(CommandDefinitionUpdatedForNestedComplete, 'rules')
      rules = '';

@setFrom(CommandSetForNestedComplete, 'stateSchema')
      @setFrom(CommandDefinitionUpdatedForNestedComplete, 'stateSchema')
      stateSchema = '';
  }

@readModel()
  @fromEvent(SliceCreatedForNestedComplete)
  class SliceNestedComplete {
      id: Guid = Guid.empty;
      name = '';

@nested
      command: CommandItemNestedComplete | null = null;
  }
  ```

| Event                                       | Effect on the nested object                                       |
| ------------------------------------------- | ----------------------------------------------------------------- |
| `SliceCreatedForNestedComplete`             | Creates the parent read model; the nested command remains `null`. |
| `CommandSetForNestedComplete`               | Populates the command object.                                     |
| `CommandRenamedForNestedComplete`           | Updates the command name in place.                                |
| `CommandDefinitionUpdatedForNestedComplete` | Updates command definition fields in place.                       |
| `CommandClearedForNestedComplete`           | Sets the command property to `null`.                              |

## Supported Nested Annotations

[Section titled “Supported Nested Annotations”](#supported-nested-annotations)

| Annotation                           | Works on nested type |
| ------------------------------------ | -------------------- |
| `FromEvent`                          | Yes                  |
| `ClearWith`                          | Yes                  |
| `SetFrom`                            | Yes                  |
| `AddFrom` / `SubtractFrom`           | Yes                  |
| `SetFromContext`                     | Yes                  |
| `Increment` / `Decrement` / `Count`  | Yes                  |
| `Join`                               | Yes                  |
| `Nested` recursively                 | Yes                  |
| `ChildrenFrom` inside nested objects | Yes                  |
| `NoAutoMap`                          | Yes                  |

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. Declare the nested property as nullable because it starts empty and is populated by events.
2. Keep the populate and clear annotations close to the nested type so its lifecycle is visible.
3. Rely on AutoMap when event and nested property names match.
4. Use a child collection instead when there can be multiple independent child objects.

## See Also

[Section titled “See Also”](#see-also)

* [Children Collections](/chronicle/projections/model-bound/children/) — arrays of items managed independently within a parent
* [Basic Mapping](/chronicle/projections/model-bound/basic-mapping/) — getting started with model-bound projections
* [Removal](/chronicle/projections/model-bound/removal/) — removing root read models on an event

# Not Rewindable

Mark a projection as not rewindable (forward-only) using `[NotRewindable]`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbNotRewindableAuditEvent(string Message, DateTimeOffset OccurredAt);

[NotRewindable]
  public record MbNotRewindableAuditLog(
      [Key]
      Guid Id,

[SetFrom<MbNotRewindableAuditEvent>(nameof(MbNotRewindableAuditEvent.Message))]
      string Message,

[SetFrom<MbNotRewindableAuditEvent>(nameof(MbNotRewindableAuditEvent.OccurredAt))]
      DateTimeOffset Timestamp);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.NotRewindable
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbNotRewindableAuditEvent(val message: String, val occurredAt: String)

@ReadModel
  @FromEvent(MbNotRewindableAuditEvent::class)
  @NotRewindable
  data class MbNotRewindableAuditLog(
      @SetFrom("message", MbNotRewindableAuditEvent::class)
      val message: String = "",

@SetFrom("occurredAt", MbNotRewindableAuditEvent::class)
      val timestamp: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.NotRewindable;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record MbNotRewindableAuditEvent(String message, String occurredAt) {}

@ReadModel
  @FromEvent(eventType = MbNotRewindableAuditEvent.class)
  @NotRewindable
  class MbNotRewindableAuditLog {
      @SetFrom(propertyPath = "message", eventType = MbNotRewindableAuditEvent.class)
      public String message = "";

@SetFrom(propertyPath = "occurredAt", eventType = MbNotRewindableAuditEvent.class)
      public String timestamp = "";
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, Guid, notRewindable, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbNotRewindableAuditEvent {
      message = '';
      occurredAt = new Date();
  }

@readModel()
  @notRewindable
  class MbNotRewindableAuditLog {
      id: Guid = Guid.empty;

@setFrom(MbNotRewindableAuditEvent, 'message')
      message = '';

@setFrom(MbNotRewindableAuditEvent, 'occurredAt')
      timestamp = new Date();
  }
  ```

## When to use

[Section titled “When to use”](#when-to-use)

* Audit logs or append-only data
* Projections that should never be replayed from scratch
* Time-sensitive data where replay would be incorrect

## Best practices

[Section titled “Best practices”](#best-practices)

* Use for append-only scenarios where historical replay would be problematic
* Consider carefully as this removes the ability to rebuild the projection from scratch
* Ensure you have alternative recovery strategies if the projection becomes corrupted

# Passive Projections

Mark a projection as passive (not actively observing) using `[Passive]`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;
  using Cratis.Chronicle.ReadModels;

[EventType]
  public record MbPassiveSnapshotCreated(string Data);

[Passive]
  public record MbPassiveHistoricalSnapshot(
      [Key]
      Guid Id,

[SetFrom<MbPassiveSnapshotCreated>(nameof(MbPassiveSnapshotCreated.Data))]
      string Data);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.Passive
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbPassiveSnapshotCreated(val data: String)

@Passive
  @ReadModel
  @FromEvent(MbPassiveSnapshotCreated::class)
  data class MbPassiveHistoricalSnapshot(
      @SetFrom("data", MbPassiveSnapshotCreated::class)
      val data: String = ""
  )
  ```

* Java

@EventType
  record MbPassiveSnapshotCreated(String data) {}

@Passive
  @ReadModel
  @FromEvent(eventType = MbPassiveSnapshotCreated.class)
  class MbPassiveHistoricalSnapshot {
      @SetFrom(propertyPath = "data", eventType = MbPassiveSnapshotCreated.class)
      public String data = "";
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.PassiveSnapshotCreated do
    use Chronicle.Events.EventType, id: "passive-snapshot-created-v1"

defstruct [:data]
  end

defmodule MyApp.ReadModels.PassiveHistoricalSnapshot do
    use Chronicle.ReadModels.ReadModel, passive: true

alias MyApp.Events.PassiveSnapshotCreated

defstruct [:id, :data]

from PassiveSnapshotCreated,
      set: [id: :event_source_id, data: :data]
  end
  ```

* TypeScript

```typescript
  import { eventType, Guid, passive, readModel, setFrom } from '@cratis/chronicle';

@eventType()
  class MbPassiveSnapshotCreated {
      data = '';
  }

@readModel()
  @passive
  class MbPassiveHistoricalSnapshot {
      id: Guid = Guid.empty;

@setFrom(MbPassiveSnapshotCreated, 'data')
      data = '';
  }
  ```

## When to use

[Section titled “When to use”](#when-to-use)

* On-demand projections that are only rebuilt when explicitly requested
* Historical snapshots
* Resource-intensive projections that shouldn’t run continuously

## Best practices

[Section titled “Best practices”](#best-practices)

* Use for expensive projections that are only needed occasionally
* Consider the trade-off between resource usage and data freshness
* Ensure you have mechanisms to trigger rebuilds when needed

# Removing Read Models

Model-bound projections support removing read models and child items through the `RemovedWith` and `RemovedWithJoin` attributes. These can be applied at both the class level (for root read models and child types) and on properties/parameters (for child collections).

## Removing Root Read Models

[Section titled “Removing Root Read Models”](#removing-root-read-models)

Use `RemovedWith` at the class level to specify which event removes the entire read model instance:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbRemovalAccountOpened(string Name, decimal Balance);

[EventType]
  public record MbRemovalAccountClosed;

[RemovedWith<MbRemovalAccountClosed>]
  public record MbRemovalAccount(
      [Key]
      Guid Id,

[SetFrom<MbRemovalAccountOpened>(nameof(MbRemovalAccountOpened.Name))]
      string Name,

[SetFrom<MbRemovalAccountOpened>(nameof(MbRemovalAccountOpened.Balance))]
      decimal Balance);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWith
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbRemovalAccountOpened(val name: String, val balance: Double)

@EventType
  class MbRemovalAccountClosed

@ReadModel
  @FromEvent(MbRemovalAccountOpened::class)
  @RemovedWith(MbRemovalAccountClosed::class)
  data class MbRemovalAccount(
      @SetFrom("name", MbRemovalAccountOpened::class)
      val name: String = "",

@SetFrom("balance", MbRemovalAccountOpened::class)
      val balance: Double = 0.0
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWith;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record MbRemovalAccountOpened(String name, double balance) {}

@EventType
  class MbRemovalAccountClosed {}

@ReadModel
  @FromEvent(eventType = MbRemovalAccountOpened.class)
  @RemovedWith(eventType = MbRemovalAccountClosed.class)
  class MbRemovalAccount {
      @SetFrom(propertyPath = "name", eventType = MbRemovalAccountOpened.class)
      public String name = "";

@SetFrom(propertyPath = "balance", eventType = MbRemovalAccountOpened.class)
      public double balance = 0.0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.RemovalAccountOpened do
    use Chronicle.Events.EventType, id: "removal-account-opened-v1"

defstruct [:name, :balance]
  end

defmodule MyApp.Events.RemovalAccountClosed do
    use Chronicle.Events.EventType, id: "removal-account-closed-v1"

defstruct []
  end

defmodule MyApp.ReadModels.RemovalAccount do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{RemovalAccountOpened, RemovalAccountClosed}

defstruct [:id, :name, :balance]

from RemovalAccountOpened,
      set: [id: :event_source_id, name: :name, balance: :balance]

removed_with RemovalAccountClosed, []
  end
  ```

* TypeScript

```typescript
  import { eventType, Guid, readModel, removedWith, setFrom } from '@cratis/chronicle';

@eventType()
  class MbRemovalAccountOpened {
      name = '';
      balance = 0;
  }

@eventType()
  class MbRemovalAccountClosed {
  }

@readModel()
  @removedWith(MbRemovalAccountClosed)
  class MbRemovalAccount {
      id: Guid = Guid.empty;

@setFrom(MbRemovalAccountOpened, 'name')
      name = '';

@setFrom(MbRemovalAccountOpened, 'balance')
      balance = 0;
  }
  ```

When an `AccountClosed` event occurs, the corresponding `Account` read model is removed from the store.

### With Custom Key

[Section titled “With Custom Key”](#with-custom-key)

You can specify which property on the event identifies the read model to remove:

* C#

```csharp
  [EventType]
  public record MbRemovalWithKeyAccountOpened(string Name);

[EventType]
  public record MbRemovalWithKeyAccountClosed(Guid AccountId);

[RemovedWith<MbRemovalWithKeyAccountClosed>(key: nameof(MbRemovalWithKeyAccountClosed.AccountId))]
  public record MbRemovalWithKeyAccount(
      [Key]
      Guid Id,

[SetFrom<MbRemovalWithKeyAccountOpened>(nameof(MbRemovalWithKeyAccountOpened.Name))]
      string Name);
  ```

* Kotlin

@EventType
  data class MbRemovalWithKeyAccountOpened(val name: String)

@EventType
  data class MbRemovalWithKeyAccountClosed(val accountId: String)

@ReadModel
  @FromEvent(MbRemovalWithKeyAccountOpened::class)
  @RemovedWith(MbRemovalWithKeyAccountClosed::class, key = "accountId")
  data class MbRemovalWithKeyAccount(
      @SetFrom("name", MbRemovalWithKeyAccountOpened::class)
      val name: String = ""
  )
  ```

* Java

@EventType
  record MbRemovalWithKeyAccountOpened(String name) {}

@EventType
  record MbRemovalWithKeyAccountClosed(String accountId) {}

@ReadModel
  @FromEvent(eventType = MbRemovalWithKeyAccountOpened.class)
  @RemovedWith(eventType = MbRemovalWithKeyAccountClosed.class, key = "accountId")
  class MbRemovalWithKeyAccount {
      @SetFrom(propertyPath = "name", eventType = MbRemovalWithKeyAccountOpened.class)
      public String name = "";
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.RemovalWithKeyAccountOpened do
    use Chronicle.Events.EventType, id: "removal-with-key-account-opened-v1"

defstruct [:name]
  end

defmodule MyApp.Events.RemovalWithKeyAccountClosed do
    use Chronicle.Events.EventType, id: "removal-with-key-account-closed-v1"

defstruct [:account_id]
  end

defmodule MyApp.ReadModels.RemovalWithKeyAccount do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{RemovalWithKeyAccountOpened, RemovalWithKeyAccountClosed}

defstruct [:id, :name]

from RemovalWithKeyAccountOpened,
      set: [id: :event_source_id, name: :name]

removed_with RemovalWithKeyAccountClosed, key: :account_id
  end
  ```

* TypeScript

```typescript
  import { eventType, Guid, readModel, removedWith, setFrom } from '@cratis/chronicle';

@eventType()
  class MbRemovalWithKeyAccountOpened {
      name = '';
  }

@eventType()
  class MbRemovalWithKeyAccountClosed {
      accountId: Guid = Guid.empty;
  }

@readModel()
  @removedWith(MbRemovalWithKeyAccountClosed, 'accountId')
  class MbRemovalWithKeyAccount {
      id: Guid = Guid.empty;

@setFrom(MbRemovalWithKeyAccountOpened, 'name')
      name = '';
  }
  ```

## Multiple Removal Options

[Section titled “Multiple Removal Options”](#multiple-removal-options)

A read model can be removed by multiple different events:

* C#

```csharp
  [EventType]
  public record MbRemovalMultipleAccountOpened(string Name);

[EventType]
  public record MbRemovalMultipleAccountClosed;

[EventType]
  public record MbRemovalMultipleAccountMerged(Guid SourceAccountId);

[EventType]
  public record MbRemovalMultipleOrganizationClosed;

[RemovedWith<MbRemovalMultipleAccountClosed>]
  [RemovedWith<MbRemovalMultipleAccountMerged>(key: nameof(MbRemovalMultipleAccountMerged.SourceAccountId))]
  [RemovedWithJoin<MbRemovalMultipleOrganizationClosed>]
  public record MbRemovalMultipleAccount(
      [Key]
      Guid Id,

[SetFrom<MbRemovalMultipleAccountOpened>(nameof(MbRemovalMultipleAccountOpened.Name))]
      string Name);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWith
  import io.cratis.chronicle.projections.RemovedWithJoin
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbRemovalMultipleAccountOpened(val name: String)

@EventType
  class MbRemovalMultipleAccountClosed

@EventType
  data class MbRemovalMultipleAccountMerged(val sourceAccountId: String)

@EventType
  class MbRemovalMultipleOrganizationClosed

@ReadModel
  @FromEvent(MbRemovalMultipleAccountOpened::class)
  @RemovedWith(MbRemovalMultipleAccountClosed::class)
  @RemovedWith(MbRemovalMultipleAccountMerged::class, key = "sourceAccountId")
  @RemovedWithJoin(MbRemovalMultipleOrganizationClosed::class)
  data class MbRemovalMultipleAccount(
      @SetFrom("name", MbRemovalMultipleAccountOpened::class)
      val name: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWith;
  import io.cratis.chronicle.projections.RemovedWithJoin;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record MbRemovalMultipleAccountOpened(String name) {}

@EventType
  class MbRemovalMultipleAccountClosed {}

@EventType
  record MbRemovalMultipleAccountMerged(String sourceAccountId) {}

@EventType
  class MbRemovalMultipleOrganizationClosed {}

@ReadModel
  @FromEvent(eventType = MbRemovalMultipleAccountOpened.class)
  @RemovedWith(eventType = MbRemovalMultipleAccountClosed.class)
  @RemovedWith(eventType = MbRemovalMultipleAccountMerged.class, key = "sourceAccountId")
  @RemovedWithJoin(eventType = MbRemovalMultipleOrganizationClosed.class)
  class MbRemovalMultipleAccount {
      @SetFrom(propertyPath = "name", eventType = MbRemovalMultipleAccountOpened.class)
      public String name = "";
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, Guid, readModel, removedWith, removedWithJoin, setFrom } from '@cratis/chronicle';

@eventType()
  class MbRemovalMultipleAccountOpened {
      name = '';
  }

@eventType()
  class MbRemovalMultipleAccountClosed {
  }

@eventType()
  class MbRemovalMultipleAccountMerged {
      sourceAccountId: Guid = Guid.empty;
  }

@eventType()
  class MbRemovalMultipleOrganizationClosed {
  }

@readModel()
  @removedWith(MbRemovalMultipleAccountClosed)
  @removedWith(MbRemovalMultipleAccountMerged, 'sourceAccountId')
  @removedWithJoin(MbRemovalMultipleOrganizationClosed)
  class MbRemovalMultipleAccount {
      id: Guid = Guid.empty;

@setFrom(MbRemovalMultipleAccountOpened, 'name')
      name = '';
  }
  ```

In this example, an account can be removed by:

* An `AccountClosed` event (direct removal)
* An `AccountMerged` event when it’s the source account
* An `OrganizationClosed` event through a join relationship

## RemovedWithJoin

[Section titled “RemovedWithJoin”](#removedwithjoin)

Use `RemovedWithJoin` when the removal event comes from a different stream (join relationship):

* C#

```csharp
  [EventType]
  public record MbRemovalJoinClassEmployeeHired(string Name);

[EventType]
  public record MbRemovalJoinClassCompanyRegistered(string Name);

[EventType]
  public record MbRemovalJoinClassCompanyDissolved;

[RemovedWithJoin<MbRemovalJoinClassCompanyDissolved>]
  public record MbRemovalJoinClassEmployee(
      [Key]
      Guid Id,

[SetFrom<MbRemovalJoinClassEmployeeHired>(nameof(MbRemovalJoinClassEmployeeHired.Name))]
      string Name,

[Join<MbRemovalJoinClassCompanyRegistered>(eventPropertyName: nameof(MbRemovalJoinClassCompanyRegistered.Name))]
      string CompanyName);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.Join
  import io.cratis.chronicle.projections.RemovedWithJoin
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbRemovalJoinClassEmployeeHired(val name: String)

@EventType
  data class MbRemovalJoinClassCompanyRegistered(val name: String)

@EventType
  class MbRemovalJoinClassCompanyDissolved

@ReadModel
  @FromEvent(MbRemovalJoinClassEmployeeHired::class)
  @RemovedWithJoin(MbRemovalJoinClassCompanyDissolved::class)
  data class MbRemovalJoinClassEmployee(
      @SetFrom("name", MbRemovalJoinClassEmployeeHired::class)
      val name: String = "",

@Join(MbRemovalJoinClassCompanyRegistered::class, eventPropertyName = "name")
      val companyName: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.Join;
  import io.cratis.chronicle.projections.RemovedWithJoin;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record MbRemovalJoinClassEmployeeHired(String name) {}

@EventType
  record MbRemovalJoinClassCompanyRegistered(String name) {}

@EventType
  class MbRemovalJoinClassCompanyDissolved {}

@ReadModel
  @FromEvent(eventType = MbRemovalJoinClassEmployeeHired.class)
  @RemovedWithJoin(eventType = MbRemovalJoinClassCompanyDissolved.class)
  class MbRemovalJoinClassEmployee {
      @SetFrom(propertyPath = "name", eventType = MbRemovalJoinClassEmployeeHired.class)
      public String name = "";

@Join(eventType = MbRemovalJoinClassCompanyRegistered.class, eventPropertyName = "name")
      public String companyName = "";
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, Guid, join, readModel, removedWithJoin, setFrom } from '@cratis/chronicle';

@eventType()
  class MbRemovalJoinClassEmployeeHired {
      name = '';
  }

@eventType()
  class MbRemovalJoinClassCompanyRegistered {
      name = '';
  }

@eventType()
  class MbRemovalJoinClassCompanyDissolved {
  }

@readModel()
  @removedWithJoin(MbRemovalJoinClassCompanyDissolved)
  class MbRemovalJoinClassEmployee {
      id: Guid = Guid.empty;

@setFrom(MbRemovalJoinClassEmployeeHired, 'name')
      name = '';

@join(MbRemovalJoinClassCompanyRegistered, undefined, 'name')
      companyName = '';
  }
  ```

When the company is dissolved, all employees associated with that company are removed.

## Removing Children

[Section titled “Removing Children”](#removing-children)

Children can be removed in two ways:

### Property-Level Removal

[Section titled “Property-Level Removal”](#property-level-removal)

Apply `RemovedWith` on the collection property alongside `ChildrenFrom`:

* C#

```csharp
  [EventType]
  public record MbChildrenRemovalPropertyLineItemAdded(Guid ItemId, string Description);

[EventType]
  public record MbChildrenRemovalPropertyLineItemRemoved(Guid ItemId);

public record MbChildrenRemovalPropertyOrder(
      [Key] Guid Id,

public record MbChildrenRemovalPropertyOrderLine(
      [Key] Guid Id,
      string Description);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ChildrenFrom
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWith
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbChildrenRemovalPropertyLineItemAdded(val itemId: String, val description: String)

@EventType
  data class MbChildrenRemovalPropertyLineItemRemoved(val itemId: String)

data class MbChildrenRemovalPropertyOrderLine(
      val itemId: String = "",

@SetFrom("description", MbChildrenRemovalPropertyLineItemAdded::class)
      val description: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ChildrenFrom;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWith;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.Collections;
  import java.util.List;

@EventType
  record MbChildrenRemovalPropertyLineItemAdded(String itemId, String description) {}

@EventType
  record MbChildrenRemovalPropertyLineItemRemoved(String itemId) {}

class MbChildrenRemovalPropertyOrderLine {
      public String itemId = "";

@SetFrom(propertyPath = "description", eventType = MbChildrenRemovalPropertyLineItemAdded.class)
      public String description = "";
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, readModel, removedWith } from '@cratis/chronicle';

@eventType()
  class MbChildrenRemovalPropertyLineItemAdded {
      itemId: Guid = Guid.empty;
      description = '';
  }

@eventType()
  class MbChildrenRemovalPropertyLineItemRemoved {
      itemId: Guid = Guid.empty;
  }

@readModel()
  class MbChildrenRemovalPropertyOrder {
      id: Guid = Guid.empty;

@childrenFrom(MbChildrenRemovalPropertyLineItemAdded, 'itemId')
      @removedWith(MbChildrenRemovalPropertyLineItemRemoved, 'itemId')
      lines: MbChildrenRemovalPropertyOrderLine[] = [];
  }

class MbChildrenRemovalPropertyOrderLine {
      id: Guid = Guid.empty;
      description = '';
  }
  ```

### Class-Level Removal on Child Types

[Section titled “Class-Level Removal on Child Types”](#class-level-removal-on-child-types)

Apply `RemovedWith` directly on the child type. This is particularly useful when the same child model is used in multiple parents or when you want to keep removal logic with the child definition:

* C#

```csharp
  [EventType]
  public record MbChildrenRemovalClassLineItemAdded(Guid ItemId, string Description);

[EventType]
  public record MbChildrenRemovalClassLineItemRemoved(Guid OrderId, Guid ItemId);

public record MbChildrenRemovalClassOrder(
      [Key] Guid Id,

[ChildrenFrom<MbChildrenRemovalClassLineItemAdded>(key: nameof(MbChildrenRemovalClassLineItemAdded.ItemId))]
      IEnumerable<MbChildrenRemovalClassOrderLine> Lines);

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, readModel, removedWith } from '@cratis/chronicle';

@eventType()
  class MbChildrenRemovalClassLineItemAdded {
      itemId: Guid = Guid.empty;
      description = '';
  }

@eventType()
  class MbChildrenRemovalClassLineItemRemoved {
      orderId: Guid = Guid.empty;
      itemId: Guid = Guid.empty;
  }

@readModel()
  class MbChildrenRemovalClassOrder {
      id: Guid = Guid.empty;

@childrenFrom(MbChildrenRemovalClassLineItemAdded, 'itemId')
      lines: MbChildrenRemovalClassOrderLine[] = [];
  }

@removedWith(MbChildrenRemovalClassLineItemRemoved, 'itemId', 'orderId')
  class MbChildrenRemovalClassOrderLine {
      id: Guid = Guid.empty;
      description = '';
  }
  ```

Both approaches produce the same result. The class-level approach keeps the removal definition with the child type, while the property-level approach keeps it with the parent.

### Parameters

[Section titled “Parameters”](#parameters)

For child removal, you can specify:

* **key**: Property on the event that identifies which child to remove
* **parentKey**: Property on the event that identifies the parent (defaults to EventSourceId)

## Children with RemovedWithJoin

[Section titled “Children with RemovedWithJoin”](#children-with-removedwithjoin)

For children that should be removed based on join events, apply `RemovedWithJoin` on the collection property (it also works at the child type’s class level, the same way `RemovedWith` does above):

* C#

```csharp
  [EventType]
  public record MbChildrenRemovedFeatureActivated(Guid FeatureId, string Name);

[EventType]
  public record MbChildrenRemovedFeatureDeactivated(Guid FeatureId);

public record MbChildrenRemovedSubscription(
      [Key]
      Guid SubscriptionId,

public record MbChildrenRemovedFeature(
      [Key] Guid FeatureId,
      string Name);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.ChildrenFrom
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.RemovedWithJoin
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbChildrenRemovedFeatureActivated(val featureId: String, val name: String)

@EventType
  data class MbChildrenRemovedFeatureDeactivated(val featureId: String)

data class MbChildrenRemovedFeature(
      val featureId: String = "",

@SetFrom("name", MbChildrenRemovedFeatureActivated::class)
      val name: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.ChildrenFrom;
  import io.cratis.chronicle.projections.FromEvent;
  import io.cratis.chronicle.projections.RemovedWithJoin;
  import io.cratis.chronicle.projections.SetFrom;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.Collections;
  import java.util.List;

@EventType
  record MbChildrenRemovedFeatureActivated(String featureId, String name) {}

@EventType
  record MbChildrenRemovedFeatureDeactivated(String featureId) {}

class MbChildrenRemovedFeature {
      public String featureId = "";

@SetFrom(propertyPath = "name", eventType = MbChildrenRemovedFeatureActivated.class)
      public String name = "";
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, readModel, removedWithJoin } from '@cratis/chronicle';

@eventType()
  class MbChildrenRemovedFeatureActivated {
      featureId: Guid = Guid.empty;
      name = '';
  }

@eventType()
  class MbChildrenRemovedFeatureDeactivated {
      featureId: Guid = Guid.empty;
  }

@readModel()
  class MbChildrenRemovedSubscription {
      id: Guid = Guid.empty;

class MbChildrenRemovedFeature {
      featureId: Guid = Guid.empty;
      name = '';
  }
  ```

## Complete Example

[Section titled “Complete Example”](#complete-example)

Here’s a comprehensive example showing both root and child removal:

* C#

```csharp
  // Events
  [EventType]
  public record MbRemovalFullShoppingCartCreated(string CustomerName);

[EventType]
  public record MbRemovalFullItemAddedToCart(Guid ItemId, string ProductName, decimal Price);

[EventType]
  public record MbRemovalFullItemRemovedFromCart(Guid CartId, Guid ItemId);

[EventType]
  public record MbRemovalFullCartCheckedOut;

[EventType]
  public record MbRemovalFullCartAbandoned;

// Read Models
  [RemovedWith<MbRemovalFullCartCheckedOut>]
  [RemovedWith<MbRemovalFullCartAbandoned>]
  public record MbRemovalFullShoppingCart(
      [Key]
      Guid Id,

[SetFrom<MbRemovalFullShoppingCartCreated>(nameof(MbRemovalFullShoppingCartCreated.CustomerName))]
      string Customer,

[ChildrenFrom<MbRemovalFullItemAddedToCart>(key: nameof(MbRemovalFullItemAddedToCart.ItemId))]
      IEnumerable<MbRemovalFullCartItem> Items);

[RemovedWith<MbRemovalFullItemRemovedFromCart>(
      key: nameof(MbRemovalFullItemRemovedFromCart.ItemId),
      parentKey: nameof(MbRemovalFullItemRemovedFromCart.CartId))]
  public record MbRemovalFullCartItem(
      [Key] Guid Id,

[SetFrom<MbRemovalFullItemAddedToCart>(nameof(MbRemovalFullItemAddedToCart.ProductName))]
      string Product,

[SetFrom<MbRemovalFullItemAddedToCart>(nameof(MbRemovalFullItemAddedToCart.Price))]
      decimal Price);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { childrenFrom, eventType, Guid, readModel, removedWith, setFrom } from '@cratis/chronicle';

// Events
  @eventType()
  class MbRemovalFullShoppingCartCreated {
      customerName = '';
  }

@eventType()
  class MbRemovalFullItemAddedToCart {
      itemId: Guid = Guid.empty;
      productName = '';
      price = 0;
  }

@eventType()
  class MbRemovalFullItemRemovedFromCart {
      cartId: Guid = Guid.empty;
      itemId: Guid = Guid.empty;
  }

@eventType()
  class MbRemovalFullCartCheckedOut {
  }

@eventType()
  class MbRemovalFullCartAbandoned {
  }

// Read Models
  @readModel()
  @removedWith(MbRemovalFullCartCheckedOut)
  @removedWith(MbRemovalFullCartAbandoned)
  class MbRemovalFullShoppingCart {
      id: Guid = Guid.empty;

@setFrom(MbRemovalFullShoppingCartCreated, 'customerName')
      customer = '';

@childrenFrom(MbRemovalFullItemAddedToCart, 'itemId')
      items: MbRemovalFullCartItem[] = [];
  }

@removedWith(MbRemovalFullItemRemovedFromCart, 'itemId', 'cartId')
  class MbRemovalFullCartItem {
      id: Guid = Guid.empty;

@setFrom(MbRemovalFullItemAddedToCart, 'productName')
      product = '';

@setFrom(MbRemovalFullItemAddedToCart, 'price')
      price = 0;
  }
  ```

## Best Practices

[Section titled “Best Practices”](#best-practices)

1. **Use class-level removal** for root read models to keep the removal logic with the model definition

2. **Choose property vs class-level removal for children** based on where the logic fits best:

* Property-level if the removal is specific to how the child is used in that parent
   * Class-level if the removal logic applies universally to that child type

3. **Always specify keys explicitly** when the default EventSourceId doesn’t apply

4. **Use RemovedWithJoin** for removal events from different streams (e.g., when a parent entity in another aggregate is deleted)

5. **Combine multiple removal attributes** when a model can be removed by different events

# Setting Constant Values

The `SetValue` attribute sets a property to a compile-time constant whenever an event of a specified type occurs. Use it when a property should take a fixed value in response to an event — for example, setting a status flag, assigning a default category, or recording a fixed version number.

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record MbSetValueOrderPlaced(string CustomerName);

[EventType]
  public record MbSetValueOrderCanceled;

public record MbSetValueOrder(
      [Key]
      Guid Id,

[SetFrom<MbSetValueOrderPlaced>(nameof(MbSetValueOrderPlaced.CustomerName))]
      string CustomerName,

[SetValue<MbSetValueOrderPlaced>("active")]
      [SetValue<MbSetValueOrderCanceled>("canceled")]
      string Status);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.projections.SetValue
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbSetValueOrderPlaced(val customerName: String)

@EventType
  data class MbSetValueOrderCanceled(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(MbSetValueOrderPlaced::class)
  @FromEvent(MbSetValueOrderCanceled::class)
  data class MbSetValueOrder(
      @SetFrom("customerName", MbSetValueOrderPlaced::class)
      val customerName: String = "",

@SetValue(MbSetValueOrderPlaced::class, value = "active")
      @SetValue(MbSetValueOrderCanceled::class, value = "canceled")
      val status: String = ""
  )
  ```

* Java

@EventType
  record MbSetValueOrderPlaced(String customerName) {}

@EventType
  record MbSetValueOrderCanceled() {}

@ReadModel
  @FromEvent(eventType = MbSetValueOrderPlaced.class)
  @FromEvent(eventType = MbSetValueOrderCanceled.class)
  class MbSetValueOrder {
      @SetFrom(propertyPath = "customerName", eventType = MbSetValueOrderPlaced.class)
      public String customerName = "";

@SetValue(eventType = MbSetValueOrderPlaced.class, value = "active")
      @SetValue(eventType = MbSetValueOrderCanceled.class, value = "canceled")
      public String status = "";
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.SetValueOrderPlaced do
    use Chronicle.Events.EventType, id: "set-value-order-placed-v1"

defstruct [:customer_name]
  end

defmodule MyApp.Events.SetValueOrderCanceled do
    use Chronicle.Events.EventType, id: "set-value-order-canceled-v1"

defstruct []
  end

defmodule MyApp.ReadModels.SetValueOrder do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{SetValueOrderPlaced, SetValueOrderCanceled}

defstruct [:id, :customer_name, :status]

# A `$value(...)` expression sets a literal constant rather than reading a
    # property off the event.
    from SetValueOrderPlaced,
      set: [id: :event_source_id, customer_name: :customer_name, status: "$value(active)"]

from SetValueOrderCanceled,
      set: [status: "$value(canceled)"]
  end
  ```

* TypeScript

```typescript
  import { eventType, fromEvent, Guid, readModel, setFrom, setValue } from '@cratis/chronicle';

@eventType()
  class MbSetValueOrderPlaced {
      customerName = '';
  }

@eventType()
  class MbSetValueOrderCanceled {
  }

@readModel()
  @fromEvent(MbSetValueOrderPlaced)
  @fromEvent(MbSetValueOrderCanceled)
  class MbSetValueOrder {
      id: Guid = Guid.empty;

@setFrom(MbSetValueOrderPlaced, 'customerName')
      customerName = '';

@setValue(MbSetValueOrderPlaced, 'active')
      @setValue(MbSetValueOrderCanceled, 'canceled')
      status = '';
  }
  ```

When an `OrderPlaced` event occurs, `Status` is set to `"active"`. When an `OrderCanceled` event occurs, `Status` is set to `"canceled"`.

## Supported Value Types

[Section titled “Supported Value Types”](#supported-value-types)

`SetValue` accepts any compile-time constant: strings, integers, longs, doubles, booleans, and enum values.

* C#

```csharp
  [EventType]
  public record MbSetValueThingHappened;

public record MbSetValueThing(
      [Key]
      Guid Id,

[SetValue<MbSetValueThingHappened>("pending")]
      string StatusLabel,

[SetValue<MbSetValueThingHappened>(42)]
      int Priority,

[SetValue<MbSetValueThingHappened>(true)]
      bool IsActive,

[SetValue<MbSetValueThingHappened>(3.14)]
      double Score);
  ```

* Kotlin

@EventType
  data class MbSetValueThingHappened(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(MbSetValueThingHappened::class)
  data class MbSetValueThing(
      @SetValue(MbSetValueThingHappened::class, value = "pending")
      val statusLabel: String = "",

// Kotlin annotation parameters can only be compile-time constants of a fixed set of types, so
      // SetValue always carries its constant as a string - a numeric or boolean value is written out
      // as its literal text and interpreted against the property's declared type.
      @SetValue(MbSetValueThingHappened::class, value = "42")
      val priority: Int = 0,

@SetValue(MbSetValueThingHappened::class, value = "true")
      val isActive: Boolean = false,

@SetValue(MbSetValueThingHappened::class, value = "3.14")
      val score: Double = 0.0
  )
  ```

* Java

@EventType
  record MbSetValueThingHappened() {}

@ReadModel
  @FromEvent(eventType = MbSetValueThingHappened.class)
  class MbSetValueThing {
      @SetValue(eventType = MbSetValueThingHappened.class, value = "pending")
      public String statusLabel = "";

// Kotlin annotation parameters can only be compile-time constants of a fixed set of types, so
      // SetValue always carries its constant as a string - a numeric or boolean value is written out
      // as its literal text and interpreted against the field's declared type.
      @SetValue(eventType = MbSetValueThingHappened.class, value = "42")
      public int priority = 0;

@SetValue(eventType = MbSetValueThingHappened.class, value = "true")
      public boolean isActive = false;

@SetValue(eventType = MbSetValueThingHappened.class, value = "3.14")
      public double score = 0.0;
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.SetValueThingHappened do
    use Chronicle.Events.EventType, id: "set-value-thing-happened-v1"

defstruct []
  end

defmodule MyApp.ReadModels.SetValueThing do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.SetValueThingHappened

defstruct [:id, status_label: "", priority: 0, is_active: false, score: 0.0]

from SetValueThingHappened,
      set: [
        id: :event_source_id,
        status_label: "$value(pending)",
        priority: 42,
        is_active: true,
        score: "$value(3.14)"
      ]
  end
  ```

* TypeScript

```typescript
  import { eventType, fromEvent, Guid, readModel, setValue } from '@cratis/chronicle';

@eventType()
  class MbSetValueThingHappened {
  }

@readModel()
  @fromEvent(MbSetValueThingHappened)
  class MbSetValueThing {
      id: Guid = Guid.empty;

@setValue(MbSetValueThingHappened, 'pending')
      statusLabel = '';

@setValue(MbSetValueThingHappened, 42)
      priority = 0;

@setValue(MbSetValueThingHappened, true)
      isActive = false;

@setValue(MbSetValueThingHappened, 3.14)
      score = 0;
  }
  ```

## Multiple Events

[Section titled “Multiple Events”](#multiple-events)

Apply the attribute more than once to respond to multiple event types:

* C#

```csharp
  [EventType]
  public record MbSetValueSubscriptionStarted;

[EventType]
  public record MbSetValueSubscriptionPaused;

[EventType]
  public record MbSetValueSubscriptionCanceled;

public record MbSetValueSubscription(
      [Key]
      Guid Id,

[SetValue<MbSetValueSubscriptionStarted>("active")]
      [SetValue<MbSetValueSubscriptionPaused>("paused")]
      [SetValue<MbSetValueSubscriptionCanceled>("canceled")]
      string State);
  ```

* Kotlin

@EventType
  data class MbSetValueSubscriptionStarted(val placeholder: Boolean = true)

@EventType
  data class MbSetValueSubscriptionPaused(val placeholder: Boolean = true)

@EventType
  data class MbSetValueSubscriptionCanceled(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(MbSetValueSubscriptionStarted::class)
  @FromEvent(MbSetValueSubscriptionPaused::class)
  @FromEvent(MbSetValueSubscriptionCanceled::class)
  data class MbSetValueSubscription(
      @SetValue(MbSetValueSubscriptionStarted::class, value = "active")
      @SetValue(MbSetValueSubscriptionPaused::class, value = "paused")
      @SetValue(MbSetValueSubscriptionCanceled::class, value = "canceled")
      val state: String = ""
  )
  ```

* Java

@EventType
  record MbSetValueSubscriptionStarted() {}

@EventType
  record MbSetValueSubscriptionPaused() {}

@EventType
  record MbSetValueSubscriptionCanceled() {}

@ReadModel
  @FromEvent(eventType = MbSetValueSubscriptionStarted.class)
  @FromEvent(eventType = MbSetValueSubscriptionPaused.class)
  @FromEvent(eventType = MbSetValueSubscriptionCanceled.class)
  class MbSetValueSubscription {
      @SetValue(eventType = MbSetValueSubscriptionStarted.class, value = "active")
      @SetValue(eventType = MbSetValueSubscriptionPaused.class, value = "paused")
      @SetValue(eventType = MbSetValueSubscriptionCanceled.class, value = "canceled")
      public String state = "";
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.SetValueSubscriptionStarted do
    use Chronicle.Events.EventType, id: "set-value-subscription-started-v1"

defstruct []
  end

defmodule MyApp.Events.SetValueSubscriptionPaused do
    use Chronicle.Events.EventType, id: "set-value-subscription-paused-v1"

defstruct []
  end

defmodule MyApp.Events.SetValueSubscriptionCanceled do
    use Chronicle.Events.EventType, id: "set-value-subscription-canceled-v1"

defstruct []
  end

defmodule MyApp.ReadModels.SetValueSubscription do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{
      SetValueSubscriptionStarted,
      SetValueSubscriptionPaused,
      SetValueSubscriptionCanceled
    }

defstruct [:id, state: ""]

from SetValueSubscriptionStarted,
      set: [id: :event_source_id, state: "$value(active)"]

from SetValueSubscriptionPaused,
      set: [state: "$value(paused)"]

from SetValueSubscriptionCanceled,
      set: [state: "$value(canceled)"]
  end
  ```

* TypeScript

```typescript
  import { eventType, fromEvent, Guid, readModel, setValue } from '@cratis/chronicle';

@eventType()
  class MbSetValueSubscriptionStarted {
  }

@eventType()
  class MbSetValueSubscriptionPaused {
  }

@eventType()
  class MbSetValueSubscriptionCanceled {
  }

@readModel()
  @fromEvent(MbSetValueSubscriptionStarted)
  @fromEvent(MbSetValueSubscriptionPaused)
  @fromEvent(MbSetValueSubscriptionCanceled)
  class MbSetValueSubscription {
      id: Guid = Guid.empty;

@setValue(MbSetValueSubscriptionStarted, 'active')
      @setValue(MbSetValueSubscriptionPaused, 'paused')
      @setValue(MbSetValueSubscriptionCanceled, 'canceled')
      state = '';
  }
  ```

## Clearing a Value

[Section titled “Clearing a Value”](#clearing-a-value)

Passing `null` clears the member instead of setting it — the projection writes it back to no value every time the event occurs. `ClearWith` says the same thing and reads better (as does the fluent `Clear`); all of them are covered in [Clearing Values](/chronicle/projections/model-bound/clearing/).

The member has to be nullable. Clearing a non-nullable member raises [CHR0048](/chronicle/code-analysis/chr0048/) and is refused when the projection is built, because the only value that could be written is the type default, which is a different fact from “not set”.

## SetValue vs SetFrom vs ClearWith

[Section titled “SetValue vs SetFrom vs ClearWith”](#setvalue-vs-setfrom-vs-clearwith)

| Attribute                   | Source                | When to use                                                     |
| --------------------------- | --------------------- | --------------------------------------------------------------- |
| `SetValue<TEvent>(value)`   | Compile-time constant | The value does not come from the event payload                  |
| `SetFrom<TEvent>(property)` | Event property        | The value comes from a property on the event                    |
| `ClearWith<TEvent>`         | No value              | The event takes the value away without putting one in its place |

Combine both on the same read model when different properties come from different sources:

* C#

```csharp
  [EventType]
  public record MbSetValueInvoiceIssued(decimal Amount);

[EventType]
  public record MbSetValueInvoicePaid;

public record MbSetValueInvoice(
      [Key]
      Guid Id,

[SetFrom<MbSetValueInvoiceIssued>(nameof(MbSetValueInvoiceIssued.Amount))]
      decimal Amount,

[SetValue<MbSetValueInvoiceIssued>("issued")]
      [SetValue<MbSetValueInvoicePaid>("paid")]
      string Status);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.FromEvent
  import io.cratis.chronicle.projections.SetFrom
  import io.cratis.chronicle.projections.SetValue
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class MbSetValueInvoiceIssued(val amount: Double)

@EventType
  data class MbSetValueInvoicePaid(val placeholder: Boolean = true)

@ReadModel
  @FromEvent(MbSetValueInvoiceIssued::class)
  @FromEvent(MbSetValueInvoicePaid::class)
  data class MbSetValueInvoice(
      @SetFrom("amount", MbSetValueInvoiceIssued::class)
      val amount: Double = 0.0,

@SetValue(MbSetValueInvoiceIssued::class, value = "issued")
      @SetValue(MbSetValueInvoicePaid::class, value = "paid")
      val status: String = ""
  )
  ```

* Java

@EventType
  record MbSetValueInvoiceIssued(double amount) {}

@EventType
  record MbSetValueInvoicePaid() {}

@ReadModel
  @FromEvent(eventType = MbSetValueInvoiceIssued.class)
  @FromEvent(eventType = MbSetValueInvoicePaid.class)
  class MbSetValueInvoice {
      @SetFrom(propertyPath = "amount", eventType = MbSetValueInvoiceIssued.class)
      public double amount = 0.0;

@SetValue(eventType = MbSetValueInvoiceIssued.class, value = "issued")
      @SetValue(eventType = MbSetValueInvoicePaid.class, value = "paid")
      public String status = "";
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.SetValueInvoiceIssued do
    use Chronicle.Events.EventType, id: "set-value-invoice-issued-v1"

defstruct [:amount]
  end

defmodule MyApp.Events.SetValueInvoicePaid do
    use Chronicle.Events.EventType, id: "set-value-invoice-paid-v1"

defstruct []
  end

defmodule MyApp.ReadModels.SetValueInvoice do
    use Chronicle.ReadModels.ReadModel

alias MyApp.Events.{SetValueInvoiceIssued, SetValueInvoicePaid}

defstruct [:id, amount: 0, status: ""]

from SetValueInvoiceIssued,
      set: [id: :event_source_id, amount: :amount, status: "$value(issued)"]

from SetValueInvoicePaid,
      set: [status: "$value(paid)"]
  end
  ```

* TypeScript

```typescript
  import { eventType, fromEvent, Guid, readModel, setFrom, setValue } from '@cratis/chronicle';

@eventType()
  class MbSetValueInvoiceIssued {
      amount = 0;
  }

@eventType()
  class MbSetValueInvoicePaid {
  }

@readModel()
  @fromEvent(MbSetValueInvoiceIssued)
  @fromEvent(MbSetValueInvoicePaid)
  class MbSetValueInvoice {
      id: Guid = Guid.empty;

@setFrom(MbSetValueInvoiceIssued, 'amount')
      amount = 0;

@setValue(MbSetValueInvoiceIssued, 'issued')
      @setValue(MbSetValueInvoicePaid, 'paid')
      status = '';
  }
  ```

# Nested Projection Objects — Design

This page is the cross-cutting design reference for **nested projection objects** — the ability to populate, update, and clear a single nullable child object on a read model from events. It is an explanation-style page that ties together every layer affected by the feature: the [Projection Declaration Language (PDL)](/screenplay/projections/nested/) syntax, the [declarative .NET client](/chronicle/projections/declarative/nested/), the [model-bound .NET client](/chronicle/projections/model-bound/nested/), the projection definition object model, the projection engine, the PDL compiler and code generator, and the Monaco language definition for the Workbench projection editor.

The user-facing references for each surface live in their respective folders. This page exists to explain *what `nested` means as a concept*, *why it is a first-class projection primitive*, *how the moving parts fit together*, and *what work was required to fully close the feature*.

> Tracking issue: [Cratis/Chronicle#3142](https://github.com/Cratis/Chronicle/issues/3142).

## Motivation

[Section titled “Motivation”](#motivation)

A read model frequently has properties that represent a single, optional, scalar child object — for example, the *active* contract on an employee, the *current* promotion on a product, or the *registered* command for a slice. These properties have three distinct behaviors:

1. They start out as `null`.
2. A specific event populates them with a fresh nested object.
3. A specific event clears them back to `null`.

Until nested objects existed as a first-class concept, you had to either:

* Model the property as a collection of one item using [children](/chronicle/projections/declarative/children/), which forces a key, breaks the scalar nature of the property, and complicates queries; or
* Hand-roll mutations into mapped properties on the parent type, which leaks nested concerns into the root read model and loses any independent lifecycle.

`nested` solves both problems with a small, dedicated primitive that mirrors the shape of [children](/chronicle/projections/declarative/children/) without the collection semantics — one scalar, nullable property, with explicit set and clear lifecycle events.

## The `nested` concept

[Section titled “The nested concept”](#the-nested-concept)

A nested object is:

* **A nullable, scalar property** on a read model — it holds at most one child object at a time.
* **Set by one or more events** declared with `from <EventType>`. Each `from` event auto-maps (or explicitly maps) properties onto the nested object, creating it on first touch and merging into the existing instance on subsequent touches.
* **Cleared by one or more events** declared with `clear with <EventType>`. When the clear event fires the property is set back to `null`.
* **Recursive** — a nested object can itself contain children, joins, counters, every-blocks, and further nested objects. Every projection primitive that works at the root works inside a `nested` block.

```
read model created

from

clear with

Empty

Populated
```

The contract is intentionally narrow: nested is *not* a soft-deletion marker for the parent, and it is *not* a workaround for one-of-many relationships — use [children](/chronicle/projections/declarative/children/) for those.

## How the surfaces compose

[Section titled “How the surfaces compose”](#how-the-surfaces-compose)

The four developer-facing surfaces of Chronicle all express the same underlying concept and compile down to the same projection definition.

```
Projection engine

Projection definition object model

Developer-facing surfaces

Compiler + codegen

INestedBuilder

Reflection

PDL: nested Command · from CommandSetForSlice · clear with CommandClearedForSlice

.NET Declarative: .Nested(...) with .From<CommandSetForSlice>() and .ClearWith<CommandClearedForSlice>()

.NET Model-Bound: [Nested] CommandItem? Command + [FromEvent<...>] / [ClearWith<...>]

ProjectionDefinition.Nested : Dictionary<PropertyPath, ChildrenDefinition>

ProjectionFactory.SetupNestedSubscriptions

ProjectNested + ClearNested
```

### PDL syntax

[Section titled “PDL syntax”](#pdl-syntax)

A `nested` block is declared with a property name and contains the same building blocks as a top-level projection or a `children` block:

```pdl
projection Slice => SliceReadModel
  from SliceCreated
    Name = name

nested command
    from CommandSetForSlice
      Name = commandName
      Schema = schema
    clear with CommandClearedForSlice
```

Two new keywords are introduced: `nested` (block opener) and `clear with` (lifecycle directive). Both can appear inside `children` and inside other `nested` blocks. See [PDL Nested Objects](/screenplay/projections/nested/) for the full surface.

### Declarative .NET client

[Section titled “Declarative .NET client”](#declarative-net-client)

The fluent builder exposes `Nested(...)` symmetrical to `Children(...)`, taking a property expression and a configuration callback. The callback receives an `INestedBuilder<TParent, TNested>` that inherits every method of the root projection builder and adds `ClearWith<TEvent>()`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record NodDeclarativeSliceCreated(string Name);

[EventType]
  public record NodDeclarativeCommandSet(string Name, string Schema);

[EventType]
  public record NodDeclarativeCommandCleared;

public record NodDeclarativeSlice(
      string Name,
      NodDeclarativeCommandItem? Command);

public record NodDeclarativeCommandItem(
      string Name,
      string Schema);

public class NodDeclarativeSliceProjection : IProjectionFor<NodDeclarativeSlice>
  {
      public void Define(IProjectionBuilderFor<NodDeclarativeSlice> builder) => builder
          .From<NodDeclarativeSliceCreated>()
          .Nested(m => m.Command, nested => nested
              .From<NodDeclarativeCommandSet>()
              .ClearWith<NodDeclarativeCommandCleared>());
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.projections.IProjectionBuilderFor
  import io.cratis.chronicle.projections.IProjectionFor

@EventType
  data class NodDeclarativeSliceCreated(val name: String)

@EventType
  data class NodDeclarativeCommandSet(val name: String, val schema: String)

@EventType
  class NodDeclarativeCommandCleared

data class NodDeclarativeSlice(
      val name: String = "",
      val command: NodDeclarativeCommandItem? = null
  )

data class NodDeclarativeCommandItem(
      val name: String = "",
      val schema: String = ""
  )

class NodDeclarativeSliceProjection : IProjectionFor<NodDeclarativeSlice> {
      override fun define(builder: IProjectionBuilderFor<NodDeclarativeSlice>) {
          builder
              .from(NodDeclarativeSliceCreated::class)
              .nested(NodDeclarativeSlice::command, NodDeclarativeCommandItem::class) { nested ->
                  nested
                      .from(NodDeclarativeCommandSet::class)
                      .clearWith(NodDeclarativeCommandCleared::class)
              }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.projections.IProjectionBuilderFor;
  import io.cratis.chronicle.projections.IProjectionFor;

@EventType
  record NodDeclarativeSliceCreated(String name) {}

@EventType
  record NodDeclarativeCommandSet(String name, String schema) {}

@EventType
  record NodDeclarativeCommandCleared() {}

record NodDeclarativeSlice(String name, NodDeclarativeCommandItem command) {}

record NodDeclarativeCommandItem(String name, String schema) {}

class NodDeclarativeSliceProjection implements IProjectionFor<NodDeclarativeSlice> {
      @Override
      public void define(IProjectionBuilderFor<NodDeclarativeSlice> builder) {
          builder
              .from(NodDeclarativeSliceCreated.class)
              .nested("command", NodDeclarativeCommandItem.class, nested -> {
                  nested
                      .from(NodDeclarativeCommandSet.class)
                      .clearWith(NodDeclarativeCommandCleared.class);
              });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  `Chronicle.Projections.Projection` has no nested single-object mechanism with
  clear semantics — only flat `from`/`join` mappings and list-style children via
  `:parent_key`. Track the client SDK issue before relying on nested object
  projection from Elixir.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class NodDeclarativeSliceCreated {
      constructor(readonly name: string) {}
  }

@eventType()
  class NodDeclarativeCommandSet {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class NodDeclarativeCommandCleared {
  }

class NodDeclarativeCommandItem {
      name = '';
      schema = '';
  }

class NodDeclarativeSlice {
      name = '';
      command: NodDeclarativeCommandItem | null = null;
  }

@projection()
  class NodDeclarativeSliceProjection implements IProjectionFor<NodDeclarativeSlice> {
      define(builder: IProjectionBuilderFor<NodDeclarativeSlice>): void {
          builder
              .from(NodDeclarativeSliceCreated)
              .nested(m => m.command, nested => nested
                  .from(NodDeclarativeCommandSet)
                  .clearWith(NodDeclarativeCommandCleared));
      }
  }
  ```

See [Declarative Nested Objects](/chronicle/projections/declarative/nested/) for the full surface.

### Model-bound .NET client

[Section titled “Model-bound .NET client”](#model-bound-net-client)

Two attributes drive the model-bound surface:

* `[Nested]` — placed on a nullable property or record parameter, marks it as a nested object on the parent.
* `[ClearWith<TEvent>]` — placed on the nested type (or its properties), declares the event that nulls the parent’s property.

- C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record NodSliceCreated(string Name);

[EventType]
  public record NodCommandSetForSlice(string Name, string Schema);

[EventType]
  public record NodCommandClearedForSlice;

[FromEvent<NodSliceCreated>]
  public record NodSlice(
      [Key] Guid Id,
      string Name,
      [Nested] NodCommandItem? Command);

[FromEvent<NodCommandSetForSlice>]
  [ClearWith<NodCommandClearedForSlice>]
  public record NodCommandItem(
      string Name,
      string Schema);
  ```

- Kotlin

@EventType
  data class NodSliceCreated(val name: String)

@EventType
  data class NodCommandSetForSlice(val name: String, val schema: String)

@EventType
  class NodCommandClearedForSlice

@ReadModel
  @FromEvent(NodSliceCreated::class)
  data class NodSlice(
      val name: String = "",

@Nested
      val command: NodCommandItem? = null
  )

@FromEvent(NodCommandSetForSlice::class)
  @ClearWith(NodCommandClearedForSlice::class)
  data class NodCommandItem(
      val name: String = "",
      val schema: String = ""
  )
  ```

- Java

@EventType
  record NodSliceCreated(String name) {}

@EventType
  record NodCommandSetForSlice(String name, String schema) {}

@EventType
  class NodCommandClearedForSlice {}

@ReadModel
  @FromEvent(eventType = NodSliceCreated.class)
  class NodSlice {
      public String name = "";

@Nested
      public NodCommandItem command = null;
  }

@FromEvent(eventType = NodCommandSetForSlice.class)
  @ClearWith(eventType = NodCommandClearedForSlice.class)
  class NodCommandItem {
      public String name = "";
      public String schema = "";
  }
  ```

- Elixir

```text
  Elixir does not support this workflow yet.
  The `from`/`join` options include a `:parent_key` for nested list-style
  children, but there is no equivalent for a single nested sub-object that gets
  cleared by a specific event. Track the client SDK issue before relying on
  nested object projection from Elixir.
  ```

- TypeScript

```typescript
  import { clearWith, eventType, fromEvent, Guid, nested, readModel } from '@cratis/chronicle';

@eventType()
  class NodSliceCreated {
      constructor(readonly name: string) {}
  }

@eventType()
  class NodCommandSetForSlice {
      constructor(readonly name: string, readonly schema: string) {}
  }

@eventType()
  class NodCommandClearedForSlice {
  }

@fromEvent(NodCommandSetForSlice)
  @clearWith(NodCommandClearedForSlice)
  class NodCommandItem {
      name = '';
      schema = '';
  }

@readModel()
  @fromEvent(NodSliceCreated)
  class NodSlice {
      id: Guid = Guid.empty;
      name = '';

@nested
      command: NodCommandItem | null = null;
  }
  ```

The nested type is scanned for `[FromEvent<T>]`, `[ClearWith<T>]`, `[SetFrom<T>]`, `[AddFrom<T>]`, `[Nested]`, `[ChildrenFrom<T>]`, and the other standard projection annotations. See [Model-Bound Nested Objects](/chronicle/projections/model-bound/nested/).

### Recursive nesting

[Section titled “Recursive nesting”](#recursive-nesting)

A `nested` block can appear inside another `nested` block, inside a `children` block, and inside a child of a child — there is no recursion depth limit imposed by the model. Each layer is rendered into the projection definition as a `ChildrenDefinition` with `IdentifiedBy = PropertyPath.NotSet`, which the engine treats as “scalar” rather than “collection”.

```pdl
projection Slice => SliceReadModel
  from SliceCreated
    Name = name

nested command
    from CommandSetForSlice
      Name = commandName

nested validation
      from ValidationConfigured
        Rules = rules
      clear with ValidationRemoved

clear with CommandClearedForSlice
```

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record NodRecursiveSliceCreated(string Name);

[EventType]
  public record NodRecursiveCommandSet(string Name);

[EventType]
  public record NodRecursiveCommandCleared;

[EventType]
  public record NodRecursiveValidationConfigured(string Rules);

[EventType]
  public record NodRecursiveValidationRemoved;

public record NodRecursiveSlice(
      string Name,
      NodRecursiveCommandItem? Command);

public record NodRecursiveCommandItem(
      string Name,
      NodRecursiveValidationItem? Validation);

public record NodRecursiveValidationItem(
      string Rules);

public class NodRecursiveSliceProjection : IProjectionFor<NodRecursiveSlice>
  {
      public void Define(IProjectionBuilderFor<NodRecursiveSlice> builder) => builder
          .From<NodRecursiveSliceCreated>()
          .Nested(m => m.Command, nested => nested
              .From<NodRecursiveCommandSet>()
              .Nested(m => m.Validation, inner => inner
                  .From<NodRecursiveValidationConfigured>()
                  .ClearWith<NodRecursiveValidationRemoved>())
              .ClearWith<NodRecursiveCommandCleared>());
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  Without a `.nested()`/`.clearWith()` equivalent, there is no way to express
  even a single level of nested sub-object projection, let alone the recursive
  (nested-within-nested) case. Track the client SDK issue before relying on
  nested object projection from Kotlin.
  ```

* Java

```text
  Java does not support this workflow yet.
  Without a `.nested()`/`.clearWith()` equivalent, there is no way to express
  even a single level of nested sub-object projection, let alone the recursive
  (nested-within-nested) case. Track the client SDK issue before relying on
  nested object projection from Java.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  Without a single-object nested-projection mechanism, there is no way to
  express even one level of nesting, let alone the recursive (nested-within-
  nested) case. Track the client SDK issue before relying on nested object
  projection from Elixir.
  ```

* TypeScript

```typescript
  import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
  class NodRecursiveSliceCreated {
      constructor(readonly name: string) {}
  }

@eventType()
  class NodRecursiveCommandSet {
      constructor(readonly name: string) {}
  }

@eventType()
  class NodRecursiveCommandCleared {
  }

@eventType()
  class NodRecursiveValidationConfigured {
      constructor(readonly rules: string) {}
  }

@eventType()
  class NodRecursiveValidationRemoved {
  }

class NodRecursiveValidationItem {
      rules = '';
  }

class NodRecursiveCommandItem {
      name = '';
      validation: NodRecursiveValidationItem | null = null;
  }

class NodRecursiveSlice {
      name = '';
      command: NodRecursiveCommandItem | null = null;
  }

@projection()
  class NodRecursiveSliceProjection implements IProjectionFor<NodRecursiveSlice> {
      define(builder: IProjectionBuilderFor<NodRecursiveSlice>): void {
          builder
              .from(NodRecursiveSliceCreated)
              .nested<NodRecursiveCommandItem>(m => m.command, nested => nested
                  .from(NodRecursiveCommandSet)
                  .nested<NodRecursiveValidationItem>(m => m.validation, inner => inner
                      .from(NodRecursiveValidationConfigured)
                      .clearWith(NodRecursiveValidationRemoved))
                  .clearWith(NodRecursiveCommandCleared));
      }
  }
  ```

### Nested within children

[Section titled “Nested within children”](#nested-within-children)

A `nested` block may also live inside a [children](/chronicle/projections/declarative/children/) collection, attaching a single nullable child object to every item in the collection. The engine resolves the property path with the child’s array indexers so each item maintains its own nested state:

```pdl
projection Project => ProjectReadModel
  from ProjectCreated
    Name = name

children tasks identified by taskId
    from TaskAdded key taskId
      parent projectId
      Title = title

nested assignee
      from TaskAssigned
        Name = assigneeName
        Email = assigneeEmail
      clear with TaskUnassigned
```

## Object model

[Section titled “Object model”](#object-model)

Nested objects are represented in the contract layer by reusing `ChildrenDefinition` — the same shape that drives collections — with a sentinel `IdentifiedBy` value:

| Field          | Children                                        | Nested                                 |
| -------------- | ----------------------------------------------- | -------------------------------------- |
| `IdentifiedBy` | An event property path that keys the collection | `PropertyPath.NotSet`                  |
| `From`         | Events that add or update items                 | Events that set or update the scalar   |
| `RemovedWith`  | Events that remove a single item                | Events that clear the scalar to `null` |
| `Children`     | Nested collections within items                 | Nested collections within the scalar   |
| `Nested`       | Nested scalars within items                     | Nested scalars within the scalar       |

`ProjectionDefinition.Nested` and `ChildrenDefinition.Nested` are dictionaries keyed by the property path of the nested object on the parent. The engine walks this structure recursively to build subscriptions.

## Engine

[Section titled “Engine”](#engine)

`ProjectionFactory.SetupNestedSubscriptions` walks the `Nested` dictionaries of a projection definition, prefixing every property path with the accumulated path to the current nested or child position. For each entry it:

1. Resolves the merged property mappers using the schema of the parent and the events.
2. Subscribes each `from` event to the engine’s `ProjectNested` operator, which writes the mapped properties onto the nested object (creating it if it doesn’t yet exist).
3. Subscribes each `clear with` event to `ClearNested`, which sets the property back to `null` while preserving the array indexers of any surrounding children.
4. Recurses into the nested definition’s own `Nested` dictionary so deeper levels are wired up in the same pass.

The `Changeset` infrastructure already carries the necessary `NestedCleared` change type so sinks can persist the null transition correctly across the MongoDB and SQL storage providers.

## Integration spec scenarios

[Section titled “Integration spec scenarios”](#integration-spec-scenarios)

Integration coverage for nested objects lives under `Integration/DotNET.InProcess/Projections/Scenarios/`:

* `when_projecting_with_nested_object/` — declarative first-level nested

* `setting_the_nested_object` — populates the nested object from a `from` event
  * `updating_the_nested_object` — multiple `from` events merge into the same nested instance
  * `clearing_the_nested_object` — the `clear with` event nulls the property

* `when_projecting_with_nested_in_children/` — declarative nested object inside a children collection.

* `ModelBound/when_projecting_with_nested_object/` — model-bound first-level nested
  * The same three scenarios driven by `[Nested]` and `[ClearWith<T>]`.

* `ModelBound/when_projecting_with_nested_in_children/` — nested object inside a children collection.

Additional recursive (2-level) scenarios are included in the current integration coverage.

## Client API specs

[Section titled “Client API specs”](#client-api-specs)

Client API contract coverage for nested objects lives under `Source/Clients/DotNET.Specs/Projections/`:

* `for_ProjectionBuilderFor/when_building/with_nested_object.cs` — declarative single nested object.
* `for_ProjectionBuilderFor/when_building/with_nested_object_in_nested_object.cs` — declarative recursive nested-in-nested.
* `for_ProjectionBuilderFor/when_building/with_nested_object_in_children_collection.cs` — declarative nested inside children.
* `ModelBound/for_ModelBoundProjectionBuilder/when_building_model/with_nested/*` — model-bound nested attributes and recursive behavior.
* `ModelBound/for_ModelBoundProjectionBuilder/when_building_model/with_children_having/*` — model-bound nested behavior inside children.

## Implementation status

[Section titled “Implementation status”](#implementation-status)

| Area                                                                                                 | Status      |
| ---------------------------------------------------------------------------------------------------- | ----------- |
| `nested` concept on the projection definition object model                                           | Implemented |
| Projection engine — `ProjectNested`, `ClearNested`, `SetupNestedSubscriptions`                       | Implemented |
| Declarative .NET client — `INestedBuilder<TParent, TNested>`, `.Nested(...)`, `.ClearWith<TEvent>()` | Implemented |
| Model-bound .NET client — `[Nested]`, `[ClearWith<TEvent>]`                                          | Implemented |
| Storage sinks — `NestedCleared` change handling for MongoDB and SQL                                  | Implemented |
| Integration specs — first-level nested (declarative + model-bound)                                   | Implemented |
| Integration specs — nested inside children (declarative + model-bound)                               | Implemented |
| Documentation — declarative, model-bound, PDL reference pages                                        | Implemented |
| Integration specs — recursive (2-level) nested-in-nested                                             | Implemented |
| PDL compiler — `nested` and `clear with` parsing rules                                               | Implemented |
| PDL grammar reference (EBNF) — `nested` and `clear with` productions                                 | Implemented |
| PDL code generator — emit `Nested` entries onto `ProjectionDefinition`                               | Implemented |
| Monaco language definition — `nested`, `clear`, `with` keywords                                      | Implemented |

## Remaining work

[Section titled “Remaining work”](#remaining-work)

The core nested-object feature is now implemented across engine, .NET surfaces, PDL compiler/codegen, Monaco grammar, and end-to-end/integration verification. Remaining follow-ups are design clarifications captured below.

## Open design questions

[Section titled “Open design questions”](#open-design-questions)

* **Empty `nested` blocks.** Should the PDL compiler accept a `nested` block with only `clear with` and no `from`, or reject it as ambiguous? The declarative and model-bound clients let you forget the clear; symmetry would suggest the same flexibility for the set side, but the resulting nested object would have no events to populate it.
* **Mapping inheritance.** Should `every` blocks at the parent level apply to nested objects by default, or require an explicit opt-in? The engine currently does not propagate `every` into nested scopes; making this explicit in PDL would prevent surprise behavior.
* **Removal cascade ordering.** When the outer object is cleared, does the inner nested object emit its own `clear with` event semantics on the sink (separate `NestedCleared` per level), or does the outer clear discard the entire subtree as one change? The current implementation cascades structurally — open question whether downstream sinks need a more granular signal.
* **Schema discovery.** The model-bound discovery walks `[Nested]` properties using reflection. There is an open question about how to surface diagnostics when a `[ClearWith<T>]` attribute references an event type that no `[FromEvent<T>]` on the nested type produces — should the framework warn at startup or be silent?

## See also

[Section titled “See also”](#see-also)

* [PDL — Nested Objects](/screenplay/projections/nested/)
* [Declarative — Nested Objects](/chronicle/projections/declarative/nested/)
* [Model-Bound — Nested Objects](/chronicle/projections/model-bound/nested/)
* [Children](/chronicle/projections/declarative/children/)
* [Projection Architecture](/chronicle/projections/architecture/)

# Projection Declaration Language

The Projection Declaration Language (PDL) is part of the **Cratis Screenplay** language — the declarative, indentation-based language for describing Cratis applications. Chronicle uses the Screenplay compiler to parse projection declarations and turn them into projection definitions.

The full language reference — from-event rules, property mapping, auto-map, keys, event context, counters, arithmetic, joins, children, nested objects, removal, expressions, and the grammar — lives in the Screenplay documentation:

* [Screenplay — Projections](/screenplay/projections/)

## What remains here

[Section titled “What remains here”](#what-remains-here)

Chronicle-specific client APIs that consume PDL declarations are documented in this section:

* [Ad-hoc Querying](/chronicle/projections/projection-declaration-language/adhoc-querying/) — running a PDL declaration ad-hoc with `IProjections.Query()`.

# Ad-hoc Querying with `IProjections.Query()`

The `IProjections.Query()` method lets you run a projection ad-hoc from the .NET client — without defining a read model type or registering a permanent projection. You write a PDL declaration, send it to the server, and get back the projected read model entries as JSON strings.

Client coverage

Ad-hoc PDL querying with `IProjections.Query()` is currently C#-only. Kotlin’s `IProjectionsService`, Elixir’s `Chronicle.Projections.Projection`, and TypeScript’s `IProjections` all support only statically-registered/annotated projections — none exposes a runtime API for sending a PDL declaration string and getting back projected results.

Caution

**This API is not a replacement for registered projections.** Every call to `Query()` replays events from the beginning of the event sequence up to an internal limit. It is designed for **small, bounded event volumes** — tooling, back-office dashboards, diagnostics, and similar scenarios where you have control over (or can reason about) the number of relevant events. Using it in high-throughput code paths or against event sequences with tens of thousands of events will be slow and resource-intensive.

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

Inject `IProjections` into your service, then call `Query()` with a PDL declaration string:

* C#

```csharp
  using Cratis.Chronicle.Projections;
  using System.Text.Json;

public class PdlOrderQueryService(IProjections projections)
  {
      public async Task<IEnumerable<PdlOrderSummary>> GetOrderSummaries()
      {
          var result = await projections.Query("""
              projection OrderSummary
                from OrderPlaced
              """);

return result.ReadModelEntries
              .Select(json => JsonSerializer.Deserialize<PdlOrderSummary>(json)!);
      }
  }

public record PdlOrderSummary(string OrderId);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.projections.ProjectionQueryResult

data class PdlOrderSummary(val orderId: String = "")

class PdlOrderQueryService(private val store: IEventStore) {
      suspend fun getOrderSummaries(): List<PdlOrderSummary> {
          val result = store.projections.query(
              """
              projection OrderSummary
                from OrderPlaced
              """
          )

return when (result) {
              is ProjectionQueryResult.Projected -> result.instancesOf(PdlOrderSummary::class)
              is ProjectionQueryResult.Invalid -> emptyList()
          }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.java.ProjectionsServiceJavaBridge;
  import io.cratis.chronicle.projections.ProjectionQueryResult;

import java.util.List;

record PdlOrderSummary(String orderId) {}

class PdlOrderQueryService {
      private final EventStore store;

PdlOrderQueryService(EventStore store) {
          this.store = store;
      }

List<String> getOrderSummaries() {
          ProjectionQueryResult result = ProjectionsServiceJavaBridge.query(
              store.getProjections(),
              "projection OrderSummary\n  from OrderPlaced"
          );

if (result instanceof ProjectionQueryResult.Projected projected) {
              // Raw JSON documents — instancesOf() takes a Kotlin KClass and has no Java-callable overload.
              return projected.getEntries();
          }
          return List.of();
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  interface PdlOrderSummary {
      orderId: string;
  }

const result = await store.projections.query(`
      projection OrderSummary
        from OrderPlaced
  `);

const summaries = result.readModelEntries.map(json => JSON.parse(json) as PdlOrderSummary);
  ```

`ReadModelEntries` is a `IReadOnlyList<string>` where each element is the JSON representation of one projected read model instance.

## Explicit vs. Inferred Read Model

[Section titled “Explicit vs. Inferred Read Model”](#explicit-vs-inferred-read-model)

You can optionally specify a `=> ReadModelType` in your declaration. When you do, the server resolves the schema from the registered read model definition. When you omit it, the schema is **inferred** from the event properties.

* C#

```csharp
  // Inferred — schema derived from OrderPlaced and OrderShipped event properties
  var inferred = await projections.Query("""
      projection Orders
        from OrderPlaced
        from OrderShipped
      """);

// Explicit — schema comes from the registered 'PdlOrderReadModel' type
  var explicitResult = await projections.Query("""
      projection Orders => PdlOrderReadModel
        from OrderPlaced
        from OrderShipped
      """);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore

suspend fun compareInferredAndExplicit(store: IEventStore) {
      // Inferred — schema derived from OrderPlaced and OrderShipped event properties
      val inferred = store.projections.query(
          """
          projection Orders
            from OrderPlaced
            from OrderShipped
          """
      )

// Explicit — schema comes from the registered 'PdlOrderReadModel' type
      val explicitResult = store.projections.query(
          """
          projection Orders => PdlOrderReadModel
            from OrderPlaced
            from OrderShipped
          """
      )
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.java.ProjectionsServiceJavaBridge;
  import io.cratis.chronicle.projections.ProjectionQueryResult;

class InferredVsExplicitOrdersQuery {
      void compareInferredAndExplicit(EventStore store) {
          // Inferred — schema derived from OrderPlaced and OrderShipped event properties
          ProjectionQueryResult inferred = ProjectionsServiceJavaBridge.query(
              store.getProjections(),
              "projection Orders\n  from OrderPlaced\n  from OrderShipped"
          );

// Explicit — schema comes from the registered 'PdlOrderReadModel' type
          ProjectionQueryResult explicitResult = ProjectionsServiceJavaBridge.query(
              store.getProjections(),
              "projection Orders => PdlOrderReadModel\n  from OrderPlaced\n  from OrderShipped"
          );
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  // Inferred - schema derived from OrderPlaced and OrderShipped event properties
  const inferred = await store.projections.query(`
      projection Orders
        from OrderPlaced
        from OrderShipped
  `);

// Explicit - schema comes from the registered 'PdlOrderReadModel' type
  const explicitResult = await store.projections.query(`
      projection Orders => PdlOrderReadModel
        from OrderPlaced
        from OrderShipped
  `);
  ```

When using an inferred schema with multiple `from` blocks, all events that contribute the same property name must use compatible types. The compiler reports an error at query time if there is a mismatch:

* C#

```csharp
  // This declaration will throw UnableToQueryProjection:
  // OrderPlaced.value is string, but OrderShipped.value is int
  var result = await projections.Query("""
      projection Bad
        from OrderPlaced   // value: string
        from OrderShipped  // value: int  → incompatible types
      """);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.projections.ProjectionQueryResult

suspend fun queryBad(store: IEventStore) {
      // This declaration comes back as ProjectionQueryResult.Invalid:
      // OrderPlaced.value is a string, but OrderShipped.value is an int
      val result = store.projections.query(
          """
          projection Bad
            from OrderPlaced   // value: string
            from OrderShipped  // value: int  -> incompatible types
          """
      )

if (result is ProjectionQueryResult.Invalid) {
          result.errors.forEach { println(it) }
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.java.ProjectionsServiceJavaBridge;
  import io.cratis.chronicle.projections.ProjectionDeclarationError;
  import io.cratis.chronicle.projections.ProjectionQueryResult;

class BadQuery {
      // This declaration comes back as ProjectionQueryResult.Invalid:
      // OrderPlaced.value is a string, but OrderShipped.value is an int
      void queryBad(EventStore store) {
          ProjectionQueryResult result = ProjectionsServiceJavaBridge.query(
              store.getProjections(),
              "projection Bad\n"
                  + "  from OrderPlaced   // value: string\n"
                  + "  from OrderShipped  // value: int  -> incompatible types"
          );

if (result instanceof ProjectionQueryResult.Invalid invalid) {
              for (ProjectionDeclarationError error : invalid.getErrors()) {
                  System.out.println(error);
              }
          }
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  // This declaration will throw UnableToQueryProjection:
  // OrderPlaced.value is a string, but OrderShipped.value is a number
  const result = await store.projections.query(`
      projection Bad
        from OrderPlaced   // value: string
        from OrderShipped  // value: number -> incompatible types
  `);
  ```

## Error Handling

[Section titled “Error Handling”](#error-handling)

If the declaration contains syntax or type errors, `Query()` throws `UnableToQueryProjection`:

* C#

```csharp
  try
  {
      var result = await projections.Query("""
          projection Orders
            from OrderPlaced
          """);
  }
  catch (UnableToQueryProjection ex)
  {
      Console.WriteLine(ex.Message);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.projections.ProjectionQueryResult

suspend fun queryOrders(store: IEventStore) {
      // A declaration that fails to parse is not an exception — it comes back as a result you branch on.
      when (val result = store.projections.query(
          """
          projection Orders
            from OrderPlaced
          """
      )) {
          is ProjectionQueryResult.Projected -> result.entries.forEach(::println)
          is ProjectionQueryResult.Invalid -> result.errors.forEach { println(it) }
      }
  }
  ```

* Java

class ErrorHandlingOrdersQuery {
      // A declaration that fails to parse is not an exception — it comes back as a result you branch on.
      void queryOrders(EventStore store) {
          ProjectionQueryResult result = ProjectionsServiceJavaBridge.query(
              store.getProjections(),
              "projection Orders\n  from OrderPlaced"
          );

if (result instanceof ProjectionQueryResult.Projected projected) {
              for (String entry : projected.getEntries()) {
                  System.out.println(entry);
              }
          } else if (result instanceof ProjectionQueryResult.Invalid invalid) {
              for (ProjectionDeclarationError error : invalid.getErrors()) {
                  System.out.println(error);
              }
          }
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { UnableToQueryProjection } from '@cratis/chronicle';

try {
      const result = await store.projections.query(`
          projection Orders
            from OrderPlaced
      `);
  } catch (error) {
      if (error instanceof UnableToQueryProjection) {
          console.log(error.message);
      }
  }
  ```

## Targeting a Different Event Sequence

[Section titled “Targeting a Different Event Sequence”](#targeting-a-different-event-sequence)

By default `Query()` reads from the `event-log` sequence. Pass a different sequence identifier as the second argument:

* C#

```csharp
  var result = await projections.Query(
      """
      projection InboxMessages
        from MessageReceived
      """,
      eventSequenceId: "inbox");
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.eventSequences.EventSequenceId

suspend fun getInboxMessages(store: IEventStore) =
      store.projections.query(
          """
          projection InboxMessages
            from MessageReceived
          """,
          EventSequenceId("inbox")
      )
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.java.ProjectionsServiceJavaBridge;
  import io.cratis.chronicle.projections.ProjectionQueryResult;

class InboxMessagesQuery {
      ProjectionQueryResult getInboxMessages(EventStore store) {
          return ProjectionsServiceJavaBridge.query(
              store.getProjections(),
              "projection InboxMessages\n  from MessageReceived",
              "inbox"
          );
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  const result = await store.projections.query(
      `
      projection InboxMessages
        from MessageReceived
      `,
      'inbox');
  ```

## Practical Use Cases

[Section titled “Practical Use Cases”](#practical-use-cases)

`Query()` is well-suited for situations where you want projection results without the overhead of defining and registering a permanent read model:

* **Back-office tooling** — maintenance screens for technical staff that need one-off views into the event log.
* **Diagnostic dashboards** — quick summaries during incident investigation.
* **Development utilities** — exploring what data an event sequence contains while building a feature.
* **Integration tests** — asserting projected state in test scenarios without registering a projection.

## Limitations

[Section titled “Limitations”](#limitations)

| Concern                     | Detail                                                                                                                                   |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Event volume**            | The server reads up to an internal maximum (currently 1 000 events). Sequences with more matching events will return incomplete results. |
| **No persistence**          | Results are not stored. Every call replays the relevant portion of the event log.                                                        |
| **No registration**         | A projection without `=> ReadModelType` can never be saved as a permanent projection.                                                    |
| **No change notifications** | Results are a point-in-time snapshot; there is no observable / reactive variant of this API.                                             |

# Registration lifecycle

Clients register their projections on every connect — the full set of definitions the client’s code declares. Chronicle compares each incoming definition against the registered one and only acts on what changed, so a re-registration from an unchanged client is near-free.

## When a definition changes

[Section titled “When a definition changes”](#when-a-definition-changes)

A changed definition — including one that *removes* a child collection — is stored, pushed to the engine on every silo, and the projection’s observer keeps running against the new definition. The change also raises a **replay recommendation** (“Projection definition has changed”), because read models already written with the old definition may no longer match; performing the recommendation rebuilds them. With `ReplayOnDefinitionChange` enabled, the replay happens automatically instead.

## When a registration partially fails

[Section titled “When a registration partially fails”](#when-a-registration-partially-fails)

Definitions are isolated from each other: a definition the engine rejects fails *alone*. Every other definition in the registration still lands — in the engine, in its projection grain, and in the registered state — and the failure is reported back to the client naming exactly the projections that did not register. A failed definition is not marked registered, so the next registration retries it.

## When the kernel is busy

[Section titled “When the kernel is busy”](#when-the-kernel-is-busy)

Registering a projection against a store that already holds events starts a catch-up, and registration does not wait for it. A projection catches up through a single job step that walks the sequence in global order, and that step is brought up on the observer’s own turn rather than inside the registration call — so the size of the event log does not decide how long registering takes.

Registration is also retried rather than fatal. The client re-runs the whole registration with an exponential backoff before giving up, configurable through [`RegistrationRetry`](/chronicle/configuration/chronicle-options/) — every step is idempotent, so a retry costs the kernel only the comparison it already does. A host therefore waits out a kernel that is merely busy instead of failing to start, restarting, and re-registering into the queue it was waiting on. A kernel that is genuinely refusing the definitions still fails the host, once the attempts are spent.

## When a projection is no longer registered — retirement

[Section titled “When a projection is no longer registered — retirement”](#when-a-projection-is-no-longer-registered--retirement)

A projection the client stops declaring — its read model was deleted, or renamed and thereby given a new identity — is **retired** when the client next registers its full set:

* Its observer is unsubscribed in every namespace, so it stops consuming events.
* Its jobs are deleted and its failed partitions are cleared.
* Its definition is removed from the engine and from storage.
* Its **sink container is left untouched** — data is never deleted implicitly. Drop or clean the container yourself if the data is no longer wanted.

Retirement only happens for a **full-set** registration: the client SDK marks the registration as the complete set for its owner, and only when every discovered artifact produced a definition. Partial registrations — such as saving a single projection from the Workbench — never retire anything, and a client-owned full set never retires server-owned projections (or the other way around).

### Renamed read models and shared containers

[Section titled “Renamed read models and shared containers”](#renamed-read-models-and-shared-containers)

A renamed read model keeps its type name and thus its **container name**. Without retirement, the old projection and its successor would keep writing the same container with different definitions and overwrite each other’s documents. With retirement the old projection stops, and because another registered projection targets the same container, Chronicle raises a replay recommendation for the successor so the container can be rebuilt cleanly from its definition alone.

# Tagging Projections

Tags provide a way to organize and tag your projections for better discoverability and management. By applying the `[Tag]` attribute to your projection classes, you can assign one or more tags that describe the purpose or domain of the projection.

`[Tag]` and `[Tags]` on projections label the projection definition. They do not filter which appended events the projection observes. Use projection event declarations and event sequence selection to control projection input, and use reducer or reactor filters when you need metadata-based filtering for appended events. See [Filter reducers and reactors by appended event metadata](/chronicle/events/filtering/).

Client coverage

Tagging a projection with `[Tag]`/`[Tags]` is currently C#-only — none of the other clients’ projection registration mechanisms (Kotlin’s `@FromEvent`/`IProjectionFor`, Elixir’s `use Chronicle.ReadModels.ReadModel`/`Chronicle.Projections.Projection`, TypeScript’s `@fromEvent`/`IProjectionFor`) expose a way to attach descriptive tags to the projection itself.

## Adding Tags

[Section titled “Adding Tags”](#adding-tags)

You can tag projections in multiple ways:

### Single Tag

[Section titled “Single Tag”](#single-tag)

Apply a single tag to your projection:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record TaggingOrderPlaced(string OrderId);

[EventType]
  public record TaggingItemAddedToOrder(decimal Amount);

public record TaggingOrderAnalytics(string OrderId, decimal TotalAmount);

[Tag("Analytics")]
  public class TaggingOrderAnalyticsProjection : IProjectionFor<TaggingOrderAnalytics>
  {
      public void Define(IProjectionBuilderFor<TaggingOrderAnalytics> builder) => builder
          .From<TaggingOrderPlaced>(_ => _
              .Set(m => m.OrderId).To(e => e.OrderId))
          .From<TaggingItemAddedToOrder>(_ => _
              .Add(m => m.TotalAmount).With(e => e.Amount));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `@Tag` only labels a reactor or reducer — neither `ProjectionsService.buildDeclarativeDefinition` nor
  `buildModelBoundDefinition` ever reads a `Tag` annotation off a projection class, so tagging a
  projection has no effect yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  `@Tag` only labels a reactor or reducer — neither `ProjectionsService.buildDeclarativeDefinition` nor
  `buildModelBoundDefinition` ever reads a `Tag` annotation off a projection class, so tagging a
  projection has no effect yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### Multiple Tags (Single Attribute)

[Section titled “Multiple Tags (Single Attribute)”](#multiple-tags-single-attribute)

Use the params feature to specify multiple tags in a single attribute:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record TaggingSaleRecorded(string ProductId, decimal Amount);

public record TaggingSalesReport(string ProductId, decimal TotalSales);

[Tag("Analytics", "Reporting", "Dashboard")]
  public class TaggingSalesReportProjection : IProjectionFor<TaggingSalesReport>
  {
      public void Define(IProjectionBuilderFor<TaggingSalesReport> builder) => builder
          .From<TaggingSaleRecorded>(_ => _
              .Set(m => m.ProductId).To(e => e.ProductId)
              .Add(m => m.TotalSales).With(e => e.Amount));
  }
  ```

* Kotlin

* Java

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### Multiple Tags (Multiple Attributes)

[Section titled “Multiple Tags (Multiple Attributes)”](#multiple-tags-multiple-attributes)

Apply multiple `[Tag]` attributes:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record TaggingAuditEntryRecorded(string EntryId, string Category);

public record TaggingComplianceReport(string EntryId, string Category);

[Tag("Analytics")]
  [Tag("Compliance")]
  [Tag("Auditing")]
  public class TaggingComplianceReportProjection : IProjectionFor<TaggingComplianceReport>
  {
      public void Define(IProjectionBuilderFor<TaggingComplianceReport> builder) => builder
          .From<TaggingAuditEntryRecorded>(_ => _
              .Set(m => m.EntryId).To(e => e.EntryId)
              .Set(m => m.Category).To(e => e.Category));
  }
  ```

* Kotlin

* Java

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### Mixed Approach

[Section titled “Mixed Approach”](#mixed-approach)

Combine both approaches:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Projections;

[EventType]
  public record TaggingKpiRecorded(string Kpi, decimal Value);

public record TaggingExecutiveDashboard(string Kpi, decimal Value);

[Tag("Analytics", "Reporting")]
  [Tag("Executive")]
  public class TaggingExecutiveDashboardProjection : IProjectionFor<TaggingExecutiveDashboard>
  {
      public void Define(IProjectionBuilderFor<TaggingExecutiveDashboard> builder) => builder
          .From<TaggingKpiRecorded>(_ => _
              .Set(m => m.Kpi).To(e => e.Kpi)
              .Set(m => m.Value).To(e => e.Value));
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `@Tag` only labels a reactor or reducer — neither the declarative nor the model-bound projection
  builder in `ProjectionsService` ever reads a `Tag` annotation off a projection class, so tagging a
  projection (fluent or model-bound) has no effect yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  `@Tag` only labels a reactor or reducer — neither the declarative nor the model-bound projection
  builder in `ProjectionsService` ever reads a `Tag` annotation off a projection class, so tagging a
  projection (fluent or model-bound) has no effect yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Model-Bound Projections

[Section titled “Model-Bound Projections”](#model-bound-projections)

Tags also work with model-bound projections:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record TaggingProductRegistered(Guid ProductId, string Name, int QuantityInStock, decimal UnitPrice);

[Tag("Inventory", "Operations")]
  [FromEvent<TaggingProductRegistered>(key: nameof(TaggingProductRegistered.ProductId))]
  public record TaggingProductInventory(
      [Key] Guid ProductId,
      string Name,
      int QuantityInStock,
      decimal UnitPrice);
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  `@Tag` only labels a reactor or reducer — `ProjectionsService.buildModelBoundDefinition` never reads a
  `Tag` annotation off the read model class, so tagging a model-bound projection has no effect yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  `@Tag` only labels a reactor or reducer — `ProjectionsService.buildModelBoundDefinition` never reads a
  `Tag` annotation off the read model class, so tagging a model-bound projection has no effect yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Best Practices

[Section titled “Best Practices”](#best-practices)

* **Use meaningful names**: Choose tag names that clearly describe the purpose or domain
* **Be consistent**: Establish tag naming conventions across your organization
* **Don’t over-tag**: Apply only relevant tags; too many can reduce their usefulness
* **Group related projections**: Use tags to group projections that serve similar purposes

## Common Tag Examples

[Section titled “Common Tag Examples”](#common-tag-examples)

Here are some common patterns for tagging projections:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Projections;

public record TaggingCategoryExamples(Guid Id);

// By domain
  [Tag("Sales", "Inventory", "Customer")]
  // By purpose
  [Tag("Analytics", "Reporting", "Dashboard", "Search")]
  // By stakeholder
  [Tag("Executive", "Operations", "Finance")]
  // By consistency model
  [Tag("Immediate", "Eventual")]
  // By data type
  [Tag("Aggregates", "Lists", "Details")]
  public class TaggingCategoryExamplesProjection : IProjectionFor<TaggingCategoryExamples>
  {
      public void Define(IProjectionBuilderFor<TaggingCategoryExamples> builder)
      {
      }
  }
  ```

* Kotlin

* Java

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Querying by Tag

[Section titled “Querying by Tag”](#querying-by-tag)

Tags stored in the event store definition can be used for:

* Filtering and searching for specific projections
* Organizing projections in administrative interfaces
* Generating documentation
* Managing projection deployments by tag
* Grouping projections for rebuild operations

Note: The specific querying capabilities depend on your Chronicle setup and tooling.

## See Also

[Section titled “See Also”](#see-also)

* [Tagging](/chronicle/concepts/tagging/) - Comprehensive guide to tagging in Chronicle
* [Reactors Tagging](/chronicle/concepts/tagging-reactors/) - Tagging reactors
* [Reducers Tagging](/chronicle/reducers/tagging-reducers/) - Tagging reducers

# Reactors

Reactors are observers that react to events and execute side effects. They are ideal for integrating with external systems, sending notifications, or emitting follow-up actions when events occur.

```
via command pipeline

Event appended

Reactor

Side effect (notify · call an API)

New command
```

## Key Concepts

[Section titled “Key Concepts”](#key-concepts)

* **Event-driven side effects** - Reactors run when events are appended and can call external services or enqueue work
* **Convention-based methods** - Public methods with supported signatures are discovered automatically
* **Event context access** - Optional `EventContext` provides metadata like timestamps and identifiers
* **Event-source isolation** - Events are processed per event source, in order, to keep behavior consistent

## When to Use Reactors

[Section titled “When to Use Reactors”](#when-to-use-reactors)

Reactors are a good fit when you need to:

* Trigger notifications or workflows when specific events occur
* Synchronize with external systems
* Run validations or side effects that do not belong in projections or reducers
* Emit follow-up events based on patterns in the event stream

## Basic Example

[Section titled “Basic Example”](#basic-example)

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReactorsIndexEmailConfirmed(string Email);

public class ReactorsIndexEmailNotificationsReactor : IReactor
  {
      public Task Confirmed(ReactorsIndexEmailConfirmed @event, EventContext context) =>
          SendConfirmationAsync(@event.Email, context.Occurred);

Task SendConfirmationAsync(string email, DateTimeOffset occurred) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class ReactorsIndexEmailConfirmed(val email: String)

@Reactor
  class ReactorsIndexEmailNotificationsReactor {
      fun confirmed(event: ReactorsIndexEmailConfirmed, context: EventContext) {
          sendConfirmation(event.email, context.occurred)
      }

private fun sendConfirmation(email: String, occurred: java.time.Instant) {}
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.Reactor;
  import java.time.Instant;

@EventType
  record ReactorsIndexEmailConfirmed(String email) {}

@Reactor
  class ReactorsIndexEmailNotificationsReactor {
      void confirmed(ReactorsIndexEmailConfirmed event, EventContext context) {
          sendConfirmation(event.email(), context.getOccurred());
      }

private void sendConfirmation(String email, Instant occurred) {}
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ReactorsIndexEmailConfirmed do
    use Chronicle.Events.EventType, id: "reactors-index-email-confirmed"

defstruct [:email]
  end

defmodule MyApp.Reactors.ReactorsIndexEmailNotificationsReactor do
    use Chronicle.Reactors.Reactor

alias MyApp.Events.ReactorsIndexEmailConfirmed

@handles ReactorsIndexEmailConfirmed

@impl true
    def handle(%ReactorsIndexEmailConfirmed{} = event, context) do
      send_confirmation(event.email, Map.get(context, :occurred))

:ok
    end

defp send_confirmation(_email, _occurred), do: :ok
  end
  ```

* TypeScript

```typescript
  import { eventType, reactor, EventContext } from '@cratis/chronicle';

@eventType()
  class ReactorsIndexEmailConfirmed {
      constructor(readonly email: string) {}
  }

@reactor()
  class ReactorsIndexEmailNotificationsReactor {
      // Method name must be the exact camelCase of the event's class name -
      // Chronicle discovers handlers by name, not by parameter type.
      async reactorsIndexEmailConfirmed(event: ReactorsIndexEmailConfirmed, context: EventContext): Promise<void> {
          await this.sendConfirmation(event.email, context.occurred);
      }

private async sendConfirmation(email: string, occurred: Date): Promise<void> {}
  }
  ```

## Topics

[Section titled “Topics”](#topics)

* [Getting Started](/chronicle/reactors/getting-started/)
* [Subscribe to External Event Stores](/chronicle/reactors/external-event-store-subscriptions/)
* [Event Processing](/chronicle/reactors/event-processing/)
* [Returning Side Effects](/chronicle/reactors/side-effects/)
* [Event Sequence](/chronicle/reactors/event-sequence/)
* [Once-Only Processing](/chronicle/reactors/once-only/)
* [Replay](/chronicle/reactors/replay/)
* [Delivery Identity](/chronicle/reactors/delivery-identity/)
* [Filtering by appended event metadata](/chronicle/events/filtering/)
* [Tagging Reactors](/chronicle/concepts/tagging-reactors/)

> Reactors react to **events**. To react instead to a **read model** being added, modified or removed — with the same convention-based methods, dependencies and side effects — see [Reacting to Read Model Changes](/chronicle/read-models/reacting-to-changes/).

# Delivery identity

A reactor can be handed the same event more than once, and nothing in the event itself says whether this is the first time. Declare a `ReactorDelivery` parameter on a handler method and Chronicle gives you a stable identity for *this delivery of this event to this reactor* — the same value every time the event comes back, and a different value for every genuinely different delivery.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record IdempotentPaymentDue(string OrderId, decimal Amount);

public interface IIdempotentPaymentGateway
  {
      Task Charge(string orderId, decimal amount);
  }

// Your storage, not Chronicle's. One row per completed delivery, keyed by its identity.
  public interface IDeliveryReceipts
  {
      Task<bool> HasCompleted(DeliveryId delivery);

Task Complete(DeliveryId delivery);
  }

public class IdempotentBilling(IIdempotentPaymentGateway payments, IDeliveryReceipts receipts) : IReactor
  {
      public async Task PaymentDue(IdempotentPaymentDue @event, ReactorDelivery delivery)
      {
          if (await receipts.HasCompleted(delivery.Id))
          {
              return;
          }

await payments.Charge(@event.OrderId, @event.Amount);
          await receipts.Complete(delivery.Id);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`delivery.Id` is the key. Record it when the side effect completes, check it before doing the side effect again.

## Why the existing markers are not enough

[Section titled “Why the existing markers are not enough”](#why-the-existing-markers-are-not-enough)

[OnceOnly](/chronicle/reactors/once-only/) and [Replay](/chronicle/reactors/replay/) both act on **replay** — the deliberate re-delivery you trigger by rewinding an observer, or that a redaction or revision triggers for you. Neither one touches the other reason an event comes back: your handler failed part-way through, the event-source partition paused, and recovering that partition re-delivers the event as an ordinary observation. That is not a replay, so `OnceOnly` does not suppress it — nor should it, since re-running the handler is the entire point of a retry. But if the handler had already charged the card before it failed, the retry charges it again (see [Troubleshooting](/chronicle/troubleshooting/) for the symptom, and [Observers](/chronicle/hosting/configuration/observers/) for how retries and quarantine are configured).

The delivery identity is the seam for that case. It is the same across the failure and the recovery, so a record you keep under it survives the retry.

```
Payment APIYour receipt storeReactorChroniclePayment APIYour receipt storeReactorChroniclepartition fails, then recoversPaymentDue (delivery A)has A completed?nochargerecord Ahandler fails after the chargePaymentDue (delivery A — same identity)has A completed?yesskip the charge, carry on
```

## How the three relate

[Section titled “How the three relate”](#how-the-three-relate)

| Mechanism         | Covers replay                                                     | Covers recovery after a failure | Needs storage |
| ----------------- | ----------------------------------------------------------------- | ------------------------------- | ------------- |
| `[OnceOnly]`      | Yes — the handler is skipped                                      | No                              | No            |
| `[Replay]`        | Yes — a different handler takes over                              | No                              | No            |
| `ReactorDelivery` | Yes — a replay repeats the same delivery, so the identity matches | Yes                             | Yes — yours   |

They compose rather than compete. Reach for `[OnceOnly]` or `[Replay]` first: they are declarative, cost nothing, and cover replay completely. Add the delivery identity when the side effect must also survive a partition failure, and keep the marker — `[OnceOnly]` then spares you a storage round-trip on every replayed event, and the receipt covers the retries the marker cannot see.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record CustomerWelcomed(string CustomerId);

public interface IWelcomeMail
  {
      Task Send(string customerId);
  }

public class WelcomeMailer(IWelcomeMail mail, IDeliveryReceipts receipts) : IReactor
  {
      [OnceOnly]
      public async Task SendWelcomeMail(CustomerWelcomed @event, ReactorDelivery delivery)
      {
          if (await receipts.HasCompleted(delivery.Id))
          {
              return;
          }

await mail.Send(@event.CustomerId);
          await receipts.Complete(delivery.Id);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## What counts as the same delivery

[Section titled “What counts as the same delivery”](#what-counts-as-the-same-delivery)

The identity is built from six things Chronicle already knows, and nothing else:

| Component        | What it is                                                           |
| ---------------- | -------------------------------------------------------------------- |
| `Reactor`        | The reactor the event is delivered to                                |
| `EventStore`     | The event store the event belongs to                                 |
| `Namespace`      | The namespace within that event store                                |
| `EventSequence`  | The event sequence the reactor observes — the event log, or an inbox |
| `Partition`      | The event source id the event is observed under                      |
| `SequenceNumber` | The event’s position in the event sequence                           |

Two deliveries agreeing on all six are the same delivery; differing on any one of them makes them different. There is deliberately nothing in there about *why* the event arrived, so a replay and the live delivery it repeats share one identity. If a handler needs to know why, take an `EventContext` alongside and read its `ObservationState`.

`ReactorDelivery` is a record, so you can compare two of them directly. `delivery.Id` renders the same components as a single string for use as a storage key.

The identity is a persisted key

Once you store receipts under `delivery.Id`, that string is part of your data. Renaming a reactor type without giving it a stable id via `[Reactor("...")]`, moving a reactor to a different event sequence, or renaming a namespace all change the identity — and every receipt written under the old one stops matching, so the side effects they covered run again. Give any reactor whose deliveries you record an explicit id.

## What it does and does not guarantee

[Section titled “What it does and does not guarantee”](#what-it-does-and-does-not-guarantee)

It is an identity. It is not exactly-once delivery, and it does not make your reactor idempotent — it gives you the one thing you cannot compute yourself, and leaves the rest to you.

* **Chronicle does not know whether your side effect ran.** It never sees your payment API or your mail server, so it cannot suppress a repeat on your behalf. Nothing is skipped unless your own code skips it.
* **Chronicle stores no receipt.** There is no framework-managed table of completed deliveries, no retention policy to configure, and no state added to your event store. The record is yours to write, index, and expire.
* **The gap between the effect and the record is still a gap.** Charge the card, die before writing the receipt, and the retry charges again. Recording the identity narrows at-least-once towards at-most-once exactly as far as your record is atomic with the effect — write both in one database transaction and the gap closes; call a remote API and it does not. Where you cannot close it, use the identity as the idempotency key the remote API itself accepts, and let it deduplicate.
* **Delivery is still at-least-once.** That is the contract Chronicle offers and this does not change it. The identity makes at-least-once *tractable*; it does not replace it.

If the integration you are calling is already idempotent, you do not need any of this — pass `delivery.Id` as its idempotency key and stop there.

Client coverage

`ReactorDelivery` is a .NET client feature. Elixir and TypeScript reactors have no equivalent parameter yet; make those integrations self-idempotent instead.

# Event Processing

This guide explains how reactors discover methods, which signatures are supported, and how event context and errors are handled.

## Event Method Discovery

[Section titled “Event Method Discovery”](#event-method-discovery)

Reactors use convention-based method discovery. Chronicle finds and invokes public methods that:

* Accept the event type as the first parameter
* Optionally accept further dependency parameters (the `EventContext`, read models, or services)
* Return `void`, `Task`, `Task<T>`, or a synchronous side-effect type (see below)

Event parameter types must be marked with `[EventType]`.

## When more than one method matches

[Section titled “When more than one method matches”](#when-more-than-one-method-matches)

Discovery matches on the first parameter type, so a helper you extract out of a handler for readability — say a `Task<string> Enrich(OrderPlaced @event)` that the handler awaits — matches the same event type the handler does. When that happens, Chronicle picks one method per event type, in this order:

1. **A public method beats a non-public one.** Handlers are public by convention; anything else is an implementation detail, so a private helper never displaces the handler that calls it.
2. **The richest signature wins.** Between two methods of the same accessibility, the one taking the most parameters asked for the most context, so it is the more specific handler.
3. **Method name, ordinal**, so a genuine tie resolves the same way on every run rather than being left to reflection order.

A private method is still a valid handler when nothing else handles that event type — the precedence only decides between candidates, it does not disqualify any of them. If a helper is not meant to take part in dispatch at all, give it a first parameter that is not an event type.

## Supported Signatures

[Section titled “Supported Signatures”](#supported-signatures)

* C#

```csharp
  using Cratis.Chronicle.Events;

public interface ReactorHandlerSignatures<TEvent, TResult>
  {
      void MethodName(TEvent @event);
      void MethodName(TEvent @event, EventContext context);

Task MethodNameAsync(TEvent @event);
      Task MethodNameAsync(TEvent @event, EventContext context);

Task<TResult> MethodNameReturningAsync(TEvent @event);
      Task<TResult> MethodNameReturningAsync(TEvent @event, EventContext context);

TResult MethodNameReturning(TEvent @event);
      TResult MethodNameReturning(TEvent @event, EventContext context);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class EventProcessingSignaturesOrderPlaced(val orderId: String)

@EventType
  data class EventProcessingSignaturesOrderShipped(val orderId: String)

@EventType
  data class EventProcessingSignaturesOrderCancelled(val orderId: String)

@EventType
  data class EventProcessingSignaturesRefundIssued(val orderId: String, val amount: Double)

@EventType
  data class EventProcessingSignaturesOrderArchived(val orderId: String)

@Reactor
  class EventProcessingSignaturesReactor {
      // (event) - no metadata needed, no side effect
      fun placed(event: EventProcessingSignaturesOrderPlaced) {
      }

// (event, context) - suspend, no side effect
      suspend fun shipped(event: EventProcessingSignaturesOrderShipped, context: EventContext) {
      }

// (event) - returns a single side-effect event
      fun cancelled(event: EventProcessingSignaturesOrderCancelled) =
          EventProcessingSignaturesOrderArchived(event.orderId)

// (event, context) - suspend, returns a list of side-effect events
      suspend fun refundIssued(
          event: EventProcessingSignaturesRefundIssued,
          context: EventContext
      ): List<Any> = listOf(EventProcessingSignaturesOrderArchived(event.orderId))
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.Reactor;

import java.util.List;

@EventType
  record EventProcessingSignaturesOrderPlaced(String orderId) {}

@EventType
  record EventProcessingSignaturesOrderShipped(String orderId) {}

@EventType
  record EventProcessingSignaturesOrderCancelled(String orderId) {}

@EventType
  record EventProcessingSignaturesRefundIssued(String orderId, double amount) {}

@EventType
  record EventProcessingSignaturesOrderArchived(String orderId) {}

@Reactor
  class EventProcessingSignaturesReactor {
      // (event) - no metadata needed, no side effect
      void placed(EventProcessingSignaturesOrderPlaced event) {
      }

// (event, context) - no side effect
      void shipped(EventProcessingSignaturesOrderShipped event, EventContext context) {
      }

// (event) - returns a single side-effect event
      EventProcessingSignaturesOrderArchived cancelled(EventProcessingSignaturesOrderCancelled event) {
          return new EventProcessingSignaturesOrderArchived(event.orderId());
      }

// (event, context) - returns a list of side-effect events
      List<Object> refundIssued(EventProcessingSignaturesRefundIssued event, EventContext context) {
          return List.of(new EventProcessingSignaturesOrderArchived(event.orderId()));
      }
  }
  ```

* Elixir

```elixir
  defmodule ReactorSupportedSignaturesOrderPlaced do
    use Chronicle.Events.EventType, id: "reactor-supported-signatures-order-placed"

defstruct [:order_id]
  end

defmodule ReactorSupportedSignaturesReactor do
    use Chronicle.Reactors.Reactor

alias ReactorSupportedSignaturesOrderPlaced

@handles ReactorSupportedSignaturesOrderPlaced

# Every reactor handler has exactly this one shape: the event, then the
    # context map. There is no family of overloads to choose between —
    # dispatch always matches on the event's struct type via @handles.
    @impl true
    def handle(%ReactorSupportedSignaturesOrderPlaced{} = event, context) do
      process(event.order_id, Map.get(context, :occurred))

:ok
    end

defp process(_order_id, _occurred), do: :ok
  end
  ```

* TypeScript

```typescript
  import { EventContext } from '@cratis/chronicle';

interface ReactorHandlerSignatures<TEvent, TResult> {
      methodName(event: TEvent): void;
      methodName(event: TEvent, context: EventContext): void;

methodNameAsync(event: TEvent): Promise<void>;
      methodNameAsync(event: TEvent, context: EventContext): Promise<void>;

methodNameReturningAsync(event: TEvent): Promise<TResult>;
      methodNameReturningAsync(event: TEvent, context: EventContext): Promise<TResult>;

methodNameReturning(event: TEvent): TResult;
      methodNameReturning(event: TEvent, context: EventContext): TResult;
  }
  ```

`TResult` can be an event type or `IEnumerable<TEvent>`. See [Returning Side Effects](/chronicle/reactors/side-effects/) for the full list of supported return types and metadata resolution.

This overload table is specific to C#‘s method-overload-based dispatch. Kotlin, Elixir, and TypeScript each use one canonical handler shape instead of a family of overloads — see [Getting started with reactors](/chronicle/reactors/getting-started/) for what that shape looks like in each client. None of them auto-append a handler’s return value the way C# does (see [Returning side effects](/chronicle/reactors/side-effects/)).

## Event Context

[Section titled “Event Context”](#event-context)

The optional `EventContext` parameter provides metadata about the event, including the event source ID, sequence number, timestamps, and correlation identifiers.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReactorAccountClosed(Guid AccountId);

public class AuditReactor : IReactor
  {
      public void AccountClosed(ReactorAccountClosed @event, EventContext context)
      {
          WriteAudit(@event.AccountId, context.Occurred, context.EventSourceId);
      }

void WriteAudit(Guid accountId, DateTimeOffset occurred, EventSourceId eventSourceId) { }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class ReactorAccountClosed(val accountId: String)

@Reactor
  class AuditReactor {
      fun accountClosed(event: ReactorAccountClosed, context: EventContext) {
          writeAudit(event.accountId, context.occurred, context.eventSourceId)
      }

private fun writeAudit(accountId: String, occurred: java.time.Instant, eventSourceId: String) {}
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.Reactor;
  import java.time.Instant;

@EventType
  record ReactorAccountClosed(String accountId) {}

@Reactor
  class AuditReactor {
      void accountClosed(ReactorAccountClosed event, EventContext context) {
          writeAudit(event.accountId(), context.getOccurred(), context.getEventSourceId());
      }

private void writeAudit(String accountId, Instant occurred, String eventSourceId) {}
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ReactorAccountClosed do
    use Chronicle.Events.EventType, id: "reactor-account-closed"

defstruct [:account_id]
  end

defmodule MyApp.Reactors.AuditReactor do
    use Chronicle.Reactors.Reactor

alias MyApp.Events.ReactorAccountClosed

@handles ReactorAccountClosed

@impl true
    def handle(%ReactorAccountClosed{} = event, context) do
      write_audit(event.account_id, Map.get(context, :occurred), Map.get(context, :event_source_id))

:ok
    end

defp write_audit(_account_id, _occurred, _event_source_id), do: :ok
  end
  ```

* TypeScript

```typescript
  import { EventContext, eventType, reactor } from '@cratis/chronicle';

@eventType()
  class ReactorAccountClosed {
      constructor(readonly accountId: string) {}
  }

@reactor()
  class AuditReactor {
      // Method name must be the exact camelCase of the event's class name -
      // Chronicle discovers handlers by name, not by parameter type.
      async reactorAccountClosed(event: ReactorAccountClosed, context: EventContext): Promise<void> {
          this.writeAudit(event.accountId, context.occurred, context.eventSourceId);
      }

private writeAudit(accountId: string, occurred: Date, eventSourceId: string): void {}
  }
  ```

## Taking Dependencies

[Section titled “Taking Dependencies”](#taking-dependencies)

Beyond the event and `EventContext`, a handler method can take additional parameters that Chronicle resolves when the method runs. Only the first parameter is fixed; it is the event that drives dispatch.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

public interface IReactorShippingService
  {
      Task Schedule(EventProcessingOrder order, decimal price);
  }

public interface IReactorPricingService
  {
      decimal PriceFor(EventProcessingOrder order);
  }

[EventType]
  public record EventProcessingOrderPlaced;

public record EventProcessingOrder(string Id, decimal Total);

public class EventProcessingOrderProcessor(IReactorShippingService shipping) : IReactor
  {
      public async Task OrderPlaced(
          EventProcessingOrderPlaced @event,
          EventContext context,
          EventProcessingOrder order,
          IReactorPricingService pricing)
      {
          await shipping.Schedule(order, pricing.PriceFor(order));
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class EventProcessingOrderPlaced(val orderId: String)

@ReadModel
  data class EventProcessingOrder(val id: String = "", val total: Double = 0.0)

interface EventProcessingShippingService {
      suspend fun schedule(order: EventProcessingOrder)
  }

@Reactor
  class EventProcessingOrderProcessor(private val shipping: EventProcessingShippingService) {
      // `order` is resolved by Chronicle itself: any parameter whose type carries @ReadModel is
      // materialized on demand, keyed by the triggering event's EventSourceId - strongly consistent
      // as of this handler call. It is null until something has been projected for that key.
      suspend fun orderPlaced(event: EventProcessingOrderPlaced, order: EventProcessingOrder?, context: EventContext) {
          if (order != null) shipping.schedule(order)
      }
  }
  ```

* Java

@EventType
  record EventProcessingOrderPlaced(String orderId) {}

@ReadModel
  record EventProcessingOrder(String id, double total) {
      EventProcessingOrder() {
          this("", 0.0);
      }
  }

interface EventProcessingShippingService {
      void schedule(EventProcessingOrder order);
  }

@Reactor
  class EventProcessingOrderProcessor {
      private final EventProcessingShippingService shipping;

EventProcessingOrderProcessor(EventProcessingShippingService shipping) {
          this.shipping = shipping;
      }

// `order` is resolved by Chronicle itself: any parameter whose type carries @ReadModel is
      // materialized on demand, keyed by the triggering event's EventSourceId - strongly consistent
      // as of this handler call. It is null until something has been projected for that key.
      void orderPlaced(EventProcessingOrderPlaced event, EventProcessingOrder order, EventContext context) {
          if (order != null) {
              shipping.schedule(order);
          }
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

This is currently a C#-only capability. Kotlin, Elixir, and TypeScript reactor handlers accept only the event and, optionally, the event context — there’s no mechanism to have Chronicle resolve and inject further parameters (services or strongly-consistent read models) into the handler call.

Each parameter after the event resolves as follows:

* An `EventContext` parameter receives the event context; its position does not matter.
* A read model — a type with a reducer or projection — is materialized on demand from that reducer or projection, making it **strongly consistent** when the reactor runs. Read models are resolved directly by Chronicle, never through the service provider.
* Any other type is resolved from the service provider.

### Resolving the read model key

[Section titled “Resolving the read model key”](#resolving-the-read-model-key)

By default the read model is materialized using the `EventSourceId` from the event context. When the key differs, implement `ICanResolveReadModelKey` on the reactor to return the `ReadModelKey` to use:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;
  using Cratis.Chronicle.ReadModels;

[EventType]
  public record ReactorOrderLineAdded(string OrderId);

public record ReactorOrderLine(string Id, string ProductId, int Quantity);

public class OrderLineProcessingReactor : IReactor, ICanResolveReadModelKey
  {
      public ReadModelKey Resolve(object @event, EventContext context) =>
          ((ReactorOrderLineAdded)@event).OrderId;

public Task OrderLineAdded(ReactorOrderLineAdded @event, ReactorOrderLine order) =>
          Task.CompletedTask;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The resolved key applies to every read model parameter across all of the reactor’s handler methods. This is also currently C#-only, since it exists to customize the read-model-parameter resolution described above.

## Event Source Isolation

[Section titled “Event Source Isolation”](#event-source-isolation)

Events are delivered per event source and in sequence order. Each reactor method is called for the specific event source that produced the event.

## Error Handling

[Section titled “Error Handling”](#error-handling)

If a reactor method throws an exception, the failing event source partition is marked as failed and processing for that partition is paused. Once the underlying issue is resolved, processing resumes from the last successful event.

## Related Rules

[Section titled “Related Rules”](#related-rules)

* [CHR0004](/chronicle/code-analysis/chr0004/) - Reactor method signatures
* [CHR0005](/chronicle/code-analysis/chr0005/) - Event parameters require `[EventType]`

# Event Sequence

By default, reactors observe the default event log. You can override this by specifying a different event sequence using either the `[EventSequence]` attribute or the `eventSequence` parameter on the `[Reactor]` attribute.

## Using the `[EventSequence]` Attribute

[Section titled “Using the \[EventSequence\] Attribute”](#using-the-eventsequence-attribute)

Apply `[EventSequence]` directly to your reactor class to pin it to a specific event sequence:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record EventSequenceShipmentDispatched(string TrackingNumber);

[EventSequence("fulfillment-events")]
  public class EventSequenceShipmentReactor : IReactor
  {
      public Task ShipmentDispatched(EventSequenceShipmentDispatched @event, EventContext context) =>
          NotifyCarrierAsync(@event.TrackingNumber);

Task NotifyCarrierAsync(string trackingNumber) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.EventSequence
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class ReactorsEventSequenceOrderDelivered(val orderId: String)

@Reactor
  @EventSequence("outbox")
  class ReactorsEventSequenceDeliveryNotifications {
      fun delivered(event: ReactorsEventSequenceOrderDelivered) {
          // Observed from the "outbox" sequence, without giving up the conventional identifier.
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.EventSequence;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record ReactorsEventSequenceOrderDelivered(String orderId) {}

@Reactor
  @EventSequence("outbox")
  class ReactorsEventSequenceDeliveryNotifications {
      void delivered(ReactorsEventSequenceOrderDelivered event) {
          // Observed from the "outbox" sequence, without giving up the conventional identifier.
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, reactor } from '@cratis/chronicle';

@eventType()
  class EventSequenceReactorShipmentDispatched {
      constructor(readonly trackingNumber: string) {}
  }

@reactor('', 'fulfillment-events')
  class EventSequenceShipmentReactor {
      async eventSequenceReactorShipmentDispatched(event: EventSequenceReactorShipmentDispatched, context: EventContext): Promise<void> {
          await this.notifyCarrier(event.trackingNumber);
      }

private async notifyCarrier(trackingNumber: string): Promise<void> {}
  }
  ```

TypeScript reaches the same result through the `reactor()` decorator’s `eventSequenceId` parameter, and Kotlin and Java through the `eventSequence` parameter on `@Reactor` — all shown under [Using the `[Reactor]` Attribute](#using-the-reactor-attribute) below, rather than as a separate attribute. Elixir doesn’t currently support targeting a non-default event sequence at all.

## Using the `[Reactor]` Attribute

[Section titled “Using the \[Reactor\] Attribute”](#using-the-reactor-attribute)

When you are already using the `[Reactor]` attribute to set a custom identifier or other options, use its `eventSequence` parameter instead of adding a separate `[EventSequence]` attribute:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record EventSequenceReactorAttributeShipmentDispatched(string TrackingNumber);

[Reactor(id: "shipment-reactor", eventSequence: "fulfillment-events")]
  public class EventSequenceReactorAttributeShipmentReactor : IReactor
  {
      public Task ShipmentDispatched(EventSequenceReactorAttributeShipmentDispatched @event, EventContext context) =>
          NotifyCarrierAsync(@event.TrackingNumber);

Task NotifyCarrierAsync(string trackingNumber) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class ReactorsEventSequenceOrderShipped(val orderId: String)

@Reactor(id = "shipping-notifications", eventSequence = "outbox")
  class ReactorsEventSequenceShippingNotifications {
      fun shipped(event: ReactorsEventSequenceOrderShipped) {
          // Observed from the "outbox" sequence rather than the default event log.
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record ReactorsEventSequenceOrderShipped(String orderId) {}

@Reactor(id = "shipping-notifications", eventSequence = "outbox")
  class ReactorsEventSequenceShippingNotifications {
      void shipped(ReactorsEventSequenceOrderShipped event) {
          // Observed from the "outbox" sequence rather than the default event log.
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { eventType, reactor, EventContext } from '@cratis/chronicle';

@eventType()
  class EventSequenceReactorAttributeShipmentDispatched {
      constructor(readonly trackingNumber: string) {}
  }

@reactor('shipment-reactor', 'fulfillment-events')
  class EventSequenceReactorAttributeShipmentReactor {
      // Method name must be the exact camelCase of the event's class name -
      // Chronicle discovers handlers by name, not by parameter type.
      async eventSequenceReactorAttributeShipmentDispatched(event: EventSequenceReactorAttributeShipmentDispatched, context: EventContext): Promise<void> {
          await this.notifyCarrier(event.trackingNumber);
      }

private async notifyCarrier(trackingNumber: string): Promise<void> {}
  }
  ```

Both approaches produce the same result. Prefer `[Reactor(eventSequence: ...)]` when you are already customizing the reactor with other parameters on that attribute.

## Convenience: `[EventLog]`

[Section titled “Convenience: \[EventLog\]”](#convenience-eventlog)

Use `[EventLog]` when you want to be explicit that the reactor reads from the default event log, even when event types in the assembly carry a `[EventStore]` attribute pointing elsewhere:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record EventSequenceLogOrderPlaced(Guid OrderId);

[EventLog]
  public class EventSequenceLocalAuditReactor : IReactor
  {
      public Task OrderPlaced(EventSequenceLogOrderPlaced @event, EventContext context) =>
          WriteAuditAsync(@event.OrderId, context.Occurred);

Task WriteAuditAsync(Guid orderId, DateTimeOffset occurred) => Task.CompletedTask;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, Guid, reactor } from '@cratis/chronicle';

@eventType()
  class EventSequenceLogReactorOrderPlaced {
      constructor(readonly orderId: Guid) {}
  }

// No eventSequenceId given - observes the default event log
  @reactor()
  class EventSequenceLocalAuditReactor {
      async eventSequenceLogReactorOrderPlaced(event: EventSequenceLogReactorOrderPlaced, context: EventContext): Promise<void> {
          await this.writeAudit(event.orderId, context.occurred);
      }

private async writeAudit(orderId: Guid, occurred: Date): Promise<void> {}
  }
  ```

This convenience is C#-only — it exists to disambiguate against C#‘s `[EventStore]` attribute on event types, which the other clients don’t have.

## External Event Store Inbox Routing

[Section titled “External Event Store Inbox Routing”](#external-event-store-inbox-routing)

For outbox-to-inbox subscriptions between event stores, including automatic inbox routing and observer-level `[EventStore]` usage, see [Subscribe Reactors to External Event Stores](/chronicle/reactors/external-event-store-subscriptions/).

## When to Use `[EventSequence]` Explicitly

[Section titled “When to Use \[EventSequence\] Explicitly”](#when-to-use-eventsequence-explicitly)

* When you need to read from a specific sequence other than the inferred one
* To suppress automatic inbox routing for a reactor that handles foreign events
* For reactors that target a specialized or partitioned event stream
* When an explicit sequence name improves readability and makes intent clear

# Subscribe Reactors to External Event Stores

Client coverage

External event store inbox routing is currently C#-only — it depends on the `[EventStore]` attribute on event types or reactors, which doesn’t exist in Kotlin, Elixir, or TypeScript.

## Automatic Inbox Routing

[Section titled “Automatic Inbox Routing”](#automatic-inbox-routing)

When all event types handled by a reactor come from the same source event store, Chronicle routes the reactor to the matching inbox sequence automatically:

* Source event store: `fulfillment-service`
* Inbox sequence observed by the reactor: `inbox-fulfillment-service`

This works when the source is declared on event types (or assembly) using `[EventStore("...")]`, and no explicit event sequence is configured on the reactor.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  [EventStore("fulfillment-service")]
  public record ExternalEventStoreShipmentDispatched(Guid OrderId, string TrackingNumber);

public class ExternalEventStoreFulfillmentReactor : IReactor
  {
      public Task ShipmentDispatched(ExternalEventStoreShipmentDispatched @event, EventContext context) => Task.CompletedTask;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Observer-Level EventStore for Missing Event Metadata

[Section titled “Observer-Level EventStore for Missing Event Metadata”](#observer-level-eventstore-for-missing-event-metadata)

When event contracts cannot carry `[EventStore]` metadata, apply `[EventStore]` directly on the reactor.

Chronicle resolves the reactor to the inbox for that source event store and implicitly creates or reuses the outbox-to-inbox subscription.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ExternalEventStoreUserInvited(Guid UserId);

[EventStore("identity-service")]
  [Reactor]
  public class ExternalEventStoreUserInvitedReactor : IReactor
  {
      public Task Invited(ExternalEventStoreUserInvited @event, EventContext context) => Task.CompletedTask;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Implicit Combined Event Type Filtering

[Section titled “Implicit Combined Event Type Filtering”](#implicit-combined-event-type-filtering)

For each source event store, Chronicle combines all reactor and reducer event types into one implicit subscription filter.

This means:

* You get one subscription per source event store.
* The filter is the union of handled event types from all participating observers.
* Only those event types are forwarded from source outbox to target inbox.

## Explicit Event Sequence Is Not Allowed with Observer EventStore

[Section titled “Explicit Event Sequence Is Not Allowed with Observer EventStore”](#explicit-event-sequence-is-not-allowed-with-observer-eventstore)

When a reactor has `[EventStore("...")]`, do not combine it with:

* `[EventSequence("...")]`
* `[EventLog]`
* `[Reactor(eventSequence: "...")]`

This is invalid and fails:

* At runtime with `EventStoreCannotBeCombinedWithExplicitEventSequence`.
* At compile time with analyzer rule `CHR0013`.

## See Also

[Section titled “See Also”](#see-also)

* [Implicit Event Store Subscriptions](/chronicle/subscriptions/implicit-subscriptions/)
* [Explicit Event Store Subscriptions](/chronicle/subscriptions/explicit-subscriptions/)
* [Event Sequence](/chronicle/reactors/event-sequence/)

# Filter reactors by appended event metadata

A reactor observes all events that match its handler method signatures by default. You can restrict which events a reactor receives by placing filter attributes on the reactor class. Chronicle evaluates these filters before dispatching an event — events that do not match are dropped before they ever reach the reactor.

## Filter attributes

[Section titled “Filter attributes”](#filter-attributes)

| Attribute                    | Filters by                           | Matches when                                         |
| ---------------------------- | ------------------------------------ | ---------------------------------------------------- |
| `[FilterEventsByTag("...")]` | Appended or static event tag         | Any filter tag matches any tag on the appended event |
| `[EventSourceType("...")]`   | Event source type set at append time | The event source type matches exactly                |
| `[EventStreamType("...")]`   | Event stream type set at append time | The event stream type matches exactly                |

These attributes correlate directly to the metadata you provide when appending an event:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;

[EventType]
  public record ReactorsFilteringOrderPlaced(decimal TotalAmount);

public class ReactorsFilteringMetadataExampleService(IEventLog eventLog)
  {
      public Task PlaceOrder(decimal totalAmount) =>
          eventLog.Append(
              EventSourceId.New(),
              new ReactorsFilteringOrderPlaced(totalAmount),
              tags: ["priority"],
              eventSourceType: "order",
              eventStreamType: "fulfillment");
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.eventSequences.IEventLog

@EventType
  data class ReactorsFilteringOrderPlaced(val totalAmount: Double)

class ReactorsFilteringMetadataExampleService(private val eventLog: IEventLog) {
      suspend fun placeOrder(eventSourceId: String, totalAmount: Double) =
          eventLog.append(
              eventSourceId,
              ReactorsFilteringOrderPlaced(totalAmount),
              AppendOptions(
                  tags = listOf("priority"),
                  eventSourceType = "order",
                  eventStreamType = "fulfillment"
              )
          )
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.IEventLog;
  import io.cratis.chronicle.java.AppendOptionsBuilder;
  import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
  record ReactorsFilteringOrderPlaced(double totalAmount) {}

class ReactorsFilteringMetadataExampleService {
      private final IEventLog eventLog;

ReactorsFilteringMetadataExampleService(IEventLog eventLog) {
          this.eventLog = eventLog;
      }

void placeOrder(String eventSourceId, double totalAmount) {
          EventLogJavaBridge.append(
              eventLog,
              eventSourceId,
              new ReactorsFilteringOrderPlaced(totalAmount),
              new AppendOptionsBuilder()
                  .tag("priority")
                  .eventSourceType("order")
                  .eventStreamType("fulfillment")
                  .build());
      }
  }
  ```

* Elixir

```elixir
  defmodule ReactorsFilteringOrderPlaced do
    use Chronicle.Events.EventType, id: "reactors-filtering-order-placed"

defstruct [:total_amount]
  end

defmodule ReactorsFilteringMetadataExampleService do
    alias ReactorsFilteringOrderPlaced

def place_order(order_id, total_amount) do
      Chronicle.append(
        order_id,
        %ReactorsFilteringOrderPlaced{total_amount: total_amount},
        tags: ["priority"],
        event_source_type: "order",
        event_stream_type: "fulfillment"
      )
    end
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Client coverage

Kotlin and Java attach the same filters with `@FilterEventsByTag`, `@EventSourceType`, and `@EventStreamType` on the reactor class. Elixir’s `use Chronicle.Reactors.Reactor` and TypeScript’s `reactor()` register a reactor without a way to attach these filters.

## Filter by tag

[Section titled “Filter by tag”](#filter-by-tag)

Append an event with a tag and place `[FilterEventsByTag]` on the reactor to receive only tagged events.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReactorsFilteringByTagOrderPlaced(decimal TotalAmount);

public class ReactorsFilteringByTagOrderService(IEventLog eventLog)
  {
      public Task PlacePriorityOrder(decimal totalAmount) =>
          eventLog.Append(
              EventSourceId.New(),
              new ReactorsFilteringByTagOrderPlaced(totalAmount),
              tags: ["priority"]);
  }

[FilterEventsByTag("priority")]
  public class ReactorsFilteringPriorityOrderNotifier : IReactor
  {
      public Task Placed(ReactorsFilteringByTagOrderPlaced @event, EventContext context) =>
          Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.eventSequences.IEventLog
  import io.cratis.chronicle.observation.FilterEventsByTag
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class ReactorsFilteringByTagOrderPlaced(val totalAmount: Double)

class ReactorsFilteringByTagOrderService(private val eventLog: IEventLog) {
      suspend fun placePriorityOrder(eventSourceId: String, totalAmount: Double) =
          eventLog.append(
              eventSourceId,
              ReactorsFilteringByTagOrderPlaced(totalAmount),
              AppendOptions(tags = listOf("priority"))
          )
  }

@Reactor
  @FilterEventsByTag("priority")
  class ReactorsFilteringPriorityOrderNotifier {
      fun placed(event: ReactorsFilteringByTagOrderPlaced, context: EventContext) {
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.IEventLog;
  import io.cratis.chronicle.java.AppendOptionsBuilder;
  import io.cratis.chronicle.java.EventLogJavaBridge;
  import io.cratis.chronicle.observation.FilterEventsByTag;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record ReactorsFilteringByTagOrderPlaced(double totalAmount) {}

class ReactorsFilteringByTagOrderService {
      private final IEventLog eventLog;

ReactorsFilteringByTagOrderService(IEventLog eventLog) {
          this.eventLog = eventLog;
      }

void placePriorityOrder(String eventSourceId, double totalAmount) {
          EventLogJavaBridge.append(
              eventLog,
              eventSourceId,
              new ReactorsFilteringByTagOrderPlaced(totalAmount),
              new AppendOptionsBuilder().tag("priority").build());
      }
  }

@Reactor
  @FilterEventsByTag("priority")
  class ReactorsFilteringPriorityOrderNotifier {
      void placed(ReactorsFilteringByTagOrderPlaced event, EventContext context) {
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, filterEventsByTag, IEventStore, reactor } from '@cratis/chronicle';

@eventType()
  class ReactorsFilteringByTagOrderPlaced {
      constructor(readonly totalAmount: number) {}
  }

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

async placePriorityOrder(eventSourceId: string, totalAmount: number): Promise<void> {
          await this.store.eventLog.append(
              eventSourceId,
              new ReactorsFilteringByTagOrderPlaced(totalAmount),
              { tags: ['priority'] });
      }
  }

@reactor()
  @filterEventsByTag('priority')
  class ReactorsFilteringPriorityOrderNotifier {
      async reactorsFilteringByTagOrderPlaced(_event: ReactorsFilteringByTagOrderPlaced, _context: EventContext): Promise<void> {}
  }
  ```

`PriorityOrderNotifier` receives the event because the append call includes the `priority` tag. Orders appended without that tag are not dispatched.

### Multiple filter tags

[Section titled “Multiple filter tags”](#multiple-filter-tags)

Multiple `[FilterEventsByTag]` attributes widen the match. The reactor receives the event if the appended event has any of the configured tags:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReactorsFilteringMultiTagOrderPlaced(decimal TotalAmount);

[FilterEventsByTag("priority")]
  [FilterEventsByTag("express")]
  public class ReactorsFilteringFastTrackOrderNotifier : IReactor
  {
      public Task Placed(ReactorsFilteringMultiTagOrderPlaced @event, EventContext context) =>
          Task.CompletedTask;
  }
  ```

* Kotlin

@EventType
  data class ReactorsFilteringMultiTagOrderPlaced(val totalAmount: Double)

@Reactor
  @FilterEventsByTag("priority")
  @FilterEventsByTag("express")
  class ReactorsFilteringFastTrackOrderNotifier {
      fun placed(
          event: ReactorsFilteringMultiTagOrderPlaced,
          context: EventContext
      ) {
          // Only events appended with both tags reach this handler.
      }
  }
  ```

* Java

@EventType
  record ReactorsFilteringMultiTagOrderPlaced(double totalAmount) {}

@Reactor
  @FilterEventsByTag("priority")
  @FilterEventsByTag("express")
  class ReactorsFilteringFastTrackOrderNotifier {
      void placed(ReactorsFilteringMultiTagOrderPlaced event, EventContext context) {
          // Only events appended with both tags reach this handler.
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, filterEventsByTag, reactor } from '@cratis/chronicle';

@eventType()
  class ReactorsFilteringMultiTagOrderPlaced {
      constructor(readonly totalAmount: number) {}
  }

@reactor()
  @filterEventsByTag('priority')
  @filterEventsByTag('express')
  class ReactorsFilteringFastTrackOrderNotifier {
      async reactorsFilteringMultiTagOrderPlaced(_event: ReactorsFilteringMultiTagOrderPlaced, _context: EventContext): Promise<void> {}
  }
  ```

## Filter by event source type

[Section titled “Filter by event source type”](#filter-by-event-source-type)

Place `[EventSourceType]` on the reactor to receive only events appended with a matching `eventSourceType`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReactorsFilteringCustomerRegistered(string EmailAddress);

public class ReactorsFilteringCustomerService(IEventLog eventLog)
  {
      public Task Register(string emailAddress) =>
          eventLog.Append(
              EventSourceId.New(),
              new ReactorsFilteringCustomerRegistered(emailAddress),
              eventSourceType: "customer");
  }

[EventSourceType("customer")]
  public class ReactorsFilteringCustomerWelcomeReactor : IReactor
  {
      public Task Registered(ReactorsFilteringCustomerRegistered @event, EventContext context) =>
          Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.eventSequences.IEventLog
  import io.cratis.chronicle.observation.EventSourceType
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class ReactorsFilteringCustomerRegistered(val emailAddress: String)

class ReactorsFilteringCustomerService(private val eventLog: IEventLog) {
      suspend fun register(eventSourceId: String, emailAddress: String) =
          eventLog.append(
              eventSourceId,
              ReactorsFilteringCustomerRegistered(emailAddress),
              AppendOptions(eventSourceType = "customer")
          )
  }

@Reactor
  @EventSourceType("customer")
  class ReactorsFilteringCustomerWelcomeReactor {
      fun registered(event: ReactorsFilteringCustomerRegistered, context: EventContext) {
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.IEventLog;
  import io.cratis.chronicle.java.AppendOptionsBuilder;
  import io.cratis.chronicle.java.EventLogJavaBridge;
  import io.cratis.chronicle.observation.EventSourceType;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record ReactorsFilteringCustomerRegistered(String emailAddress) {}

class ReactorsFilteringCustomerService {
      private final IEventLog eventLog;

ReactorsFilteringCustomerService(IEventLog eventLog) {
          this.eventLog = eventLog;
      }

void register(String eventSourceId, String emailAddress) {
          EventLogJavaBridge.append(
              eventLog,
              eventSourceId,
              new ReactorsFilteringCustomerRegistered(emailAddress),
              new AppendOptionsBuilder().eventSourceType("customer").build());
      }
  }

@Reactor
  @EventSourceType("customer")
  class ReactorsFilteringCustomerWelcomeReactor {
      void registered(ReactorsFilteringCustomerRegistered event, EventContext context) {
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Filter by event stream type

[Section titled “Filter by event stream type”](#filter-by-event-stream-type)

Place `[EventStreamType]` on the reactor to receive only events appended to a matching stream type:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReactorsFilteringPaymentCaptured(decimal Amount);

public class ReactorsFilteringPaymentsService(IEventLog eventLog)
  {
      public Task Capture(decimal amount) =>
          eventLog.Append(
              EventSourceId.New(),
              new ReactorsFilteringPaymentCaptured(amount),
              eventStreamType: "payments");
  }

[EventStreamType("payments")]
  public class ReactorsFilteringPaymentReceivedNotifier : IReactor
  {
      public Task Captured(ReactorsFilteringPaymentCaptured @event, EventContext context) =>
          Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.AppendOptions
  import io.cratis.chronicle.eventSequences.IEventLog
  import io.cratis.chronicle.observation.EventStreamType
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class ReactorsFilteringPaymentCaptured(val amount: Double)

class ReactorsFilteringPaymentsService(private val eventLog: IEventLog) {
      suspend fun capture(eventSourceId: String, amount: Double) =
          eventLog.append(
              eventSourceId,
              ReactorsFilteringPaymentCaptured(amount),
              AppendOptions(eventStreamType = "payments")
          )
  }

@Reactor
  @EventStreamType("payments")
  class ReactorsFilteringPaymentReceivedNotifier {
      fun captured(event: ReactorsFilteringPaymentCaptured, context: EventContext) {
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.IEventLog;
  import io.cratis.chronicle.java.AppendOptionsBuilder;
  import io.cratis.chronicle.java.EventLogJavaBridge;
  import io.cratis.chronicle.observation.EventStreamType;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record ReactorsFilteringPaymentCaptured(double amount) {}

class ReactorsFilteringPaymentsService {
      private final IEventLog eventLog;

ReactorsFilteringPaymentsService(IEventLog eventLog) {
          this.eventLog = eventLog;
      }

void capture(String eventSourceId, double amount) {
          EventLogJavaBridge.append(
              eventLog,
              eventSourceId,
              new ReactorsFilteringPaymentCaptured(amount),
              new AppendOptionsBuilder().eventStreamType("payments").build());
      }
  }

@Reactor
  @EventStreamType("payments")
  class ReactorsFilteringPaymentReceivedNotifier {
      void captured(ReactorsFilteringPaymentCaptured event, EventContext context) {
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Combine multiple filters

[Section titled “Combine multiple filters”](#combine-multiple-filters)

You can combine `[FilterEventsByTag]`, `[EventSourceType]`, and `[EventStreamType]` on the same reactor. Chronicle requires all filter categories to match:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReactorsFilteringShipmentDispatched(string TrackingNumber);

public class ReactorsFilteringShippingService(IEventLog eventLog)
  {
      public Task Dispatch(string trackingNumber) =>
          eventLog.Append(
              EventSourceId.New(),
              new ReactorsFilteringShipmentDispatched(trackingNumber),
              tags: ["express"],
              eventSourceType: "shipment",
              eventStreamType: "logistics");
  }

[FilterEventsByTag("express")]
  [EventSourceType("shipment")]
  [EventStreamType("logistics")]
  public class ReactorsFilteringExpressShipmentNotifier : IReactor
  {
      public Task Dispatched(ReactorsFilteringShipmentDispatched @event, EventContext context) =>
          Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.EventSourceType
  import io.cratis.chronicle.observation.EventStreamType
  import io.cratis.chronicle.observation.FilterEventsByTag
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class ReactorsFilteringShipmentDispatched(val trackingNumber: String)

@Reactor
  @FilterEventsByTag("priority")
  @EventSourceType("Order")
  @EventStreamType("Fulfilment")
  class ReactorsFilteringShipmentNotifier {
      fun dispatched(
          event: ReactorsFilteringShipmentDispatched,
          context: EventContext
      ) {
          // Every filter has to match: the tag, the event source type, and the stream type.
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.EventSourceType;
  import io.cratis.chronicle.observation.EventStreamType;
  import io.cratis.chronicle.observation.FilterEventsByTag;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record ReactorsFilteringShipmentDispatched(String trackingNumber) {}

@Reactor
  @FilterEventsByTag("priority")
  @EventSourceType("Order")
  @EventStreamType("Fulfilment")
  class ReactorsFilteringShipmentNotifier {
      void dispatched(ReactorsFilteringShipmentDispatched event, EventContext context) {
          // Every filter has to match: the tag, the event source type, and the stream type.
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The reactor only receives events that match all three: the `express` tag, the `shipment` event source type, and the `logistics` stream type.

## Tagging the reactor vs filtering events

[Section titled “Tagging the reactor vs filtering events”](#tagging-the-reactor-vs-filtering-events)

`[Tag]` and `[Tags]` on a reactor class label the reactor itself for organization and discoverability. They do not filter incoming events:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReactorsFilteringTagVsFilterShipmentDispatched(string TrackingNumber);

// These labels appear on the reactor definition — they do not affect dispatch
  [Tag("notifications")]
  [Tag("express")]
  public class ReactorsFilteringLabeledShipmentNotifier : IReactor
  {
      public Task Dispatched(ReactorsFilteringTagVsFilterShipmentDispatched @event, EventContext context) =>
          Task.CompletedTask;
  }

// These filter which events are dispatched to the reactor
  [FilterEventsByTag("express")]
  [EventSourceType("shipment")]
  public class ReactorsFilteringFilteredShipmentNotifier : IReactor
  {
      public Task Dispatched(ReactorsFilteringTagVsFilterShipmentDispatched @event, EventContext context) =>
          Task.CompletedTask;
  }
  ```

* Kotlin

@EventType
  data class ReactorsFilteringInvoiceIssued(val amount: Double)

// @Tag labels the reactor itself and shows up in tooling - it changes nothing about
  // what the reactor observes. @FilterEventsByTag is what narrows the event stream.
  @Reactor
  @Tag("finance", "owned-by-billing")
  @FilterEventsByTag("audited")
  class ReactorsFilteringInvoiceAuditor {
      fun issued(
          event: ReactorsFilteringInvoiceIssued,
          context: EventContext
      ) {
      }
  }
  ```

* Java

@EventType
  record ReactorsFilteringInvoiceIssued(double amount) {}

// @Tag labels the reactor itself and shows up in tooling - it changes nothing about
  // what the reactor observes. @FilterEventsByTag is what narrows the event stream.
  @Reactor
  @Tag({"finance", "owned-by-billing"})
  @FilterEventsByTag("audited")
  class ReactorsFilteringInvoiceAuditor {
      void issued(ReactorsFilteringInvoiceIssued event, EventContext context) {
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Detailed guides

[Section titled “Detailed guides”](#detailed-guides)

* [Filter by tag](/chronicle/events/filtering/by-tag/)
* [Filter by event source type](/chronicle/events/filtering/by-event-source-type/)
* [Filter by event stream type](/chronicle/events/filtering/by-event-stream-type/)

# Getting Started with Reactors

Reactors observe events and run side effects. Use them for work such as sending notifications, calling an external API, publishing integration messages, or triggering a workflow in another system.

Reactors do not build queryable state. Use a [projection](/chronicle/projections/) or [reducer](/chronicle/reducers/) when the outcome should be a read model.

## Define the event

[Section titled “Define the event”](#define-the-event)

A reactor handles one or more event types. The event is still a normal Chronicle event: an immutable fact with a stable event type identity.

* C#

```csharp
  [EventType]
  public record ReactorOrderPlaced(string CustomerEmail, decimal TotalAmount);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class ReactorOrderPlaced(
      val customerEmail: String,
      val totalAmount: Double
  )
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record ReactorOrderPlaced(String customerEmail, double totalAmount) {}
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ReactorOrderPlaced do
    use Chronicle.Events.EventType, id: "reactor-order-placed-v1"

defstruct [:customer_email, :total_amount]
  end
  ```

* TypeScript

```typescript
  import { eventType } from '@cratis/chronicle';

@eventType()
  class ReactorOrderPlaced {
      constructor(
          readonly customerEmail: string,
          readonly totalAmount: number
      ) {}
  }
  ```

## Define the reactor

[Section titled “Define the reactor”](#define-the-reactor)

The client SDK decides how a reactor is declared. The common shape is the same: mark a type or module as a reactor, add a handler for the event, and accept event context when the side effect needs metadata such as sequence number, occurrence time, event store, namespace, or correlation.

* C#

```csharp
  public interface ReactorEmailGateway
  {
      Task SendOrderPlaced(string email, decimal amount, DateTimeOffset occurred);
  }

public class OrderNotificationsReactor(ReactorEmailGateway emailGateway) : IReactor
  {
      public Task Placed(ReactorOrderPlaced @event, EventContext context) =>
          emailGateway.SendOrderPlaced(
              @event.CustomerEmail,
              @event.TotalAmount,
              context.Occurred);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.observation.Reactor
  import java.time.Instant

interface ReactorEmailGateway {
      fun sendOrderPlaced(email: String, amount: Double, occurred: Instant)
  }

@Reactor
  class OrderNotificationsReactor(private val emailGateway: ReactorEmailGateway) {
      fun placed(event: ReactorOrderPlaced, context: EventContext) {
          emailGateway.sendOrderPlaced(
              event.customerEmail,
              event.totalAmount,
              context.occurred)
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.observation.Reactor;
  import java.time.Instant;

interface ReactorEmailGateway {
      void sendOrderPlaced(String email, double amount, Instant occurred);
  }

@Reactor
  class OrderNotificationsReactor {
      private final ReactorEmailGateway emailGateway;

OrderNotificationsReactor(ReactorEmailGateway emailGateway) {
          this.emailGateway = emailGateway;
      }

void placed(ReactorOrderPlaced event, EventContext context) {
          emailGateway.sendOrderPlaced(
              event.customerEmail(),
              event.totalAmount(),
              context.getOccurred());
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.EmailGateway do
    def order_placed(_email, _amount, _occurred), do: :ok
  end

defmodule MyApp.Reactors.OrderNotificationsReactor do
    use Chronicle.Reactors.Reactor

alias MyApp.Events.ReactorOrderPlaced

@handles ReactorOrderPlaced

@impl true
    def handle(%ReactorOrderPlaced{} = event, context) do
      MyApp.EmailGateway.order_placed(
        event.customer_email,
        event.total_amount,
        Map.get(context, :occurred))

:ok
    end
  end
  ```

* TypeScript

```typescript
  import { EventContext, reactor } from '@cratis/chronicle';

interface ReactorEmailGateway {
      sendOrderPlaced(email: string, amount: number, occurred: Date): Promise<void>;
  }

@reactor()
  class OrderNotificationsReactor {
      constructor(private readonly emailGateway: ReactorEmailGateway) {}

// Method name must be the exact camelCase of the event's class name -
      // Chronicle discovers handlers by name, not by parameter type.
      async reactorOrderPlaced(event: ReactorOrderPlaced, context: EventContext): Promise<void> {
          await this.emailGateway.sendOrderPlaced(
              event.customerEmail,
              event.totalAmount,
              context.occurred);
      }
  }
  ```

## Register the reactor

[Section titled “Register the reactor”](#register-the-reactor)

Registration is client-specific. Some clients discover reactor types and register them as part of event-store startup. Others register a reactor instance or include the reactor module in client startup options.

* C#

```csharp
  public class ReactorRegistration
  {
      public Task Register(IEventStore eventStore) => eventStore.Reactors.Register();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import kotlinx.coroutines.Job

class ReactorRegistration(private val emailGateway: ReactorEmailGateway) {
      suspend fun register(store: IEventStore): Job =
          store.reactors.register(OrderNotificationsReactor(emailGateway))
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingEventStore;
  import kotlinx.coroutines.Job;

class ReactorRegistration {
      private final ReactorEmailGateway emailGateway;

ReactorRegistration(ReactorEmailGateway emailGateway) {
          this.emailGateway = emailGateway;
      }

Job register(IEventStore store) {
          return new BlockingEventStore(store)
              .getReactors()
              .register(new OrderNotificationsReactor(emailGateway));
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReactorClientConfig do
    def child_spec do
      {Chronicle.Client,
       connection_string: "chronicle://localhost:35000",
       event_store: "store",
       reactors: [MyApp.Reactors.OrderNotificationsReactor]}
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

class ReactorRegistration {
      async register(store: IEventStore): Promise<void> {
          await store.reactors.register();
      }
  }
  ```

## Use a stable reactor ID

[Section titled “Use a stable reactor ID”](#use-a-stable-reactor-id)

By default, clients derive a reactor identifier from the type or module name. Set an explicit ID when the reactor’s identity must survive a rename. Changing the ID makes Chronicle treat it as a different observer, with a different observation position.

* C#

```csharp
  [Reactor(id: "order-notifications")]
  public class NamedOrderNotificationsReactor : IReactor
  {
      public Task Placed(ReactorOrderPlaced @event) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.observation.Reactor

@Reactor(id = "order-notifications")
  class NamedOrderNotificationsReactor {
      fun placed(event: ReactorOrderPlaced) {
          // Perform the side effect.
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.observation.Reactor;

@Reactor(id = "order-notifications")
  class NamedOrderNotificationsReactor {
      void placed(ReactorOrderPlaced event) {
          // Perform the side effect.
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Reactors.NamedOrderNotificationsReactor do
    use Chronicle.Reactors.Reactor, id: "order-notifications"

alias MyApp.Events.ReactorOrderPlaced

@handles ReactorOrderPlaced

@impl true
    def handle(%ReactorOrderPlaced{}, _context), do: :ok
  end
  ```

* TypeScript

```typescript
  import { reactor } from '@cratis/chronicle';

@reactor('order-notifications')
  class NamedOrderNotificationsReactor {
      // Method name must be the exact camelCase of the event's class name -
      // Chronicle discovers handlers by name, not by parameter type.
      async reactorOrderPlaced(_event: ReactorOrderPlaced): Promise<void> {
          // Perform the side effect.
      }
  }
  ```

## Design for replay

[Section titled “Design for replay”](#design-for-replay)

Reactors may see the same event again after replay, recovery, reconnect, or a retry. Make every side effect idempotent. Common patterns are idempotency keys, check-then-act storage, database upserts, or downstream APIs that tolerate duplicate requests.

## Next steps

[Section titled “Next steps”](#next-steps)

* Learn the shared [reactor event-processing model](/chronicle/reactors/event-processing/)
* Compare reactors with [reducers](/chronicle/reducers/) and [projections](/chronicle/projections/)
* Use [tagging reactors](/chronicle/concepts/tagging-reactors/) when you need to organize observer behavior

# OnceOnly

The `OnceOnly` attribute marks a reactor handler that must not run again when its observer is replayed.

There are scenarios where you need side effects to occur only on the initial event processing, such as sending notifications, triggering external integrations, or performing non-idempotent operations.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record OnceOnlyOrderPlaced(string OrderId);

public class OnceOnlyOrderReactor : IReactor
  {
      [OnceOnly]
      public void SendNotification(OnceOnlyOrderPlaced @event)
      {
          // This code will only execute once when the event is first processed,
          // and will be skipped during replay.
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.OnceOnly
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class OnceOnlyOrderPlaced(val orderId: String)

@Reactor
  class OnceOnlyOrderReactor {
      @OnceOnly
      fun sendNotification(event: OnceOnlyOrderPlaced) {
          // Runs once when the event is first observed, and is skipped during replay.
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.OnceOnly;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record OnceOnlyOrderPlaced(String orderId) {}

@Reactor
  class OnceOnlyOrderReactor {
      @OnceOnly
      void sendNotification(OnceOnlyOrderPlaced event) {
          // Runs once when the event is first observed, and is skipped during replay.
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

`OnceOnly` gives you a clean way to separate one-time operations from normal reactor behavior.

## What it does and does not guarantee

[Section titled “What it does and does not guarantee”](#what-it-does-and-does-not-guarantee)

`OnceOnly` takes the handler out of **replay** — the deliberate re-delivery you trigger by rewinding an observer, or that a redaction or revision triggers for you. That is the whole of it.

It is not an exactly-once delivery guarantee. In particular, **recovering a failed partition re-delivers the event as an ordinary observation, so a `OnceOnly` handler runs again** — which is the point of a retry: the handler failed before its side effect ran, and recovery exists to run it. Keep designing for the handler being invoked more than once when it fails partway through.

When the side effect must survive that retry too, take a [delivery identity](/chronicle/reactors/delivery-identity/) alongside this attribute: it gives you a key that is stable across the failure and the recovery, so a record you keep under it lets the handler recognize the redelivery. The two compose — `OnceOnly` keeps replay out for free, the identity covers what is left.

## Where you put it

[Section titled “Where you put it”](#where-you-put-it)

`OnceOnly` goes on a handler method or on the reactor class, and the two mean different things:

* **On a method** — that handler is skipped for every event that arrives as part of a replay. The rest of the reactor still replays, which is what you want when only one of its handlers has a non-idempotent side effect.
* **On the class** — the whole reactor registers as non-replayable, so a replay of its observer never starts and none of its handlers run again. This is strictly coarser: it takes every handler out of replay, not just the one with the side effect.

Reach for the method placement unless the entire reactor exists to do something that must not happen twice.

Client coverage

Elixir and TypeScript have no equivalent marker, so a replay always re-runs the full handler there. Design side effects to be idempotent instead (see [Getting started with reactors](/chronicle/reactors/getting-started/)).

# Replay

A reactor sees the same event twice for different reasons: once as it happens, and again whenever its observer is replayed. Those often call for different work — a confirmation that should go out once when an order is placed has no business going out again while a read model is being rebuilt.

Mark a second handler for the same event type with the `Replay` attribute and it takes over for the duration of the replay.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReplayAwareOrderPlaced(string OrderId);

public class ReplayAwareOrderReactor : IReactor
  {
      public void SendConfirmation(ReplayAwareOrderPlaced @event)
      {
          // Runs as the event happens.
      }

[Replay]
      public void RebuildProjectionCache(ReplayAwareOrderPlaced @event)
      {
          // Runs instead of SendConfirmation while the observer is replaying.
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.observation.Replay

@EventType
  data class ReplayAwareOrderPlaced(val orderId: String)

@Reactor
  class ReplayAwareOrderReactor {
      fun sendConfirmation(event: ReplayAwareOrderPlaced) {
          // Runs as the event happens.
      }

@Replay
      fun rebuildProjectionCache(event: ReplayAwareOrderPlaced) {
          // Runs instead of sendConfirmation while the observer is replaying.
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.Reactor;
  import io.cratis.chronicle.observation.Replay;

@EventType
  record ReplayAwareOrderPlaced(String orderId) {}

@Reactor
  class ReplayAwareOrderReactor {
      void sendConfirmation(ReplayAwareOrderPlaced event) {
          // Runs as the event happens.
      }

@Replay
      void rebuildProjectionCache(ReplayAwareOrderPlaced event) {
          // Runs instead of sendConfirmation while the observer is replaying.
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { EventContext, eventType, ICanBeNotifiedWhenReplay, reactor } from '@cratis/chronicle';

@eventType()
  class ReplayAwareOrderPlaced {
      constructor(readonly orderId: string = '') {}
  }

// Implement ICanBeNotifiedWhenReplay to be told when a full replay of this reactor's
  // observation begins and ends - useful for suppressing side effects (e.g.
  // notifications) while historical events are being reprocessed. A throwing hook marks
  // the batch Failed, the same as a handler that throws.
  @reactor()
  class ReplayAwareOrderReactor implements ICanBeNotifiedWhenReplay {
      private _isReplaying = false;

async beginReplay(): Promise<void> {
          this._isReplaying = true;
      }

async endReplay(): Promise<void> {
          this._isReplaying = false;
      }

async replayAwareOrderPlaced(event: ReplayAwareOrderPlaced, context: EventContext): Promise<void> {
          if (this._isReplaying) {
              // Runs during replay too - skip side effects that must not repeat.
              return;
          }

// Runs as the event happens for the first time.
      }
  }
  ```

The rules are:

* With a `Replay` handler, **only** it runs during a replay — the regular handler does not also run.
* Without one, the regular handler runs during a replay exactly as it always has, so adding this to one event type changes nothing for the others.
* An event type handled **only** by a `Replay` handler is still subscribed to, so the replay it exists for delivers it.

Reach for [OnceOnly](/chronicle/reactors/once-only/) instead when the side effect should simply not happen again. Use `Replay` when a replay needs to do something *different* rather than nothing. Neither covers the re-delivery that follows a failed partition being recovered — for that, see [Delivery identity](/chronicle/reactors/delivery-identity/).

Client coverage

Elixir and TypeScript have no equivalent marker, so a replay always re-runs the regular handler there.

# Returning Side Effects from Reactor Handler Methods

Reactor handler methods can return side-effect events directly instead of taking a dependency on `IEventLog`. The framework automatically appends the returned events to the correct sequence after the handler completes.

Client coverage

Auto-appending a reactor handler’s return value is currently C#-only. Kotlin and Java reactor dispatch (`ReactorsService`) ignores the handler’s return value entirely; Elixir’s `handle/2` return value (`:ok` / `{:error, reason}`) reports success/failure, not an event to append; TypeScript’s dispatch likewise doesn’t inspect what the handler returns. In all four other clients, appending a follow-up event from a reactor means calling the append API explicitly inside the handler — see [Getting started with reactors](/chronicle/reactors/getting-started/) and [Event Processing](/chronicle/reactors/event-processing/) for what each client’s handler can and can’t do.

> **Important**: Side-effect appends are not fire-and-forget. If a returned event fails to append — a constraint violation, a concurrency conflict, or an error — the reactor’s partition fails with the failure details and is retried per the observer’s retry policy. Failures never pass silently. See [Error handling](#error-handling).

## Basic Usage

[Section titled “Basic Usage”](#basic-usage)

Return a single event directly from a handler method — synchronously or as a `Task<T>`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record SideEffectsBookReserved(string Isbn);

[EventType]
  public record StockDecreased(string Isbn, int Quantity);

public class WarehouseReactor : IReactor
  {
      public StockDecreased BookReserved(SideEffectsBookReserved @event, EventContext context) =>
          new(@event.Isbn, 1);

public async Task<StockDecreased> BookReservedAsync(SideEffectsBookReserved @event, EventContext context)
      {
          var available = await FetchCurrentStockAsync(@event.Isbn);
          return new StockDecreased(@event.Isbn, available);
      }

Task<int> FetchCurrentStockAsync(string isbn) => Task.FromResult(0);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class SideEffectsBookReserved(val isbn: String)

@EventType
  data class SideEffectsStockCheckRequested(val isbn: String)

@EventType
  data class StockDecreased(val isbn: String, val quantity: Int)

@Reactor
  class WarehouseReactor {
      // Return the event directly - it is appended to the event log using the EventSourceId from
      // the incoming event.
      fun bookReserved(event: SideEffectsBookReserved, context: EventContext) =
          StockDecreased(event.isbn, 1)

// A handler may suspend before returning its side-effect event.
      suspend fun stockCheckRequested(event: SideEffectsStockCheckRequested, context: EventContext): StockDecreased {
          val available = fetchCurrentStock(event.isbn)
          return StockDecreased(event.isbn, available)
      }

private suspend fun fetchCurrentStock(isbn: String): Int = 0
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record SideEffectsBookReserved(String isbn) {}

@EventType
  record SideEffectsStockCheckRequested(String isbn) {}

@EventType
  record StockDecreased(String isbn, int quantity) {}

@Reactor
  class WarehouseReactor {
      // Return the event directly - it is appended to the event log using the EventSourceId from
      // the incoming event.
      StockDecreased bookReserved(SideEffectsBookReserved event, EventContext context) {
          return new StockDecreased(event.isbn(), 1);
      }

StockDecreased stockCheckRequested(SideEffectsStockCheckRequested event, EventContext context) {
          int available = fetchCurrentStock(event.isbn());
          return new StockDecreased(event.isbn(), available);
      }

private int fetchCurrentStock(String isbn) {
          return 0;
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.OrderConfirmationQueued do
    use Chronicle.Events.EventType, id: "order-confirmation-queued"

defstruct [:customer_id]
  end

defmodule MyApp.Reactors.OrderNotifier do
    use Chronicle.Reactors.Reactor

alias MyApp.Events.{OrderConfirmationQueued, OrderPlaced}

@handles OrderPlaced

@impl true
    def handle(%OrderPlaced{} = event, _context) do
      {:ok, %OrderConfirmationQueued{customer_id: event.customer_id}}
    end
  end
  ```

* TypeScript

```typescript
  import { EventContext, eventType, reactor } from '@cratis/chronicle';

@eventType()
  class SideEffectsBookReserved {
      constructor(readonly isbn: string = '') {}
  }

@eventType()
  class SideEffectsStockDecreased {
      constructor(readonly isbn: string = '', readonly quantity: number = 0) {}
  }

@reactor()
  class SideEffectsWarehouseReactor {
      // Returning an event from a handler appends it for you, targeting the triggering
      // event's own event source id, stream, and subject.
      async sideEffectsBookReserved(event: SideEffectsBookReserved, context: EventContext): Promise<SideEffectsStockDecreased> {
          return new SideEffectsStockDecreased(event.isbn, 1);
      }
  }
  ```

The returned event is appended to the event log using the `EventSourceId` from the incoming `EventContext`. No `IEventLog` injection required.

## Multiple Side Effects

[Section titled “Multiple Side Effects”](#multiple-side-effects)

Return `IEnumerable<TEvent>` to append several events in one handler call:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record MultipleSideEffectsBookReserved(string Isbn);

[EventType]
  public record MultipleStockDecreased(string Isbn, int Quantity);

[EventType]
  public record StockLow(string Isbn);

public class InventoryReactor : IReactor
  {
      public IEnumerable<object> BookReserved(MultipleSideEffectsBookReserved @event, EventContext context) =>
      [
          new MultipleStockDecreased(@event.Isbn, 1),
          new StockLow(@event.Isbn),
      ];
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class MultipleSideEffectsBookReserved(val isbn: String)

@EventType
  data class MultipleStockDecreased(val isbn: String, val quantity: Int)

@EventType
  data class StockLow(val isbn: String)

@Reactor
  class InventoryReactor {
      // Return a List to append several events in one handler call.
      fun bookReserved(event: MultipleSideEffectsBookReserved, context: EventContext): List<Any> = listOf(
          MultipleStockDecreased(event.isbn, 1),
          StockLow(event.isbn)
      )
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.observation.Reactor;

import java.util.List;

@EventType
  record MultipleSideEffectsBookReserved(String isbn) {}

@EventType
  record MultipleStockDecreased(String isbn, int quantity) {}

@EventType
  record StockLow(String isbn) {}

@Reactor
  class InventoryReactor {
      // Return a List to append several events in one handler call.
      List<Object> bookReserved(MultipleSideEffectsBookReserved event, EventContext context) {
          return List.of(
              new MultipleStockDecreased(event.isbn(), 1),
              new StockLow(event.isbn()));
      }
  }
  ```

* Elixir

```elixir
  defmodule ReactorSideEffectsMultipleBookReserved do
    use Chronicle.Events.EventType, id: "reactor-side-effects-multiple-book-reserved"

defstruct [:isbn]
  end

defmodule ReactorSideEffectsMultipleStockDecreased do
    use Chronicle.Events.EventType, id: "reactor-side-effects-multiple-stock-decreased"

defstruct [:isbn, :quantity]
  end

defmodule ReactorSideEffectsMultipleStockLow do
    use Chronicle.Events.EventType, id: "reactor-side-effects-multiple-stock-low"

defstruct [:isbn]
  end

defmodule ReactorSideEffectsMultipleInventoryReactor do
    use Chronicle.Reactors.Reactor

alias ReactorSideEffectsMultipleBookReserved
    alias ReactorSideEffectsMultipleStockDecreased
    alias ReactorSideEffectsMultipleStockLow

@handles ReactorSideEffectsMultipleBookReserved

# Returning a list of bare event structs appends all of them, atomically,
    # to the triggering event's own event source id.
    @impl true
    def handle(%ReactorSideEffectsMultipleBookReserved{} = event, _context) do
      {:ok,
       [
         %ReactorSideEffectsMultipleStockDecreased{isbn: event.isbn, quantity: 1},
         %ReactorSideEffectsMultipleStockLow{isbn: event.isbn}
       ]}
    end
  end
  ```

* TypeScript

```typescript
  import { EventContext, eventType, reactor } from '@cratis/chronicle';

@eventType()
  class MultipleSideEffectsBookReserved {
      constructor(readonly isbn: string = '') {}
  }

@eventType()
  class MultipleSideEffectsStockDecreased {
      constructor(readonly isbn: string = '', readonly quantity: number = 0) {}
  }

@eventType()
  class MultipleSideEffectsStockLow {
      constructor(readonly isbn: string = '') {}
  }

@reactor()
  class MultipleSideEffectsInventoryReactor {
      // An array of events is appended together in one atomic AppendMany call - never
      // one append per item.
      async multipleSideEffectsBookReserved(event: MultipleSideEffectsBookReserved, context: EventContext): Promise<object[]> {
          return [
              new MultipleSideEffectsStockDecreased(event.isbn, 1),
              new MultipleSideEffectsStockLow(event.isbn)
          ];
      }
  }
  ```

## Targeting a Specific Event Source Id

[Section titled “Targeting a Specific Event Source Id”](#targeting-a-specific-event-source-id)

Everything above lands the returned event on the *triggering* event’s `EventSourceId` — optionally redirected once for the whole reactor via [`ICanProvideEventSourceId`](#icanprovideeventsourceid). That covers most reactors. But automation and translation reactors often need to write to a *different* entity than the one that triggered them — or to several at once.

Picture a library. A member reserves a book, and that reservation is a fact about the *book*:

* C#

```csharp
  using Cratis.Chronicle.Events;

public readonly record struct MemberId(string Value)
  {
      public static implicit operator EventSourceId(MemberId id) => new(id.Value);
  }

public readonly record struct Isbn(string Value)
  {
      public static implicit operator EventSourceId(Isbn id) => new(id.Value);
  }

[EventType]
  public record BookReserved(MemberId MemberId, Isbn Isbn);
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType

@EventType
  data class BookReserved(val memberId: String, val isbn: String)
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;

@EventType
  record BookReserved(String memberId, String isbn) {}
  ```

* Elixir

```elixir
  defmodule ReactorSideEffectsSourceEventBookReserved do
    use Chronicle.Events.EventType, id: "reactor-side-effects-source-event-book-reserved"

# Event source ids are plain strings in Elixir — no typed-id wrapper needed.
    defstruct [:member_id, :isbn]
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

When it happens you want to record activity on the *member* — a different event source altogether. Return an `EventForEventSourceId` and pick the target `EventSourceId` yourself:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record MemberActivityRecorded(Isbn Isbn);

public class ReservationReactor : IReactor
  {
      public EventForEventSourceId BookReserved(BookReserved @event, EventContext context) =>
          new(@event.MemberId, new MemberActivityRecorded(@event.Isbn));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.eventSequences.EventForEventSourceId
  import io.cratis.chronicle.observation.Reactor

@EventType
  data class MemberActivityRecorded(val isbn: String)

@Reactor
  class ReservationReactor {
      fun bookReserved(event: BookReserved, context: EventContext) =
          EventForEventSourceId(event.memberId, MemberActivityRecorded(event.isbn))
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.eventSequences.EventForEventSourceId;
  import io.cratis.chronicle.observation.Reactor;

@EventType
  record MemberActivityRecorded(String isbn) {}

@Reactor
  class ReservationReactor {
      EventForEventSourceId bookReserved(BookReserved event, EventContext context) {
          return new EventForEventSourceId(event.memberId(), new MemberActivityRecorded(event.isbn()));
      }
  }
  ```

* Elixir

```elixir
  defmodule ReactorSideEffectsSpecificBookReserved do
    use Chronicle.Events.EventType, id: "reactor-side-effects-specific-book-reserved"

defstruct [:member_id, :isbn]
  end

defmodule ReactorSideEffectsSpecificMemberActivityRecorded do
    use Chronicle.Events.EventType, id: "reactor-side-effects-specific-member-activity-recorded"

defstruct [:isbn]
  end

defmodule ReactorSideEffectsSpecificReservationReactor do
    use Chronicle.Reactors.Reactor

alias Chronicle.EventSequences.EventForEventSourceId
    alias ReactorSideEffectsSpecificBookReserved
    alias ReactorSideEffectsSpecificMemberActivityRecorded

@handles ReactorSideEffectsSpecificBookReserved

# MemberActivityRecorded is a fact about the member, not the book that
    # triggered the reactor — pick the target event source id explicitly by
    # returning an EventForEventSourceId instead of a bare event.
    @impl true
    def handle(%ReactorSideEffectsSpecificBookReserved{} = event, _context) do
      {:ok,
       %EventForEventSourceId{
         event_source_id: event.member_id,
         event: %ReactorSideEffectsSpecificMemberActivityRecorded{isbn: event.isbn}
       }}
    end
  end
  ```

* TypeScript

```typescript
  import { EventContext, EventForEventSourceId, eventType, reactor } from '@cratis/chronicle';

@eventType()
  class SpecificSourceBookReserved {
      constructor(readonly isbn: string = '', readonly memberId: string = '') {}
  }

@eventType()
  class SpecificSourceMemberActivityRecorded {
      constructor(readonly isbn: string = '') {}
  }

@reactor()
  class SpecificSourceReservationReactor {
      // Returning an EventForEventSourceId targets a different event source than the one
      // that triggered the reactor - here, the member's own stream rather than the book's.
      async specificSourceBookReserved(event: SpecificSourceBookReserved, context: EventContext): Promise<EventForEventSourceId> {
          return {
              eventSourceId: event.memberId,
              event: new SpecificSourceMemberActivityRecorded(event.isbn)
          };
      }
  }
  ```

`MemberActivityRecorded` is appended to `@event.MemberId`, **not** to the book that triggered the reactor — so it shows up on the member’s stream, ready for a member-activity projection to pick up.

A single reservation usually ripples to more than one entity: the member gains activity, and the book loses stock. Return `IEnumerable<EventForEventSourceId>` to fan out to several event source ids in one go — they are appended together as a single transaction:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record FanOutStockDecreased(Isbn Isbn, int Quantity);

public class ReservationFanOutReactor : IReactor
  {
      public IEnumerable<EventForEventSourceId> BookReserved(BookReserved @event, EventContext context) =>
      [
          new(@event.MemberId, new MemberActivityRecorded(@event.Isbn)),
          new(@event.Isbn, new FanOutStockDecreased(@event.Isbn, 1)),
      ];
  }
  ```

* Kotlin

@EventType
  data class FanOutStockDecreased(val isbn: String, val quantity: Int)

@Reactor
  class ReservationFanOutReactor {
      // Fan out to several event source ids in one go - they are appended together as a single
      // transaction.
      fun bookReserved(event: BookReserved, context: EventContext): List<EventForEventSourceId> = listOf(
          EventForEventSourceId(event.memberId, MemberActivityRecorded(event.isbn)),
          EventForEventSourceId(event.isbn, FanOutStockDecreased(event.isbn, 1))
      )
  }
  ```

* Java

import java.util.List;

@EventType
  record FanOutStockDecreased(String isbn, int quantity) {}

@Reactor
  class ReservationFanOutReactor {
      // Fan out to several event source ids in one go - they are appended together as a single
      // transaction.
      List<EventForEventSourceId> bookReserved(BookReserved event, EventContext context) {
          return List.of(
              new EventForEventSourceId(event.memberId(), new MemberActivityRecorded(event.isbn())),
              new EventForEventSourceId(event.isbn(), new FanOutStockDecreased(event.isbn(), 1)));
      }
  }
  ```

* Elixir

```elixir
  defmodule ReactorSideEffectsFanOutBookReserved do
    use Chronicle.Events.EventType, id: "reactor-side-effects-fan-out-book-reserved"

defstruct [:member_id, :isbn]
  end

defmodule ReactorSideEffectsFanOutMemberActivityRecorded do
    use Chronicle.Events.EventType, id: "reactor-side-effects-fan-out-member-activity-recorded"

defstruct [:isbn]
  end

defmodule ReactorSideEffectsFanOutStockDecreased do
    use Chronicle.Events.EventType, id: "reactor-side-effects-fan-out-stock-decreased"

defstruct [:isbn, :quantity]
  end

defmodule ReactorSideEffectsFanOutReservationReactor do
    use Chronicle.Reactors.Reactor

alias Chronicle.EventSequences.EventForEventSourceId
    alias ReactorSideEffectsFanOutBookReserved
    alias ReactorSideEffectsFanOutMemberActivityRecorded
    alias ReactorSideEffectsFanOutStockDecreased

@handles ReactorSideEffectsFanOutBookReserved

# A reservation ripples to two different event sources — the member gains
    # activity, and the book loses stock. Returning a list of
    # EventForEventSourceId appends them together as one atomic transaction.
    @impl true
    def handle(%ReactorSideEffectsFanOutBookReserved{} = event, _context) do
      {:ok,
       [
         %EventForEventSourceId{
           event_source_id: event.member_id,
           event: %ReactorSideEffectsFanOutMemberActivityRecorded{isbn: event.isbn}
         },
         %EventForEventSourceId{
           event_source_id: event.isbn,
           event: %ReactorSideEffectsFanOutStockDecreased{isbn: event.isbn, quantity: 1}
         }
       ]}
    end
  end
  ```

* TypeScript

```typescript
  import { EventContext, EventForEventSourceId, eventType, reactor } from '@cratis/chronicle';

@eventType()
  class FanOutBookReserved {
      constructor(readonly isbn: string = '', readonly memberId: string = '') {}
  }

@eventType()
  class FanOutMemberActivityRecorded {
      constructor(readonly isbn: string = '') {}
  }

@eventType()
  class FanOutStockDecreased {
      constructor(readonly isbn: string = '', readonly quantity: number = 0) {}
  }

@reactor()
  class ReservationFanOutReactor {
      async fanOutBookReserved(event: FanOutBookReserved, context: EventContext): Promise<EventForEventSourceId[]> {
          return [
              { eventSourceId: event.memberId, event: new FanOutMemberActivityRecorded(event.isbn) },
              { eventSourceId: event.isbn, event: new FanOutStockDecreased(event.isbn, 1) }
          ];
      }
  }
  ```

Each `EventForEventSourceId` is self-describing: alongside the source id it carries the event stream type and id, source type, subject, occurred time, tags and causation. Set only the ones you need — the rest fall back to sensible defaults:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

public class ExplicitMetadataReactor : IReactor
  {
      public EventForEventSourceId BookReserved(BookReserved @event, EventContext context) =>
          new(@event.MemberId, new MemberActivityRecorded(@event.Isbn))
          {
              EventStreamType = new EventStreamType("members"),
              Subject = new Subject(@event.MemberId.Value),
          };
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventContext
  import io.cratis.chronicle.observation.Reactor
  import io.cratis.chronicle.eventSequences.EventForEventSourceId

@Reactor
  class ExplicitMetadataReactor {
      fun bookReserved(event: BookReserved, context: EventContext) =
          EventForEventSourceId(
              eventSourceId = event.memberId,
              event = MemberActivityRecorded(event.isbn),
              eventStreamType = "members",
              subject = event.memberId
          )
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventContext;
  import io.cratis.chronicle.eventSequences.EventForEventSourceId;
  import io.cratis.chronicle.observation.Reactor;

@Reactor
  class ExplicitMetadataReactor {
      EventForEventSourceId bookReserved(BookReserved event, EventContext context) {
          return new EventForEventSourceId(
              event.memberId(),
              new MemberActivityRecorded(event.isbn()),
              "members",
              null,
              null,
              java.util.List.of(),
              null,
              event.memberId(),
              java.util.List.of());
      }
  }
  ```

* Elixir

```elixir
  defmodule ReactorSideEffectsExplicitBookReserved do
    use Chronicle.Events.EventType, id: "reactor-side-effects-explicit-book-reserved"

defstruct [:member_id, :isbn]
  end

defmodule ReactorSideEffectsExplicitMemberActivityRecorded do
    use Chronicle.Events.EventType, id: "reactor-side-effects-explicit-member-activity-recorded"

defstruct [:isbn]
  end

defmodule ReactorSideEffectsExplicitMetadataReactor do
    use Chronicle.Reactors.Reactor

alias Chronicle.EventSequences.EventForEventSourceId
    alias ReactorSideEffectsExplicitBookReserved
    alias ReactorSideEffectsExplicitMemberActivityRecorded

@handles ReactorSideEffectsExplicitBookReserved

# An EventForEventSourceId is self-describing: alongside the target event
    # source id it carries the stream type, subject, and every other append
    # option. Set only the fields you need — the rest fall back to defaults.
    @impl true
    def handle(%ReactorSideEffectsExplicitBookReserved{} = event, _context) do
      {:ok,
       %EventForEventSourceId{
         event_source_id: event.member_id,
         event: %ReactorSideEffectsExplicitMemberActivityRecorded{isbn: event.isbn},
         event_stream_type: "members",
         subject: event.member_id
       }}
    end
  end
  ```

* TypeScript

```typescript
  import { EventContext, EventForEventSourceId, eventType, reactor } from '@cratis/chronicle';

@eventType()
  class ExplicitMetadataBookReserved {
      constructor(readonly isbn: string = '', readonly memberId: string = '') {}
  }

@eventType()
  class ExplicitMetadataMemberActivityRecorded {
      constructor(readonly isbn: string = '') {}
  }

@reactor()
  class ExplicitMetadataReactor {
      async explicitMetadataBookReserved(event: ExplicitMetadataBookReserved, context: EventContext): Promise<EventForEventSourceId> {
          return {
              eventSourceId: event.memberId,
              event: new ExplicitMetadataMemberActivityRecorded(event.isbn),
              eventStreamType: 'members',
              subject: event.memberId
          };
      }
  }
  ```

> **Two modes**: a **bare event** uses the reactor’s resolved metadata — its `[EventStreamType]`/`[EventSourceType]` attributes and `ICanProvide*` interfaces. An **`EventForEventSourceId`** is the *explicit* mode: it is self-describing and uses only the values on it, so the reactor’s metadata does **not** apply (an unset field takes the append default such as `EventStreamType.All`, and an omitted `Subject` is resolved from the event). Reach for a bare event when you want “use my reactor’s config”, and an `EventForEventSourceId` when you want “I’ll specify exactly where and how”.

You can also **mix** the two in a single `IEnumerable<object>` return — each bare event uses the reactor’s resolved metadata and the triggering event source id, while each `EventForEventSourceId` keeps its own. They are appended together as one transaction:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ActivityLogged(Isbn Isbn);

public class MixedSideEffectsReactor : IReactor
  {
      public IEnumerable<object> BookReserved(BookReserved @event, EventContext context) =>
      [
          new ActivityLogged(@event.Isbn),
          new EventForEventSourceId(@event.MemberId, new MemberActivityRecorded(@event.Isbn)),
      ];
  }
  ```

* Kotlin

@EventType
  data class ActivityLogged(val isbn: String)

@Reactor
  class MixedSideEffectsReactor {
      // A bare event uses the triggering event's EventSourceId; an EventForEventSourceId keeps its
      // own. Mix both in a single List and they are appended together as one transaction.
      fun bookReserved(event: BookReserved, context: EventContext): List<Any> = listOf(
          ActivityLogged(event.isbn),
          EventForEventSourceId(event.memberId, MemberActivityRecorded(event.isbn))
      )
  }
  ```

* Java

import java.util.List;

@EventType
  record ActivityLogged(String isbn) {}

@Reactor
  class MixedSideEffectsReactor {
      // A bare event uses the triggering event's EventSourceId; an EventForEventSourceId keeps its
      // own. Mix both in a single List and they are appended together as one transaction.
      List<Object> bookReserved(BookReserved event, EventContext context) {
          return List.of(
              new ActivityLogged(event.isbn()),
              new EventForEventSourceId(event.memberId(), new MemberActivityRecorded(event.isbn())));
      }
  }
  ```

* Elixir

```elixir
  defmodule ReactorSideEffectsMixedBookReserved do
    use Chronicle.Events.EventType, id: "reactor-side-effects-mixed-book-reserved"

defstruct [:member_id, :isbn]
  end

defmodule ReactorSideEffectsMixedActivityLogged do
    use Chronicle.Events.EventType, id: "reactor-side-effects-mixed-activity-logged"

defstruct [:isbn]
  end

defmodule ReactorSideEffectsMixedMemberActivityRecorded do
    use Chronicle.Events.EventType, id: "reactor-side-effects-mixed-member-activity-recorded"

defstruct [:isbn]
  end

defmodule ReactorSideEffectsMixedReservationReactor do
    use Chronicle.Reactors.Reactor

alias Chronicle.EventSequences.EventForEventSourceId
    alias ReactorSideEffectsMixedBookReserved
    alias ReactorSideEffectsMixedActivityLogged
    alias ReactorSideEffectsMixedMemberActivityRecorded

@handles ReactorSideEffectsMixedBookReserved

# A bare event uses the triggering event's own event source id; an
    # EventForEventSourceId keeps its own explicit target. Mixing both in one
    # list still appends them together as a single transaction.
    @impl true
    def handle(%ReactorSideEffectsMixedBookReserved{} = event, _context) do
      {:ok,
       [
         %ReactorSideEffectsMixedActivityLogged{isbn: event.isbn},
         %EventForEventSourceId{
           event_source_id: event.member_id,
           event: %ReactorSideEffectsMixedMemberActivityRecorded{isbn: event.isbn}
         }
       ]}
    end
  end
  ```

* TypeScript

```typescript
  import { EventContext, EventForEventSourceId, eventType, reactor } from '@cratis/chronicle';

@eventType()
  class MixedBookReserved {
      constructor(readonly isbn: string = '', readonly memberId: string = '') {}
  }

@eventType()
  class MixedActivityLogged {
      constructor(readonly isbn: string = '') {}
  }

@eventType()
  class MixedMemberActivityRecorded {
      constructor(readonly isbn: string = '') {}
  }

@reactor()
  class MixedSideEffectsReactor {
      // A bare event uses the triggering event's own target; an EventForEventSourceId
      // entry keeps its own explicit target - both can be returned together, in one
      // atomic AppendMany call.
      async mixedBookReserved(event: MixedBookReserved, context: EventContext): Promise<Array<object | EventForEventSourceId>> {
          return [
              new MixedActivityLogged(event.isbn),
              { eventSourceId: event.memberId, event: new MixedMemberActivityRecorded(event.isbn) }
          ];
      }
  }
  ```

## Add concurrency scopes to returned events

[Section titled “Add concurrency scopes to returned events”](#add-concurrency-scopes-to-returned-events)

Returning events is convenient, but sometimes the decision is only valid against the exact event-log state the reactor read. Return `EventsWithConcurrencyScopes` to submit an ordered list of `EventForEventSourceId` values and its concurrency scopes through one `AppendMany` call:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.EventSequences.Concurrency;
  using Cratis.Chronicle.Reactors;

[EventType]
  public record ReservationConfirmed(Isbn Isbn);

public class ReservationConfirmationReactor : IReactor
  {
      public EventsWithConcurrencyScopes BookReserved(BookReserved @event, EventContext context) =>
          new(
              [new EventForEventSourceId(context.EventSourceId, new ReservationConfirmed(@event.Isbn))],
              new Dictionary<EventSourceId, ConcurrencyScope>
              {
                  [context.EventSourceId] = new(
                      context.SequenceNumber,
                      EventSourceId: context.EventSourceId),
              });
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```elixir
  defmodule ReactorSideEffectsConcurrencyBookReserved do
    use Chronicle.Events.EventType, id: "reactor-side-effects-concurrency-book-reserved"

defstruct [:isbn]
  end

defmodule ReactorSideEffectsConcurrencyReservationConfirmed do
    use Chronicle.Events.EventType, id: "reactor-side-effects-concurrency-reservation-confirmed"

defstruct [:isbn]
  end

defmodule ReactorSideEffectsConcurrencyReservationReactor do
    use Chronicle.Reactors.Reactor

alias Chronicle.EventSequences.EventForEventSourceId
    alias Chronicle.Events.ConcurrencyScope
    alias ReactorSideEffectsConcurrencyBookReserved
    alias ReactorSideEffectsConcurrencyReservationConfirmed

@handles ReactorSideEffectsConcurrencyBookReserved

# Only append if no later event for the triggering source has appeared
    # since this one was read — set concurrency_scope on the
    # EventForEventSourceId to the sequence number the reactor observed.
    @impl true
    def handle(%ReactorSideEffectsConcurrencyBookReserved{} = event, context) do
      {:ok,
       %EventForEventSourceId{
         event_source_id: Map.get(context, :event_source_id),
         event: %ReactorSideEffectsConcurrencyReservationConfirmed{isbn: event.isbn},
         concurrency_scope: ConcurrencyScope.for_event_source(Map.get(context, :sequence_number))
       }}
    end
  end
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Here the reactor appends only if no later event for the triggering source has appeared since `BookReserved`. Chronicle materializes the events and copies the scope dictionary when you create the result, then submits both together. A failed constraint, concurrency check, or append fails the reactor partition; Chronicle never splits the return into partial appends.

A scope entry with `ConcurrencyScope.NotSet`, or a missing entry for an event source id in the batch, asks the configured concurrency strategy to resolve that source’s scope. Use `ConcurrencyScope.None` when you explicitly want no check for a key. Chronicle passes every other scope through unchanged.

The event list preserves the order you supplied to the append operation. That does not impose a global processing order on observers: events targeting different source partitions can be observed independently. The scope dictionary also holds one scope per `EventSourceId` key; it cannot represent multiple independent scopes under the same key.

## Reactor-Level Metadata Resolution

[Section titled “Reactor-Level Metadata Resolution”](#reactor-level-metadata-resolution)

Set metadata once on the reactor type so every returned event inherits it automatically.

### `ICanProvideEventSourceId`

[Section titled “ICanProvideEventSourceId”](#icanprovideeventsourceid)

Implement this interface to supply a custom `EventSourceId` for all side-effect events from this reactor:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

public class WarehouseEventSourceReactor(string warehouseId) : IReactor, ICanProvideEventSourceId
  {
      public EventSourceId GetEventSourceId() => warehouseId;

public StockDecreased BookReserved(SideEffectsBookReserved @event, EventContext context) =>
          new(@event.Isbn, 1);
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### `ICanProvideSubject`

[Section titled “ICanProvideSubject”](#icanprovidesubject)

Implement this interface to attach a `Subject` (e.g. a user or principal) to appended events:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

public class OrderReactor(string userId) : IReactor, ICanProvideSubject
  {
      public Subject GetSubject() => new(userId);
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### `ICanProvideEventStreamId`

[Section titled “ICanProvideEventStreamId”](#icanprovideeventstreamid)

Implement this interface to specify a runtime `EventStreamId`:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

public class TenantReactor(string tenantId) : IReactor, ICanProvideEventStreamId
  {
      public EventStreamId GetEventStreamId() => tenantId;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### `[EventStreamType]` and `[EventSourceType]` Attributes

[Section titled “\[EventStreamType\] and \[EventSourceType\] Attributes”](#eventstreamtype-and-eventsourcetype-attributes)

Apply these attributes to the reactor class for a compile-time stream or source type:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reactors;

[EventStreamType("warehouse")]
  [EventSourceType("product")]
  public class WarehouseMetadataReactor : IReactor
  {
      public StockDecreased BookReserved(SideEffectsBookReserved @event, EventContext context) =>
          new(@event.Isbn, 1);
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### Priority Order

[Section titled “Priority Order”](#priority-order)

| Metadata          | Priority                                                            |
| ----------------- | ------------------------------------------------------------------- |
| `EventSourceId`   | `ICanProvideEventSourceId` -> `eventContext.EventSourceId`          |
| `EventStreamId`   | `ICanProvideEventStreamId` -> `[EventStreamId]` attribute -> `null` |
| `EventStreamType` | `[EventStreamType]` attribute -> `null`                             |
| `EventSourceType` | `[EventSourceType]` attribute -> `null`                             |
| `Subject`         | `ICanProvideSubject` -> `null`                                      |

## Custom Return Type Handlers

[Section titled “Custom Return Type Handlers”](#custom-return-type-handlers)

Extend the pipeline by registering a custom `IReactorSideEffectHandler`:

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Reactors.SideEffects;
  using Cratis.Monads;
  using Microsoft.Extensions.DependencyInjection;

public record MySpecialResult;

public class MyHandler : IReactorSideEffectHandler
  {
      public bool CanHandle(ReactorContext reactorContext, object value) =>
          value is MySpecialResult;

public bool CanHandle(ReactorContext reactorContext, IEventStore eventStore, object value) =>
          CanHandle(reactorContext, value);

public Task<Result<ReactorSideEffectFailure>> Handle(
          ReactorContext reactorContext,
          IEventStore eventStore,
          object value)
      {
          return Task.FromResult(Result.Success<ReactorSideEffectFailure>());
      }
  }

public static class ReactorSideEffectRegistration
  {
      public static void Add(IServiceCollection services)
      {
          services.AddSingleton<IReactorSideEffectHandler, MyHandler>();
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Supported Return Types

[Section titled “Supported Return Types”](#supported-return-types)

| Return type                                                     | Handler invoked                                                                                                                                 |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `TEvent`                                                        | `EventResultHandler` — appends single event to the triggering/reactor event source id                                                           |
| `Task<TEvent>`                                                  | `EventResultHandler`                                                                                                                            |
| `IEnumerable<TEvent>`                                           | `EventsResultHandler` — appends each event                                                                                                      |
| `Task<IEnumerable<TEvent>>`                                     | `EventsResultHandler`                                                                                                                           |
| `EventForEventSourceId`                                         | `EventForEventSourceIdResultHandler` — appends to the event source id carried by the value                                                      |
| `Task<EventForEventSourceId>`                                   | `EventForEventSourceIdResultHandler`                                                                                                            |
| `IEnumerable<EventForEventSourceId>`                            | `EventsForEventSourceIdResultHandler` — appends all as one transaction                                                                          |
| `Task<IEnumerable<EventForEventSourceId>>`                      | `EventsForEventSourceIdResultHandler`                                                                                                           |
| `EventsWithConcurrencyScopes`                                   | `EventsWithConcurrencyScopesResultHandler` — appends its ordered events and scopes as one transaction                                           |
| `Task<EventsWithConcurrencyScopes>`                             | `EventsWithConcurrencyScopesResultHandler`                                                                                                      |
| `IEnumerable<object>` mixing events and `EventForEventSourceId` | `MixedSideEffectsResultHandler` — bare events use reactor metadata, each `EventForEventSourceId` keeps its own; all appended as one transaction |
| `void` / `Task`                                                 | No side effects appended                                                                                                                        |

## Error handling

[Section titled “Error handling”](#error-handling)

If a side-effect append fails, Chronicle marks the reactor partition as failed. Fix the underlying cause and retry or rewind the observer to continue processing.

# Read Models

Your events are the truth of *what happened*, but they’re a terrible thing to query — to show an account balance you’d have to replay every deposit and withdrawal. A **read model** is the answer to that: a shaped, queryable view of your data, built from events and kept up to date for you. It’s the “read side” of CQRS — the events are the write side.

```
projection / reducer

query

Events

Read model

Your app
```

The power is specialization: one event log can feed *many* read models, each tailored to a single screen or question. You don’t reuse one model across conflicting needs — you build a focused one per view, so each stays small, fast, and independent.

## How a read model gets built

[Section titled “How a read model gets built”](#how-a-read-model-gets-built)

You don’t write to a read model directly — an [observer](/chronicle/concepts/observers/) keeps it in sync with the events:

* A [projection](/chronicle/projections/) maps events into the model declaratively — the usual choice.
* A [reducer](/chronicle/reducers/) folds events into the model imperatively, when you need more control.

## What to read next

[Section titled “What to read next”](#what-to-read-next)

| Topic                                                                        | What it covers                                                                                      |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [Consistency models](/chronicle/read-models/consistency/)                    | The key decision: when does the read model have to be correct — immediately, or eventually?         |
| [Empty child collections](/chronicle/read-models/empty-child-collections/)   | Why a child collection with no children is absent rather than `[]`, and how to say what that means. |
| [Getting a single instance](/chronicle/read-models/getting-single-instance/) | Retrieve one read model instance by its key.                                                        |
| [Getting a collection](/chronicle/read-models/getting-collection-instances/) | Retrieve all instances of a read model.                                                             |
| [Getting snapshots](/chronicle/read-models/getting-snapshots/)               | Retrieve historical snapshots of a read model’s state.                                              |
| [Watching read models](/chronicle/read-models/watching-read-models/)         | Observe a read model and react to changes in real time.                                             |
| [Releasing PII](/chronicle/read-models/releasing-pii/)                       | Decrypt PII in a read model instance you already have, and how the subject is resolved.             |

To expose a read model to a React frontend, pair it with an [Arc query](/arc/backend/queries/) — or see the whole loop in [Build a full-stack feature](/build-a-full-app/).

# Consistency Models

Read models in Chronicle can be retrieved with different consistency guarantees, depending on how they are computed and when they reflect the latest events. Understanding these models helps you make the right trade-off between data freshness, query latency, and throughput.

Tip

For information on how to define and configure read models in Arc, see `Arc.Chronicle.ReadModels`.

## The Consistency Spectrum

[Section titled “The Consistency Spectrum”](#the-consistency-spectrum)

Chronicle offers a spectrum of consistency choices, ranging from strong consistency — where data is guaranteed to reflect all events at query time — to eventual consistency — where data is materialized asynchronously in the background.

```
Strong Consistency

(On-Demand)

Immediate Projections

(Synchronous)

Eventual Consistency

(Materialized)
```

Each model has distinct performance and consistency characteristics. The right choice depends on how frequently the data is read, how long the event history is, and how critical it is that queries always return up-to-date state.

## Strong Consistency — On-Demand Computation

[Section titled “Strong Consistency — On-Demand Computation”](#strong-consistency--on-demand-computation)

The strongest guarantee comes from computing a read model on-demand by replaying events from the event log every time you request it. This is sometimes called an *ad-hoc projection query* because no pre-materialized state is consulted — the result is built fresh from source events on each call.

You opt into this by marking the read model **passive**, which keeps any observer from materializing it and therefore leaves the event log as its only source. `GetInstanceById` then:

1. Locates the projection or reducer registered for the read model type
2. Retrieves all relevant events for the requested key from the event log
3. Executes the projection or reducer logic in memory, event by event
4. Returns the resulting instance that reflects the exact current state

Note

`GetInstanceById` only computes on-demand for a passive read model. When the read model *is* materialized — the default for both projections and reducers — Chronicle serves the stored instance from the sink instead, releasing any PII before it leaves the kernel. That read is O(1) and eventually consistent. See [Getting a Single Instance](/chronicle/read-models/getting-single-instance/).

```
ProjectorEventLogIReadModelsCallerProjectorEventLogIReadModelsCallerGetInstanceById<AccountInfo>(id)Fetch events for keyReturn event sequenceApply projection logicReturn current state
```

Because the projection runs inline at query time, you always get a result that is consistent with every event appended so far — including one you may have just appended a millisecond ago.

### When to Use On-Demand Computation

[Section titled “When to Use On-Demand Computation”](#when-to-use-on-demand-computation)

On-demand computation is the right choice when:

* Strong read-after-write consistency is required
* The event history for each instance is short (tens to low hundreds of events)
* The read model is accessed infrequently relative to how often events are appended
* You are validating a command against current state before appending new events

When those apply, mark the read model passive — see [Passive projections](/chronicle/projections/declarative/passive/). For a practical guide to working with read model instances, see [Getting a Single Instance](/chronicle/read-models/getting-single-instance/) and [Getting a Collection of Instances](/chronicle/read-models/getting-collection-instances/).

### Performance Considerations

[Section titled “Performance Considerations”](#performance-considerations)

The cost of on-demand computation grows linearly with the number of events in the history. Short histories are fast; histories that run into thousands of events per instance can become too slow for interactive use cases. For high-volume, frequently accessed data, materialized projections are a better fit.

## Immediate Projections — Synchronous Materialization

[Section titled “Immediate Projections — Synchronous Materialization”](#immediate-projections--synchronous-materialization)

Immediate projections sit between on-demand computation and eventual consistency. Instead of running the projection at query time, the projection runs synchronously as part of the event append operation itself. The read model is guaranteed to be up to date before the append call returns.

This model provides strong consistency for subsequent queries without incurring event-replay cost at read time. The trade-off is added latency on writes — every append operation waits for the projection to complete before returning.

Use immediate projections when:

* Strong consistency is required and the read model is accessed far more often than events are appended
* You need low query latency without bearing event-replay cost on each read
* The projection logic is fast enough that adding it to the write path is acceptable

For details on configuring and using immediate projections, see [Immediate Projections](/chronicle/projections/immediate-projections/).

## Eventual Consistency — Materialized Projections

[Section titled “Eventual Consistency — Materialized Projections”](#eventual-consistency--materialized-projections)

Most projections in Chronicle operate with eventual consistency. Events are appended to the event log and the append operation returns immediately. The projection engine then processes those events asynchronously in the background, updating the stored read model.

### How Materialization Works

[Section titled “How Materialization Works”](#how-materialization-works)

```
Read Model StorageProjection EngineEventLogCallerRead Model StorageProjection EngineEventLogCallerAppend EventReturns immediatelyNotify (async)Match event to projectionsUpdate read model
```

The append operation completes before any projection has run. There is a brief window during which the event is safely stored but the read model has not yet been updated. Under normal conditions this lag is milliseconds, but it grows under heavy load or during recovery.

For a detailed look at how projections are compiled and materialized from definition through to storage — covering the three projection styles and the runtime execution pipeline — see [Projection Architecture](/chronicle/projections/architecture/).

### Consistency Guarantees

[Section titled “Consistency Guarantees”](#consistency-guarantees)

Materialized projections guarantee:

* **Event ordering**: Events for the same event source key are processed in sequence
* **At-least-once delivery**: Every event will be processed, with automatic retries on failure
* **Partition consistency**: All projections for a given event source key will eventually converge to the correct state

They do **not** guarantee:

* **Immediate consistency**: The stored read model may lag behind the event log
* **Cross-partition ordering**: Events from different event source keys may be projected out of relative order
* **Synchronous updates**: Projection updates always happen after the append returns

For patterns that help you design applications around eventual consistency, see [Eventual Consistency in Projections](/chronicle/projections/eventual-consistency/).

### When to Use Materialized Projections

[Section titled “When to Use Materialized Projections”](#when-to-use-materialized-projections)

Materialized projections are the right choice when:

* Read models are queried frequently and must respond quickly
* Event histories are long and on-demand computation would be too slow
* The application can tolerate a brief lag between an event being appended and the read model reflecting it
* High read throughput is needed independently of write throughput

## Choosing the Right Model

[Section titled “Choosing the Right Model”](#choosing-the-right-model)

| Scenario                                                    | Recommended Model                      |
| ----------------------------------------------------------- | -------------------------------------- |
| Financial or inventory checks requiring exact current state | On-demand computation                  |
| Read-after-write in the same request                        | On-demand computation                  |
| Command validation against current state                    | On-demand computation                  |
| Low-latency reads with strong consistency                   | Immediate projections                  |
| Dashboards and list views over large datasets               | Materialized projections               |
| Real-time UIs observing changes as they happen              | Materialized projections with watchers |
| Infrequently accessed instances with short event histories  | On-demand computation                  |

## Summary

[Section titled “Summary”](#summary)

| Model                           | Updated         | Consistency | Read Cost                            |
| ------------------------------- | --------------- | ----------- | ------------------------------------ |
| On-demand computation (passive) | At query time   | Strong      | Proportional to event history length |
| Immediate projections           | At event append | Strong      | O(1) — stored result                 |
| Materialized projections        | Asynchronously  | Eventual    | O(1) — stored result                 |

The three models are not mutually exclusive. A real application often uses materialized projections for high-volume list views, on-demand computation for authoritative state checks, and immediate projections for a small number of read models where strong consistency and fast reads are both required.

# Empty Child Collections

> Why a child collection with no children is stored as an absent field, what Chronicle materializes it as, and how to say whether absent means empty.

A read model with a `[ChildrenFrom<T>]` collection — or a declarative `.Children(...)` projection — has no children until a child event arrives. That is not an edge case. It is the state every instance is in the moment its root event creates it, so it is the first read of every new instance. This page covers what Chronicle stores then, what you read back, and how to say which answer you want.

## A child collection with no children is not stored

[Section titled “A child collection with no children is not stored”](#a-child-collection-with-no-children-is-not-stored)

Chronicle never writes a children collection on behalf of the root event. A children path is owned exclusively by the child add and remove operations for the whole lifetime of the read model, and the root projection’s initial state is applied with every children path removed.

The reason is replay. Chronicle replays event source partitions independently and in parallel, so a `LineItemAdded` for one partition can be processed before the `OrderPlaced` for the order it belongs to. If the root event were allowed to write `Lines = []`, that empty array would erase the line item the sibling partition had already added.

```
OrderPlaced partitionRead modelLineItemAdded partitionOrderPlaced partitionRead modelLineItemAdded partitionlines is held back from this write,so the child already added survivesadd a child to linesset customer and status
```

So absence is the encoding: a child collection with no children is a field that is **not there**, not a field holding `[]`. The exclusion is specific to children collections; the rest of the initial state is applied as written.

## What you read back

[Section titled “What you read back”](#what-you-read-back)

When Chronicle materializes a read model for you, a collection property the stored data carries no value for is filled in according to how you declared it:

| Declared as                    | No value stored     | A value stored                     |
| ------------------------------ | ------------------- | ---------------------------------- |
| `IEnumerable<LineItem> Lines`  | An empty collection | Exactly that value, including `[]` |
| `IEnumerable<LineItem>? Lines` | `null`              | Exactly that value, including `[]` |

A non-nullable declaration is a promise, and Chronicle keeps it — you can enumerate the property without a guard, on an instance that has never had a child. A nullable declaration says you want to tell “no children yet” apart from “an empty list”, so Chronicle leaves it alone.

Two things stay out of scope. A `string` is left alone even though it is an `IEnumerable`, and so is a dictionary — whether a missing dictionary means an empty one is a different question with a different answer. A collection type Chronicle cannot construct, such as a custom collection with no parameterless constructor, is also left as it was rather than guessed at.

## Say which answer you want

[Section titled “Say which answer you want”](#say-which-answer-you-want)

The declaration is the decision point. There is no option to set and nothing to register:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Keys;
  using Cratis.Chronicle.Projections.ModelBound;

[EventType]
  public record EmptyChildrenOrderPlaced(string Customer);

[EventType]
  public record EmptyChildrenLineItemAdded(Guid ItemId, string ProductName, int Quantity);

public record EmptyChildrenLineItem([Key] Guid Id, string ProductName, int Quantity);

// Non-nullable: an order with no line items reads back as an empty collection,
  // so enumerating Lines never needs a guard.
  [FromEvent<EmptyChildrenOrderPlaced>]
  public record EmptyChildrenOrder(
      [Key]
      Guid OrderId,

string Customer,

[ChildrenFrom<EmptyChildrenLineItemAdded>(key: nameof(EmptyChildrenLineItemAdded.ItemId))]
      IEnumerable<EmptyChildrenLineItem> Lines);

// Nullable: "no line items yet" stays distinguishable from "an empty list".
  [FromEvent<EmptyChildrenOrderPlaced>]
  public record EmptyChildrenDraftOrder(
      [Key]
      Guid DraftOrderId,

string Customer,

[ChildrenFrom<EmptyChildrenLineItemAdded>(key: nameof(EmptyChildrenLineItemAdded.ItemId))]
      IEnumerable<EmptyChildrenLineItem>? Lines);
  ```

* Kotlin

@EventType
  data class EmptyChildrenOrderPlaced(val customer: String = "")

@EventType
  data class EmptyChildrenLineItemAdded(val itemId: String = "", val productName: String = "", val quantity: Int = 0)

data class EmptyChildrenLineItem(val id: String = "", val productName: String = "", val quantity: Int = 0)

// Non-nullable: an order with no line items reads back as an empty collection, so enumerating
  // lines never needs a guard.
  @ReadModel
  @FromEvent(EmptyChildrenOrderPlaced::class)
  data class EmptyChildrenOrder(
      val id: String = "",
      val customer: String = "",
      @ChildrenFrom(EmptyChildrenLineItemAdded::class, key = "itemId")
      val lines: List<EmptyChildrenLineItem> = emptyList()
  )

// Nullable: "no line items yet" stays distinguishable from "an empty list".
  @ReadModel
  @FromEvent(EmptyChildrenOrderPlaced::class)
  data class EmptyChildrenDraftOrder(
      val id: String = "",
      val customer: String = "",
      @ChildrenFrom(EmptyChildrenLineItemAdded::class, key = "itemId")
      val lines: List<EmptyChildrenLineItem>? = null
  )
  ```

* Java

import java.util.List;

@EventType
  record EmptyChildrenOrderPlaced(String customer) {}

@EventType
  record EmptyChildrenLineItemAdded(String itemId, String productName, int quantity) {}

record EmptyChildrenLineItem(String id, String productName, int quantity) {}

// Non-nullable: an order with no line items reads back as an empty collection, so enumerating
  // lines never needs a guard.
  @ReadModel
  @FromEvent(eventType = EmptyChildrenOrderPlaced.class)
  class EmptyChildrenOrder {
      private String id = "";
      private String customer = "";
      @ChildrenFrom(eventType = EmptyChildrenLineItemAdded.class, key = "itemId")
      private List<EmptyChildrenLineItem> lines = List.of();

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getCustomer() { return customer; }
      public void setCustomer(String customer) { this.customer = customer; }

public List<EmptyChildrenLineItem> getLines() { return lines; }
      public void setLines(List<EmptyChildrenLineItem> lines) { this.lines = lines; }
  }

// Nullable: "no line items yet" stays distinguishable from "an empty list".
  @ReadModel
  @FromEvent(eventType = EmptyChildrenOrderPlaced.class)
  class EmptyChildrenDraftOrder {
      private String id = "";
      private String customer = "";
      @ChildrenFrom(eventType = EmptyChildrenLineItemAdded.class, key = "itemId")
      private List<EmptyChildrenLineItem> lines;

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getCustomer() { return customer; }
      public void setCustomer(String customer) { this.customer = customer; }

public List<EmptyChildrenLineItem> getLines() { return lines; }
      public void setLines(List<EmptyChildrenLineItem> lines) { this.lines = lines; }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

The rule is applied when the instance is materialized, not when it is stored, so changing a declaration takes effect for instances that were written long before you changed it. Nothing needs replaying.

Caution

A normalizer in the record — `IEnumerable<LineItem> Lines { get; init; } = Lines ?? [];` — looks like the obvious in-language fix, and it is not one. The MongoDB driver materializes a record without running its constructor whenever the stored document omits a member, which is exactly this case, so the normalizer never runs. [Designing read models](/chronicle/concepts/designing-read-models/#the-constructor-may-not-run) explains why the record body is the wrong place for it.

## Initial values do not reach a child collection

[Section titled “Initial values do not reach a child collection”](#initial-values-do-not-reach-a-child-collection)

[Initial values](/chronicle/projections/declarative/initial-values/) look like the place to say “this collection starts empty”, and for a children collection they do nothing. The initial state is applied with every children path removed — the same exclusion, for the same replay reason — so an initial `Lines = []` is dropped before it reaches the sink.

Use the declaration instead. Initial values remain the right tool for business defaults, sentinel values, and properties that are not children collections.

## Where these semantics apply

[Section titled “Where these semantics apply”](#where-these-semantics-apply)

These rules belong to Chronicle’s reader, not to the stored document. They apply wherever Chronicle materializes the read model for you — [reading a single instance](/chronicle/read-models/getting-single-instance/), [reading a collection](/chronicle/read-models/getting-collection-instances/), [materialized instances and paging](/chronicle/read-models/materialized-pagination/), [snapshots](/chronicle/read-models/getting-snapshots/), [watching a read model](/chronicle/read-models/watching-read-models/), and [read model reactors](/chronicle/read-models/reacting-to-changes/) — and to anything layered on those APIs. The [read model testing scenarios](/chronicle/testing/read-models/scenario/) materialize through the same code, so a spec and a running system answer this question identically.

They do **not** apply when something else deserializes the same stored document. If you query the read model’s MongoDB collection directly with `IMongoCollection<T>`, as [Get started](/chronicle/get-started/) shows for reporting and ad-hoc reads, the MongoDB driver builds the instance — and the driver has never heard of this page. Left alone, it hands you `null` for a field the document does not carry.

If you are on [Cratis Arc](/arc/backend/mongodb/convention-packs/), you already have the answer: Arc registers a convention pack that materializes a non-nullable collection on a `[ReadModel]` type as empty, for both an absent field and a stored `null`. It makes the driver agree with this page rather than differ from it. Without Arc, configure the equivalent on the driver yourself, or read through Chronicle.

Caution

The driver does not run your record’s constructor. A read model with a primary constructor gets no creator map at all, so the driver materializes it uninitialized and assigns members directly — on every document, not only an incomplete one. A normalizer written in the record body (`Lines = Lines ?? []`) therefore never executes on this path, and neither does any other default, clamp or guard you put there. See [The constructor may not run](/chronicle/concepts/designing-read-models/#the-constructor-may-not-run).

Client coverage

The absent-collection rule is applied by the .NET client’s read model reader. Other clients materialize read models with their own runtime’s deserialization — check what yours does with a missing field before relying on a non-nullable declaration.

## Related topics

[Section titled “Related topics”](#related-topics)

* [Children Collections](/chronicle/projections/model-bound/children/) - Declaring child collections on a read model
* [Consistency Models](/chronicle/read-models/consistency/) - When a read model has to be correct
* [Sinks](/chronicle/sinks/) - Where read model instances are stored

# Getting a Collection of Instances

> Read every instance of a read model for small reports, diagnostics, and current-state analysis.

Sometimes you need every instance of a read model at once: a small report, an integrity check, a back-office export, or a diagnostic script. Chronicle answers this the same way it answers a single-instance read — from the materialized store when the read model has one, and by replaying events when it does not.

Either way the whole result set comes back in one call, so this is not the tool for hot list views or large data sets. Reach for [materialized paging](/chronicle/read-models/materialized-pagination/) when the caller needs a window rather than everything.

## Read all instances

[Section titled “Read all instances”](#read-all-instances)

* C#

```csharp
  var accounts = await eventStore.ReadModels.GetInstances<Account>();

foreach (var account in accounts)
  {
      Console.WriteLine($"{account.Name}: {account.Balance:C}");
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class GettingCollectionAccount(val name: String = "", val balance: Double = 0.0)

suspend fun printAllAccounts(store: IEventStore) {
      val accounts = store.readModels.getInstances(GettingCollectionAccount::class)
      accounts.forEach { println("${it.name}: ${it.balance}") }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;

import io.cratis.chronicle.java.ReadModelsJavaBridge;

@ReadModel
  class GettingCollectionAccount {
      private String name = "";
      private double balance = 0;

public String getName() { return name; }
      public void setName(String name) { this.name = name; }

public double getBalance() { return balance; }
      public void setBalance(double balance) { this.balance = balance; }
  }

class ReadModelsGettingCollectionInstancesBasic {
      void printAllAccounts(EventStore store) {
          List<GettingCollectionAccount> accounts = ReadModelsJavaBridge.getInstances(store.getReadModels(), GettingCollectionAccount.class);
          accounts.forEach(account -> System.out.println(account.getName() + ": " + account.getBalance()));
      }
  }
  ```

* Elixir

```elixir
  alias MyApp.ReadModels.Account

{:ok, accounts} = Chronicle.ReadModels.get_instances(Account)

Enum.each(accounts, fn account ->
    IO.puts("#{account.name}: #{account.balance}")
  end)
  ```

* TypeScript

```typescript
  const accounts = await store.readModels.getInstances(Account);

for (const account of accounts) {
      console.log(`${account.name}: ${account.balance}`);
  }
  ```

Kotlin currently exposes single-instance read-model lookup only, so collection reads are not shown for that client.

For a **materialized** read model the kernel pages through the sink until it has read every stored instance, releases compliance-protected values, and returns them. For a **passive** read model it replays the events that feed the read model and returns the state that falls out, which is strongly consistent and proportional to the length of the history.

## Filter in memory

[Section titled “Filter in memory”](#filter-in-memory)

The read returns every instance. Apply language-native filtering afterwards, and keep that in-memory cost in mind.

* C#

```csharp
  var accounts = await eventStore.ReadModels.GetInstances<Account>();

var highValueAccounts = accounts
      .Where(account => account.Balance > threshold)
      .OrderByDescending(account => account.Balance)
      .ToList();

Console.WriteLine($"Found {highValueAccounts.Count} high-value accounts.");
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class GettingCollectionFilteringAccount(val name: String = "", val balance: Double = 0.0)

/**
   * The read returns every instance; apply language-native filtering afterwards.
   */
  suspend fun highValueAccounts(store: IEventStore, threshold: Double): List<GettingCollectionFilteringAccount> =
      store.readModels.getInstances(GettingCollectionFilteringAccount::class)
          .filter { it.balance > threshold }
          .sortedByDescending { it.balance }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.Comparator;
  import java.util.List;
  import java.util.stream.Collectors;

import io.cratis.chronicle.java.ReadModelsJavaBridge;

@ReadModel
  class GettingCollectionFilteringAccount {
      private String name = "";
      private double balance = 0;

public String getName() { return name; }
      public void setName(String name) { this.name = name; }

public double getBalance() { return balance; }
      public void setBalance(double balance) { this.balance = balance; }
  }

class ReadModelsGettingCollectionInstancesFiltering {
      // The read returns every instance; apply language-native filtering afterwards.
      List<GettingCollectionFilteringAccount> highValueAccounts(EventStore store, double threshold) {
          List<GettingCollectionFilteringAccount> accounts = ReadModelsJavaBridge.getInstances(store.getReadModels(), GettingCollectionFilteringAccount.class);
          return accounts.stream()
              .filter(account -> account.getBalance() > threshold)
              .sorted(Comparator.comparingDouble(GettingCollectionFilteringAccount::getBalance).reversed())
              .collect(Collectors.toList());
      }
  }
  ```

* Elixir

```elixir
  alias MyApp.ReadModels.Account

{:ok, accounts} = Chronicle.ReadModels.get_instances(Account)

high_value_accounts =
    accounts
    |> Enum.filter(&(&1.balance > threshold))
    |> Enum.sort_by(& &1.balance, :desc)

IO.inspect(high_value_accounts, label: "High-value accounts")
  ```

* TypeScript

```typescript
  const accounts = await store.readModels.getInstances(Account);

const highValueAccounts = accounts
      .filter((account) => account.balance > threshold)
      .sort((left, right) => right.balance - left.balance);
  ```

For large result sets, page the materialized read model or use a product-specific query model instead of reading everything and filtering afterward.

## Limit the replay

[Section titled “Limit the replay”](#limit-the-replay)

You can cap the number of events Chronicle processes. Because a cap only means something to a replay, passing one always replays — even for a materialized read model.

* C#

```csharp
  var orders = await eventStore.ReadModels.GetInstances<Order>(eventCount: 1_000);

Console.WriteLine($"Replayed {orders.Count()} orders from the capped history.");
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class EventCountOrder(val status: String = "", val total: Double = 0.0)

/**
   * Caps the replay to the first 1,000 events - faster, but can return incomplete state if the
   * cap cuts off events that matter.
   */
  suspend fun replayCappedOrders(store: IEventStore): List<EventCountOrder> =
      store.readModels.getInstances(EventCountOrder::class, eventCount = 1_000)
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;

@ReadModel
  record EventCountOrder(String status, double total) {
  }

class EventCountOrders {
      /**
       * Caps the replay to the first 1,000 events - faster, but can return incomplete state if the
       * cap cuts off events that matter.
       */
      static List<EventCountOrder> replayCappedOrders(IEventStore store) {
          return ReadModelsJavaBridge.getInstances(store.getReadModels(), EventCountOrder.class, 1_000L);
      }
  }
  ```

* Elixir

```elixir
  alias MyApp.ReadModels.Order

{:ok, orders} =
    Chronicle.ReadModels.get_instances(
      Order,
      event_count: 1_000
    )

IO.puts("Replayed #{length(orders)} orders from the capped history.")
  ```

* TypeScript

```typescript
  const orders = await store.readModels.getInstances(Order, 1000n);

console.log(`Replayed ${orders.length} orders from the capped history.`);
  ```

This can make diagnostics faster, but it can also return incomplete state if the cap cuts off events that matter. Use an event-count cap for historical analysis, back-testing, or bounded diagnostics. Do not use it when the reader expects the current truth.

## When to use this

[Section titled “When to use this”](#when-to-use-this)

Read the whole collection when:

* The read model population is small.
* You are running an administrative or diagnostic task.
* You are validating data derived from the event log.

Prefer paging or a database-native read when:

* The page is user-facing and called frequently.
* You need server-side filtering, sorting, or paging.
* The read model has many instances.

## Related topics

[Section titled “Related topics”](#related-topics)

* [Getting a Single Instance](/chronicle/read-models/getting-single-instance/) - Read one read model instance by key
* [Getting Snapshots](/chronicle/read-models/getting-snapshots/) - Inspect historical state for one instance
* [Watching Read Models](/chronicle/read-models/watching-read-models/) - React to read model changes
* [Materialized Read Models](/chronicle/read-models/materialized-pagination/) - Read sink-stored read models with paging

# Getting a Single Instance

> Read one read model instance by key, and understand whether the answer comes from the materialized store or from replaying events.

When you need one read model and you have its key, ask Chronicle for it by key. You always call the same operation; what differs is where the answer comes from.

Chronicle knows whether the read model is **materialized** — whether an observer writes its state to a sink. If it is, the kernel reads the stored instance and releases any PII before returning it. If it is not — a passive read model has no observer and therefore no sink — the kernel rebuilds the instance from the events that feed it. You do not choose between the two at the call site; the read model’s own definition decides.

## How it works

[Section titled “How it works”](#how-it-works)

The client sends the read model type and key to the kernel. The kernel resolves the read model’s definition and takes one of two paths:

* **Materialized read model** — the kernel looks the instance up in the sink by key, releases compliance-protected values, and returns it. The cost is a single storage lookup regardless of how long the event history is. The instance is as current as the observer that wrote it, so it is eventually consistent.
* **Passive read model** — the kernel replays the relevant events through the projection or reducer that owns the read model and returns the result. The instance reflects every event appended up to that call, so it is strongly consistent. The cost grows with the length of the history.

The materialized path is also the only one that sees the whole picture for a projection that joins across event sources or resolves keys from other events. Replay walks one event source, so it cannot reconstruct state that was built from events belonging to a different key.

## Read by key

[Section titled “Read by key”](#read-by-key)

The read model type must already be registered by the client, either as a model-bound projection, a declarative projection, or the read model produced by a reducer.

* C#

```csharp
  AccountInfo? account = await eventStore.ReadModels.GetInstanceById<AccountInfo>(accountId);

if (account is not null)
  {
      Console.WriteLine($"{account.Name}: {account.Balance:C}");
  }
  ```

* Kotlin

```kotlin
  val account = store.readModels.getInstanceByKey(AccountInfo::class, accountId)

if (account != null) {
      println("${account.name}: ${account.balance}")
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.BlockingEventStore;
  import io.cratis.chronicle.readModels.ReadModel;

@ReadModel
  record AccountInfo(String name, double balance) {
      AccountInfo() {
          this("", 0.0);
      }
  }

class ReadModelLookup {
      void printAccount(IEventStore store, String accountId) {
          var account = new BlockingEventStore(store)
              .getReadModels()
              .getInstanceByKey(AccountInfo.class, accountId);

if (account != null) {
              System.out.println(account.name() + ": " + account.balance());
          }
      }
  }
  ```

* Elixir

```elixir
  alias MyApp.ReadModels.AccountInfo

{:ok, account} = Chronicle.ReadModels.get_instance_by_id(AccountInfo, account_id)

if account do
    IO.puts("#{account.name}: #{account.balance}")
  end
  ```

* TypeScript

```typescript
  const account = await store.readModels.getInstanceById(AccountInfo, accountId);

console.log(`${account.name}: ${account.balance}`);
  ```

Each client names the operation in its own idiom, but the inputs are the same: the read model type and the read model key.

## Missing instances

[Section titled “Missing instances”](#missing-instances)

If no instance exists for that key, clients return their normal “not found” shape: `null`, `nil`, or an empty result depending on the language. Treat that as “no state exists yet,” not as a projection failure. For a materialized read model this covers both a key that was never created and one that has been removed — the observer is authoritative, so Chronicle does not fall back to a replay that would resurrect it.

If the read model type itself is unknown, that is a configuration error. Register the projection, reducer, or read model before querying it.

## Choosing which you get

[Section titled “Choosing which you get”](#choosing-which-you-get)

Because the read model’s definition decides the path, choose when you design the read model rather than when you query it.

Leave the read model materialized — the default — when:

* The same data is read often, or read from lists, dashboards, and user interfaces.
* The event history for a key can grow long.
* A brief lag between an append and the read reflecting it is acceptable.
* The projection joins events across event sources.

Mark the read model passive when:

* A command needs the exact current state before making a decision.
* You append an event and immediately need to read the state it creates.
* The event history for each key stays short.
* The read model is queried rarely relative to how often its events are appended.

## Related topics

[Section titled “Related topics”](#related-topics)

* [Getting a Collection of Instances](/chronicle/read-models/getting-collection-instances/) - Read or replay every instance of a read model
* [Getting Snapshots](/chronicle/read-models/getting-snapshots/) - Inspect how one instance evolved over time
* [Watching Read Models](/chronicle/read-models/watching-read-models/) - React to read model changes as they happen
* [Materialized Read Models](/chronicle/read-models/materialized-pagination/) - Page through sink-stored read models
* [Passive projections](/chronicle/projections/declarative/passive/) - Keep a read model out of the sink so it is computed on demand

# Getting Snapshots

> Inspect the historical states Chronicle produced for one read model key, grouped by correlation ID.

Snapshots let you inspect how a read model reached its current state. Chronicle groups events by correlation ID, replays the read model after each group, and returns the state produced by each step.

This is useful when a projection or reducer produced a surprising result and you need to see the path as well as the final state.

## How snapshots are grouped

[Section titled “How snapshots are grouped”](#how-snapshots-are-grouped)

Each snapshot represents the cumulative read model state after one correlation group. In practice, a correlation group often maps to one user request, command, import batch, scheduled job, or other operation that appended related events.

Every snapshot includes:

| Field          | Meaning                                                       |
| -------------- | ------------------------------------------------------------- |
| Read model     | The read model state after that correlation group was applied |
| Events         | The events that were applied for that group                   |
| Occurred       | The timestamp of the first event in the group                 |
| Correlation ID | The identifier that ties the related events together          |

## Read snapshots

[Section titled “Read snapshots”](#read-snapshots)

The read model type must be registered, and the key must identify the read model instance you want to inspect.

* C#

```csharp
  var snapshots = await eventStore.ReadModels.GetSnapshotsById<Order>(orderId);

Console.WriteLine($"Found {snapshots.Count()} snapshots.");
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class SnapshotsBasicOrder(val status: String = "", val total: Double = 0.0)

suspend fun countSnapshots(store: IEventStore, orderId: String) {
      val snapshots = store.readModels.getSnapshotsById(SnapshotsBasicOrder::class, orderId)
      println("Found ${snapshots.size} snapshots.")
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;
  import io.cratis.chronicle.readModels.ReadModelSnapshot;

import java.util.List;

import io.cratis.chronicle.java.ReadModelsJavaBridge;

@ReadModel
  class SnapshotsBasicOrder {
      private String status = "";
      private double total = 0;

public String getStatus() { return status; }
      public void setStatus(String status) { this.status = status; }

public double getTotal() { return total; }
      public void setTotal(double total) { this.total = total; }
  }

class ReadModelsGettingSnapshotsBasic {
      void countSnapshots(EventStore store, String orderId) {
          List<ReadModelSnapshot<SnapshotsBasicOrder>> snapshots = ReadModelsJavaBridge.getSnapshotsById(store.getReadModels(), SnapshotsBasicOrder.class, orderId);
          System.out.println("Found " + snapshots.size() + " snapshots.");
      }
  }
  ```

* Elixir

```elixir
  alias MyApp.ReadModels.Order

{:ok, snapshots} = Chronicle.ReadModels.get_snapshots_by_id(Order, order_id)

IO.puts("Found #{length(snapshots)} snapshots.")
  ```

* TypeScript

```typescript
  const snapshots = await store.readModels.getSnapshotsById(Order, orderId);

console.log(`Found ${snapshots.length} snapshots.`);
  ```

Kotlin currently exposes single-instance read-model lookup only, so snapshots are not shown for that client.

## Analyze the timeline

[Section titled “Analyze the timeline”](#analyze-the-timeline)

Snapshot data is usually most useful when you print or inspect the correlation ID, event count, timestamp, and resulting state together.

* C#

```csharp
  var snapshots = await eventStore.ReadModels.GetSnapshotsById<Order>(orderId);

foreach (var snapshot in snapshots)
  {
      Console.WriteLine($"Snapshot at {snapshot.Occurred}:");
      Console.WriteLine($"  Correlation ID: {snapshot.CorrelationId}");
      Console.WriteLine($"  Event count: {snapshot.Events.Count()}");
      Console.WriteLine($"  State: {snapshot.Instance}");
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class SnapshotsAnalyzeOrder(val status: String = "", val total: Double = 0.0)

suspend fun analyzeSnapshots(store: IEventStore, orderId: String) {
      val snapshots = store.readModels.getSnapshotsById(SnapshotsAnalyzeOrder::class, orderId)
      snapshots.forEach { snapshot ->
          println("Snapshot at ${snapshot.occurred}:")
          println("  Correlation ID: ${snapshot.correlationId}")
          println("  Event count: ${snapshot.events.size}")
          println("  State: ${snapshot.instance}")
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;
  import io.cratis.chronicle.readModels.ReadModelSnapshot;

import java.util.List;

import io.cratis.chronicle.java.ReadModelsJavaBridge;

@ReadModel
  class SnapshotsAnalyzeOrder {
      private String status = "";
      private double total = 0;

public String getStatus() { return status; }
      public void setStatus(String status) { this.status = status; }

public double getTotal() { return total; }
      public void setTotal(double total) { this.total = total; }
  }

class ReadModelsGettingSnapshotsAnalyze {
      void analyzeSnapshots(EventStore store, String orderId) {
          List<ReadModelSnapshot<SnapshotsAnalyzeOrder>> snapshots = ReadModelsJavaBridge.getSnapshotsById(store.getReadModels(), SnapshotsAnalyzeOrder.class, orderId);
          for (ReadModelSnapshot<SnapshotsAnalyzeOrder> snapshot : snapshots) {
              System.out.println("Snapshot at " + snapshot.getOccurred() + ":");
              System.out.println("  Correlation ID: " + snapshot.getCorrelationId());
              System.out.println("  Event count: " + snapshot.getEvents().size());
              System.out.println("  State: " + snapshot.getInstance());
          }
      }
  }
  ```

* Elixir

```elixir
  alias MyApp.ReadModels.Order

{:ok, snapshots} = Chronicle.ReadModels.get_snapshots_by_id(Order, order_id)

Enum.each(snapshots, fn snapshot ->
    IO.puts("Snapshot at #{snapshot.occurred}")
    IO.puts("  Correlation ID: #{snapshot.correlation_id}")
    IO.puts("  Event count: #{length(snapshot.events)}")
    IO.inspect(snapshot.read_model, label: "  State")
  end)
  ```

* TypeScript

```typescript
  const snapshots = await store.readModels.getSnapshotsById(Order, orderId);

for (const snapshot of snapshots) {
      console.log(`Snapshot at ${snapshot.occurred?.toISOString() ?? 'unknown'}`);
      console.log(`  Correlation ID: ${snapshot.correlationId ?? 'none'}`);
      console.log(`  Event count: ${snapshot.events.length}`);
      console.log('  State:', snapshot.readModel);
  }
  ```

If you need to compare two states, materialize the snapshot list and compare neighboring entries. Chronicle gives you the timeline; your diagnostic tool decides which properties matter.

## Cost and limits

[Section titled “Cost and limits”](#cost-and-limits)

Snapshot retrieval has to read the relevant history, group events by correlation ID, and replay the read model through each group. That can be expensive for keys with long histories or many correlation groups.

Use snapshots when:

* You are debugging a projection or reducer.
* You need an audit trail for how one instance evolved.
* You need to understand transaction or request boundaries.
* The key has a reasonable event history.

Prefer current-state or materialized reads when:

* You only need the latest state.
* You need to query many instances.
* You are serving a hot user-facing path.

## Related topics

[Section titled “Related topics”](#related-topics)

* [Getting a Single Instance](/chronicle/read-models/getting-single-instance/) - Read the latest state for one key
* [Getting a Collection of Instances](/chronicle/read-models/getting-collection-instances/) - Replay all current instances
* [Watching Read Models](/chronicle/read-models/watching-read-models/) - Subscribe to changes as they happen

# Materialized Read Models

When a projection or reducer processes an event, Chronicle persists the resulting read model instance in a *sink* — a database-backed store that holds the materialized state. The `Materialized` API gives you direct, paginated access to that stored state without replaying the event log.

Client coverage

Getting/paginating materialized instances and observing a live paginated window (below) are real in Elixir (`Chronicle.ReadModels.query/2`, page-based rather than skip/take) and TypeScript (`readModels.materialized.getInstances`/`.observeInstances`, an `AsyncIterable` rather than an `IObservable`) too. Kotlin and Java only support the single-instance strongly-consistent lookup covered in [Getting a single instance](/chronicle/read-models/getting-single-instance/) — no bulk or paginated materialized access exists in the Kotlin SDK yet. The named-constants convenience and the ASP.NET paged-endpoint example are C#-specific idioms with no equivalent elsewhere.

Note

The `Materialized` API is **not** a substitute for working directly with the underlying database. It provides a simple, database-agnostic way to retrieve and observe stored read model instances using skip/take pagination. For advanced queries — filtering, sorting, aggregation, full-text search, joins — use the sink’s native query capabilities (MongoDB queries, SQL queries, etc.) directly.

## What Materialized Access Covers

[Section titled “What Materialized Access Covers”](#what-materialized-access-covers)

The `Materialized` API is intentionally narrow. It answers one question well: *give me a page of instances I already know are stored in a sink*. This keeps it:

* **Database-agnostic** — the same call works regardless of whether the sink is MongoDB, SQL, or any future backend
* **Simple to use** — two methods, optional skip/take, and sensible defaults
* **Safe for large datasets** — only the requested page is loaded, never the full collection

What it does **not** cover:

* Filtering by field value
* Sorting by any property
* Aggregation or count queries
* Full-text or range searches
* Complex joins or projections across collections

For those needs, inject the sink’s native client directly. If your sink is MongoDB, inject `IMongoCollection<TReadModel>`. If it is SQL, inject your `DbContext`. Those tools are purpose-built for complex queries and Chronicle does not try to replace them.

## Accessing the API

[Section titled “Accessing the API”](#accessing-the-api)

`IMaterializedReadModels` is exposed through `IReadModels.Materialized`:

* C#

```csharp
  using Cratis.Chronicle;

public record MaterializedPaginationOrder(string CustomerName, decimal Total);

public class MaterializedPaginationAccessingApi(IEventStore eventStore)
  {
      public async Task<IEnumerable<MaterializedPaginationOrder>> GetOrders()
      {
          // Inject IEventStore, then reach through to the Materialized API
          var instances = await eventStore.ReadModels.Materialized.GetInstances<MaterializedPaginationOrder>();
          return instances;
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore

data class MaterializedPaginationOrder(val customerName: String = "", val total: Double = 0.0)

class MaterializedPaginationAccessingApi(private val eventStore: IEventStore) {
      // Reach through IEventStore, then the Materialized API
      suspend fun getOrders(): List<MaterializedPaginationOrder> =
          eventStore.readModels.materialized.getInstances(MaterializedPaginationOrder::class)
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;

import java.util.List;

record MaterializedPaginationOrder(String customerName, double total) {
      MaterializedPaginationOrder() {
          this("", 0.0);
      }
  }

class MaterializedPaginationAccessingApi {
      private final IEventStore eventStore;

MaterializedPaginationAccessingApi(IEventStore eventStore) {
          this.eventStore = eventStore;
      }

// Reach through IEventStore, then the Java bridge for the Materialized API
      List<MaterializedPaginationOrder> getOrders() {
          return ReadModelsJavaBridge.getMaterializedInstances(eventStore.getReadModels(), MaterializedPaginationOrder.class, 0, 50);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.ReadModels.MaterializedPaginationOrder do
    defstruct [:customer_name, :total]
  end

defmodule MyApp.MaterializedPaginationAccessingApi do
    alias MyApp.ReadModels.MaterializedPaginationOrder

def get_orders do
      # Query the materialized read-model container directly, rather than replaying events
      Chronicle.ReadModels.query(MaterializedPaginationOrder)
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

class MaterializedPaginationOrder {
      constructor(
          readonly customerName: string,
          readonly total: number
      ) {}
  }

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

// Inject IEventStore, then reach through to the materialized API
      async getOrders(): Promise<MaterializedPaginationOrder[]> {
          return this.store.readModels.materialized.getInstances(MaterializedPaginationOrder);
      }
  }
  ```

## Getting Instances

[Section titled “Getting Instances”](#getting-instances)

### Basic Usage

[Section titled “Basic Usage”](#basic-usage)

Retrieve the first page of stored instances using the defaults (skip: 0, take: 50):

* C#

```csharp
  using Cratis.Chronicle;

public class MaterializedPaginationBasicUsage(IEventStore eventStore)
  {
      public Task<IEnumerable<MaterializedPaginationOrder>> GetOrders() =>
          eventStore.ReadModels.Materialized.GetInstances<MaterializedPaginationOrder>();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore

class MaterializedPaginationBasicUsage(private val eventStore: IEventStore) {
      suspend fun getOrders(): List<MaterializedPaginationOrder> =
          eventStore.readModels.materialized.getInstances(MaterializedPaginationOrder::class)
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;

import java.util.List;

class MaterializedPaginationBasicUsage {
      private final IEventStore eventStore;

MaterializedPaginationBasicUsage(IEventStore eventStore) {
          this.eventStore = eventStore;
      }

List<MaterializedPaginationOrder> getOrders() {
          return ReadModelsJavaBridge.getMaterializedInstances(eventStore.getReadModels(), MaterializedPaginationOrder.class, 0, 50);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.MaterializedPaginationBasicUsage do
    alias MyApp.ReadModels.MaterializedPaginationOrder

def get_orders do
      Chronicle.ReadModels.query(MaterializedPaginationOrder)
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async getOrders(): Promise<MaterializedPaginationOrder[]> {
          return this.store.readModels.materialized.getInstances(MaterializedPaginationOrder);
      }
  }
  ```

### Pagination

[Section titled “Pagination”](#pagination)

Both `skip` and `take` are optional with sensible defaults. Use them for page-based or offset-based navigation:

* C#

```csharp
  using System.Linq;
  using Cratis.Chronicle;

public class MaterializedPaginationPagination(IEventStore eventStore)
  {
      public async Task GetPages()
      {
          // First page of 20
          var page1 = await eventStore.ReadModels.Materialized.GetInstances<MaterializedPaginationOrder>(take: 20);
          Console.WriteLine($"Page 1: {page1.Count()} orders");

// Second page of 20
          var page2 = await eventStore.ReadModels.Materialized.GetInstances<MaterializedPaginationOrder>(skip: 20, take: 20);
          Console.WriteLine($"Page 2: {page2.Count()} orders");

// Third page of 20
          var page3 = await eventStore.ReadModels.Materialized.GetInstances<MaterializedPaginationOrder>(skip: 40, take: 20);
          Console.WriteLine($"Page 3: {page3.Count()} orders");
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore

class MaterializedPaginationPagination(private val eventStore: IEventStore) {
      suspend fun getPages() {
          // First page of 20
          val page1 = eventStore.readModels.materialized.getInstances(MaterializedPaginationOrder::class, take = 20)
          println("Page 1: ${page1.size} orders")

// Second page of 20
          val page2 = eventStore.readModels.materialized.getInstances(MaterializedPaginationOrder::class, skip = 20, take = 20)
          println("Page 2: ${page2.size} orders")

// Third page of 20
          val page3 = eventStore.readModels.materialized.getInstances(MaterializedPaginationOrder::class, skip = 40, take = 20)
          println("Page 3: ${page3.size} orders")
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;

class MaterializedPaginationPagination {
      private final IEventStore eventStore;

MaterializedPaginationPagination(IEventStore eventStore) {
          this.eventStore = eventStore;
      }

void getPages() {
          // First page of 20
          var page1 = ReadModelsJavaBridge.getMaterializedInstances(eventStore.getReadModels(), MaterializedPaginationOrder.class, 0, 20);
          System.out.println("Page 1: " + page1.size() + " orders");

// Second page of 20
          var page2 = ReadModelsJavaBridge.getMaterializedInstances(eventStore.getReadModels(), MaterializedPaginationOrder.class, 20, 20);
          System.out.println("Page 2: " + page2.size() + " orders");

// Third page of 20
          var page3 = ReadModelsJavaBridge.getMaterializedInstances(eventStore.getReadModels(), MaterializedPaginationOrder.class, 40, 20);
          System.out.println("Page 3: " + page3.size() + " orders");
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.MaterializedPaginationPagination do
    alias MyApp.ReadModels.MaterializedPaginationOrder

def get_pages do
      # Page 1 of 20
      {:ok, page1} = Chronicle.ReadModels.query(MaterializedPaginationOrder, page: 1, page_size: 20)
      IO.puts("Page 1: #{length(page1.instances)} orders")

# Page 2 of 20
      {:ok, page2} = Chronicle.ReadModels.query(MaterializedPaginationOrder, page: 2, page_size: 20)
      IO.puts("Page 2: #{length(page2.instances)} orders")

# Page 3 of 20
      {:ok, page3} = Chronicle.ReadModels.query(MaterializedPaginationOrder, page: 3, page_size: 20)
      IO.puts("Page 3: #{length(page3.instances)} orders")
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async getPages(): Promise<void> {
          // First page of 20
          const page1 = await this.store.readModels.materialized.getInstances(MaterializedPaginationOrder, 0, 20);
          console.log(`Page 1: ${page1.length} orders`);

// Second page of 20
          const page2 = await this.store.readModels.materialized.getInstances(MaterializedPaginationOrder, 20, 20);
          console.log(`Page 2: ${page2.length} orders`);

// Third page of 20
          const page3 = await this.store.readModels.materialized.getInstances(MaterializedPaginationOrder, 40, 20);
          console.log(`Page 3: ${page3.length} orders`);
      }
  }
  ```

### Pagination Parameters

[Section titled “Pagination Parameters”](#pagination-parameters)

The parameters use strongly-typed concepts that convert implicitly from `int`:

| Parameter | Type                   | Default | Named Constants                                    |
| --------- | ---------------------- | ------- | -------------------------------------------------- |
| `skip`    | `InstanceCountToSkip?` | `0`     | `InstanceCountToSkip.Zero`                         |
| `take`    | `InstanceCount?`       | `50`    | `InstanceCount.Default`, `InstanceCount.Unlimited` |

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.ReadModels;

public class MaterializedPaginationNamedConstants(IEventStore eventStore)
  {
      public Task<IEnumerable<MaterializedPaginationOrder>> GetOrders() =>
          // Using named constants
          eventStore.ReadModels.Materialized.GetInstances<MaterializedPaginationOrder>(
              skip: InstanceCountToSkip.Zero,
              take: InstanceCount.Default);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class NamedConstantsOrder(val status: String = "", val total: Double = 0.0)

/**
   * `skip` and `take` both default to well-known values (0 and 50) - call without arguments to
   * use them rather than repeating the numbers yourself.
   */
  suspend fun getOrders(store: IEventStore): List<NamedConstantsOrder> =
      store.readModels.materialized.getInstances(NamedConstantsOrder::class)
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;

import io.cratis.chronicle.java.ReadModelsJavaBridge;

@ReadModel
  class NamedConstantsOrder {
      private String status = "";
      private double total = 0;

public String getStatus() { return status; }
      public void setStatus(String status) { this.status = status; }

public double getTotal() { return total; }
      public void setTotal(double total) { this.total = total; }
  }

class ReadModelsMaterializedPaginationNamedConstants {
      // skip: 0, take: 50 are the Kotlin client's built-in defaults - repeat them explicitly since
      // the Java bridge has no default-argument support.
      List<NamedConstantsOrder> getOrders(EventStore store) {
          return ReadModelsJavaBridge.getMaterializedInstances(store.getReadModels(), NamedConstantsOrder.class, 0, 50);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

### Building a Paged API Endpoint

[Section titled “Building a Paged API Endpoint”](#building-a-paged-api-endpoint)

* C#

```csharp
  using Cratis.Chronicle;
  using Microsoft.AspNetCore.Mvc;

[ApiController]
  [Route("orders")]
  public class MaterializedPaginationOrdersController(IEventStore eventStore) : ControllerBase
  {
      [HttpGet]
      public async Task<IEnumerable<MaterializedPaginationOrder>> GetOrders(
          [FromQuery] int page = 0,
          [FromQuery] int pageSize = 20)
      {
          return await eventStore.ReadModels.Materialized.GetInstances<MaterializedPaginationOrder>(
              skip: page * pageSize,
              take: pageSize);
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class PagedEndpointOrder(val status: String = "", val total: Double = 0.0)

/**
   * A paged read suitable for backing a list endpoint - only the requested page is loaded.
   */
  suspend fun getOrders(store: IEventStore, page: Int, pageSize: Int): List<PagedEndpointOrder> =
      store.readModels.materialized.getInstances(PagedEndpointOrder::class, skip = page * pageSize, take = pageSize)
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;

import io.cratis.chronicle.java.ReadModelsJavaBridge;

@ReadModel
  class PagedEndpointOrder {
      private String status = "";
      private double total = 0;

public String getStatus() { return status; }
      public void setStatus(String status) { this.status = status; }

public double getTotal() { return total; }
      public void setTotal(double total) { this.total = total; }
  }

class ReadModelsMaterializedPaginationPagedEndpoint {
      // A paged read suitable for backing a list endpoint - only the requested page is loaded.
      List<PagedEndpointOrder> getOrders(EventStore store, int page, int pageSize) {
          return ReadModelsJavaBridge.getMaterializedInstances(
              store.getReadModels(), PagedEndpointOrder.class, page * pageSize, pageSize);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Observing Changes

[Section titled “Observing Changes”](#observing-changes)

`ObserveInstances` returns an `IObservable<IEnumerable<TReadModel>>` that emits a new page snapshot whenever the underlying stored data changes. This is useful for live-updating UIs, dashboards, and monitoring tools.

* C#

```csharp
  using System.Linq;
  using Cratis.Chronicle;

public record MaterializedPaginationProduct(string Name, decimal Price);

public class MaterializedPaginationObserving(IEventStore eventStore)
  {
      public void Run()
      {
          var subscription = eventStore.ReadModels.Materialized
              .ObserveInstances<MaterializedPaginationProduct>(take: 50)
              .Subscribe(products =>
              {
                  // Called whenever the stored instances change
                  Console.WriteLine($"Products updated: {products.Count()} in view");
              });

// Dispose when done to release the change stream
          subscription.Dispose();
      }
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import kotlinx.coroutines.coroutineScope
  import kotlinx.coroutines.launch

data class MaterializedPaginationProduct(val name: String = "", val price: Double = 0.0)

class MaterializedPaginationObserving(private val eventStore: IEventStore) {
      suspend fun run() = coroutineScope {
          val subscription = launch {
              eventStore.readModels.materialized
                  .observeInstances(MaterializedPaginationProduct::class, take = 50)
                  .collect { products ->
                      // Called whenever the stored instances change
                      println("Products updated: ${products.size} in view")
                  }
          }

// Cancel when done to release the change stream
          subscription.cancel()
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;

import kotlinx.coroutines.Job;

record MaterializedPaginationProduct(String name, double price) {
  }

class MaterializedPaginationObserving {
      private final IEventStore eventStore;

MaterializedPaginationObserving(IEventStore eventStore) {
          this.eventStore = eventStore;
      }

void run() {
          Job subscription = ReadModelsJavaBridge.observeMaterializedInstances(
              eventStore.getReadModels(),
              MaterializedPaginationProduct.class,
              0,
              50,
              products -> {
                  // Called whenever the stored instances change
                  System.out.println("Products updated: " + products.size() + " in view");
              });

// Cancel when done to release the change stream
          subscription.cancel(null);
      }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.MaterializedPaginationObserving do
    alias Chronicle.ReadModels
    alias MyApp.ReadModels.MaterializedPaginationOrder

# Elixir has no single "ObserveInstances" call — combine watch/2
    # (per-instance change notifications) with query/2 (the current
    # materialized page) to get the same "re-emit the page whenever the
    # stored data changes" behavior as ObserveInstances(take: 50).
    def run do
      {:ok, watcher} = ReadModels.watch(MaterializedPaginationOrder)

receive do
        {:chronicle_read_model_changed, MaterializedPaginationOrder, _changeset} ->
          {:ok, page} = ReadModels.query(MaterializedPaginationOrder, page: 1, page_size: 50)
          IO.puts("Orders updated: #{length(page.instances)} in view")
      after
        5_000 -> :timeout
      end

# Stop watching once done, to release the change stream.
      ReadModels.unwatch(watcher)
    end
  end
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

class MaterializedPaginationProduct {
      constructor(
          readonly name: string,
          readonly price: number
      ) {}
  }

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

async run(): Promise<void> {
          // Called whenever the stored instances change
          for await (const products of this.store.readModels.materialized.observeInstances(MaterializedPaginationProduct, 0, 50)) {
              console.log(`Products updated: ${products.length} in view`);
          }
      }
  }
  ```

Observation relies on the sink’s change stream mechanism:

* **MongoDB** — uses native MongoDB change streams
* **SQL** — uses polling-based change detection via `DbContext`

Note

Always dispose observation subscriptions when the consumer is torn down to prevent resource leaks and keep change streams closed.

### Observing in a Service

[Section titled “Observing in a Service”](#observing-in-a-service)

* C#

```csharp
  using Cratis.Chronicle;

public class MaterializedPaginationProductDashboard : IDisposable
  {
      readonly IDisposable _subscription;

public MaterializedPaginationProductDashboard(IEventStore eventStore)
      {
          _subscription = eventStore.ReadModels.Materialized
              .ObserveInstances<MaterializedPaginationProduct>(take: 100)
              .Subscribe(UpdateView);
      }

void UpdateView(IEnumerable<MaterializedPaginationProduct> products) { /* ... */ }

public void Dispose() => _subscription.Dispose();
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import kotlinx.coroutines.CoroutineScope
  import kotlinx.coroutines.launch

/**
   * Observes a live paginated window of materialized instances for as long as [scope] is active.
   */
  class ProductDashboard(store: IEventStore, scope: CoroutineScope) {
      init {
          scope.launch {
              store.readModels.materialized.observeInstances(MaterializedPaginationProduct::class, take = 100)
                  .collect { products -> updateView(products) }
          }
      }

private fun updateView(products: List<MaterializedPaginationProduct>) {
          // ...
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.IEventStore;
  import io.cratis.chronicle.java.ReadModelsJavaBridge;

import kotlinx.coroutines.Job;

import java.util.List;

/**
   * Observes a live paginated window of materialized instances until {@code close()} releases it.
   */
  class ProductDashboard implements AutoCloseable {
      private final Job subscription;

ProductDashboard(IEventStore store) {
          subscription = ReadModelsJavaBridge.observeMaterializedInstances(
              store.getReadModels(),
              MaterializedPaginationProduct.class,
              0,
              100,
              this::updateView);
      }

private void updateView(List<MaterializedPaginationProduct> products) {
          // ...
      }

@Override
      public void close() {
          subscription.cancel(null);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async start(updateView: (products: MaterializedPaginationProduct[]) => void): Promise<void> {
          for await (const products of this.store.readModels.materialized.observeInstances(MaterializedPaginationProduct, 0, 100)) {
              updateView(products);
          }
      }
  }
  ```

## When to Use the Materialized API

[Section titled “When to Use the Materialized API”](#when-to-use-the-materialized-api)

Use `Materialized.GetInstances` and `ObserveInstances` when:

* You need a page of stored read model instances for a list view, data grid, or infinite scroll UI
* You want real-time updates pushed to a connected UI without polling
* The dataset is large and loading everything into memory via event replay would be too slow or too expensive

Do **not** use the `Materialized` API when:

* You need to filter by a specific field — query the sink directly
* You need instances sorted by a property — query the sink directly
* You need a count of matching records — query the sink directly
* You need to run an aggregation — query the sink directly

## Comparison with On-Demand GetInstances

[Section titled “Comparison with On-Demand GetInstances”](#comparison-with-on-demand-getinstances)

|                       | `ReadModels.GetInstances<T>()` | `ReadModels.Materialized.GetInstances<T>()` |
| --------------------- | ------------------------------ | ------------------------------------------- |
| **Data source**       | Event log replay               | Materialized sink (database)                |
| **Consistency**       | Strong — always current        | Eventual — milliseconds behind              |
| **Performance**       | Proportional to event history  | O(1) — direct database lookup               |
| **Pagination**        | No                             | Yes — skip/take                             |
| **Large datasets**    | Slow — replays all events      | Fast — loads only the requested page        |
| **Filtering/sorting** | Post-fetch with LINQ           | Not supported — query the sink directly     |

## Related Topics

[Section titled “Related Topics”](#related-topics)

* [Consistency Models](/chronicle/read-models/consistency/) — Understanding strong vs. eventual consistency
* [Getting a Single Instance](/chronicle/read-models/getting-single-instance/) — On-demand computation for a single instance
* [Getting a Collection of Instances](/chronicle/read-models/getting-collection-instances/) — On-demand collection retrieval via event replay
* [Watching Read Models](/chronicle/read-models/watching-read-models/) — Observe event-log-sourced read model changesets
* [Projections](/chronicle/projections/) — How read models are produced from events
* [Reducers](/chronicle/reducers/) — Imperative state-building from events
* [MongoDB Sink](/chronicle/sinks/#mongodb-sink) — How read model instances are stored in MongoDB
* [SQL Sink](/chronicle/sinks/#sql-sink) — How read model instances are stored in a SQL database

# Querying Read Models

Chronicle’s read model API is keyed. You can get an instance by its id, get snapshots of it, watch it, and replay the whole collection. What you cannot do through `IReadModels` is filter, page, or search by a field that is not the key — there is no predicate-taking read and no `IQueryable`.

That is deliberate, and this page says so plainly, because from the outside a missing method looks the same whether it was left out or never intended.

## Why there is no query surface

[Section titled “Why there is no query surface”](#why-there-is-no-query-surface)

A read model is not a table you query. It is a shape you decided on in advance, built by a projection from the events that feed it, so that one read case is answered by one direct lookup. Deciding what a read model contains, how it is keyed, and which events maintain it *is* the design work. A read model that has to be searched by arbitrary fields is usually a read model that has not been shaped for the read it is serving.

So the boundary is drawn on purpose: Chronicle takes responsibility for building read models from events and handing them back by key. It does not take on being a query engine, because the storage you already have is one.

## What to do instead

[Section titled “What to do instead”](#what-to-do-instead)

**First, ask whether the read model is the right shape.** If you are searching by a field, that field is what the read case is really keyed on. A projection keyed that way turns the search into a lookup — and unlike a query, it stays correct as events arrive.

**When the shape genuinely cannot be known in advance**, go to the storage directly. Searching an arbitrary field, ad-hoc reporting, an admin screen with user-chosen filters — these are query problems, and a query engine solves them better than an abstraction over one would. Reaching for the driver here is not a workaround; it is the supported answer.

**For a small collection, replay and filter in memory.** See [Getting a Collection of Instances](/chronicle/read-models/getting-collection-instances/). This is proportional to event history, so keep it to result sets you know are small.

## What this costs you

[Section titled “What this costs you”](#what-this-costs-you)

Going to storage directly means that code knows which store the read model lives in, and a test for it needs that store rather than the in-memory read model harness. That is a real cost and worth weighing against reshaping the read model — which is why reshaping is the first thing to consider, not the last.

The trade is deliberate: Chronicle would have to leak a query language into its own API to avoid it, and the abstraction that resulted would be worse than the one you already have underneath.

# Reacting to Read Model Changes

> React to a read model being added, modified or removed with a convention-based IReadModelReactor, instead of subscribing to the watch stream yourself.

[Watching a read model](/chronicle/read-models/watching-read-models/) hands you a raw stream of changes: you subscribe, filter, branch on whether the instance was removed, and dispose the subscription yourself. When all you want is *“when an account appears, send a welcome; when it changes, sync it downstream”*, that plumbing is noise.

A **read model reactor** removes it. You write a class, name a method after the change you care about — `Added`, `Modified` or `Removed` — and Chronicle dispatches to it. It is a convenience layer over the [Watch APIs](/chronicle/read-models/watching-read-models/): the same delivery underneath, none of the subscription bookkeeping.

## Write the reactor

[Section titled “Write the reactor”](#write-the-reactor)

Implement the `IReadModelReactor` marker interface and add a method named `Added`, `Modified` or `Removed`. The method name selects the change it reacts to, and the first parameter selects which read model is watched.

* C#

```csharp
  using Cratis.Chronicle.ReadModels;

public class AccountNotifier : IReadModelReactor
  {
      public Task Added(Account account) => SendWelcome(account);

public Task Modified(Account account) => SendUpdated(account);

public Task Removed(Account account) => SendClosed(account);

Task SendWelcome(Account account) => Task.CompletedTask;
      Task SendUpdated(Account account) => Task.CompletedTask;
      Task SendClosed(Account account) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.readModels.IReadModelReactor
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class ReactingReactorAccount(val name: String = "", val balance: Double = 0.0)

class AccountNotifier : IReadModelReactor {
      fun added(account: ReactingReactorAccount) = sendWelcome(account)
      fun modified(account: ReactingReactorAccount) = sendUpdated(account)
      fun removed(account: ReactingReactorAccount?) = sendClosed(account)

private fun sendWelcome(account: ReactingReactorAccount) { /* ... */ }
      private fun sendUpdated(account: ReactingReactorAccount) { /* ... */ }
      private fun sendClosed(account: ReactingReactorAccount?) { /* ... */ }
  }
  ```

* Java

```java
  import io.cratis.chronicle.readModels.IReadModelReactor;
  import io.cratis.chronicle.readModels.ReadModel;

@ReadModel
  class ReactingReactorAccount {
      private String name = "";
      private double balance = 0;

public String getName() { return name; }
      public void setName(String name) { this.name = name; }

public double getBalance() { return balance; }
      public void setBalance(double balance) { this.balance = balance; }
  }

class AccountNotifier implements IReadModelReactor {
      public void added(ReactingReactorAccount account) { sendWelcome(account); }
      public void modified(ReactingReactorAccount account) { sendUpdated(account); }
      public void removed(ReactingReactorAccount account) { sendClosed(account); }

private void sendWelcome(ReactingReactorAccount account) { }
      private void sendUpdated(ReactingReactorAccount account) { }
      private void sendClosed(ReactingReactorAccount account) { }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

There is nothing to register. Reactors are discovered and started automatically, and their subscriptions are tracked and cleaned up when the client is disposed. React to as many read models as you like — one method per change, per model.

## Handle a single instance or a collection

[Section titled “Handle a single instance or a collection”](#handle-a-single-instance-or-a-collection)

A handler may be synchronous or asynchronous — return `void`, `Task`, or `Task<T>`. Its first parameter is either a single read model or a collection of them:

* C#

```csharp
  using Cratis.Chronicle.ReadModels;

public class AccountBatchProjector : IReadModelReactor
  {
      public async Task Modified(IEnumerable<Account> accounts)
      {
          foreach (var account in accounts)
          {
              await Sync(account);
          }
      }

Task Sync(Account account) => Task.CompletedTask;
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.readModels.IReadModelReactor
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class ReactingCollectionAccount(val name: String = "", val balance: Double = 0.0)

class AccountBatchProjector : IReadModelReactor {
      fun modified(accounts: List<ReactingCollectionAccount>) {
          accounts.forEach { sync(it) }
      }

private fun sync(account: ReactingCollectionAccount) { /* ... */ }
  }
  ```

* Java

```java
  import io.cratis.chronicle.readModels.IReadModelReactor;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;

@ReadModel
  class ReactingCollectionAccount {
      private String name = "";
      private double balance = 0;

public String getName() { return name; }
      public void setName(String name) { this.name = name; }

public double getBalance() { return balance; }
      public void setBalance(double balance) { this.balance = balance; }
  }

class AccountBatchProjector implements IReadModelReactor {
      public void modified(List<ReactingCollectionAccount> accounts) {
          accounts.forEach(this::sync);
      }

private void sync(ReactingCollectionAccount account) { }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Take dependencies

[Section titled “Take dependencies”](#take-dependencies)

The first parameter is the read model; every parameter after it is resolved for you. Ask for the `EventContext` of the event that caused the change — that gives you its sequence number, occurrence time and correlation id — and ask for any service registered in the container. Inject through the constructor, the method signature, or both:

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.EventSequences;
  using Cratis.Chronicle.ReadModels;

public interface IAccountNotifications
  {
      Task Notify(string accountId);
  }

public interface IAccountAuditLog
  {
      void Record(string accountId, EventSequenceNumber sequenceNumber);
  }

public class AccountAuditor(IAccountNotifications notifications) : IReadModelReactor
  {
      public Task Modified(Account account, EventContext context, IAccountAuditLog audit)
      {
          audit.Record(account.Id, context.SequenceNumber);
          return notifications.Notify(account.Id);
      }
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## Return side effects

[Section titled “Return side effects”](#return-side-effects)

A handler can append events, exactly like a [reactor side effect](/chronicle/reactors/side-effects/). Return a single event, a collection, an `EventForEventSourceId`, or a mix, and Chronicle appends them. The `[EventStreamType]` and `[EventSourceType]` attributes on the reactor are honored when it does.

* C#

```csharp
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.ReadModels;

[EventType]
  public record AccountFlagged(string AccountId);

public class AccountReviewer : IReadModelReactor
  {
      public Task<AccountFlagged> Modified(Account account) =>
          Task.FromResult(new AccountFlagged(account.Id));
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.readModels.IReadModelReactor
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class AccountFlagged(val accountId: String = "")

@ReadModel
  data class ReactingSideEffectsAccount(val id: String = "", val balance: Double = 0.0)

class AccountReviewer : IReadModelReactor {
      /**
       * Returning an event from a handler appends it, using the changed instance's key as the
       * event source id by default.
       */
      fun modified(account: ReactingSideEffectsAccount): AccountFlagged = AccountFlagged(account.id)
  }
  ```

* Java

```java
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.readModels.IReadModelReactor;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record AccountFlagged(String accountId) {}

@ReadModel
  class ReactingSideEffectsAccount {
      private String id = "";
      private double balance = 0;

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public double getBalance() { return balance; }
      public void setBalance(double balance) { this.balance = balance; }
  }

class AccountReviewer implements IReadModelReactor {
      // Returning an event from a handler appends it, using the changed instance's key as the
      // event source id by default.
      public AccountFlagged modified(ReactingSideEffectsAccount account) {
          return new AccountFlagged(account.getId());
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

## The three change types

[Section titled “The three change types”](#the-three-change-types)

| Method     | Reacts to                                               |
| ---------- | ------------------------------------------------------- |
| `Added`    | The read model instance was created for the first time. |
| `Modified` | The read model instance changed.                        |
| `Removed`  | The read model instance was removed.                    |

For **projection-backed** read models the change type and the causing event’s context come straight from the server, so `Added` versus `Modified` is precise and `EventContext` is fully populated. Other backings infer more of this locally — see the limits below.

## Watch through the materialized read model

[Section titled “Watch through the materialized read model”](#watch-through-the-materialized-read-model)

Apply the `[Materialized]` attribute to observe the materialized read model API instead of the change stream. Chronicle then deduces the change type by comparing successive materialized windows.

* C#

```csharp
  using Cratis.Chronicle.ReadModels;

[Materialized]
  public class AccountSnapshotReactor : IReadModelReactor
  {
      public Task Added(Account account) => Task.CompletedTask;
  }
  ```

* Kotlin

```text
  Kotlin does not support this workflow yet.
  ```

* Java

```text
  Java does not support this workflow yet.
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```text
  TypeScript does not support this workflow yet.
  ```

Reach for this only when you specifically want the materialized view — most reactors do not need it, and it trades away some fidelity, described next.

## When the fit is imperfect

[Section titled “When the fit is imperfect”](#when-the-fit-is-imperfect)

A read model reactor is convenient, not transactional. Design for that:

Caution

**Side effects are best-effort.** Returned events are appended fire-and-forget — a failure is logged, but nothing pauses or retries, because a read model reactor has no partition to fail. Ordering across rapid changes is not guaranteed. Make every handler **idempotent**: it may run again after a reconnect.

* **Materialized fidelity is reduced.** The materialized API delivers full windows of already-deserialized instances, so the change type is inferred by comparing serialized values keyed by `id`, and the `EventContext` carries only the model key — no event sequence number.
* **Reducer-backed read models infer additions client-side.** Reducers compute changesets locally with no server-provided change type, so the first time a key is seen it is reported as `Added` and everything after as `Modified`. Only projection-backed read models carry the precise change type and causing event context.

When you need transactional, ordered, replayable reactions, react to the **domain event** with a [reactor](/chronicle/reactors/) rather than to the derived read model.

## Related topics

[Section titled “Related topics”](#related-topics)

* [Watching Read Models](/chronicle/read-models/watching-read-models/) — the lower-level change stream this builds on
* [Reactors](/chronicle/reactors/) — react to events directly, with delivery guarantees
* [Reactor Side Effects](/chronicle/reactors/side-effects/) — the append model reused here

# Releasing PII

> Decrypt PII in a read model instance you already have, and how Chronicle decides whose encryption key to use.

Most of the time you never think about this. `GetInstanceById`, `GetInstances`, and `GetSnapshotsById` on `IReadModels` already hand you PII decrypted — a projection is decrypted by the kernel before it reaches you, and a reducer-backed instance is decrypted by the client right before it’s returned. See [Read models and PII](/chronicle/compliance/read-models/) for how that automatic path works and what it takes to mark a property as PII in the first place.

`IReadModels.Release` is the same decryption, exposed for the cases that skip that path: an instance you built from raw storage, restored from a cache or message payload, or received somewhere that doesn’t release automatically. One built-in case exists today — `Watch<TReadModel>()` streams changes to you directly and does not call `Release` first.

* C#

```csharp
  using Cratis.Chronicle;
  using Cratis.Chronicle.Compliance.GDPR;
  using Cratis.Chronicle.Events;
  using Cratis.Chronicle.Reducers;

[PII]
  public record ReleasingPiiRequesterName(string Value) : ConceptAs<string>(Value)
  {
      public static readonly ReleasingPiiRequesterName NotSet = new(string.Empty);
      public static implicit operator string(ReleasingPiiRequesterName name) => name.Value;
      public static implicit operator ReleasingPiiRequesterName(string value) => new(value);
  }

[EventType]
  public record ReleasingPiiSupportTicketOpened(string CustomerId, ReleasingPiiRequesterName RequesterName);

public record ReleasingPiiSupportTicket(string Id, [Subject] string CustomerId, [PII] string RequesterName);

public class ReleasingPiiSupportTicketReducer : IReducerFor<ReleasingPiiSupportTicket>
  {
      public ReleasingPiiSupportTicket Opened(ReleasingPiiSupportTicketOpened @event, ReleasingPiiSupportTicket? current, EventContext context) =>
          new(context.EventSourceId.Value, @event.CustomerId, @event.RequesterName);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.compliance.Pii
  import io.cratis.chronicle.events.EventType
  import io.cratis.chronicle.readModels.ReadModel

@EventType
  data class SupportTicketOpened(val customerId: String = "", val requesterName: String = "")

/**
   * [Release][io.cratis.chronicle.readModels.IReadModelsService.release] resolves whose encryption
   * key to use by looking for a property named `id`, case-insensitive - here that is the ticket's
   * own key, which is also the customer it belongs to.
   */
  @ReadModel
  data class ReleasingReadModelSupportTicket(
      val id: String = "",
      @Pii val requesterName: String = ""
  )
  ```

* Java

```java
  import io.cratis.chronicle.compliance.Pii;
  import io.cratis.chronicle.events.EventType;
  import io.cratis.chronicle.readModels.ReadModel;

@EventType
  record SupportTicketOpened(String customerId, String requesterName) {}

// Release resolves whose encryption key to use by looking for a property named "id",
  // case-insensitive - here that is the ticket's own key, which is also the customer it belongs to.
  @ReadModel
  class ReleasingReadModelSupportTicket {
      private String id = "";
      @Pii
      private String requesterName = "";

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getRequesterName() { return requesterName; }
      public void setRequesterName(String requesterName) { this.requesterName = requesterName; }
  }
  ```

* Elixir

```elixir
  defmodule MyApp.Events.ReleasingPiiSupportTicketOpened do
    use Chronicle.Events.EventType, id: "releasing-pii-support-ticket-opened"

defstruct [:customer_id, :requester_name]
  end

defmodule MyApp.ReadModels.ReleasingPiiSupportTicket do
    use Chronicle.ReadModels.ReadModel

defstruct [:id, :customer_id, :requester_name]

subject :customer_id
    pii :requester_name
  end

defmodule MyApp.Reducers.ReleasingPiiSupportTicketReducer do
    use Chronicle.Reducers.Reducer, model: MyApp.ReadModels.ReleasingPiiSupportTicket

alias MyApp.Events.ReleasingPiiSupportTicketOpened

@handles ReleasingPiiSupportTicketOpened

@impl true
    def reduce(%ReleasingPiiSupportTicketOpened{} = event, _model, context) do
      %MyApp.ReadModels.ReleasingPiiSupportTicket{
        id: context.event_source_id,
        customer_id: event.customer_id,
        requester_name: event.requester_name
      }
    end
  end
  ```

* TypeScript

```typescript
  import { EventContext, eventType, pii, reducer, subject } from '@cratis/chronicle';

@eventType()
  class ReleasingPiiSupportTicketOpened {
      constructor(readonly customerId: string, readonly requesterName: string) {}
  }

class ReleasingPiiSupportTicket {
      // The ticket's own id identifies the ticket, not the person the PII belongs to - @subject()
      // tells release() to use customerId as the encryption key's owner instead. Without it,
      // release() would fall back to id.
      id = '';

@subject()
      customerId = '';

@pii('The name of the person who opened the ticket')
      requesterName = '';
  }

@reducer('', undefined, ReleasingPiiSupportTicket)
  class ReleasingPiiSupportTicketReducer {
      releasingPiiSupportTicketOpened(
          event: ReleasingPiiSupportTicketOpened,
          current: ReleasingPiiSupportTicket | undefined,
          context: EventContext
      ): ReleasingPiiSupportTicket {
          return { id: context.eventSourceId, customerId: event.customerId, requesterName: event.requesterName };
      }
  }
  ```

`RequesterName` is `[PII]`-marked explicitly on the read model — required for a reducer, since Chronicle can’t infer PII lineage through arbitrary reducer logic the way it can for a model-bound projection. `CustomerId` carries `[Subject]`: the ticket’s own `Id` identifies the ticket, not the person the PII belongs to, so `Release` needs to be told which property to use as the encryption key’s owner. A property having the `Subject` type does not select it by itself; the attribute is what declares the role.

## Release a single instance

[Section titled “Release a single instance”](#release-a-single-instance)

* C#

```csharp
  using Cratis.Chronicle;

public class ReleasingPiiSupportTicketService(IEventStore eventStore)
  {
      public Task<ReleasingPiiSupportTicket> Release(ReleasingPiiSupportTicket ticket) =>
          eventStore.ReadModels.Release(ticket);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class ReleasingSingleInstanceSupportTicket(val id: String = "", val requesterName: String = "")

suspend fun release(store: IEventStore, ticket: ReleasingSingleInstanceSupportTicket): ReleasingSingleInstanceSupportTicket =
      store.readModels.release(ticket)
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;

import io.cratis.chronicle.java.ReadModelsJavaBridge;

@ReadModel
  class ReleasingSingleInstanceSupportTicket {
      private String id = "";
      private String requesterName = "";

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getRequesterName() { return requesterName; }
      public void setRequesterName(String requesterName) { this.requesterName = requesterName; }
  }

class ReadModelsReleasingPiiSingleInstance {
      ReleasingSingleInstanceSupportTicket release(EventStore store, ReleasingSingleInstanceSupportTicket ticket) {
          return ReadModelsJavaBridge.release(store.getReadModels(), ticket);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

release(ticket: ReleasingPiiSupportTicket): Promise<ReleasingPiiSupportTicket> {
          return this.store.readModels.release(ReleasingPiiSupportTicket, ticket);
      }
  }
  ```

## Release a collection

[Section titled “Release a collection”](#release-a-collection)

Releasing more than one instance at once resolves the subject for each independently, so a single batch can freely mix data belonging to different people.

* C#

```csharp
  using Cratis.Chronicle;

public class ReleasingPiiSupportTicketBatchService(IEventStore eventStore)
  {
      public Task<IEnumerable<ReleasingPiiSupportTicket>> ReleaseAll(IEnumerable<ReleasingPiiSupportTicket> tickets) =>
          eventStore.ReadModels.Release(tickets);
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel

@ReadModel
  data class ReleasingCollectionSupportTicket(val id: String = "", val requesterName: String = "")

/**
   * Releases more than one instance at once - the subject for each is resolved independently, so
   * a single batch can freely mix data belonging to different people.
   */
  suspend fun releaseAll(store: IEventStore, tickets: List<ReleasingCollectionSupportTicket>): List<ReleasingCollectionSupportTicket> =
      store.readModels.releaseMany(tickets)
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;

import java.util.List;

import io.cratis.chronicle.java.ReadModelsJavaBridge;

@ReadModel
  class ReleasingCollectionSupportTicket {
      private String id = "";
      private String requesterName = "";

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getRequesterName() { return requesterName; }
      public void setRequesterName(String requesterName) { this.requesterName = requesterName; }
  }

class ReadModelsReleasingPiiCollection {
      // Releases more than one instance at once - the subject for each is resolved independently.
      List<ReleasingCollectionSupportTicket> releaseAll(EventStore store, List<ReleasingCollectionSupportTicket> tickets) {
          return ReadModelsJavaBridge.releaseMany(store.getReadModels(), tickets);
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

releaseAll(tickets: ReleasingPiiSupportTicket[]): Promise<ReleasingPiiSupportTicket[]> {
          return this.store.readModels.releaseMany(ReleasingPiiSupportTicket, tickets);
      }
  }
  ```

## Release while watching for changes

[Section titled “Release while watching for changes”](#release-while-watching-for-changes)

* C#

```csharp
  using Cratis.Chronicle;

public class ReleasingPiiSupportTicketWatcher(IEventStore eventStore)
  {
      public IDisposable Start() =>
          eventStore.ReadModels.Watch<ReleasingPiiSupportTicket>().Subscribe(async changeset =>
          {
              if (changeset.Removed || changeset.ReadModel is null)
              {
                  return;
              }

var ticket = await eventStore.ReadModels.Release(changeset.ReadModel);
              Console.WriteLine($"{changeset.ModelKey}: {ticket.RequesterName}");
          });
  }
  ```

* Kotlin

```kotlin
  import io.cratis.chronicle.IEventStore
  import io.cratis.chronicle.readModels.ReadModel
  import kotlinx.coroutines.flow.collect

@ReadModel
  data class ReleasingWatchSupportTicket(val id: String = "", val requesterName: String = "")

/**
   * [io.cratis.chronicle.readModels.IReadModelsService.watch] is the one built-in read that does
   * not release PII automatically - release each change yourself as it arrives.
   */
  suspend fun watchTickets(store: IEventStore) {
      store.readModels.watch(ReleasingWatchSupportTicket::class).collect { changeset ->
          if (changeset.removed || changeset.readModel == null) return@collect

val ticket = store.readModels.release(changeset.readModel!!)
          println("${changeset.modelKey}: ${ticket.requesterName}")
      }
  }
  ```

* Java

```java
  import io.cratis.chronicle.EventStore;
  import io.cratis.chronicle.readModels.ReadModel;

import io.cratis.chronicle.java.ReadModelsJavaBridge;
  import kotlinx.coroutines.Job;

@ReadModel
  class ReleasingWatchSupportTicket {
      private String id = "";
      private String requesterName = "";

public String getId() { return id; }
      public void setId(String id) { this.id = id; }

public String getRequesterName() { return requesterName; }
      public void setRequesterName(String requesterName) { this.requesterName = requesterName; }
  }

class ReadModelsReleasingPiiWatch {
      // watch() is the one built-in read that does not release PII automatically - release each
      // change yourself as it arrives.
      Job watchTickets(EventStore store) {
          return ReadModelsJavaBridge.watch(store.getReadModels(), ReleasingWatchSupportTicket.class, changeset -> {
              if (changeset.getRemoved() || changeset.getReadModel() == null) {
                  return;
              }

ReleasingWatchSupportTicket ticket = ReadModelsJavaBridge.release(store.getReadModels(), changeset.getReadModel());
              System.out.println(changeset.getModelKey() + ": " + ticket.getRequesterName());
          });
      }
  }
  ```

* Elixir

```text
  Elixir does not support this workflow yet.
  ```

* TypeScript

```typescript
  import { IEventStore } from '@cratis/chronicle';

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

async start(): Promise<void> {
          for await (const changeset of this.store.readModels.watch(ReleasingPiiSupportTicket)) {
              if (changeset.removed) {
                  continue;
              }

const ticket = await this.store.readModels.release(ReleasingPiiSupportTicket, changeset.readModel);
              console.log(`${changeset.key}: ${ticket.requesterName}`);
          }
      }
  }
  ```

Every other read on `IReadModels` releases before returning to you. `Watch` is the exception, because it’s a live feed rather than one completed read — release each change yourself as it arrives, the same way you’d release any other instance.

## How the subject is resolved

[Section titled “How the subject is resolved”](#how-the-subject-is-resolved)

`Release` looks at the instance you hand it to work out whose encryption key to use, in this order:

| Priority | Mechanism                                                             |
| -------- | --------------------------------------------------------------------- |
| 1        | A property decorated with `[Subject]`                                 |
| 2        | A constructor parameter decorated with `[Subject]` (record shorthand) |
| 3        | A property named `Id`, case-insensitive                               |

The first match **with a value** wins. If an attributed property is `null`, empty or `Subject.NotSet`, `Release` continues to the `Id` fallback. This lets older rows and partially populated instances remain releasable while a newly projected `[Subject]` property is introduced.

If none of the three resolve to a value, `Release` returns the instance unchanged and logs a warning when the model has PII metadata. If the read model has no PII-annotated properties, it returns the instance unchanged without a warning because there is nothing to release.

Add `[Subject]` when the identity that manual `Release` should use differs from the read model’s own key, exactly as you would on a command or event property to control which identity an append is encrypted under. When the two already match — a person’s own profile, keyed by their own identity — the `Id` fallback handles it and no attribute is needed.

This attribute affects only subject discovery from the object passed to `Release`; it does not assign ownership to a managed projection document. Chronicle’s projection pipeline derives ownership from the event that supplied each PII value and persists that information in its reserved `__subject` and `__subjects` fields. An explicit subject supplied while appending an event therefore controls the values originating from that event, regardless of whether the read model exposes a `Subject` property.

## When release can’t recover a value

[Section titled “When release can’t recover a value”](#when-release-cant-recover-a-value)

A property that can’t be decrypted — its encryption key was deleted, or it was encrypted under a different subject entirely — degrades on its own; the rest of the instance still comes back intact. What a caller sees for each of those cases is covered in [Read models and PII](/chronicle/compliance/read-models/#one-property-never-fails-the-whole-read).

If the release call itself can’t complete — a schema mismatch, for instance — Chronicle logs the failure and returns the instance exactly as you passed it in, still encrypted. If a value you expect to read back stays ciphertext after calling `Release`, check the application logs for that failure before assuming the data is unrecoverable.

## Related topics

[Section titled “Related topics”](#related-topics)

* [Read models and PII](/chronicle/compliance/read-models/) - How Chronicle encrypts and decrypts PII automatically, and GDPR erasure
* [The PII attribute](/chronicle/compliance/pii/) - Marking event and read model properties as PII
* [Watching Read Models](/chronicle/read-models/watching-read-models/) - Subscribing to read model changes
* [Getting a Single Instance](/chronicle/read-models/getting-single-instance/) - The strongly consistent read path that releases for you

# Watching Read Models

> Subscribe to read model changes when a client needs pushed updates instead of polling.

Watching a read model gives a client a stream of changes as Chronicle applies projections and reducers. Use it for live dashboards, cache invalidation, background coordination, and interfaces that should update without polling.

Not every Chronicle client exposes the watch API yet. The examples below show the clients that currently do.

## What a change contains

[Section titled “What a change contains”](#what-a-change-contains)

Each change tells you:

| Field      | Meaning                                           |
| ---------- | ------------------------------------------------- |
| Namespace  | The Chronicle namespace where the change happened |
| Key        | The read model key that changed                   |
| Read model | The current state after the change                |
| Removed    | Whether the instance was removed                  |

The change carries the current read model state, not the previous state. If you need to detect a transition, keep the last

Warnings

Edit User

Create Your Account