@cratis/pi 7.56.3 → 7.57.0

package/package/corpus/harnesses/copilot/instructions/elixir.instructions.md

@@ -12,13 +12,13 @@ paths:
 # Elixir Conventions
 
 Use Elixir and OTP idioms, not translated C# or JVM shapes. These conventions
-are grounded in `Cratis/Chronicle.Elixir v3.10.2` (`Source/chronicle/mix.exs`,
+are grounded in `Cratis/Chronicle.Elixir v3.13.0` (`Source/chronicle/mix.exs`,
 `.formatter.exs`, and `lib/chronicle/`). Client-specific APIs belong in the
 **cratis-chronicle-client-elixir** skill.
 
 ## Build and format
 
-- For Chronicle 3.10.x use Elixir 1.18 or later (`~> 1.18`).
+- For Chronicle 3.13.x use Elixir 1.18 or later (`~> 1.18`).
 - Run `mix compile --warnings-as-errors`, `mix test`, and
   `mix format --check-formatted` with the project's formatter inputs.
 - Use two-space indentation and let `mix format` own layout.

package/package/corpus/product-sync.json

@@ -579,17 +579,19 @@
         }
       ],
       "synced": {
-        "version": "3.10.2",
-        "date": "2026-10-12",
-        "by": "Cratis/AI#620"
+        "version": "3.13.0",
+        "date": "2026-10-15",
+        "by": "Cratis/AI#719"
       },
       "covers": {
         "skills": [
           "cratis-chronicle-client-elixir"
         ],
-        "rules": []
+        "rules": [
+          "elixir.md"
+        ]
       },
-      "notes": "Initial historical floor recorded on 2026-10-12 by Cratis/AI#619; date records this inventory, not a new product verification."
+      "notes": "Synced to the v3.13.0 tag: decision reads, Chronicle.Testing, captures, discovery drift, standalone constraints, children collections, concurrency scopes and observability."
     },
     {
       "id": "authproxy",

package/package/corpus/rules/elixir.md

@@ -11,13 +11,13 @@ paths:
 # Elixir Conventions
 
 Use Elixir and OTP idioms, not translated C# or JVM shapes. These conventions
-are grounded in `Cratis/Chronicle.Elixir v3.10.2` (`Source/chronicle/mix.exs`,
+are grounded in `Cratis/Chronicle.Elixir v3.13.0` (`Source/chronicle/mix.exs`,
 `.formatter.exs`, and `lib/chronicle/`). Client-specific APIs belong in the
 **cratis-chronicle-client-elixir** skill.
 
 ## Build and format
 
-- For Chronicle 3.10.x use Elixir 1.18 or later (`~> 1.18`).
+- For Chronicle 3.13.x use Elixir 1.18 or later (`~> 1.18`).
 - Run `mix compile --warnings-as-errors`, `mix test`, and
   `mix format --check-formatted` with the project's formatter inputs.
 - Use two-space indentation and let `mix format` own layout.

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 - Chronicle.Client supervision and connection lifecycle, EventType structs, append errors, event sources and streams, Chronicle.Concept, PII and encrypted secrets, reactors, read models/projections with composite keys, variants and GlobalHandler, and observer inspection. 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 - Chronicle.Client supervision and connection lifecycle, EventType structs, append errors, event sources and streams, Chronicle.Concept, PII and encrypted secrets, reactors, read models/projections with composite keys, children, variants and GlobalHandler, decision reads, in-memory testing, captures, constraints, discovery drift and observer inspection. 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
 ---
 
@@ -17,23 +17,11 @@ to yours, and everything after that is ordinary OTP.
 
 Source: `Cratis/Chronicle.Elixir` (Hex package `cratis_chronicle`). Source paths below are relative to `Source/chronicle/`.
 
-Read [references/upgrading.md](references/upgrading.md) when moving an application from an older client; wire compatibility and corrected behavior both matter.
+Read [references/upgrading.md](references/upgrading.md) when moving an application from an older client. Requires Elixir `~> 1.18`; read [references/product-sources.md](references/product-sources.md) for the package and contracts dependency facts.
 
-Requires Elixir `~> 1.18`. Read [references/product-sources.md](references/product-sources.md) for the package and contracts dependency facts.
+> **A git tag is not a Hex release.** `mix deps.get` fetches only published versions, and the repository's `VERSION` file is a build-time placeholder: never quote it. Use namespaced modules (`Chronicle.Events.EventType`, not `Chronicle.EventType`); older READMEs got this wrong. Maintained snippets live in `Documentation/client-snippets/`.
 
-> **A git tag is not a Hex release.** `mix deps.get` fetches only published versions. The `Chronicle.Concept` macro
-> (`use Chronicle.Concept, type: :string`, a single-value concept that carries its
-> `pii` classification once, mirroring `ConceptAs<T>`) is the preferred way to
-> classify a personal value; a client without it annotates fields with `pii/1,2`.
-
-Requires `cratis_chronicle` 3.0.0 for `Chronicle.Concept`.
-
-> **The repository's `VERSION` file is a build-time placeholder** overwritten by the publish workflow. Never quote it.
-
-> Use namespaced modules (`Chronicle.Events.EventType`, not `Chronicle.EventType`); older READMEs got this wrong. Maintained
-> snippets live in `Documentation/client-snippets/`.
-
-Select the published version from hex.pm rather than treating a guide's range as a pin.
+`Chronicle.Concept` (`use Chronicle.Concept, type: :string`) is the preferred way to classify a personal value once, mirroring `ConceptAs<T>`; it requires `cratis_chronicle` 3.0.0, and an older client annotates fields with `pii/1,2`.
 
 ## Adding it
 
@@ -41,7 +29,7 @@ Select the published version from hex.pm rather than treating a guide's range as
 # mix.exs
 defp deps do
   [
-    {:cratis_chronicle, "~> 3.10"}
+    {:cratis_chronicle, "~> 3.13"}
   ]
 end
 ```
@@ -104,17 +92,14 @@ case Lifecycle.wait_until(Lifecycle.name_for(Chronicle.Client), :registered, 30_
 end
 ```
 
-`wait_until(lifecycle, target_phase, timeout \\ 30_000)` is the blocking wait.
-`subscribe/1` returns `{:ok, phase, connection_id}` **and** sends it as a message,
-which closes the subscribe-after-transition race; `phase/1` is the plain
-read.
+`wait_until(lifecycle, target_phase, timeout \\ 30_000)` is the blocking wait;
+`subscribe/1` returns `{:ok, phase, connection_id}` **and** sends it as a message
+(closing the subscribe-after-transition race); `phase/1` is the plain read.
 
-Reconnect never gives up: exponential backoff starts at 1000 ms and caps at
-10000 ms, re-resolving addresses each time. `:retry_attempts` is ignored.
-Registration failures leave the client in `:connected`, log
+Reconnect never gives up (backoff 1000 to 10000 ms; `:retry_attempts` is
+ignored). Registration failures leave the client in `:connected`, log
 `Chronicle registration failed`, and retry every five seconds. Appends before a
-channel exists return `{:error, :not_connected}`; read model queries wait up to
-30 seconds for `:registered`.
+channel exists return `{:error, :not_connected}`.
 
 ## Authentication and TLS
 
@@ -154,24 +139,23 @@ defaults: `nil` registers as string, numbers as number, booleans as boolean;
 list element schemas use the first default element. Nested structs and concepts
 are descended into (`schemas/json_schema_generator.ex`).
 
-The macro imports constraint macros into your module:
-`unique/1`, `unique/2`, `unique_event_type/0`, `unique_event_type/1`,
-`remove_constraint/1`, plus `Chronicle.Compliance.pii/1,2` and
-`Chronicle.Confidentiality.encrypted/1,2,3`. The
-equivalent accumulating module attributes `@unique`, `@unique_event_type`,
-`@remove_constraint` also work.
+The macro imports `unique/1,2`, `unique_event_type/0,1`, `remove_constraint/1,2`,
+`closes_stream/1`, `Chronicle.Compliance.pii/1,2` and
+`Chronicle.Confidentiality.encrypted/1,2,3`; the accumulating attributes
+`@unique`, `@unique_event_type`, `@remove_constraint` also work. Read
+[references/constraints.md](references/constraints.md) for their options.
 
 **Only top-level event keys are camelCased.** `encode_event/1` transforms them
 before `Jason.encode!` (`event_sequences/event_log.ex`); nested keys are
 not transformed. Event structs get no `Jason.Encoder` implementation;
-`Chronicle.Concept` does, encoding its wrapped value rather than a wrapper.
+`Chronicle.Concept` does, encoding its wrapped value.
 
 Read [references/compliance.md](references/compliance.md) when defining personal data, data subjects, concepts or encrypted operational secrets. `pii` and `encrypted` are not interchangeable and cannot mark the same leaf.
 
 Schema evolution is
 `use Chronicle.Events.Migration, from: {Mod, generation: n}, to: {Mod, generation: n + 1}`
-with `upcast/1` and `downcast/1`; the generations must be exactly one apart or it
-raises at compile time.
+with `upcast/1` and `downcast/1`; the generations must be exactly one apart. Mark
+the older module with `generation_for:`, not a second `:id`.
 
 ## Appending
 
@@ -183,40 +167,30 @@ case Chronicle.append("account-1", %MyApp.Events.FundsDeposited{amount: 50}) do
 end
 ```
 
-`Chronicle.append/3` delegates to `Chronicle.EventSequences.EventLog`
-(`lib/chronicle.ex`):
-
-```elixir
-@spec append(String.t(), struct(), keyword()) :: :ok | {:error, term()}
-```
-
+`Chronicle.append/3` delegates to `Chronicle.EventSequences.EventLog`.
 **The event source id comes first, the event second.** The return is a bare
-`:ok`, not a result struct — this client's `append/3` deliberately carries no
-sequence number, and `append_and_wait_for_completion/3` exists for when you need
-the outcome.
+`:ok`, carrying no sequence number; use `append_with_result/3` or
+`append_and_wait_for_completion/3` when you need the outcome.
 
 Read [references/append-api.md](references/append-api.md) when you need an append variant, a read-back function, or an append option such as `:event_stream_type`, `:concurrency_scope` or `:tags`.
 
 Requires `cratis_chronicle` 3.2.0 for rejected appends to return `{:error, reason}`; an older client could report a rejection as `:ok`.
 
-Failed appends return `{:error, reason}`. Reasons include `{:constraint_violations, violations}`,
+Failed appends return `{:error, reason}`: `{:constraint_violations, violations}`,
 `{:concurrency_violations, violations}`, `{:append_errors, errors}`,
-`:not_connected`, and `{:incompatible_server, response}` from the first append's
-compatibility preflight per channel. Pair the kernel and installed contracts;
-do not blindly retry a timed-out write.
-
-**Match on them.** A bare `:ok = Chronicle.append(...)` raises a `MatchError` on
-a constraint violation, which is a fine choice in a script and the wrong one in a
-GenServer.
+`{:unknown_event_type, module}`, `:not_connected`, and `{:incompatible_server, response}`
+from the first append's compatibility preflight per channel. Pair the kernel and
+installed contracts; do not blindly retry a timed-out write. **Match on them**: a
+bare `:ok = Chronicle.append(...)` raises a `MatchError` on a violation, fine in a
+script and wrong in a GenServer.
 
 Read [references/event-sources.md](references/event-sources.md) when declaring named event sources/streams, deriving concurrency scopes or routing mixed-source batches; definitions have client and kernel requirements stated there.
 
-A unit of work is a process: `Chronicle.begin_unit_of_work/1` starts an `Agent`,
-and while one is current for the calling process `append`/`append_many` buffer
-instead of sending, until `UnitOfWork.commit/1` or `rollback/1`.
-`commit/1` returns `:ok | {:error, reason}`. `Chronicle.with_unit_of_work(fun, opts)`
-passes the unit to an arity-one function, commits on return, and raises on commit
-failure. Source/stream options apply to buffered appends too.
+A unit of work is a process: `Chronicle.begin_unit_of_work/1` starts an `Agent`;
+while one is current for the calling process, `append`/`append_many` buffer until
+`UnitOfWork.commit/1` (`:ok | {:error, reason}`) or `rollback/1`.
+`Chronicle.with_unit_of_work(fun, opts)` commits on return and raises on commit
+failure.
 
 ## Observing
 
@@ -224,11 +198,8 @@ failure. Source/stream options apply to buffered appends too.
 
 Read [references/reactor-example.md](references/reactor-example.md) when you need a worked reactor module.
 
-This follows `Documentation/client-snippets/get-started/common/reactor.md`.
-
 - **`@handles` is an accumulating module attribute** declaring the subscription;
-  dispatch is then ordinary Elixir pattern matching in `handle/2`. This is the
-  Elixir answer to the other clients' method-name or parameter-type conventions.
+  dispatch is then ordinary Elixir pattern matching in `handle/2`.
 - The callback is
   `handle(event :: struct(), context :: map()) :: :ok | {:error, term()} | {:ok, struct() | [struct()]}`.
 - **Returning `{:ok, event_or_events}` appends those events as a side effect** —
@@ -239,28 +210,27 @@ This follows `Documentation/client-snippets/get-started/common/reactor.md`.
 - Optional replay callbacks: `on_replay_begin/0`, `on_replay_end/0`,
   `on_partition_replay_begin/1`, `on_partition_replay_end/1`.
 
-**The reactor context has six keys**: `event_source_id`, `sequence_number`,
-`occurred`, `event_source`, `event_store`, `namespace`
-(`lib/chronicle/reactors/handler.ex`). `event_source` is the registered
-source name or `nil` for legacy appends. The moduledoc mentions `:correlation_id`,
-but **it is not in the map**. Reducer context differs: `event_source_id`,
-`sequence_number`, `occurred`, `event_source`, `observation_state`
-(`reducers/handler.ex`).
+**The context is a `Chronicle.Events.EventContext` struct** (requires 3.11.0; a
+bare map before). Pattern match on keys or use `context.caused_by`. It carries
+`event_source_id`, `sequence_number`, `occurred`, `event_source` (the registered
+source name or `nil`), `event_store`, `namespace`, `correlation_id`, `caused_by`,
+`causation`, `tags`, `subject`, `appended_generation`, `replaying?` and, for
+reactors only, `delivery_id` (stable across replay and failed-partition
+recovery; key a receipt on it). Reducers get the same struct with
+`observation_state` set (`lib/chronicle/events/event_context.ex`).
 
 ### Read models and projections
 
-Read [references/reactor-example.md](references/reactor-example.md#read-model-example) for a worked model-bound read model.
-
-This is the model-bound shape; use typed defaults for its registered schema.
+Read [references/reactor-example.md](references/reactor-example.md#read-model-example) for a worked model-bound read model with typed defaults.
 
-The DSL macros are `from/1`, `from/2`, `join/2`, `removed_with/2`, `from_every/1`.
+The DSL macros are `from/1,2`, `join/2`, `removed_with/2`, `from_every/1`, `children/2,3`.
 `from/2` options: `:key` (defaults to `"$eventSourceId"`), `:parent_key`, `:set`,
 `:add`, `:subtract`, `:count`. `join/2` requires `:on`.
 
-Read [references/projections.md](references/projections.md) when choosing `passive`, `not_rewindable`, `event_sequence`, `no_auto_map`, composite/event-context keys or dictionary counters. Snake_case field atoms now map correctly; no camelCase-string workaround is needed.
+Read [references/projections.md](references/projections.md) when choosing `passive`, `not_rewindable`, `event_sequence`, `no_auto_map`, composite/event-context keys, dictionary counters or `children/2,3` collections. Snake_case field atoms now map correctly; no camelCase-string workaround is needed.
 
 > **The read model id sent to the kernel is the last module segment** —
-> `Module.split() |> List.last()` at `lib/chronicle/read_models/read_model.ex`.
+> `Module.split() |> List.last()` at `read_models/read_model.ex`.
 > `MyApp.ReadModels.Account` registers as `"Account"`, so two read models with the
 > same final segment collide. Pass `id:` to disambiguate.
 
@@ -283,10 +253,8 @@ Querying (`lib/chronicle/read_models.ex`):
 {:ok, account} = Chronicle.read_model(MyApp.ReadModels.AccountBalance, "account-1")
 ```
 
-`Chronicle.read_model/3` delegates to `ReadModels.get/3` (`lib/chronicle.ex`,
-`read_models.ex`), returning `{:ok, struct() | nil} | {:error, term()}`.
-`Chronicle.all/2` delegates to `ReadModels.all/2`
-(`lib/chronicle.ex`, `read_models.ex`).
+`Chronicle.read_model/3` returns `{:ok, struct() | nil} | {:error, term()}`; `nil`
+means absent **or not projected yet**.
 
 Use `Chronicle.ReadModels.query(MyApp.ReadModels.AccountBalance, page: 0)` for paging:
 `:page` is zero-based (default `0`), `:page_size` defaults to `50`, and
@@ -294,18 +262,26 @@ Use `Chronicle.ReadModels.query(MyApp.ReadModels.AccountBalance, page: 0)` for p
 `occurrences/2`, and `definitions/1` expose history, replay containers, and
 registered definitions.
 
-**Live updates arrive as messages, not as a stream.** `ReadModels.watch/2`
-(`read_models.ex`) sends
-`{:chronicle_read_model_changed, module, %Changeset{}}` and
-`{:chronicle_read_model_watch_error, module, reason}` to the calling process. The receiving process needs a `handle_info` for both.
+**Live updates arrive as messages, not as a stream.** `ReadModels.watch/2` and `subscribe/2` send `{:chronicle_read_model_changed, module, %Changeset{}}` and error messages to the calling process, which needs a `handle_info` for each. Read [references/read-models.md](references/read-models.md) when subscribing, filtering, observing collections, previewing or waiting for a projection.
+
+## Guarding decisions, testing and more
+
+Read the reference that matches the task:
+
+- [references/decision-reads.md](references/decision-reads.md) when an append depends on state a concurrent append could change: `Chronicle.decide/2`, `DecisionReads`, `ConcurrencyScope` builders, the optimistic default.
+- [references/testing.md](references/testing.md) when writing specs: `Chronicle.Testing.Case`, assertions, the in-memory kernel's limits.
+- [references/constraints.md](references/constraints.md) when declaring uniqueness, standalone constraint modules, `remove_constraint/2`, violation details or closing events.
+- [references/discovery-and-generations.md](references/discovery-and-generations.md) when pinning ids, setting `:drift_policy`, running `mix chronicle.discover`, or handling older event generations.
+- [references/captures.md](references/captures.md) when turning external API, webhook or other-store data into events.
+- [references/observability.md](references/observability.md) and [references/patterns.md](references/patterns.md) for OpenTelemetry/`:telemetry` and `Chronicle.Patterns`.
 
 ## Idioms and operational inspection
 
-Read [references/idioms-and-inspection.md](references/idioms-and-inspection.md) when carrying correlation or identity across a `Task`, formatting the DSL, supervising `ReadModels.watch/2`, or removing observers (obtain explicit authority first).
+Read [references/idioms-and-inspection.md](references/idioms-and-inspection.md) when carrying correlation or identity across a `Task`, formatting the DSL, supervising watches, or removing observers (obtain explicit authority first).
 
 ## Common pitfalls
 
-Read [references/pitfalls.md](references/pitfalls.md) when troubleshooting discovery, defaults, process context, variant registration or older-version examples.
+Read [references/pitfalls.md](references/pitfalls.md) when troubleshooting discovery, defaults, process context, variants or older-version examples.
 
 ## Verify
 
@@ -319,10 +295,11 @@ Read [references/pitfalls.md](references/pitfalls.md) when troubleshooting disco
 - Every event type module passes an explicit, stable `id:`.
 - Every `Chronicle.append/3` call site handles `{:error, _}` as well as `:ok`.
 - Every reactor's `@handles` list matches the clauses of its `handle/2`.
+- Reactors, reducers and projections that must survive a rename pin their `:id`.
 - 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.
 - Production logging filters credential-bearing gRPC/Mint crash reports; see
   the connections reference for limits.
 - Examples match the APIs and schema defaults at the installed tag.
-- `mix compile --warnings-as-errors` and `mix test` are clean.
+- `mix compile --warnings-as-errors` and `mix test` are clean; `mix chronicle.discover --otp-app my_app` lists every expected artifact.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/append-api.md

@@ -38,3 +38,13 @@ Read [event-sources.md](event-sources.md) for definitions, stream routing and de
 `append_response.ex` returns `{:error, {:constraint_violations, violations}}`, `{:error, {:concurrency_violations, violations}}` or `{:error, {:append_errors, errors}}` on rejection. Channel/preflight errors include `{:error, :not_connected}` and `{:error, {:incompatible_server, response}}`. A transport timeout does not prove that no event was stored.
 
 `append_and_wait_for_completion/3` has **no many-event variant**. `{:ok, result}` does not imply every observer succeeded: inspect `result.success` and `failed_partitions`. Its wait happens **after** the append (`event_log.ex`), so `{:error, reason}` can follow a stored event if waiting fails. Do not retry the write blindly; reconcile the stored outcome first.
+
+## Structured results, prepared events and unknown types
+
+Requires `cratis_chronicle` 3.13.0 for everything in this section.
+
+- `append_with_result/3` and `append_many_with_result/3` return `{:ok, %AppendResult{sequence_number: _}}` (batch: every assigned number, in order) or `{:error, %AppendResult{}}` carrying `:constraint_violations` (each with `:constraint_name`, `:message`, `:event_type_id`, `:sequence_number`, `:details`), `:concurrency_violations` (`:event_source_id`, `:expected_sequence_number`, `:actual_sequence_number`) and `:errors`. Use them when you need the assigned sequence number or the structured reason; transport failures stay plain `{:error, reason}`. `AppendResult.wait_for_completion/2` waits for observers.
+- `EventLog.prepare/2` serializes an event once into a `PreparedEvent` bound to the client, namespace and event sequence that prepared it; reuse it with `EventLog.append_prepared/3` and `Streams.verify_content/3`. Appending it through another client, namespace or sequence returns `{:error, :prepared_event_belongs_to_another_sequence}`. Single use is not enforced.
+- **A struct that does not `use Chronicle.Events.EventType` returns `{:error, {:unknown_event_type, module}}`** from every append path, `prepare/2` and `Streams.verify_content/3`; it does not raise. Match it like any other error.
+- A payload over 4 MiB returns `{:error, {:payload_too_large, size, limit}}` before sending. Raise or disable the guard with `config :cratis_chronicle, max_payload_bytes: ...` (or `:infinity`) only when the kernel is configured for larger messages.
+- Reads: `get_for_event_source/3` and `get_from_sequence_number/2` return raw wire events; pass `decode: true` for `Chronicle.Events.AppendedEvent` structs (`event: nil` and `:raw` for an unknown type, `redacted?: true` for a redacted event).

package/package/corpus/skills/cratis-chronicle-client-elixir/references/captures.md

@@ -0,0 +1,43 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Captures
+
+Source: `Cratis/Chronicle.Elixir`: `Source/chronicle/lib/chronicle/captures.ex`, `captures/capture.ex`, `captures/registrar.ex`, and `Documentation/captures.md`.
+
+Requires `cratis_chronicle` 3.13.0.
+
+A capture turns data that arrives from outside the event log (an external API, an inbound webhook, another event store's public events) into events appended to this event store. The DSL compiles at build time to Capture Declaration Language (CDL), the text the kernel's `SaveCapture` accepts. Use a capture instead of a hand-written poller when the source data should become facts you own.
+
+```elixir
+# Copyright (c) Cratis. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+defmodule MyApp.Captures.InvoiceCapture do
+  use Chronicle.Captures.Capture, name: "InvoiceCapture"
+
+  api_source("InvoicingApi", route: "/invoices", poll: "10m")
+
+  key("id")
+
+  append MyApp.Events.InvoiceStatusChanged, when: "status" do
+    set(:status, "$.status")
+  end
+end
+```
+
+- Exactly one source: `api_source/1,2` (polls a named external service), `webhook_source/1`, or `events_source/1` (a list of registered event type modules from another event store's public events).
+- `key/1` names the property path that identifies and diffs an item; use `"$eventSourceId"` for an events source.
+- `:id` defaults to a UUIDv5 of the module name, so redeploying updates the same kernel-side capture. `:name` defaults to the last module segment. `start: true` makes the registrar start it once saved.
+- `when:` takes a property name, `{:any, [...]}`, `{:all, [...]}`, `{:transition, property, from, to}`, `:added`, `:removed`, or `{:expression, "template"}`. `set/2` maps a target field from `"$.path"` (payload) or `"$context.<property>"`.
+- The DSL also has `nested` and `children` scopes, and a `map do` block with `rename`, `template`, `translate` and `split`.
+
+**An appended event type's id must start with an uppercase letter and contain only letters, digits and underscores.** The kernel's CDL parser rejects hyphens, so `use Chronicle.Events.EventType, id: "InvoiceStatusChanged"` works as an `append` target and `id: "invoice-status-changed"` raises `ArgumentError` at compile time. This restriction does not apply to `events_source/1`.
+
+**The kernel's capture engine runs a subset of the language**: only `api` and `events` sources, and only root-level `append` rules. `map`, `nested` and `children` compile and validate but are not applied at runtime, and webhook sources cannot carry authentication.
+
+## Registering and managing
+
+Captures are discovered with `otp_app:` or listed in the client's `:captures` option. `Chronicle.Captures.Registrar` saves them at `:registered` and again on every reconnect. It skips a capture whose declaration already matches, and warns before saving over a **started** capture whose declaration changed, because saving stops it on the kernel.
+
+Manage directly with `Chronicle.Captures.register/1`, `start/1`, `stop/1`, `delete/1`, `list/0`, `validate/1` (a module or raw CDL text) and `captured_events/1`. `start`, `stop` and `delete` also accept a raw capture id; `delete` is destructive, so obtain authority for the specific capture first.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/client-options.md

@@ -16,6 +16,12 @@ your app must read its own configuration and pass it in (`lib/chronicle/client.e
 | `:discover` | `true` |
 | `:otp_app` | none; falls back to scanning loaded modules |
 | `:event_types`, `:event_sources`, `:migrations`, `:reactors`, `:reducers`, `:read_models`, `:projections`, `:seeders`, `:webhooks`, `:event_store_subscriptions`, `:global_handlers` | `[]`, merged with discovered |
+| `:constraints`, `:captures`, `:read_model_reactors` | `[]`, merged with discovered where discoverable |
+| `:drift_policy` | `:warn`; `:ignore` or `:fail`. See [discovery-and-generations.md](discovery-and-generations.md) |
+| `:strict_validation` | `false`; `true` raises on event type and migration mistakes instead of logging |
+| `:warn_defaulted_ids` | `true` |
+| `:event_generation_delivery` | `:compatibility`; `:pinned` delivers events at their appended generation |
+| `:concurrency` | none; `[default: :optimistic, check_first_append: bool]`. See [decision-reads.md](decision-reads.md) |
 | `:default_sink_type_id` | `:mongodb`; accepts `:mongodb`, `:sql`, `:in_memory`, `:none` or a raw string |
 | `:server_address` | alternative `"host:port"` address (connection option) |
 | `:skip_tls_validation`, `:load_balancer`, `:grpc_options`, `:reconnect_base_delay`, `:reconnect_max_delay` | forwarded to the connection | — |

package/package/corpus/skills/cratis-chronicle-client-elixir/references/connections.md

@@ -45,7 +45,7 @@ The client uses grpc 1.x and Mint 1.11+, owns its transport, and needs no `GRPC.
 
 ## Credential-safe logging is still necessary
 
-Chronicle's own process status redacts credentials, but dependency crash reports can expose gRPC headers, bearer tokens, API keys and Mint HPACK tables. Before starting the client, install the primary Logger filter from the [client crash-report guide](https://github.com/Cratis/Chronicle.Elixir/blob/main/Documentation/connections/crash-reports.md). It matches `Elixir.GRPC.Client`, `Elixir.GRPC.Channel`, and `Elixir.Mint.` report content and replaces reports with a notice.
+Chronicle's own process status redacts credentials, but dependency crash reports can expose gRPC headers, bearer tokens, API keys and Mint HPACK tables. The client itself installs a primary Logger filter (`Chronicle.Connections.ResponseCrashRedaction`) when a connection starts, replacing the Mint response-process termination report, the one shape it can intercept generically, with a one-line notice (requires `cratis_chronicle` 3.13.0). The `ConnectionProcess` and `GRPC.Client.Connection` state can still print credentials, so before starting the client, install the primary Logger filter from the [client crash-report guide](https://github.com/Cratis/Chronicle.Elixir/blob/main/Documentation/connections/crash-reports.md). It matches `Elixir.GRPC.Client`, `Elixir.GRPC.Channel`, and `Elixir.Mint.` report content and replaces reports with a notice.
 
 Keep `handle_sasl_reports: false`. This is a safety net, not a guarantee: plain warning strings carrying exit reasons are not covered, and filters do not survive a Logger restart. Restrict production log access and rotate any credential already exposed. Never log connection strings.
 

package/package/corpus/skills/cratis-chronicle-client-elixir/references/constraints.md

@@ -0,0 +1,63 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Constraints
+
+Source: `Cratis/Chronicle.Elixir`: `Source/chronicle/lib/chronicle/events/event_type.ex`, `events/constraint.ex`, `events/constraint_violation.ex`, and `Documentation/constraints.md`.
+
+Requires `cratis_chronicle` 3.13.0 for standalone constraint modules, `remove_constraint/2`, `:scope` and `ConstraintViolation.details/1`.
+
+A constraint is checked by the kernel at append time; a violation returns `{:error, {:constraint_violations, violations}}` (or `{:error, %AppendResult{}}` from `append_with_result/3`).
+
+## On the event type
+
+`unique/2`, `unique_event_type/1`, `remove_constraint/1,2` and `closes_stream/1` are imported by `use Chronicle.Events.EventType`.
+
+| Option | Meaning |
+| --- | --- |
+| `:name` | Constraint name; defaults to the first field (`unique`) or the event type id (`unique_event_type`) |
+| `:mode` | `:per_event_source` (default) keeps one value per event source and frees the old one when replaced; `:per_value` keeps every value until a removal event releases it |
+| `:ignore_casing` | Case-insensitive comparison (`unique` only) |
+| `:message` | A string or a `{Module, :function}` callback invoked with the violation |
+| `:scope` | `:per_event_source_type`, `:per_event_stream_type`, `:per_event_stream_id`, or a list; narrows uniqueness to values seen along those dimensions. Unscoped is global |
+| `:event_sequences` | Restrict to specific event sequences |
+
+An unknown option or invalid `:scope` compiles with a warning naming the module and is ignored; an invalid `:mode` raises `ArgumentError` when the definition is built.
+
+## Releasing a held value
+
+In `:per_value` mode, `remove_constraint("Name")` releases every value the removal event's event source held. `remove_constraint("Name", properties: [:version_id])` releases only the value the removal event carries, in the order of the constrained properties.
+
+## Standalone constraint modules
+
+Use `use Chronicle.Events.Constraint` when one name spans several event types or lives apart from any one event type's module.
+
+```elixir
+# Copyright (c) Cratis. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+defmodule MyApp.Constraints.UniqueEmail do
+  use Chronicle.Events.Constraint
+
+  unique name: "UniqueEmail" do
+    on MyApp.Events.UserRegistered, [:email]
+    on MyApp.Events.UserEmailChanged, [:new_email]
+    removed_with MyApp.Events.UserRemoved
+  end
+end
+```
+
+- `name:` is **required** on a standalone declaration.
+- `removed_with/1,2` inside `unique/2` releases the value (with `properties:` in `:per_value` mode). After a bare `unique_event_type/1,2` it releases that constraint; calling it before any `unique_event_type` is a compile error.
+- Two `unique_event_type` declarations with the same `:name` merge into one mutually exclusive constraint: at most one event of the named set per event source (`unique_event_type MyApp.Events.PersonErased, name: "PersonTerminal"`).
+- Modules are discovered like event types, or listed in the client's `:constraints` option (and in `start_supervised_client/1` when testing).
+
+## Violation details
+
+`Chronicle.Events.ConstraintViolation.details(violation)` maps the kernel's detail keys to atoms: `:property_name`, `:property_value`, `:closed_by`, `:closed_at_sequence_number`; any other key stays a string. A PII property's `:property_value` is its **encrypted** form. Use it in a `:message` callback: `"A project named '#{ConstraintViolation.details(violation)[:property_value]}' already exists."`.
+
+## Closing events
+
+`closes_stream event_stream_id_from: :period, reopened_by: [MyApp.Events.PeriodReopened]` on an event type closes that stream scope when the event is appended; later events in the scope are refused. Options: `:dimensions`, `:event_stream_id_from`, `:reopened_by`, `:name`, `:event_sequences`; same-named declarations merge and must agree on dimensions. Registration closes nothing in history. Inspect closed scopes with `Chronicle.EventSequences.Streams`. The in-memory test kernel does not model `closes_stream`.
+
+Constraint drift is not detected: the kernel cannot list registered constraints.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/decision-reads.md

@@ -0,0 +1,65 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Decision reads and the dynamic consistency boundary
+
+Source: `Cratis/Chronicle.Elixir`: `Source/chronicle/lib/chronicle/read_models/decision_reads.ex`, `decision_read_refused.ex`, `decision_conflict.ex`, `transactions/unit_of_work.ex`, and `Documentation/dynamic-consistency-boundary.md`.
+
+Requires `cratis_chronicle` 3.13.0.
+
+Use a decision read when an append depends on state that a concurrent append could change (a seat can be booked once, a course has capacity). It folds a read model at a key in a fresh session and remembers the exact log position it stopped at; the commit is then rejected by the kernel if a matching event arrived since. An ordinary `Chronicle.read_model/3` followed by `append/3` is **not** a guard: it can silently act on stale state.
+
+## Decide
+
+```elixir
+result =
+  Chronicle.decide(fn _unit_of_work ->
+    {:ok, read} = Chronicle.ReadModels.DecisionReads.get(MyApp.ReadModels.Seat, "seat-5")
+
+    if read.instance == nil do
+      Chronicle.EventSequences.EventLog.append("seat-5", %MyApp.Events.SeatBooked{by: "alice"})
+    end
+  end)
+
+case result do
+  {:ok, _} -> :booked
+  {:error, %Chronicle.ReadModels.DecisionConflict{}} -> :retry
+  {:error, reason} -> {:error, reason}
+end
+```
+
+- `Chronicle.decide/2` runs the function in a unit of work and commits on return. It returns `{:ok, result}`, or `{:error, %DecisionConflict{}}` when an enrolled decision read conflicted with a concurrent append; nothing from that attempt was written, so re-read and decide again. Other commit failures are plain `{:error, reason}`.
+- Unlike `with_unit_of_work/2`, `decide/2` never raises on a conflict. A concurrency violation without an enrolled decision read stays `{:error, {:concurrency_violations, _}}`.
+- **`DecisionReads.get/2` enrolls the read only inside a unit of work** (`decide/2` or `UnitOfWork.with_unit_of_work/2`). Outside one it returns `{:error, :requires_unit_of_work}`.
+- `DecisionReads.get_detached/2` folds the same way and enrolls nothing; use it for a read you do not intend to guard.
+- A rule across two entities needs one decision read per event source. Enroll both inside the same `decide/2` and append one event to each; the kernel accepts or rejects the whole batch.
+- `get/4` and `get_detached/4` take `(model, event_source_id, event_stream_type, event_stream_id)` to guard one named stream. The default stream (`""` or `"All"`) is refused with `:all_streams_not_supported`.
+
+## Admission
+
+`DecisionReads.admit/2` and `admit_for_stream/2` check a model's shape without any I/O and return `{:ok, event_types}` or `{:error, reason}`. `get` and `get_detached` **raise** `Chronicle.ReadModels.DecisionReadRefused` for a refused shape, because that is a programming error. Refusal reasons: `:reducer` (an active reducer), `:join`, `:hierarchy` (`children/2`), `:not_event_log`, `:open_ended_event_types` (`from_every/1`), `:no_event_types`, `:not_event_source_keyed`, `:unsupported_event_type_id`, `:all_streams_not_supported`, `:stream_scope_not_supported`, `:fold_incomplete`.
+
+A model with `join/2`, `removed_with_join/2`, `children/2` or `from_every/1` cannot be guarded. A **passive** reducer (`use Chronicle.Reducers.Reducer, model: M, active: false`) can back a decision read because it is folded fresh on the client; an active reducer cannot.
+
+## Explicit concurrency scopes
+
+When a plain guard on the tail is enough, use `Chronicle.Events.ConcurrencyScope` (`:concurrency_scope` append option) instead of a read model.
+
+| Need | Builder |
+| --- | --- |
+| Guard at the current tail in one call | `{:ok, scope} = ConcurrencyScope.at_tail("account-1", event_stream_type: "Transactions")`; narrowing options: `:event_stream_type`, `:event_stream_id`, `:event_source_type`, `:event_types` |
+| "This can only happen once" | `ConcurrencyScope.expecting_no_matching_event(event_source_id: true, event_types: [MyApp.Events.UserRegistered])` |
+| Build by hand | `12 \|> ConcurrencyScope.new() \|> with_event_source() \|> with_event_stream_type("Transactions") \|> with_event_type(Mod)`; also `with_sequence_number/2`, `with_event_stream_id/2`, `with_event_source_type/2`, `with_event_types/2` |
+| No guard | `ConcurrencyScope.none()` |
+
+**Leaving the expected sequence number unset turns the check off.** It does not mean "expect no event"; use `expecting_no_matching_event/1`, which sends the kernel's explicit condition (requires 3.11.0).
+
+## Default optimistic strategy
+
+```elixir
+{Chronicle.Client, ..., concurrency: [default: :optimistic, check_first_append: false]}
+```
+
+By default an append with no explicit or definition-derived scope sends no guard. With `default: :optimistic` the client reads the tail, narrowed the way the append is routed, and expects nothing newer. `check_first_append: true` also guards the first append into an empty narrowing with `expecting_no_matching_event/1`. An explicit or definition-derived scope always wins.
+
+Two **unequal** explicit scopes for one event source id in one batch or unit of work fail before sending with `{:error, {:duplicate_concurrency_scope, event_source_id}}`; equal scopes collapse to one.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/discovery-and-generations.md

@@ -0,0 +1,56 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Discovery, artifact identity and event generations
+
+Source: `Cratis/Chronicle.Elixir`: `Source/chronicle/lib/chronicle/discovery/`, `artifacts.ex`, `client.ex`, `events/event_type.ex`, `events/event_types.ex`, `reactors/reactor.ex`, `reducers/reducer.ex`, `lib/mix/tasks/chronicle.discover.ex`, and `Documentation/discovery.md`, `events.md`, `reactors.md`, `reducers.md`.
+
+Requires `cratis_chronicle` 3.13.0.
+
+## The discovery report
+
+`Chronicle.Client` builds a `%Chronicle.Discovery.Report{}` at start, logs a one-line summary at `:info` and the whole report at `:debug`. Read it with `Chronicle.Client.discovery_report()` and print it with `Chronicle.Discovery.Report.format/1`. `Chronicle.Artifacts.report(:my_app)` builds the same report without starting a client; `Chronicle.Artifacts.discover/1` still returns its plain map.
+
+Run it from the shell with `mix chronicle.discover --otp-app my_app`; add `--connection-string "chronicle://..."` to compare against a kernel (event store `"default"`, namespace `"Default"`) and `--fail-on-drift` to exit `1` on a warning-severity finding. Exit codes: `0` clean, `1` drift found, `2` could not run (no `--otp-app`, or kernel unreachable). `--fail-on-drift` has no effect without `--connection-string`.
+
+## Pin ids that default to a module name
+
+A reactor, reducer or declarative projection with no `:id` defaults it from its module name (reactors and reducers: the full module name; projections: the last segment). **Renaming or moving the module then creates a different artifact and silently resets its observation position.** Pin it:
+
+```elixir
+use Chronicle.Reactors.Reactor, id: "notification-reactor"
+use Chronicle.Projections.Projection, id: "account-summary", model: MyApp.ReadModels.AccountSummary
+```
+
+Discovery logs a warning once per module per BEAM node for a defaulted id. `warn_defaulted_ids: false` on `Chronicle.Client` suppresses it; prefer pinning. In-memory test clients skip it.
+
+## Drift policy
+
+Before registering, the client compares what it would register with the kernel. The `:drift_policy` client option:
+
+| Value | Behavior |
+| --- | --- |
+| `:warn` (default) | Log findings and register anyway |
+| `:fail` | Log findings and refuse to register on a `:warning`-severity finding |
+| `:ignore` | Skip the check and its kernel calls |
+
+Findings: `:schema_changed_without_generation` (an event type generation's coarse shape changed: added, removed or retyped field), `:observer_missing_from_code` (always `:info`, never blocks: other clients may own the observer), `:observer_event_types_changed` (a reactor's handled types differ; `:warning`). An indeterminate check (kernel unreachable, exception, 5 s deadline) continues under `:warn` and stops under `:fail`. Read the current findings with `Chronicle.Client.identity_drift()`. The kernel rejects a schema change without a bumped generation itself, regardless of policy.
+
+## Event type generations
+
+A module for an **older** generation uses `generation_for:` instead of its own `:id`, so the ids cannot drift apart:
+
+```elixir
+defmodule MyApp.Events.CustomerRegisteredV1 do
+  use Chronicle.Events.EventType, generation_for: MyApp.Events.CustomerRegistered, generation: 1
+  defstruct customer_id: "", owner_name: ""
+end
+```
+
+`generation_for:` requires an explicit `generation:` and cannot be combined with `:id`. Bridge the generations with `Chronicle.Events.Migration` (exactly one migrator per pair).
+
+Mistakes such as two modules for one id and generation, two migrators for a pair, or `generation_for:` naming a module that is not an event type are logged and the client continues. Set `strict_validation: true` on `Chronicle.Client` to raise instead; `Chronicle.Events.EventTypes.validate/2` returns `:ok | {:error, exception}` and `validate!/2` raises.
+
+## Pinned generation delivery
+
+By default (`:compatibility`) every event is upgraded to the generation of the module a reactor or reducer handles. For a handler written against an **older** generation, `use Chronicle.Reactors.Reactor, generation_delivery: :pinned` (or the same on a reducer) delivers the event as appended. `context.appended_generation` reports the appended generation (`0` means unknown). The client-wide default is `event_generation_delivery: :pinned`; an artifact's own option wins. A pinned observer that handles two generations of one event type raises `Chronicle.Observers.MultipleGenerationsOfEventTypeInObserver` on start.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/event-sources.md

@@ -63,4 +63,4 @@ Without an explicit `:concurrency_scope`, the client reads the tail narrowed by
 
 The wire carries one scope per event source id. Guarded entries of that id must agree on dimensions and selected source type, stream type and stream id. Unguarded entries never suppress a later guarded entry. Incompatible derived guards fail before any tail read or append; use separate batches, or deliberately supply one explicit scope on an entry for that id.
 
-Reactor and reducer contexts expose `:event_source` as the registered name, or `nil` for events appended without a definition. Their other context keys differ; do not assume the reactor context shape for a reducer.
+Reactor and reducer contexts expose `:event_source` as the registered name, or `nil` for events appended without a definition. Only reactor contexts carry `:delivery_id`.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/idioms-and-inspection.md

@@ -25,8 +25,8 @@ client-side. Observer types include `:reactor`, `:projection`, `:reducer`,
 - **Discovery is compile-time reflection.** The `use` macros generate
   `__chronicle_*__/1` functions via `__before_compile__`, and discovery is
   `function_exported?/3` over the application's modules — not runtime scanning.
-- **No client-owned telemetry events.** `telemetry` is a direct dependency;
-  transport failure detection subscribes to grpc events. Logging is `Logger`.
+- **Telemetry is built in.** The client emits OpenTelemetry spans and `:telemetry`
+  events; read [observability.md](observability.md). Logging is `Logger`.
 - **No formatter export.** `.formatter.exs` declares no `locals_without_parens`
   for `from`, `join`, `removed_with`, `from_every`, `pii`, `subject`, `unique`, or
   `unique_event_type`, and there is no `import_deps: [:cratis_chronicle]` to

package/package/corpus/skills/cratis-chronicle-client-elixir/references/observability.md

@@ -0,0 +1,37 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Observability: OpenTelemetry and `:telemetry`
+
+Source: `Cratis/Chronicle.Elixir`: `Source/chronicle/lib/chronicle/diagnostics/tracing.ex`, `connections/trace_propagation_interceptor.ex`, and `Documentation/observability.md`.
+
+Requires `cratis_chronicle` 3.13.0.
+
+The client is always instrumented and depends only on `opentelemetry_api`. With no OpenTelemetry SDK started in the release, every span and propagation call is a no-op and nothing leaves the process; there is no Chronicle-specific enable switch. To export, add `opentelemetry` and `opentelemetry_exporter` to the application and configure them the standard way (`OTEL_*` variables or `config :opentelemetry`).
+
+All spans use the instrumentation scope `Cratis.Chronicle.Client`, shared with the other Chronicle clients.
+
+| Span | Kind | Where |
+| --- | --- | --- |
+| `cratis.chronicle.client.event_sequence.append` | Client | `append/3`, `append_with_result/3` |
+| `cratis.chronicle.client.event_sequence.append_many` | Client | `append_many/3` variants, `append_many_for_event_sources/2`, unit-of-work commit |
+| `cratis.chronicle.client.reactor.handle` | Consumer | a reactor delivery |
+| `cratis.chronicle.client.reducer.reduce` | Consumer | a reducer delivery |
+
+Attributes: `cratis.event_store.name`, `cratis.event_store.namespace`, `cratis.event_sequence.id`, `cratis.event_type.id` (append spans), `cratis.event.count` (batches), `cratis.observer.id`, `cratis.correlation_id`. **`cratis.event_source.id` is off by default** because an event source id can be sensitive; enable it with `config :cratis_chronicle, trace_event_source_id: true`.
+
+A span is marked error when the operation returns `{:error, _}`, and a raised exception is recorded before re-raising. The status description is a fixed classification; messages, reasons and stacktraces are never put on a span because they can carry payloads.
+
+## `:telemetry` events
+
+For metrics built on `:telemetry`, the same operations emit spans of `:start`, `:stop` and `:exception` events:
+
+- `[:cratis, :chronicle, :client, :append, ...]`
+- `[:cratis, :chronicle, :client, :reactor, :handle, ...]`
+- `[:cratis, :chronicle, :client, :reducer, :reduce, ...]`
+
+The `:stop` metadata carries `error: true` when the operation returned `{:error, _}`. Observer lag is a separate event, `[:chronicle, :observer, :lag]`.
+
+## Trace propagation
+
+Every outbound gRPC call carries W3C `traceparent`/`tracestate` for the span active in the **calling process**, injected by `Chronicle.Connections.TracePropagationInterceptor` (always installed). A trace continues into the kernel only when the append or query runs inside the active span (for example inside `OpenTelemetry.Tracer.with_span/2`); a `Task` is a different process. The kernel does not store trace context on events, so an observer's span is not linked to the append that caused it. OpenTelemetry metrics instruments are not emitted, only `:telemetry` events.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/patterns.md

@@ -0,0 +1,22 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Behavior patterns
+
+Source: `Cratis/Chronicle.Elixir`: `Source/chronicle/lib/chronicle/patterns.ex` and `Documentation/patterns.md`.
+
+Requires `cratis_chronicle` 3.13.0.
+
+`Chronicle.Patterns` queries the recurring behavior (combinations of facets such as `Day`, `TimeBucket`, `CommandType`, `AggregateType`) that Chronicle mined from an event store's history for a scope, for example one user. **An empty result is an answer, not a failure**: the scope has no established behavior for that context. Treat it as "do not claim to know".
+
+```elixir
+{:ok, patterns} = Chronicle.Patterns.get_patterns_at("user-42")
+{:ok, patterns} = Chronicle.Patterns.get_patterns_at("user-42", moment, also_constraining: %{Chronicle.Patterns.FacetName.aggregate_type() => "Invoice"})
+action = pattern.facets[Chronicle.Patterns.FacetName.command_type()]
+```
+
+- Default to `get_patterns_at/3` ("what does this scope usually do now"). It derives `Day` and `TimeBucket` from the moment's **own offset**, not UTC, with the rule the kernel mined with; the moment defaults to now.
+- Use `get_patterns/3` and `get_usual_actions/3` only for a hand-built facet map; `get_usual_actions/3` returns at most one answer per action.
+- `get_patterns_for_scope/2` and `get_scopes/1` inspect what has been mined.
+- `Chronicle.Patterns.time_bucket/1` exposes the kernel's part-of-day rule (`:early_morning`, `:morning`, `:midday`, `:afternoon`, `:evening`, `:night`). **Never write a copy**: a slot the mining never used looks exactly like "nothing established".
+- Options on every call: `:client`, `:namespace`, `:minimum_confidence` (0.0 to 1.0) and `:max_results`. The all-patterns query is not exposed.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/pitfalls.md

@@ -16,10 +16,18 @@ Source: `Cratis/Chronicle.Elixir`.
 | Assuming the namespace default is `"default"` | It is `"Default"`; the moduledoc is wrong |
 | `:ok = Chronicle.append(...)` in a server | A constraint violation returns `{:error, _}` and raises `MatchError` |
 | Waiting for `:connected` | Observers attach at `:registered` |
-| Reading `:correlation_id` from a reactor context | The map has six keys and that is not one |
+| Reading `:correlation_id` or `:caused_by` from the context of an older client | It was a bare six-key map before the `EventContext` struct; see the upgrading reference |
 | Two read models with the same final module segment | The default id is the last segment only |
 | Appending from a `Task` and expecting the correlation id | Ambient context is per process |
 | Treating quiet observers as "no events" | Keepalive eviction can silence observers while appends still succeed |
 | Shipping the default TLS behavior | `skip_tls_validation` defaults to `true` |
 | Forgetting `global_handlers:` or `:otp_app` discovery | Shared mappings are not merged into variants unless registered |
 | A shared handler mapping a field one variant lacks | `GlobalHandlerPropertyNotOnVariant` at registration, not a silently skipped mapping |
+| `DecisionReads.get/2` outside `Chronicle.decide/2` | Returns `{:error, :requires_unit_of_work}`; it guards nothing |
+| Unset expected sequence number as "expect no event" | It disables the check; use `ConcurrencyScope.expecting_no_matching_event/1` |
+| Passing no `client: client` in a `Chronicle.Testing.Case` spec | The call addresses the default client, not the test's |
+| Trusting a spec that passed on the in-memory kernel | Queries, projections and `closes_stream` return `{:error, {:not_supported_in_memory, rpc}}`; use `Testing.Integration` |
+| Renaming a reactor, reducer or projection module without a pinned `:id` | Its observation position silently resets |
+| Capture event type ids with hyphens | `append/2,3` needs an uppercase-first, letters-digits-underscore id |
+| Nested `children/3` ids reused across read model instances | Nested events can land on the wrong instance; use UUIDs |
+| Reading a read model right after an append | `{:ok, nil}` means absent or not projected yet; use `Projections.wait_for/3` |

package/package/corpus/skills/cratis-chronicle-client-elixir/references/projections.md

@@ -50,3 +50,31 @@ from_every(increment: [event_counts: {:event_context, :type}])
 ```
 
 `decrement:` supports the corresponding dictionary operation. Use typed defaults for numeric and boolean fields on every model: schemas are generated from those defaults, not static Elixir types.
+
+## Child collections
+
+Requires `cratis_chronicle` 3.13.0 for the one-line form, `removed_with_join/2`, `clear_with/2` and the compile-time checks below; `children/2,3` itself requires 3.11.0.
+
+`children/2,3` declares a list on the parent that grows, changes and shrinks with events. It works in `use Chronicle.ReadModels.ReadModel` and `use Chronicle.Projections.Projection`; declare the list field's element type with `types: [items: {:list, MyApp.ReadModels.BasketItem}]`.
+
+```elixir
+children :items, identified_by: :item_id do
+  from MyApp.Events.ItemAdded,
+    key: :item_id,
+    parent_key: :event_source_id,
+    set: [item_id: :item_id, name: :name]
+
+  removed_with MyApp.Events.ItemRemoved, key: :item_id, parent_key: :event_source_id
+end
+```
+
+A collection that only grows from one event needs no block: `children :entries, from: MyApp.Events.EntryAdded, identified_by: :entry_id, key: :entry_id, set: [entry_id: :entry_id, name: :name]`.
+
+- Inside the block `from/2`, `join/2`, `removed_with/2`, `removed_with_join/2`, `clear_with/2`, `from_every/1` and a nested `children/3` take the options they take on the read model. `key` selects the child an event applies to; `parent_key` selects its parent.
+- A `join` in a children block defaults `:on` to `identified_by`; an explicit disagreeing `:on` compiles with a warning. A root `join/2` still requires `:on`.
+- `removed_with_join event, key: :archived_entry_id` removes a child when an event from a **different** event source matches it by property instead of the collection key.
+- `clear_with event, [:field]` (or `clear: [:field]` in a mapping) sets a scalar back to no value. The field must default to `nil`; a field defaulting to `""` is not nullable to the kernel, so clearing writes the type default.
+- **Give nested child collections globally unique identifiers (UUIDs).** In a nested `children/3`, `parent_key` names a child of the collection one level up, and the kernel finds it across every instance of the read model; two instances that both hold `"e-1"` can receive each other's nested events.
+- Compile-time errors cover a `children` without `:identified_by`, a root `join/2` without `:on`, one target property assigned twice by one event, and a `from`/`join` target or `children` name that is not a struct field.
+
+A read model document is limited to 4 MiB; give a child collection that can grow without bound its own read model.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/read-models.md

@@ -0,0 +1,41 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Querying, observing and previewing read models
+
+Source: `Cratis/Chronicle.Elixir`: `Source/chronicle/lib/chronicle/read_models.ex`, `read_models/watchers.ex`, `read_models/reactor.ex`, `projections.ex`, and `Documentation/read-models.md`, `projections.md`.
+
+Requires `cratis_chronicle` 3.13.0 for everything below except `watch/2`.
+
+A read model is eventually consistent: `Chronicle.read_model/3` returns `{:ok, nil}` both for an absent key and for one not projected yet. To read your own write, append with `append_and_wait_for_completion/3` or call `Chronicle.Projections.wait_for/3`.
+
+## Wait for a projection
+
+```elixir
+{:ok, %{sequence_number: sequence}} = Chronicle.EventSequences.EventLog.append_with_result(id, event)
+:ok = Chronicle.Projections.wait_for(MyApp.ReadModels.Account, sequence)
+```
+
+`wait_for/3` polls until the projection has handled that sequence number or returns `{:error, :timeout}`.
+
+## Filter and sort
+
+`Chronicle.ReadModels.query/2` accepts `:filter` (all conditions must match; a value means equality, or `{:gt, v}`, `{:gte, v}`, `{:lt, v}`, `{:lte, v}`, `{:ne, v}`, `{:in, [v]}`, `{:contains, v}`) and `:sort` (`{:amount, :desc}`). An unknown field returns `{:error, {:unknown_field, field}}`.
+
+**The client applies the filter** by paging through the whole read model, because the kernel contract cannot filter. A read model with more than `:max_scan` instances (default `10_000`) returns `{:error, {:scan_limit_exceeded, max_scan}}` rather than a partial answer. For large data, give the question its own projection.
+
+## Live changes: pick by what you need
+
+| Need | Function | Messages the process receives |
+| --- | --- | --- |
+| Changes to a read model, one stream per caller | `watch/2` / `unwatch/1` | `{:chronicle_read_model_changed, module, %Changeset{}}`, `{:chronicle_read_model_watch_error, module, reason}` (the watch has ended; call again) |
+| Same, shared across callers (default) | `subscribe/2` / `unsubscribe/1` | the two above plus `{:chronicle_read_model_watch_ended, module, reason}` and `{:chronicle_read_model_watch_resumed, module}` |
+| The current page of instances, re-sent on change | `observe/2` / `unobserve/1`, or `observe_stream/2` as an Elixir `Stream` of `%QueryResult{}` | `{:chronicle_read_model_instances, module, %{instances: _}}`, `{:chronicle_read_model_observe_error, module, reason}` (observation ended) |
+
+`subscribe/2` shares one kernel stream per read model, client, namespace and event sequence and reconnects with backoff (500 ms doubling to 30 s). **Changes made while the stream was down are not replayed**; query again after `:chronicle_read_model_watch_resumed`. `observe/2` accepts `:page_size`, `:filter` and `:sort`; with a filter, `total_count` counts matches within the delivered page only.
+
+A `use Chronicle.ReadModels.Reactor, model: M` module reacts to read model changes through optional `on_added/2`, `on_modified/2` and `on_removed/2`, and is registered with the client's `:read_model_reactors` option. It subscribes through `subscribe/2` and re-subscribes after a reconnect.
+
+## Ad-hoc queries and previews
+
+`Chronicle.Projections.query/2` sends a Projection Declaration Language string to the kernel and returns the projected entries without registering a projection or defining a module; entries are plain maps unless `:read_model` is given. Bad syntax returns `{:error, {:invalid_declaration, [%{message:, line:, column:}]}}`. `Chronicle.Projections.preview/2` runs an **already registered** projection's declaration over the stored event sequence; previewing over events you supply is not possible.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/testing.md

@@ -0,0 +1,63 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Testing against an in-memory kernel
+
+Source: `Cratis/Chronicle.Elixir`: `Source/chronicle/lib/chronicle/testing.ex`, `testing/case.ex`, `testing/assertions.ex`, `testing/in_memory_kernel.ex`, `testing/integration.ex`, `testing/projections.ex`, and `Documentation/testing.md`.
+
+Requires `cratis_chronicle` 3.13.0. Earlier clients ship no `Chronicle.Testing` modules.
+
+## Default: `Chronicle.Testing.Case`
+
+Use the case template for ExUnit specs. It starts a real `Chronicle.Client` against `Chronicle.Testing.InMemoryKernel`, puts the client name in the test context as `:chronicle`, and stops it on exit. Every test gets a unique event store, so it is safe under `async: true`.
+
+```elixir
+# Copyright (c) Cratis. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+defmodule MyApp.AccountTest do
+  use Chronicle.Testing.Case,
+    event_types: [MyApp.Events.AccountOpened],
+    reducers: [MyApp.Reducers.AccountReducer]
+
+  import Chronicle.Testing.Assertions
+
+  test "opening an account appends AccountOpened", %{chronicle: client} do
+    :ok =
+      Chronicle.EventSequences.EventLog.append(
+        "account-1",
+        %MyApp.Events.AccountOpened{owner_name: "Alice"},
+        client: client
+      )
+
+    assert_appended(client, MyApp.Events.AccountOpened, event_source_id: "account-1")
+  end
+end
+```
+
+**Pass `client: client` on every call.** Without it the call addresses the default `Chronicle.Client` name, not the test's client.
+
+`start_supervised_client/1` (outside ExUnit templates; pair with `stop_supervised_client/1`) accepts `:event_types`, `:event_sources`, `:constraints` (standalone constraint modules), `:reactors`, `:reducers`, `:projections`, `:name`, `:event_store` and `:namespace`.
+
+## Waiting and reading
+
+An append returns once the event is committed; reactors and reducers run afterward in `Chronicle.Testing.Dispatcher`, synchronously after each committed append. Call `Chronicle.Testing.wait_for_observers(client)` before asserting on their effects; it is a sleep-free barrier that returns `{:error, failures}` when a reactor or reducer raised.
+
+- `Chronicle.Testing.read_model(client, ReducerModule, key)` reads the state a **reducer** built, keyed by event source id.
+- `Chronicle.Testing.appended_events(client, event_source_id)` returns decoded `Chronicle.Events.AppendedEvent` structs.
+
+## Assertions
+
+`assert_appended/3` and `refute_appended/3` take a matcher: an exact event struct (`==`), an event type module, or a one-arity predicate; options include `:event_source_id` and `:count`. `assert_constraint_violation(result, constraint_name \\ nil)` and `assert_concurrency_violation(result)` match the `{:error, {:constraint_violations, _}}` and `{:error, {:concurrency_violations, _}}` append results.
+
+## What the in-memory kernel does not model
+
+Appends, reads, the tail lookups, concurrency scopes (including `expecting_no_matching_event/1`), and `unique/2` and `unique_event_type/1` constraints are modeled. **Everything else returns `{:error, {:not_supported_in_memory, rpc}}`**: `closes_stream` constraints, `ReadModels` queries and `Projections` queries. A spec that passes against it proves client logic, not kernel behavior.
+
+`Chronicle.Testing.Projections.apply_event(ReadModel, instance_or_nil, event)` folds one event through the supported subset of a read model's declarations (`from/2` with `:set`, `:add`, `:subtract`, `:count`, `:increment`, `:decrement`, `:clear`, AutoMap, and `removed_with/2`). `join/2`, `children/2`, `from_every/1` and `removed_with_join/2` raise `Chronicle.Testing.UnsupportedProjectionOperation`; test those against a real kernel.
+
+## Real kernel: `Chronicle.Testing.Integration`
+
+Tag these specs `@moduletag :integration`. `Chronicle.Testing.Integration.setup_isolated_client(opts, client \\ Chronicle.Client)` starts a real client with a unique event store and namespace, reading `CHRONICLE_INTEGRATION_CONNECTION_STRING` unless `:connection_string` is given, and waits for registration. Use `append_with_result/3` then `Integration.wait_for_observers(result.sequence_number, client: client)`; do not sleep. The stores it creates are not deleted afterward because the kernel has no delete call.
+
+`Chronicle` adopts `Chronicle.Behaviour`, so code that only needs to be observed calling the facade can use a Mox mock (`Mox.defmock(Mock, for: Chronicle.Behaviour)`); Mox is not a dependency of the client.

package/package/corpus/skills/cratis-chronicle-client-elixir/references/upgrading.md

@@ -32,3 +32,21 @@ Rejected appends (including concurrency/constraint failures) return `{:error, re
 Declared `unique(..., message: ...)` violation messages are preserved on single, batch and transactional appends. Retain the constraint name and diagnostics when handling violations rather than assuming every message came from the kernel.
 
 Requires `cratis_chronicle` 3.10.0 and Chronicle kernel 19.30.0 for named event source definitions.
+
+## Behavior changes to review when raising the requirement
+
+Requires `cratis_chronicle` 3.13.0 for the behaviors below; each is a difference an older application can observe.
+
+| Behavior | Review |
+| --- | --- |
+| Reactor and reducer `context` is a `Chronicle.Events.EventContext` struct | Pattern matches on a bare map keep working; `correlation_id`, `caused_by`, `causation`, `tags`, `subject`, `appended_generation` and `replaying?` are now present |
+| `drift_policy` defaults to `:warn` | Start-up makes extra kernel calls and logs findings; set `:ignore` to skip them, `:fail` to block on a drift warning |
+| Discovery warns once per module for a reactor, reducer or projection with no pinned `:id` | Pin ids before renaming or moving modules; see [discovery-and-generations.md](discovery-and-generations.md) |
+| Appending a struct that is not an event type returns `{:error, {:unknown_event_type, module}}` | Handle it as an ordinary append error |
+| Spans and `:telemetry` events are always emitted | No action without an SDK; see [observability.md](observability.md) |
+| The client installs a Logger filter for Mint response crash reports | Keep your own production filter for the remaining crash shapes |
+| `children/2,3` and projection mistakes are rejected at compile time | Fix declarations that assigned one target twice or named a missing field |
+
+Requires `cratis_chronicle` 3.11.0 for the context struct; it was a bare map before.
+
+Capabilities covered by these references: decision reads ([decision-reads.md](decision-reads.md)), `Chronicle.Testing` ([testing.md](testing.md)), captures ([captures.md](captures.md)), standalone constraints ([constraints.md](constraints.md)), `Chronicle.Patterns` ([patterns.md](patterns.md)) and read model subscriptions ([read-models.md](read-models.md)). A git tag is not a Hex release: confirm the version is on hex.pm before depending on it.

package/package/corpus/skills/cratis-chronicle-client-elixir/verification.json

@@ -4,12 +4,12 @@
   "fixtures": [],
   "assertions": [
     { "kind": "skill-contains", "value": "`Cratis/Chronicle.Elixir`" },
-    { "kind": "skill-contains", "value": "{:cratis_chronicle, \"~> 3.10\"}" },
+    { "kind": "skill-contains", "value": "{:cratis_chronicle, \"~> 3.13\"}" },
     { "kind": "skill-contains", "value": "ConnectionString.development()" },
     { "kind": "skill-contains", "value": "`~> 1.18`" },
     { "kind": "skill-contains", "value": "`nil` registers as string" },
-    { "kind": "skill-contains", "value": "**The reactor context has six keys**" },
-    { "kind": "skill-contains", "value": "`sequence_number`, `occurred`, `event_source`, `observation_state`" },
+    { "kind": "skill-contains", "value": "**The context is a `Chronicle.Events.EventContext` struct**" },
+    { "kind": "skill-contains", "value": "`delivery_id` (stable across replay and failed-partition" },
     { "kind": "skill-contains", "value": "**Page 1 is the second page**" },
     { "kind": "skill-contains", "value": "`:retry_attempts` is accepted but ignored", "file": "references/connections.md" },
     { "kind": "skill-contains", "value": "Client certificates cannot be combined with `disableTls=true`", "file": "references/connections.md" },
@@ -18,6 +18,19 @@
     { "kind": "skill-contains", "value": "`Chronicle.Events.ConcurrencyScope.none()`", "file": "references/event-sources.md" },
     { "kind": "skill-contains", "value": "**no many-event variant**", "file": "references/append-api.md" },
     { "kind": "skill-contains", "value": "`subject/1` is not imported by `EventType`", "file": "references/compliance.md" },
-    { "kind": "skill-contains", "value": "calendar year, not the ISO week-year", "file": "references/projections.md" }
+    { "kind": "skill-contains", "value": "calendar year, not the ISO week-year", "file": "references/projections.md" },
+    { "kind": "skill-contains", "value": "Outside one it returns `{:error, :requires_unit_of_work}`", "file": "references/decision-reads.md" },
+    { "kind": "skill-contains", "value": "**Leaving the expected sequence number unset turns the check off.**", "file": "references/decision-reads.md" },
+    { "kind": "skill-contains", "value": "**Everything else returns `{:error, {:not_supported_in_memory, rpc}}`**", "file": "references/testing.md" },
+    { "kind": "skill-contains", "value": "**Pass `client: client` on every call.**", "file": "references/testing.md" },
+    { "kind": "skill-contains", "value": "`name:` is **required** on a standalone declaration.", "file": "references/constraints.md" },
+    { "kind": "skill-contains", "value": "**Renaming or moving the module then creates a different artifact", "file": "references/discovery-and-generations.md" },
+    { "kind": "skill-contains", "value": "`mix chronicle.discover --otp-app my_app`", "file": "references/discovery-and-generations.md" },
+    { "kind": "skill-contains", "value": "**An appended event type's id must start with an uppercase letter", "file": "references/captures.md" },
+    { "kind": "skill-contains", "value": "**Give nested child collections globally unique identifiers (UUIDs).**", "file": "references/projections.md" },
+    { "kind": "skill-contains", "value": "**The client applies the filter**", "file": "references/read-models.md" },
+    { "kind": "skill-contains", "value": "**`cratis.event_source.id` is off by default**", "file": "references/observability.md" },
+    { "kind": "skill-contains", "value": "**An empty result is an answer, not a failure**", "file": "references/patterns.md" },
+    { "kind": "skill-contains", "value": "`{:error, {:unknown_event_type, module}}`", "file": "references/append-api.md" }
   ]
 }

package/package.json

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