---
title: Model lifecycle stages with Cratis Chronicle read model variants
editUrl: https://github.com/Cratis/Chronicle/edit/main/Documentation/projections/model-bound/variants.mdx
description: Use Cratis Chronicle model-bound variants to give each lifecycle stage its own read model, with entering events that remove the entity from other stages.
lastUpdated: 2026-11-05T00:00:00.000Z
---

<a id="variants"></a>

Cratis Chronicle read model variants represent lifecycle stages as separate model-bound projections. Use them when a query should return only entities in one stage, such as backlog items or pull requests, without filtering a shared collection by status.

Each variant has its own properties and collection. A backlog item can carry a title while a pull request also carries its URL and build status. The shapes can be nearly identical, too: separate collections are useful whenever callers want to query a stage directly.

An entering event creates that stage's read model and removes the entity from the other variants in its group. Before an entity has entered a variant, it need not exist in any of them.

## Declaring a group of variants

In C#, apply `[VariantOf<TIdentity>]` to every read model in the group and `[EntersOn<TEvent>]` to name its entering event. The identity type groups the variants; the entity's key identifies the instance moving between them. Each variant must declare a key and an entering event:

**C#**

```csharp
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;

[EventType]
public record MbVariantIssueCreated(string Title);

[EventType]
public record MbVariantPullRequestCreated(string PullRequestUrl);

/// <summary>
/// Anchors the logical identity shared by every variant. It does not need to be a
/// read model itself, and it does not need a common CLR base type with any of the variants.
/// </summary>
public class MbVariantWorkItem;

[VariantOf<MbVariantWorkItem>]
[EntersOn<MbVariantIssueCreated>]
public record MbVariantBacklogItem([property: Key] Guid Id, string Title);

[VariantOf<MbVariantWorkItem>]
[EntersOn<MbVariantPullRequestCreated>]
public record MbVariantPullRequestItem([property: Key] Guid Id, [property: SetFrom<MbVariantPullRequestCreated>] string PullRequestUrl);
```

[View C# snippet source on GitHub](https://github.com/Cratis/Chronicle/blob/main/Documentation/client-snippets/projections/model-bound/variants/basic.md)

**Kotlin**

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.EntersOn
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.FromEventSourceId
import io.cratis.chronicle.projections.SetFrom
import io.cratis.chronicle.projections.VariantOf
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class MbVariantIssueCreated(val title: String)

@EventType
data class MbVariantPullRequestCreated(val pullRequestUrl: String)

/**
 * Anchors the logical identity shared by every variant. It does not need to be a read model
 * itself, and it does not need a common supertype with any of the variants.
 */
class MbVariantWorkItem

@ReadModel
@VariantOf(MbVariantWorkItem::class, key = "id")
@EntersOn(MbVariantIssueCreated::class)
@FromEvent(MbVariantIssueCreated::class)
data class MbVariantBacklogItem(
    @FromEventSourceId
    val id: String = "",

    @SetFrom("title", MbVariantIssueCreated::class)
    val title: String = ""
)

@ReadModel
@VariantOf(MbVariantWorkItem::class, key = "id")
@EntersOn(MbVariantPullRequestCreated::class)
@FromEvent(MbVariantPullRequestCreated::class)
data class MbVariantPullRequestItem(
    @FromEventSourceId
    val id: String = "",

    @SetFrom("pullRequestUrl", MbVariantPullRequestCreated::class)
    val pullRequestUrl: String = ""
)
```

[View Kotlin snippet source on GitHub](https://github.com/Cratis/Chronicle.Kotlin/blob/main/Documentation/client-snippets/projections/model-bound/variants/basic.md)

**Java**

```java
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.EntersOn;
import io.cratis.chronicle.projections.FromEvent;
import io.cratis.chronicle.projections.FromEventSourceId;
import io.cratis.chronicle.projections.SetFrom;
import io.cratis.chronicle.projections.VariantOf;
import io.cratis.chronicle.readModels.ReadModel;

@EventType
record MbVariantIssueCreated(String title) {}

@EventType
record MbVariantPullRequestCreated(String pullRequestUrl) {}

/**
 * Anchors the logical identity shared by every variant. It does not need to be a read model
 * itself, and it does not need a common supertype with any of the variants.
 */
class MbVariantWorkItem {}

@ReadModel
@VariantOf(identity = MbVariantWorkItem.class, key = "id")
@EntersOn(eventType = MbVariantIssueCreated.class)
@FromEvent(eventType = MbVariantIssueCreated.class)
class MbVariantBacklogItem {
    @FromEventSourceId
    public String id = "";

    @SetFrom(propertyPath = "title", eventType = MbVariantIssueCreated.class)
    public String title = "";
}

@ReadModel
@VariantOf(identity = MbVariantWorkItem.class, key = "id")
@EntersOn(eventType = MbVariantPullRequestCreated.class)
@FromEvent(eventType = MbVariantPullRequestCreated.class)
class MbVariantPullRequestItem {
    @FromEventSourceId
    public String id = "";

    @SetFrom(propertyPath = "pullRequestUrl", eventType = MbVariantPullRequestCreated.class)
    public String pullRequestUrl = "";
}
```

[View Java snippet source on GitHub](https://github.com/Cratis/Chronicle.Kotlin/blob/main/Documentation/client-snippets-java/projections/model-bound/variants/basic.md)

**Elixir**

```elixir
defmodule MyApp.Events.MbVariantIssueCreated do
  use Chronicle.Events.EventType, id: "mb-variant-issue-created-v1"

  defstruct [:title]
end

defmodule MyApp.Events.MbVariantPullRequestCreated do
  use Chronicle.Events.EventType, id: "mb-variant-pull-request-created-v1"

  defstruct [:pull_request_url]
end

# Anchors the logical identity shared by every variant. It does not need to be a read model
# itself, and it does not need a common shape with any of the variants.
defmodule MyApp.ReadModels.MbVariantWorkItem do
end

defmodule MyApp.ReadModels.MbVariantBacklogItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.MbVariantIssueCreated
  alias MyApp.ReadModels.MbVariantWorkItem

  defstruct [:id, :title]

  variant_of MbVariantWorkItem, key: :id
  enters_on MbVariantIssueCreated

  from MbVariantIssueCreated,
    set: [id: :event_source_id, title: :title]
end

defmodule MyApp.ReadModels.MbVariantPullRequestItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.MbVariantPullRequestCreated
  alias MyApp.ReadModels.MbVariantWorkItem

  defstruct [:id, :pull_request_url]

  variant_of MbVariantWorkItem, key: :id
  enters_on MbVariantPullRequestCreated

  from MbVariantPullRequestCreated,
    set: [id: :event_source_id, pull_request_url: :pull_request_url]
end
```

[View Elixir snippet source on GitHub](https://github.com/Cratis/Chronicle.Elixir/blob/main/Documentation/client-snippets/projections/model-bound/variants/basic.md)

**TypeScript**

```typescript
import { entersOn, eventType, fromEvent, setFrom, variantOf } from '@cratis/chronicle';

@eventType()
export class MbVariantIssueCreated {
    title = '';
}

@eventType()
export class MbVariantPullRequestCreated {
    pullRequestUrl = '';
}

/**
 * Anchors the logical identity shared by every variant. It does not need to be a read model
 * itself, and it does not need a common shape with any of the variants.
 */
export class MbVariantWorkItem {}

@variantOf(MbVariantWorkItem, 'id')
@entersOn(MbVariantIssueCreated)
@fromEvent(MbVariantIssueCreated)
export class MbVariantBacklogItem {
    id = '';

    @setFrom(MbVariantIssueCreated, 'title')
    title = '';
}

@variantOf(MbVariantWorkItem, 'id')
@entersOn(MbVariantPullRequestCreated)
@fromEvent(MbVariantPullRequestCreated)
export class MbVariantPullRequestItem {
    id = '';

    @setFrom(MbVariantPullRequestCreated, 'pullRequestUrl')
    pullRequestUrl = '';
}
```

[View TypeScript snippet source on GitHub](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/client-snippets/projections/model-bound/variants/basic.md)

`MbVariantWorkItem` is the shared identity type in this example. It does not have to be a read model, and the variants do not have to inherit from it.

The issue-created event creates a backlog item and maps `Title` by name. A pull-request-created event for the same entity creates a pull request item and removes its backlog item. Chronicle adds that removal behavior from the group declaration; you do not need a separate `RemovedWith` attribute.

A pull request can also be the first variant the entity enters. The group does not require a backlog item to exist before accepting its entering event.

## Only the entering event can create a variant

Use the usual property mappings for events that update a variant after entry. Chronicle treats these non-entering events as update-only: they can change an existing instance but cannot create one.

**C#**

```csharp
[EventType]
public record MbVariantUpdatingPullRequestCreated(string PullRequestUrl);

[EventType]
public record MbVariantUpdatingBuildCompleted(string BuildStatus);

public class MbVariantUpdatingWorkItem;

/// <summary>
/// BuildStatus is mapped from MbVariantUpdatingBuildCompleted - an event that is NOT this
/// variant's entering event, so it is automatically reclassified into an update-only join. It can bring
/// an already-active instance up to date, but it can never create one on its own.
/// </summary>
[VariantOf<MbVariantUpdatingWorkItem>]
[EntersOn<MbVariantUpdatingPullRequestCreated>]
public record MbVariantUpdatingPullRequestItem(
    [property: Key] Guid Id,
    [property: SetFrom<MbVariantUpdatingPullRequestCreated>] string PullRequestUrl,
    [property: SetFrom<MbVariantUpdatingBuildCompleted>] string BuildStatus);
```

[View C# snippet source on GitHub](https://github.com/Cratis/Chronicle/blob/main/Documentation/client-snippets/projections/model-bound/variants/updating-a-variant.md)

**Kotlin**

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.EntersOn
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.FromEventSourceId
import io.cratis.chronicle.projections.SetFrom
import io.cratis.chronicle.projections.VariantOf
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class MbVariantUpdatingPullRequestCreated(val pullRequestUrl: String)

@EventType
data class MbVariantUpdatingBuildCompleted(val buildStatus: String)

class MbVariantUpdatingWorkItem

/**
 * buildStatus is mapped from MbVariantUpdatingBuildCompleted - an event that is NOT this variant's
 * entering event, so it is automatically reclassified into an update-only join. It can bring an
 * already-active instance up to date, but it can never create one on its own.
 */
@ReadModel
@VariantOf(MbVariantUpdatingWorkItem::class, key = "id")
@EntersOn(MbVariantUpdatingPullRequestCreated::class)
@FromEvent(MbVariantUpdatingPullRequestCreated::class)
@FromEvent(MbVariantUpdatingBuildCompleted::class)
data class MbVariantUpdatingPullRequestItem(
    @FromEventSourceId
    val id: String = "",

    @SetFrom("pullRequestUrl", MbVariantUpdatingPullRequestCreated::class)
    val pullRequestUrl: String = "",

    @SetFrom("buildStatus", MbVariantUpdatingBuildCompleted::class)
    val buildStatus: String = ""
)
```

[View Kotlin snippet source on GitHub](https://github.com/Cratis/Chronicle.Kotlin/blob/main/Documentation/client-snippets/projections/model-bound/variants/updating-a-variant.md)

**Java**

```java
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.EntersOn;
import io.cratis.chronicle.projections.FromEvent;
import io.cratis.chronicle.projections.FromEventSourceId;
import io.cratis.chronicle.projections.SetFrom;
import io.cratis.chronicle.projections.VariantOf;
import io.cratis.chronicle.readModels.ReadModel;

@EventType
record MbVariantUpdatingPullRequestCreated(String pullRequestUrl) {}

@EventType
record MbVariantUpdatingBuildCompleted(String buildStatus) {}

class MbVariantUpdatingWorkItem {}

/**
 * buildStatus is mapped from MbVariantUpdatingBuildCompleted - an event that is NOT this variant's
 * entering event, so it is automatically reclassified into an update-only join. It can bring an
 * already-active instance up to date, but it can never create one on its own.
 */
@ReadModel
@VariantOf(identity = MbVariantUpdatingWorkItem.class, key = "id")
@EntersOn(eventType = MbVariantUpdatingPullRequestCreated.class)
@FromEvent(eventType = MbVariantUpdatingPullRequestCreated.class)
@FromEvent(eventType = MbVariantUpdatingBuildCompleted.class)
class MbVariantUpdatingPullRequestItem {
    @FromEventSourceId
    public String id = "";

    @SetFrom(propertyPath = "pullRequestUrl", eventType = MbVariantUpdatingPullRequestCreated.class)
    public String pullRequestUrl = "";

    @SetFrom(propertyPath = "buildStatus", eventType = MbVariantUpdatingBuildCompleted.class)
    public String buildStatus = "";
}
```

[View Java snippet source on GitHub](https://github.com/Cratis/Chronicle.Kotlin/blob/main/Documentation/client-snippets-java/projections/model-bound/variants/updating-a-variant.md)

**Elixir**

```elixir
defmodule MyApp.Events.MbVariantUpdatingPullRequestCreated do
  use Chronicle.Events.EventType, id: "mb-variant-updating-pull-request-created-v1"

  defstruct [:pull_request_url]
end

defmodule MyApp.Events.MbVariantUpdatingBuildCompleted do
  use Chronicle.Events.EventType, id: "mb-variant-updating-build-completed-v1"

  defstruct [:build_status]
end

defmodule MyApp.ReadModels.MbVariantUpdatingWorkItem do
end

# build_status is mapped from MbVariantUpdatingBuildCompleted - an event that is NOT this
# variant's entering event, so it is automatically reclassified into an update-only join. It can
# bring an already-active instance up to date, but it can never create one on its own.
defmodule MyApp.ReadModels.MbVariantUpdatingPullRequestItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.{MbVariantUpdatingPullRequestCreated, MbVariantUpdatingBuildCompleted}
  alias MyApp.ReadModels.MbVariantUpdatingWorkItem

  defstruct [:id, :pull_request_url, :build_status]

  variant_of MbVariantUpdatingWorkItem, key: :id
  enters_on MbVariantUpdatingPullRequestCreated

  from MbVariantUpdatingPullRequestCreated,
    set: [id: :event_source_id, pull_request_url: :pull_request_url]

  from MbVariantUpdatingBuildCompleted,
    set: [build_status: :build_status]
end
```

[View Elixir snippet source on GitHub](https://github.com/Cratis/Chronicle.Elixir/blob/main/Documentation/client-snippets/projections/model-bound/variants/updating-a-variant.md)

**TypeScript**

```typescript
import { entersOn, eventType, fromEvent, setFrom, variantOf } from '@cratis/chronicle';

@eventType()
export class MbVariantUpdatingPullRequestCreated {
    pullRequestUrl = '';
}

@eventType()
export class MbVariantUpdatingBuildCompleted {
    buildStatus = '';
}

export class MbVariantUpdatingWorkItem {}

/**
 * buildStatus is mapped from MbVariantUpdatingBuildCompleted - an event that is NOT this variant's
 * entering event, so it is automatically reclassified into an update-only join. It can bring an
 * already-active instance up to date, but it can never create one on its own.
 */
@variantOf(MbVariantUpdatingWorkItem, 'id')
@entersOn(MbVariantUpdatingPullRequestCreated)
@fromEvent(MbVariantUpdatingPullRequestCreated)
@fromEvent(MbVariantUpdatingBuildCompleted)
export class MbVariantUpdatingPullRequestItem {
    id = '';

    @setFrom(MbVariantUpdatingPullRequestCreated, 'pullRequestUrl')
    pullRequestUrl = '';

    @setFrom(MbVariantUpdatingBuildCompleted, 'buildStatus')
    buildStatus = '';
}
```

[View TypeScript snippet source on GitHub](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/client-snippets/projections/model-bound/variants/updating-a-variant.md)

`BuildStatus` comes from `MbVariantUpdatingBuildCompleted`, while the pull-request-created event controls entry. Chronicle converts the build mapping into a join on the variant's own key. A join updates matching read models without creating a missing one, so a late build event cannot recreate a pull request that has moved to another stage.

The join also resolves against stored history when the entering event creates the variant. If a build-completed event was appended first, it does not create a pull request item on its own, but its stored value can populate `BuildStatus` when the pull request enters. Non-entering events are update-only, not discarded history.

If you also declare `[Join<TEvent>]` for that non-entering event, Chronicle preserves the explicit join's mappings and routing. It adds non-conflicting `From` mappings, and the join wins where both map the same property. The join's key remains the event source ID. Its `On` uses the attribute's explicit property name or defaults to the annotated member's name. Specify `on: nameof(Id)` if it should match the variant's `Id`; an explicit join does not automatically switch to the variant key.

These entry rules apply to non-entering events. An entering event still creates its variant, including during replay. See [Joins](/chronicle/projections/model-bound/joins/) for how join keys select existing read models.

## Sharing handlers across variants

Declare common mappings once on a type marked `[GlobalFor<TIdentity>]`. Use the same identity type as the variants so, for example, one title-change mapping keeps the title current in whichever stage is active:

**C#**

```csharp
[EventType]
public record MbVariantSharedIssueCreated(string Title);

[EventType]
public record MbVariantSharedPullRequestCreated(string PullRequestUrl);

[EventType]
public record MbVariantSharedTitleChanged(string Title);

public class MbVariantSharedWorkItem;

[VariantOf<MbVariantSharedWorkItem>]
[EntersOn<MbVariantSharedIssueCreated>]
public record MbVariantSharedBacklogItem([property: Key] Guid Id, string Title);

[VariantOf<MbVariantSharedWorkItem>]
[EntersOn<MbVariantSharedPullRequestCreated>]
public record MbVariantSharedPullRequestItem(
    [property: Key] Guid Id,
    string Title,
    [property: SetFrom<MbVariantSharedPullRequestCreated>] string PullRequestUrl);

/// <summary>
/// Declares a mapping every variant of MbVariantSharedWorkItem shares. Every variant must have a
/// Title member - one that does not is a declaration error, not a silently skipped mapping.
/// </summary>
/// <param name="Title">The title every variant carrying one keeps up to date.</param>
[GlobalFor<MbVariantSharedWorkItem>]
public record MbVariantSharedHandlers([property: SetFrom<MbVariantSharedTitleChanged>] string Title);
```

[View C# snippet source on GitHub](https://github.com/Cratis/Chronicle/blob/main/Documentation/client-snippets/projections/model-bound/variants/shared-handler.md)

**Kotlin**

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.EntersOn
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.FromEventSourceId
import io.cratis.chronicle.projections.GlobalFor
import io.cratis.chronicle.projections.SetFrom
import io.cratis.chronicle.projections.VariantOf
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class MbVariantSharedIssueCreated(val title: String)

@EventType
data class MbVariantSharedPullRequestCreated(val pullRequestUrl: String)

@EventType
data class MbVariantSharedTitleChanged(val title: String)

class MbVariantSharedWorkItem

@ReadModel
@VariantOf(MbVariantSharedWorkItem::class, key = "id")
@EntersOn(MbVariantSharedIssueCreated::class)
@FromEvent(MbVariantSharedIssueCreated::class)
data class MbVariantSharedBacklogItem(
    @FromEventSourceId
    val id: String = "",
    val title: String = ""
)

@ReadModel
@VariantOf(MbVariantSharedWorkItem::class, key = "id")
@EntersOn(MbVariantSharedPullRequestCreated::class)
@FromEvent(MbVariantSharedPullRequestCreated::class)
data class MbVariantSharedPullRequestItem(
    @FromEventSourceId
    val id: String = "",
    val title: String = "",

    @SetFrom("pullRequestUrl", MbVariantSharedPullRequestCreated::class)
    val pullRequestUrl: String = ""
)

/**
 * Declares a mapping every variant of MbVariantSharedWorkItem shares. Every variant must have a
 * title member - one that does not is a declaration error, not a silently skipped mapping.
 */
@GlobalFor(MbVariantSharedWorkItem::class)
@FromEvent(MbVariantSharedTitleChanged::class)
data class MbVariantSharedHandlers(
    @SetFrom("title", MbVariantSharedTitleChanged::class)
    val title: String = ""
)
```

[View Kotlin snippet source on GitHub](https://github.com/Cratis/Chronicle.Kotlin/blob/main/Documentation/client-snippets/projections/model-bound/variants/shared-handler.md)

**Java**

```java
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.EntersOn;
import io.cratis.chronicle.projections.FromEvent;
import io.cratis.chronicle.projections.FromEventSourceId;
import io.cratis.chronicle.projections.GlobalFor;
import io.cratis.chronicle.projections.SetFrom;
import io.cratis.chronicle.projections.VariantOf;
import io.cratis.chronicle.readModels.ReadModel;

@EventType
record MbVariantSharedIssueCreated(String title) {}

@EventType
record MbVariantSharedPullRequestCreated(String pullRequestUrl) {}

@EventType
record MbVariantSharedTitleChanged(String title) {}

class MbVariantSharedWorkItem {}

@ReadModel
@VariantOf(identity = MbVariantSharedWorkItem.class, key = "id")
@EntersOn(eventType = MbVariantSharedIssueCreated.class)
@FromEvent(eventType = MbVariantSharedIssueCreated.class)
class MbVariantSharedBacklogItem {
    @FromEventSourceId
    public String id = "";
    public String title = "";
}

@ReadModel
@VariantOf(identity = MbVariantSharedWorkItem.class, key = "id")
@EntersOn(eventType = MbVariantSharedPullRequestCreated.class)
@FromEvent(eventType = MbVariantSharedPullRequestCreated.class)
class MbVariantSharedPullRequestItem {
    @FromEventSourceId
    public String id = "";
    public String title = "";

    @SetFrom(propertyPath = "pullRequestUrl", eventType = MbVariantSharedPullRequestCreated.class)
    public String pullRequestUrl = "";
}

/**
 * Declares a mapping every variant of MbVariantSharedWorkItem shares. Every variant must have a
 * title member - one that does not is a declaration error, not a silently skipped mapping.
 */
@GlobalFor(identity = MbVariantSharedWorkItem.class)
@FromEvent(eventType = MbVariantSharedTitleChanged.class)
class MbVariantSharedHandlers {
    @SetFrom(propertyPath = "title", eventType = MbVariantSharedTitleChanged.class)
    public String title = "";
}
```

[View Java snippet source on GitHub](https://github.com/Cratis/Chronicle.Kotlin/blob/main/Documentation/client-snippets-java/projections/model-bound/variants/shared-handler.md)

**Elixir**

```elixir
defmodule MyApp.Events.MbVariantSharedIssueCreated do
  use Chronicle.Events.EventType, id: "mb-variant-shared-issue-created-v1"

  defstruct [:title]
end

defmodule MyApp.Events.MbVariantSharedPullRequestCreated do
  use Chronicle.Events.EventType, id: "mb-variant-shared-pull-request-created-v1"

  defstruct [:pull_request_url]
end

defmodule MyApp.Events.MbVariantSharedTitleChanged do
  use Chronicle.Events.EventType, id: "mb-variant-shared-title-changed-v1"

  defstruct [:title]
end

defmodule MyApp.ReadModels.MbVariantSharedWorkItem do
end

defmodule MyApp.ReadModels.MbVariantSharedBacklogItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.MbVariantSharedIssueCreated
  alias MyApp.ReadModels.MbVariantSharedWorkItem

  defstruct [:id, :title]

  variant_of MbVariantSharedWorkItem, key: :id
  enters_on MbVariantSharedIssueCreated

  from MbVariantSharedIssueCreated,
    set: [id: :event_source_id]
end

defmodule MyApp.ReadModels.MbVariantSharedPullRequestItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.MbVariantSharedPullRequestCreated
  alias MyApp.ReadModels.MbVariantSharedWorkItem

  defstruct [:id, :title, :pull_request_url]

  variant_of MbVariantSharedWorkItem, key: :id
  enters_on MbVariantSharedPullRequestCreated

  from MbVariantSharedPullRequestCreated,
    set: [id: :event_source_id, pull_request_url: :pull_request_url]
end

# Declares a mapping every variant of MbVariantSharedWorkItem shares. Every variant must have a
# title member - one that does not is a declaration error, not a silently skipped mapping. Never
# registered as a projection on its own.
defmodule MyApp.Projections.MbVariantSharedHandlers do
  use Chronicle.Projections.GlobalHandler, identity: MyApp.ReadModels.MbVariantSharedWorkItem

  alias MyApp.Events.MbVariantSharedTitleChanged

  from MbVariantSharedTitleChanged,
    set: [title: :title]
end
```

[View Elixir snippet source on GitHub](https://github.com/Cratis/Chronicle.Elixir/blob/main/Documentation/client-snippets/projections/model-bound/variants/shared-handler.md)

**TypeScript**

```typescript
import { entersOn, eventType, fromEvent, globalFor, setFrom, variantOf } from '@cratis/chronicle';

@eventType()
export class MbVariantSharedIssueCreated {
    title = '';
}

@eventType()
export class MbVariantSharedPullRequestCreated {
    pullRequestUrl = '';
}

@eventType()
export class MbVariantSharedTitleChanged {
    title = '';
}

export class MbVariantSharedWorkItem {}

@variantOf(MbVariantSharedWorkItem, 'id')
@entersOn(MbVariantSharedIssueCreated)
@fromEvent(MbVariantSharedIssueCreated)
export class MbVariantSharedBacklogItem {
    id = '';
    title = '';
}

@variantOf(MbVariantSharedWorkItem, 'id')
@entersOn(MbVariantSharedPullRequestCreated)
@fromEvent(MbVariantSharedPullRequestCreated)
export class MbVariantSharedPullRequestItem {
    id = '';
    title = '';

    @setFrom(MbVariantSharedPullRequestCreated, 'pullRequestUrl')
    pullRequestUrl = '';
}

/**
 * Declares a mapping every variant of MbVariantSharedWorkItem shares. Every variant must have a
 * title member - one that does not is a declaration error, not a silently skipped mapping. Never
 * registered as a projection on its own.
 */
@globalFor(MbVariantSharedWorkItem)
export class MbVariantSharedHandlers {
    @setFrom(MbVariantSharedTitleChanged, 'title')
    title = '';
}
```

[View TypeScript snippet source on GitHub](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/client-snippets/projections/model-bound/variants/shared-handler.md)

The shared handler maps the title-change event to `Title` in both variants. Like other non-entering mappings, this mapping updates an existing variant without creating an inactive one. The `CHR0024` analyzer counts the group's entering events and shared handlers as mapping sources; it discovers shared handlers only within the same compilation.

Every variant must declare the member that a shared mapping targets. A missing `Title` member is a declaration error caught during projection discovery; Chronicle does not silently skip the mapping for that variant.

## Complete example

This example combines entry, build-status updates, and a shared title mapping. Follow one entity key through the events: issue creation puts it in the backlog, pull request creation moves it out, and later build or title changes update only the active variant.

**C#**

```csharp
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;

[EventType]
public record MbVariantFullIssueCreated(string Title);

[EventType]
public record MbVariantFullPullRequestCreated(string PullRequestUrl);

[EventType]
public record MbVariantFullBuildCompleted(string BuildStatus);

[EventType]
public record MbVariantFullTitleChanged(string Title);

/// <summary>
/// Anchors the logical identity shared by MbVariantFullBacklogItem and MbVariantFullPullRequestItem.
/// Deliberately not a read model itself.
/// </summary>
public class MbVariantFullWorkItem;

/// <summary>
/// The variant an entity is in before a pull request exists for it.
/// </summary>
[VariantOf<MbVariantFullWorkItem>]
[EntersOn<MbVariantFullIssueCreated>]
public record MbVariantFullBacklogItem([property: Key] Guid Id, string Title);

/// <summary>
/// The variant an entity enters once a pull request is created for it. BuildStatus is
/// mapped from MbVariantFullBuildCompleted - an event that is NOT this variant's entering event, so it
/// becomes an update-only join and can never create the row on its own.
/// </summary>
[VariantOf<MbVariantFullWorkItem>]
[EntersOn<MbVariantFullPullRequestCreated>]
public record MbVariantFullPullRequestItem(
    [property: Key] Guid Id,
    string Title,
    [property: SetFrom<MbVariantFullPullRequestCreated>] string PullRequestUrl,
    [property: SetFrom<MbVariantFullBuildCompleted>] string BuildStatus);

/// <summary>
/// Declares a mapping every variant of MbVariantFullWorkItem shares.
/// </summary>
/// <param name="Title">The title every variant carrying one keeps up to date.</param>
[GlobalFor<MbVariantFullWorkItem>]
public record MbVariantFullSharedHandlers([property: SetFrom<MbVariantFullTitleChanged>] string Title);
```

[View C# snippet source on GitHub](https://github.com/Cratis/Chronicle/blob/main/Documentation/client-snippets/projections/model-bound/variants/full-example.md)

**Kotlin**

```kotlin
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.EntersOn
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.FromEventSourceId
import io.cratis.chronicle.projections.GlobalFor
import io.cratis.chronicle.projections.SetFrom
import io.cratis.chronicle.projections.VariantOf
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class MbVariantFullIssueCreated(val title: String)

@EventType
data class MbVariantFullPullRequestCreated(val pullRequestUrl: String)

@EventType
data class MbVariantFullBuildCompleted(val buildStatus: String)

@EventType
data class MbVariantFullTitleChanged(val title: String)

/**
 * Anchors the logical identity shared by MbVariantFullBacklogItem and MbVariantFullPullRequestItem.
 * Deliberately not a read model itself.
 */
class MbVariantFullWorkItem

/** The variant an entity is in before a pull request exists for it. */
@ReadModel
@VariantOf(MbVariantFullWorkItem::class, key = "id")
@EntersOn(MbVariantFullIssueCreated::class)
@FromEvent(MbVariantFullIssueCreated::class)
data class MbVariantFullBacklogItem(
    @FromEventSourceId
    val id: String = "",
    val title: String = ""
)

/**
 * The variant an entity enters once a pull request is created for it. buildStatus is mapped from
 * MbVariantFullBuildCompleted - an event that is NOT this variant's entering event, so it becomes
 * an update-only join and can never create the row on its own.
 */
@ReadModel
@VariantOf(MbVariantFullWorkItem::class, key = "id")
@EntersOn(MbVariantFullPullRequestCreated::class)
@FromEvent(MbVariantFullPullRequestCreated::class)
@FromEvent(MbVariantFullBuildCompleted::class)
data class MbVariantFullPullRequestItem(
    @FromEventSourceId
    val id: String = "",
    val title: String = "",

    @SetFrom("pullRequestUrl", MbVariantFullPullRequestCreated::class)
    val pullRequestUrl: String = "",

    @SetFrom("buildStatus", MbVariantFullBuildCompleted::class)
    val buildStatus: String = ""
)

/** Declares a mapping every variant of MbVariantFullWorkItem shares. */
@GlobalFor(MbVariantFullWorkItem::class)
@FromEvent(MbVariantFullTitleChanged::class)
data class MbVariantFullSharedHandlers(
    @SetFrom("title", MbVariantFullTitleChanged::class)
    val title: String = ""
)
```

[View Kotlin snippet source on GitHub](https://github.com/Cratis/Chronicle.Kotlin/blob/main/Documentation/client-snippets/projections/model-bound/variants/full-example.md)

**Java**

```java
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.EntersOn;
import io.cratis.chronicle.projections.FromEvent;
import io.cratis.chronicle.projections.FromEventSourceId;
import io.cratis.chronicle.projections.GlobalFor;
import io.cratis.chronicle.projections.SetFrom;
import io.cratis.chronicle.projections.VariantOf;
import io.cratis.chronicle.readModels.ReadModel;

@EventType
record MbVariantFullIssueCreated(String title) {}

@EventType
record MbVariantFullPullRequestCreated(String pullRequestUrl) {}

@EventType
record MbVariantFullBuildCompleted(String buildStatus) {}

@EventType
record MbVariantFullTitleChanged(String title) {}

/**
 * Anchors the logical identity shared by MbVariantFullBacklogItem and MbVariantFullPullRequestItem.
 * Deliberately not a read model itself.
 */
class MbVariantFullWorkItem {}

/** The variant an entity is in before a pull request exists for it. */
@ReadModel
@VariantOf(identity = MbVariantFullWorkItem.class, key = "id")
@EntersOn(eventType = MbVariantFullIssueCreated.class)
@FromEvent(eventType = MbVariantFullIssueCreated.class)
class MbVariantFullBacklogItem {
    @FromEventSourceId
    public String id = "";
    public String title = "";
}

/**
 * The variant an entity enters once a pull request is created for it. buildStatus is mapped from
 * MbVariantFullBuildCompleted - an event that is NOT this variant's entering event, so it becomes
 * an update-only join and can never create the row on its own.
 */
@ReadModel
@VariantOf(identity = MbVariantFullWorkItem.class, key = "id")
@EntersOn(eventType = MbVariantFullPullRequestCreated.class)
@FromEvent(eventType = MbVariantFullPullRequestCreated.class)
@FromEvent(eventType = MbVariantFullBuildCompleted.class)
class MbVariantFullPullRequestItem {
    @FromEventSourceId
    public String id = "";
    public String title = "";

    @SetFrom(propertyPath = "pullRequestUrl", eventType = MbVariantFullPullRequestCreated.class)
    public String pullRequestUrl = "";

    @SetFrom(propertyPath = "buildStatus", eventType = MbVariantFullBuildCompleted.class)
    public String buildStatus = "";
}

/** Declares a mapping every variant of MbVariantFullWorkItem shares. */
@GlobalFor(identity = MbVariantFullWorkItem.class)
@FromEvent(eventType = MbVariantFullTitleChanged.class)
class MbVariantFullSharedHandlers {
    @SetFrom(propertyPath = "title", eventType = MbVariantFullTitleChanged.class)
    public String title = "";
}
```

[View Java snippet source on GitHub](https://github.com/Cratis/Chronicle.Kotlin/blob/main/Documentation/client-snippets-java/projections/model-bound/variants/full-example.md)

**Elixir**

```elixir
defmodule MyApp.Events.MbVariantFullIssueCreated do
  use Chronicle.Events.EventType, id: "mb-variant-full-issue-created-v1"

  defstruct [:title]
end

defmodule MyApp.Events.MbVariantFullPullRequestCreated do
  use Chronicle.Events.EventType, id: "mb-variant-full-pull-request-created-v1"

  defstruct [:pull_request_url]
end

defmodule MyApp.Events.MbVariantFullBuildCompleted do
  use Chronicle.Events.EventType, id: "mb-variant-full-build-completed-v1"

  defstruct [:build_status]
end

defmodule MyApp.Events.MbVariantFullTitleChanged do
  use Chronicle.Events.EventType, id: "mb-variant-full-title-changed-v1"

  defstruct [:title]
end

# Anchors the logical identity shared by MbVariantFullBacklogItem and
# MbVariantFullPullRequestItem. Deliberately not a read model itself.
defmodule MyApp.ReadModels.MbVariantFullWorkItem do
end

# The variant an entity is in before a pull request exists for it.
defmodule MyApp.ReadModels.MbVariantFullBacklogItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.MbVariantFullIssueCreated
  alias MyApp.ReadModels.MbVariantFullWorkItem

  defstruct [:id, :title]

  variant_of MbVariantFullWorkItem, key: :id
  enters_on MbVariantFullIssueCreated

  from MbVariantFullIssueCreated,
    set: [id: :event_source_id]
end

# The variant an entity enters once a pull request is created for it. build_status is mapped
# from MbVariantFullBuildCompleted - an event that is NOT this variant's entering event, so it
# becomes an update-only join and can never create the row on its own.
defmodule MyApp.ReadModels.MbVariantFullPullRequestItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.{MbVariantFullPullRequestCreated, MbVariantFullBuildCompleted}
  alias MyApp.ReadModels.MbVariantFullWorkItem

  defstruct [:id, :title, :pull_request_url, :build_status]

  variant_of MbVariantFullWorkItem, key: :id
  enters_on MbVariantFullPullRequestCreated

  from MbVariantFullPullRequestCreated,
    set: [id: :event_source_id, pull_request_url: :pull_request_url]

  from MbVariantFullBuildCompleted,
    set: [build_status: :build_status]
end

# Declares a mapping every variant of MbVariantFullWorkItem shares.
defmodule MyApp.Projections.MbVariantFullSharedHandlers do
  use Chronicle.Projections.GlobalHandler, identity: MyApp.ReadModels.MbVariantFullWorkItem

  alias MyApp.Events.MbVariantFullTitleChanged

  from MbVariantFullTitleChanged,
    set: [title: :title]
end
```

[View Elixir snippet source on GitHub](https://github.com/Cratis/Chronicle.Elixir/blob/main/Documentation/client-snippets/projections/model-bound/variants/full-example.md)

**TypeScript**

```typescript
import { entersOn, eventType, fromEvent, globalFor, setFrom, variantOf } from '@cratis/chronicle';

@eventType()
export class MbVariantFullIssueCreated {
    title = '';
}

@eventType()
export class MbVariantFullPullRequestCreated {
    pullRequestUrl = '';
}

@eventType()
export class MbVariantFullBuildCompleted {
    buildStatus = '';
}

@eventType()
export class MbVariantFullTitleChanged {
    title = '';
}

/**
 * Anchors the logical identity shared by MbVariantFullBacklogItem and MbVariantFullPullRequestItem.
 * Deliberately not a read model itself.
 */
export class MbVariantFullWorkItem {}

/** The variant an entity is in before a pull request exists for it. */
@variantOf(MbVariantFullWorkItem, 'id')
@entersOn(MbVariantFullIssueCreated)
@fromEvent(MbVariantFullIssueCreated)
export class MbVariantFullBacklogItem {
    id = '';
    title = '';
}

/**
 * The variant an entity enters once a pull request is created for it. buildStatus is mapped from
 * MbVariantFullBuildCompleted - an event that is NOT this variant's entering event, so it becomes
 * an update-only join and can never create the row on its own.
 */
@variantOf(MbVariantFullWorkItem, 'id')
@entersOn(MbVariantFullPullRequestCreated)
@fromEvent(MbVariantFullPullRequestCreated)
@fromEvent(MbVariantFullBuildCompleted)
export class MbVariantFullPullRequestItem {
    id = '';
    title = '';

    @setFrom(MbVariantFullPullRequestCreated, 'pullRequestUrl')
    pullRequestUrl = '';

    @setFrom(MbVariantFullBuildCompleted, 'buildStatus')
    buildStatus = '';
}

/** Declares a mapping every variant of MbVariantFullWorkItem shares. */
@globalFor(MbVariantFullWorkItem)
export class MbVariantFullSharedHandlers {
    @setFrom(MbVariantFullTitleChanged, 'title')
    title = '';
}
```

[View TypeScript snippet source on GitHub](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/client-snippets/projections/model-bound/variants/full-example.md)

## Best practices

Choose an identity type that names the entity, such as the work item in these examples, and give each variant the properties its callers need. Keep common event mappings on a shared handler when they apply to every stage.

Plan queries around the separate collections. There is no built-in query spanning a variant group: a caller that needs an entity regardless of stage must query the variants explicitly, using the shared entity key where appropriate. For reading a particular variant by key, continue with [Read-model consistency](/chronicle/read-models/consistency/).
