@cratis/pi 2.27.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.json

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