@cratis/pi 2.26.0 → 2.28.0

package/package/corpus/skills/cratis-chronicle-client-elixir/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-chronicle-client-elixir
-description: Talk to a Chronicle server from an Elixir application with the cratis_chronicle Hex package - putting Chronicle.Client in a supervision tree, connection strings, use Chronicle.Events.EventType structs, Chronicle.append returning ok or error tuples, reactors with the @handles attribute and a handle/2 callback, model-bound read models, and the connection lifecycle phases and keepalive. Use when an OTP application appends to or observes a Chronicle event store. Do not use for the .NET, TypeScript, or Kotlin clients.
+description: Talk to a Chronicle server from an Elixir application with the cratis_chronicle Hex package - putting Chronicle.Client in a supervision tree, connection strings, use Chronicle.Events.EventType structs, Chronicle.append returning ok or error tuples, reactors with the @handles attribute and a handle/2 callback, model-bound and declarative read models/projections, variant_of/enters_on/GlobalHandler for an entity with mutually exclusive lifecycle shapes, and the connection lifecycle phases and keepalive. Use when an OTP application appends to or observes a Chronicle event store. Do not use for the .NET, TypeScript, or Kotlin clients.
 license: MIT
 ---
 
@@ -100,7 +100,7 @@ All configuration is **child-spec keyword options**. There is no
 | `:namespace` | `"Default"` — capital D | `:160` |
 | `:discover` | `true` | `:161` |
 | `:otp_app` | none; falls back to scanning loaded modules | `:168` |
-| `:event_types`, `:migrations`, `:reactors`, `:reducers`, `:read_models`, `:projections`, `:seeders`, `:webhooks`, `:event_store_subscriptions` | `[]`, merged with discovered | `:186-197` |
+| `:event_types`, `:migrations`, `:reactors`, `:reducers`, `:read_models`, `:projections`, `:seeders`, `:webhooks`, `:event_store_subscriptions`, `:global_handlers` | `[]`, merged with discovered | `:186-197` |
 | `:skip_tls_validation`, `:load_balancer`, `:grpc_options`, `:retry_attempts`, `:reconnect_base_delay`, `:reconnect_max_delay` | forwarded to the connection | — |
 
 > The moduledoc at `client.ex:81` says the namespace defaults to `"default"`.
@@ -311,6 +311,78 @@ A standalone projection is `use Chronicle.Projections.Projection, model: Mod`
 `reduce(event, model_or_nil, context) :: struct()`. **Reducers run in your
 process**, so the reduction is Elixir code you own.
 
+#### Variants — mutually exclusive read models for one entity's lifecycle
+
+> Requires `cratis_chronicle` `3.4.0` or later — newer than this skill's
+> `3.1.0` baseline (`lib/chronicle/projections/variant_reclassifier.ex` and
+> siblings). Reverify before claiming support; take the version from hex.pm.
+
+Some entities do not have one shape for their whole lifetime — a work item is a
+backlog entry until a pull request exists for it, then it is a pull request
+until it merges. `variant_of/2` and `enters_on/1,2` are macros imported by
+**both** `use Chronicle.ReadModels.ReadModel` and
+`use Chronicle.Projections.Projection`, so the model-bound and declarative
+paths declare a variant identically:
+
+```elixir
+defmodule MyApp.ReadModels.WorkItem do
+end
+
+defmodule MyApp.ReadModels.BacklogItem do
+  use Chronicle.ReadModels.ReadModel
+  defstruct id: nil, title: nil
+
+  variant_of MyApp.ReadModels.WorkItem, key: :id
+  enters_on MyApp.Events.IssueCreated
+
+  from MyApp.Events.IssueCreated, set: [id: :event_source_id, title: :title]
+end
+
+defmodule MyApp.ReadModels.PullRequestItem do
+  use Chronicle.ReadModels.ReadModel
+  defstruct id: nil, pull_request_url: nil, build_status: nil
+
+  variant_of MyApp.ReadModels.WorkItem, key: :id
+  enters_on MyApp.Events.PullRequestCreated
+
+  from MyApp.Events.PullRequestCreated,
+    set: [id: :event_source_id, pull_request_url: :pull_request_url]
+
+  # not the entering event -> automatically reclassified into an update-only join
+  from MyApp.Events.BuildCompleted, set: [build_status: :build_status]
+end
+```
+
+`variant_of/2` takes `:key` — **required** — the field on this variant that
+carries the shared identity. `enters_on/1,2` is repeatable and its own `:key`
+option names an *event* property (defaults to `:event_source_id`); every
+`from`/`join` this variant declares for a non-entering event, whether declared
+locally or merged from a shared handler, is automatically reclassified into an
+update-only join keyed on `variant_of`'s `:key`.
+
+A mapping shared across every variant of an identity is a
+`Chronicle.Projections.GlobalHandler`, never registered as a projection on its
+own:
+
+```elixir
+defmodule MyApp.Projections.WorkItemTitleHandler do
+  use Chronicle.Projections.GlobalHandler, identity: MyApp.ReadModels.WorkItem
+
+  from MyApp.Events.TitleChanged, set: [title: :title]
+end
+```
+
+Register it explicitly with `global_handlers: [...]` on `Chronicle.Client`, or
+let `:otp_app` auto-discovery find it (modules exporting
+`__chronicle_global_handler__/1`). A mapping that targets a field some variant
+lacks raises `Chronicle.Projections.GlobalHandlerPropertyNotOnVariant` at
+registration, not a silently skipped mapping.
+
+**A variant with no `enters_on` raises
+`Chronicle.Projections.VariantMustDeclareEntersOnEvent`** at registration — a
+variant that could never be entered could never be written to at all, since
+every other handler on it is update-only.
+
 Querying (`lib/chronicle/read_models.ex`):
 
 ```elixir
@@ -416,6 +488,8 @@ attempt.
 | Appending from a `Task` and expecting the correlation id | Ambient context is per process |
 | Treating quiet observers as "no events" | Keepalive eviction silences observers while appends still succeed |
 | Shipping the default TLS behavior | `skip_tls_validation` defaults to `true` |
+| Forgetting `global_handlers:` or `:otp_app` discovery | A `GlobalHandler` module is never merged into its variants unless registered one way or the other |
+| A shared handler mapping a field one variant lacks | `GlobalHandlerPropertyNotOnVariant` at registration, not a silently skipped mapping |
 
 ## Verify
 
@@ -428,6 +502,8 @@ attempt.
 - Every `Chronicle.append/3` call site handles `{:error, _}` as well as `:ok`.
 - Every reactor's `@handles` list matches the clauses of its `handle/2`.
 - Read model module names have distinct final segments, or explicit ids.
+- Every variant group has at least one `enters_on` per variant, and every
+  `GlobalHandler` member exists on every variant it targets.
 - Every code example was copied from `Documentation/client-snippets/`, not from
   the README.
 - `mix compile --warnings-as-errors` and `mix test` are clean.

package/package/corpus/skills/cratis-chronicle-client-kotlin/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-chronicle-client-kotlin
-description: Talk to a Chronicle server from a Kotlin or Java application with the io.cratis:chronicle client - connection strings, ChronicleClient and the Spring Boot starter, @EventType classes, suspending append, reactors and reducers dispatched by first-parameter type, model-bound read models, classpath artifact discovery, and the blocking API Java uses. Use when building a JVM application that appends to or observes a Chronicle event store. Do not use for the .NET, TypeScript, or Elixir clients, and do not use for Chronicle kernel or Arc work.
+description: Talk to a Chronicle server from a Kotlin or Java application with the io.cratis:chronicle client - connection strings, ChronicleClient and the Spring Boot starter, @EventType classes, suspending append, reactors and reducers dispatched by first-parameter type, model-bound and declarative projections, variants (@VariantOf/@EntersOn/@GlobalFor or variantOf()/entersOn()) for an entity with mutually exclusive lifecycle shapes, classpath artifact discovery, and the blocking API Java uses. Use when building a JVM application that appends to or observes a Chronicle event store. Do not use for the .NET, TypeScript, or Elixir clients, and do not use for Chronicle kernel or Arc work.
 license: MIT
 ---
 
@@ -367,6 +367,84 @@ A model-bound projection puts the projection on the read model with `@FromEvent`
 `NotRewindable`. The declarative
 alternative is a class implementing `IProjectionFor<TReadModel>`.
 
+### Variants — mutually exclusive read models for one entity's lifecycle
+
+> Requires `io.cratis:chronicle` `6.3.0` or later — newer than this skill's
+> `5.1.0` baseline (`Source/src/main/kotlin/io/cratis/chronicle/projections/VariantOf.kt`
+> and siblings). Reverify before claiming support; take the version from Maven
+> Central, not the checked-in source.
+
+Some entities do not have one shape for their whole lifetime — a work item is a
+backlog entry until a pull request exists for it, then it is a pull request
+until it merges. **Variants** let several read models share one logical
+identity and be mutually exclusive: entering one variant removes the entity
+from every other variant in the group, and only the event named by
+`@EntersOn`/`entersOn(...)` can create or resurrect a variant — every other
+event it handles is automatically reclassified into an update-only join.
+
+**Model-bound** (the annotations are ordinary Java annotations, so Kotlin and
+Java use the identical shape):
+
+```kotlin
+class WorkItem  // anchors the group; not itself a read model
+
+@ReadModel
+@VariantOf(WorkItem::class, key = "id")
+@EntersOn(IssueCreated::class)
+@FromEvent(IssueCreated::class)
+data class BacklogItem(
+    @FromEventSourceId val id: String = "",
+    @SetFrom("title", IssueCreated::class) val title: String = ""
+)
+
+@ReadModel
+@VariantOf(WorkItem::class, key = "id")
+@EntersOn(PullRequestCreated::class)
+@FromEvent(PullRequestCreated::class)
+@FromEvent(BuildCompleted::class)   // not the entering event -> update-only join
+data class PullRequestItem(
+    @FromEventSourceId val id: String = "",
+    @SetFrom("pullRequestUrl", PullRequestCreated::class) val pullRequestUrl: String = "",
+    @SetFrom("buildStatus", BuildCompleted::class) val buildStatus: String = ""
+)
+```
+
+`@VariantOf(identity, key)` — **`key` is always an explicit property-name
+string**, on both Kotlin and Java, because reflection resolves it rather than a
+compile-time property reference. `@EntersOn(eventType, key = "EventSourceId")`
+is repeatable — a variant may enter on more than one event — and its `key`
+names an *event* property (not the read model's), defaulting to the event
+source id. A mapping shared by every variant of an identity goes on a type
+annotated `@GlobalFor(identity)` instead of being repeated per variant; every
+variant it targets must actually have the member it maps, or
+`GlobalHandlerPropertyNotOnVariant` is thrown at registration.
+
+**Declarative** — `variantOf` and `entersOn` are members of
+`IProjectionBuilderFor<TReadModel>` itself:
+
+```kotlin
+class PullRequestItemProjection : IProjectionFor<PullRequestItem> {
+    override fun define(builder: IProjectionBuilderFor<PullRequestItem>) {
+        builder
+            .variantOf(WorkItem::class, PullRequestItem::id)   // or variantOf(WorkItem::class, "id")
+            .entersOn(PullRequestCreated::class)
+            .from(BuildCompleted::class)                        // update-only, same reason
+    }
+}
+```
+
+Java calls the same builder with a `Class` and a string key — there is no
+property-reference overload in Java:
+
+```java
+builder.variantOf(WorkItem.class, "id").entersOn(PullRequestCreated.class);
+```
+
+**A variant that declares no `@EntersOn`/`entersOn(...)` throws
+`VariantMustDeclareEntersOnEvent`** at registration — a variant that could
+never be entered could never be written to at all, since every other handler
+on it is update-only.
+
 ## Discovery and registration
 
 `ClientArtifacts` scans the classpath with ClassGraph
@@ -492,6 +570,8 @@ only; there is no in-process reactor, projection, or constraint scenario
 | Leaving the default classpath scan on in a large app | Use `withArtifactsFrom(...)` or `artifact-packages` to narrow it (`ChronicleOptions.kt:58`) |
 | Expecting WebFlux support from the starter | The web auto-configuration is `SERVLET`-only (`ChronicleWebAutoConfiguration.kt:29`) |
 | Exiting `main` after an append | Reactors and reducers stop with the process; the stream is live |
+| Passing a `KProperty1` as `@VariantOf`'s `key` | The annotation form always takes a plain string; only the declarative `variantOf(...)` builder accepts a property reference |
+| A `@GlobalFor` mapping targeting a property one variant lacks | `GlobalHandlerPropertyNotOnVariant` at registration, not a silently skipped mapping |
 
 ## Verify
 
@@ -505,5 +585,7 @@ only; there is no in-process reactor, projection, or constraint scenario
   class.
 - `awaitRegistration()` is followed by a check that registration actually
   succeeded, not treated as proof on its own.
+- Every variant group has at least one `@EntersOn`/`entersOn(...)` per variant,
+  and every `@GlobalFor` member exists on every variant it targets.
 - The build is clean and the specifications pass against the verified artifact
   version.

package/package/corpus/skills/cratis-chronicle-client-typescript/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-chronicle-client-typescript
-description: Talk to a Chronicle server from a Node.js or TypeScript application with @cratis/chronicle - reflect-metadata and decorator compiler settings, ChronicleClient and connection strings, @eventType classes, eventLog.append, reactors and reducers dispatched by camelCase method name, model-bound and declarative projections, glob-based artifact discovery, and the lazy connect and keepalive lifecycle. Use when a Node application appends to or observes a Chronicle event store. Do not use for the .NET, Kotlin, or Elixir clients, and do not use for Arc React frontends or generated Arc proxies.
+description: Talk to a Chronicle server from a Node.js or TypeScript application with @cratis/chronicle - reflect-metadata and decorator compiler settings, ChronicleClient and connection strings, @eventType classes, eventLog.append, reactors and reducers dispatched by camelCase method name, model-bound and declarative projections, variants (@variantOf/@entersOn/@globalFor or .variantOf()/.entersOn()) for an entity with mutually exclusive lifecycle shapes, glob-based artifact discovery, and the lazy connect and keepalive lifecycle. Use when a Node application appends to or observes a Chronicle event store. Do not use for the .NET, Kotlin, or Elixir clients, and do not use for Arc React frontends or generated Arc proxies.
 license: MIT
 ---
 
@@ -317,6 +317,70 @@ Constraints are `@constraint()` on a class implementing `IConstraint` with a
 model-bound constraint decorators in this client** — the class-plus-builder form
 is the only one.
 
+### Variants — mutually exclusive read models for one entity's lifecycle
+
+> Requires `@cratis/chronicle` `6.2.0` or later — newer than this skill's
+> `5.1.0` baseline (`Source/projections/VariantReclassifier.ts` and siblings).
+> Reverify before claiming support; take the version from npm.
+
+Some entities do not have one shape for their whole lifetime — a work item is a
+backlog entry until a pull request exists for it, then it is a pull request
+until it merges. **Model-bound** — `@variantOf(identity, key)` and
+`@entersOn(eventType, key?)`, alongside the ordinary `@fromEvent`/`@setFrom`
+decorators:
+
+```typescript
+class WorkItem {}   // anchors the group; not itself a read model
+
+@variantOf(WorkItem, 'id')
+@entersOn(IssueCreated)
+@fromEvent(IssueCreated)
+@readModel()
+class BacklogItem {
+    id = '';
+    @setFrom(IssueCreated, 'title') title = '';
+}
+
+@variantOf(WorkItem, 'id')
+@entersOn(PullRequestCreated)
+@fromEvent(PullRequestCreated)
+@fromEvent(BuildCompleted)          // not the entering event -> update-only join
+@readModel()
+class PullRequestItem {
+    id = '';
+    @setFrom(PullRequestCreated, 'pullRequestUrl') pullRequestUrl = '';
+    @setFrom(BuildCompleted, 'buildStatus') buildStatus = '';
+}
+```
+
+`entersOn` is repeatable (a variant may enter on more than one event) and its
+`key` argument names an *event* property, defaulting to the event source id. A
+mapping shared by every variant of an identity goes on a class decorated
+`@globalFor(identity)` instead of being repeated on each variant — every
+variant it targets must actually declare the property it maps, or
+`GlobalHandlerPropertyNotOnVariant` is thrown when the group is built. A class
+carrying only `@globalFor` is never itself registered as a projection.
+
+**Declarative** — `variantOf` and `entersOn` are members of
+`IProjectionBuilderFor<TReadModel>` itself:
+
+```typescript
+@projection()
+class PullRequestItemProjection implements IProjectionFor<PullRequestItem> {
+    define(builder: IProjectionBuilderFor<PullRequestItem>): void {
+        builder
+            .variantOf(WorkItem, m => m.id)
+            .entersOn(PullRequestCreated)
+            .from(BuildCompleted);   // update-only, same reason
+    }
+}
+```
+
+**A variant that declares no `@entersOn`/`entersOn(...)` throws
+`VariantMustDeclareEntersOnEvent`** when the group is built — a variant that
+could never be entered could never be written to at all, since every other
+handler on it is update-only.
+
 ## Discovery is a runtime file glob — this is the biggest difference
 
 `ChronicleOptions.discoveryPatterns` defaults to
@@ -382,6 +446,8 @@ not work**. Use module-scope collaborators, as the shipped sample does.
 | Constructor-injecting a dependency into a reactor | There is no DI; the client constructs it |
 | Carrying a `3.x` example forward | Tags, the reducer context parameter, and two RPC names changed in `4.0.0` |
 | Reading `result.sequenceNumber` as a number | It is a `bigint` behind `.value` |
+| A `@globalFor` mapping targeting a property one variant lacks | `GlobalHandlerPropertyNotOnVariant` when the group is built, not a silently skipped mapping |
+| Expecting a `@globalFor`-only class to appear as a projection | It is never registered on its own; it is merged into its variants |
 
 ## Verify
 
@@ -397,4 +463,6 @@ not work**. Use module-scope collaborators, as the shipped sample does.
   class, and an appended event demonstrably reaches it.
 - A production connection string carries credentials and `skipTlsValidation=false`.
 - `client.dispose()` runs on shutdown.
+- Every variant group has at least one `@entersOn`/`entersOn(...)` per variant,
+  and every `@globalFor` member exists on every variant it targets.
 - Lint, `tsc`, and the test suite are clean against the verified package version.

package/package/corpus/skills/cratis-chronicle-projection/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-chronicle-projection
-description: Add Chronicle projection behavior to an existing read model - model-bound attributes first, the fluent IProjectionFor<T> builder when they cannot express the shape. Covers AutoMap, keys, children and nested types, counters, event-sequence selection, and the startup-crash traps. Use when populating a read model from events; do not use to create the read model and its query surface, and do not reach for a reducer before exhausting these options.
+description: Add Chronicle projection behavior to an existing read model - model-bound attributes first, the fluent IProjectionFor<T> builder when they cannot express the shape. Covers AutoMap, keys, children and nested types, counters, event-sequence selection, variants ([VariantOf<T>]/.VariantOf<T>() and [EntersOn<T>]/.EntersOn<T>()) for an entity with mutually exclusive lifecycle shapes such as a work item that is a backlog entry then a pull request then closed, and the startup-crash traps. Use when populating a read model from events; do not use to create the read model and its query surface, and do not reach for a reducer before exhausting these options.
 license: MIT
 ---
 
@@ -104,6 +104,64 @@ query edge. Chronicle's analyzer **`CHR0042` (`JoinOverridesLocalWrite`)** repor
 the overlap; suppress it only when the join is deliberately keeping that property
 fresh.
 
+## Variants — mutually exclusive shapes for one entity's lifecycle
+
+Some entities do not have one shape for their whole lifetime — a work item is a
+backlog entry until a pull request exists for it, then it is a pull request
+until it merges. Modeling that as one read model with a `Status` property and
+an ever-growing set of nullable columns makes every query filter on state
+before it can trust a field. **Variants** let you declare several mutually
+exclusive read models for the same logical entity instead — entering one
+variant automatically removes the entity from every other variant in the
+group, so at any point an entity exists in exactly one of them. Reach for
+variants only when the shapes genuinely diverge; a single read model with a
+`Status` flag is still right when every stage shares almost all its
+properties.
+
+> Variants require `Cratis.Chronicle` `19.1.0` or later — newer than this
+> skill's `18.3.0` baseline. Reverify before claiming support.
+
+Both approaches use the identity type only to anchor the group — it does not
+need to be a read model itself, and does not need a common CLR base type with
+any of the variants.
+
+**Model-bound:** `[VariantOf<TIdentity>]` on each variant type, `[EntersOn<TEvent>]`
+naming the event that activates it, and an optional `[GlobalFor<TIdentity>]` type
+carrying mappings shared across every variant.
+
+```csharp
+[VariantOf<WorkItem>]
+[EntersOn<IssueCreated>]
+public record BacklogItem([property: Key] Guid Id, string Title);
+
+[VariantOf<WorkItem>]
+[EntersOn<PullRequestCreated>]
+public record PullRequestItem([property: Key] Guid Id, [property: SetFrom<PullRequestCreated>] string PullRequestUrl);
+```
+
+**Fluent:** `.VariantOf<TIdentity>(keyAccessor)` and `.EntersOn<TEvent>()` are
+members of `IProjectionBuilderFor<TReadModel>` itself — there is no
+`[GlobalFor<T>]` equivalent, so a shared mapping is declared with `.From<TEvent>()`
+on each variant's builder.
+
+```csharp
+public void Define(IProjectionBuilderFor<PullRequestItem> builder) => builder
+    .VariantOf<WorkItem>(_ => _.Id)
+    .EntersOn<PullRequestCreated>();
+```
+
+Only the entering event can create or resurrect a variant. Every other event a
+variant handles — declared exactly like an ordinary `.From<TEvent>()` /
+`[SetFrom<T>]` mapping — is automatically reclassified into an update-only
+join, so an out-of-order or replayed event can never resurrect a variant the
+entity has since left. A variant that declares no entering event at all throws
+`VariantMustDeclareEntersOnEvent` at startup.
+
+Read [references/variants.md](references/variants.md) for the complete group
+declaration, the update-only reclassification in full, `[GlobalFor<T>]` rules
+and its declaration-error trap, and best practices for picking an identity
+type.
+
 ## Selecting the source
 
 Class-level `[EventSequence("<name>")]`, `[EventLog]`, or `[EventStore("<name>")]`
@@ -146,6 +204,10 @@ or a reactor rather than annotating the projection.
 - **Chaining after `AutoMap()`/`NoAutoMap()`.** Those two return the base builder
   interface, so `.NotRewindable()`, `.Passive()`, `.ContainerName()`, and
   `.FromEventSequence()` will not compile after them. Put them last.
+- **A variant with no `[EntersOn<T>]` / `.EntersOn<T>()`.** Throws
+  `VariantMustDeclareEntersOnEvent` at startup — a variant that could never be
+  entered could never be written to at all. See
+  [references/variants.md](references/variants.md).
 
 ## `[FromAll]` versus `[FromEvery]`
 
@@ -177,5 +239,7 @@ projection spans streams.
 - `ConstantKey` is written as a property initializer.
 - The same event does not carry class-level `[FromEvent<T>]` on both a parent and
   a nested or child type.
+- Every variant group has at least one `[EntersOn<T>]` / `.EntersOn<T>()` per
+  variant, and every `[GlobalFor<T>]` member exists on every variant it targets.
 - The project builds clean and the read-model specifications pass against the
   verified package version.

package/package/corpus/skills/cratis-chronicle-projection/references/fluent-builder.md

@@ -21,15 +21,26 @@ member that Chronicle does not read. Use
 `[Projection(id: "<id>", eventSequence: "<name>")]` when the identity or source
 sequence must be explicit.
 
-## `IProjectionBuilderFor<TReadModel>` — its own four members
+## `IProjectionBuilderFor<TReadModel>` — its own members
 
 ```csharp
 IProjectionBuilderFor<TReadModel> FromEventSequence(EventSequenceId eventSequenceId);
 IProjectionBuilderFor<TReadModel> ContainerName(string containerName);
 IProjectionBuilderFor<TReadModel> NotRewindable();
 IProjectionBuilderFor<TReadModel> Passive();
+IProjectionBuilderFor<TReadModel> VariantOf<TIdentity>(Expression<Func<TReadModel, object?>> keyAccessor);
+IProjectionBuilderFor<TReadModel> EntersOn<TEvent>();
 ```
 
+`VariantOf<TIdentity>` and `EntersOn<TEvent>` require `Cratis.Chronicle`
+`19.1.0` or later — newer than this file's `18.3.0` baseline. See
+[variants.md](variants.md) for the full mechanics: the identity type anchors a
+group of mutually exclusive read models, only the event named in `EntersOn`
+can create or resurrect the variant, and every other `.From<TEvent>()` on the
+same builder is automatically reclassified into an update-only join. There is
+no fluent equivalent of the model-bound `[GlobalFor<T>]` shared handler — a
+mapping shared across variants is repeated on each variant's builder.
+
 ## Inherited from `IProjectionBuilder<TReadModel, TBuilder>`
 
 ```csharp

package/package/corpus/skills/cratis-chronicle-projection/references/model-bound-attributes.md

@@ -70,6 +70,19 @@ Setting it routes every matching event into a single aggregating document at
 that key. That is a different mechanism from the fluent builder's
 `UsingConstantKey("<key>")`, even though the effect is similar.
 
+## Variants
+
+| Attribute | Arity | Parameters | Targets |
+| --- | --- | --- | --- |
+| `[VariantOf<TIdentity>]` | `<TIdentity>` | none | class, struct; single |
+| `[EntersOn<T>]` | `<T>` | `(string? key = default)` | class, struct; repeatable |
+| `[GlobalFor<TIdentity>]` | `<TIdentity>` | none | class, struct; single |
+
+Requires `Cratis.Chronicle` `19.1.0` or later. See
+[variants.md](variants.md) for the full mechanics, the update-only
+reclassification of non-entering events, and the `VariantMustDeclareEntersOnEvent`
+startup trap.
+
 ## Relationships
 
 | Attribute | Arity | Parameters | Targets |

package/package/corpus/skills/cratis-chronicle-projection/references/variants.md

@@ -0,0 +1,182 @@
+# Variants — mutually exclusive read models for one entity
+
+Verified against `Cratis.Chronicle` `19.1.0` (first version carrying this
+feature; the skill's own baseline in `SKILL.md` is `18.3.0` — variants need at
+least `19.1.0`).
+
+Reach for variants when a single logical entity has genuinely different shapes
+across its lifecycle — a work item that is a backlog entry, then a pull
+request, then closed — and modeling it as one read model would mean a `Status`
+column plus an ever-growing set of properties that are only meaningful in one
+stage. A single read model with a `Status` flag is still correct when the
+stages differ only by a flag or two; reach for variants only when the shapes
+themselves diverge. See `choosing-a-read-model-style` in the Chronicle docs for
+the wider decision.
+
+Each variant is an ordinary projection — model-bound or fluent — with its own
+shape. Entering one variant automatically removes the entity from every other
+variant in the same group, so at any point an entity exists in exactly one
+variant. There is no CLR relationship required between the variants or the
+identity type; the identity type's only job is to anchor the group.
+
+## Declaring a group — model-bound
+
+```csharp
+using Cratis.Chronicle.Events;
+using Cratis.Chronicle.Keys;
+using Cratis.Chronicle.Projections.ModelBound;
+
+[EventType]
+public record IssueCreated(string Title);
+
+[EventType]
+public record PullRequestCreated(string PullRequestUrl);
+
+// Anchors the group. Does not need to be a read model itself, and does not
+// need a common CLR base type with any of the variants.
+public class WorkItem;
+
+[VariantOf<WorkItem>]
+[EntersOn<IssueCreated>]
+public record BacklogItem([property: Key] Guid Id, string Title);
+
+[VariantOf<WorkItem>]
+[EntersOn<PullRequestCreated>]
+public record PullRequestItem([property: Key] Guid Id, [property: SetFrom<PullRequestCreated>] string PullRequestUrl);
+```
+
+`[VariantOf<TIdentity>]` targets a class or struct, is not repeatable, and
+lives in `Cratis.Chronicle.Projections.ModelBound`. `TIdentity` is what groups
+variants — every type marked `[VariantOf<WorkItem>]` is mutually exclusive with
+every other. `[EntersOn<TEvent>]` targets a class or struct, **is repeatable**
+(a variant can be entered by more than one event type), and takes an optional
+`key` constructor argument naming the event property that identifies the
+instance — it defaults to the event source id.
+
+When `IssueCreated` is processed, a `BacklogItem` is created. When
+`PullRequestCreated` is processed for the same entity, `PullRequestItem` is
+created **and `BacklogItem` is removed automatically** — no `[RemovedWith<T>]`
+needed, the group handles it. Variants do not have to be entered in order: if
+`PullRequestCreated` arrives for an entity that was never a `BacklogItem`,
+`PullRequestItem` is still created.
+
+## Declaring a group — fluent (`IProjectionFor<T>`)
+
+```csharp
+using Cratis.Chronicle.Projections;
+
+// Anchors the group, same rules as above.
+public class WorkItem;
+
+public record BacklogItem(Guid Id, string Title);
+public record PullRequestItem(Guid Id, string PullRequestUrl);
+
+public class BacklogItemProjection : IProjectionFor<BacklogItem>
+{
+    public void Define(IProjectionBuilderFor<BacklogItem> builder) => builder
+        .VariantOf<WorkItem>(_ => _.Id)
+        .EntersOn<IssueCreated>();
+}
+
+public class PullRequestItemProjection : IProjectionFor<PullRequestItem>
+{
+    public void Define(IProjectionBuilderFor<PullRequestItem> builder) => builder
+        .VariantOf<WorkItem>(_ => _.Id)
+        .EntersOn<PullRequestCreated>();
+}
+```
+
+`VariantOf<TIdentity>(Expression<Func<TReadModel, object?>> keyAccessor)` and
+`EntersOn<TEvent>()` are members of `IProjectionBuilderFor<TReadModel>` itself
+(`Cratis.Chronicle.Projections`), alongside `FromEventSequence`,
+`ContainerName`, `NotRewindable`, and `Passive`. Unlike the model-bound
+attribute, the fluent `VariantOf` call takes the key accessor explicitly —
+there is no separate `[Key]` to infer it from. AutoMap still applies exactly as
+for any other fluent projection.
+
+## Only the entering event can create a variant
+
+Every other `.From<TEvent>()` (fluent) or `[SetFrom<T>]` (model-bound) the
+variant declares works exactly as it would on an ordinary projection — with one
+difference: because the event is not the one named in `[EntersOn<T>]` /
+`.EntersOn<T>()`, Chronicle automatically reclassifies that mapping into an
+**update-only join** on the variant's own key before the definition reaches the
+projection engine. It can update an already-active instance; it can never
+create or resurrect one.
+
+```csharp
+// Model-bound
+[VariantOf<WorkItem>]
+[EntersOn<PullRequestCreated>]
+public record PullRequestItem(
+    [property: Key] Guid Id,
+    [property: SetFrom<PullRequestCreated>] string PullRequestUrl,
+    [property: SetFrom<BuildCompleted>] string BuildStatus); // update-only: BuildCompleted is not the entering event
+
+// Fluent
+public class PullRequestItemProjection : IProjectionFor<PullRequestItem>
+{
+    public void Define(IProjectionBuilderFor<PullRequestItem> builder) => builder
+        .VariantOf<WorkItem>(_ => _.Id)
+        .EntersOn<PullRequestCreated>()
+        .From<BuildCompleted>(); // update-only, same reason
+}
+```
+
+**Why this matters:** without the reclassification, an out-of-order or
+replayed `BuildCompleted` could resurrect a `PullRequestItem` for an entity
+that has since moved to another variant — or one that was never a pull request
+at all. Declaring `[EntersOn<T>]` / `.EntersOn<T>()` is what makes that
+structurally impossible; you do not have to reason about event ordering
+yourself.
+
+## Sharing handlers across variants
+
+**Model-bound** has a dedicated mechanism: `[GlobalFor<TIdentity>]` on a type
+carrying the shared mappings as ordinary members. Every mapping is merged into
+every variant of `TIdentity`:
+
+```csharp
+[EventType]
+public record TitleChanged(string Title);
+
+[GlobalFor<WorkItem>]
+public record WorkItemSharedHandlers([property: SetFrom<TitleChanged>] string Title);
+```
+
+Every variant in the group **must** have the member a shared mapping targets —
+a variant missing it is a declaration error caught when the projection is
+discovered, not a silently skipped mapping at runtime. A shared handler is
+always update-only, exactly like any non-entering event, so it is safe to
+share across variants that enter at different times: it can never create or
+resurrect one on its own.
+
+**Fluent has no equivalent of `[GlobalFor<T>]`.** Each `IProjectionFor<T>` is
+its own class producing its own definition, so a mapping every variant needs is
+declared with `.From<TEvent>()` on each variant's builder individually. If that
+repetition becomes a maintenance concern, that is itself a reason to reach for
+model-bound projections for that group instead.
+
+## Startup-crash trap
+
+**A variant with no `[EntersOn<T>]` / `.EntersOn<T>()` throws
+`VariantMustDeclareEntersOnEvent` at startup.** A variant that could never be
+entered could never be created — and because every other handler on a variant
+is update-only, it would silently never be written to at all, so Chronicle
+refuses to start rather than let that pass silently.
+
+## Best practices
+
+1. **Pick an identity type that means something on its own** — not a marker
+   interface with no purpose beyond grouping. It is the type every variant (and
+   every shared handler) points back to.
+2. **Give every variant only the properties that stage of the entity actually
+   has.** A property every stage needs is either a `[GlobalFor<T>]` handler
+   (model-bound) or repeated on each variant's builder (fluent) — never a
+   reason to fall back to one shared shape with nullable columns.
+3. **Reach for variants only when the shapes genuinely diverge.** A single read
+   model with a `Status` property is still correct when every stage shares
+   almost all of its properties and differs only in a flag or two.
+4. **Each variant is its own collection; there is no query that spans a whole
+   group.** A caller that needs "this entity, whichever stage it's in" queries
+   each variant explicitly rather than assuming a single combined collection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "2.26.0",
+  "version": "2.28.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [