@cratis/pi 7.56.2 → 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

@@ -63,9 +63,9 @@
         }
       ],
       "synced": {
-        "version": "22.97.0",
-        "date": "2026-10-14",
-        "by": "Cratis/AI#695"
+        "version": "22.100.0",
+        "date": "2026-10-15",
+        "by": "Cratis/AI#710"
       },
       "covers": {
         "skills": [
@@ -98,7 +98,7 @@
           "vertical-slices.md"
         ]
       },
-      "notes": "Release-tag delta through 22.97.0: scoped completion and routing validation, generated-target freshness, observable scenarios, asynchronous execution scopes, read-model diagnostics and ordered reactor refusal handling. Existing context generation/self-reduction guidance retained; Screenplay extraction deltas handed to its owning lane. No new runtime probe."
+      "notes": "Release-tag delta through 22.100.0: scoped completion and routing validation, generated-target freshness (including direct unit-of-work writes and nested commands), observable scenarios, asynchronous execution scopes, read-model diagnostics, ordered reactor refusal handling and ICommandExceptionMapper. Existing context generation/self-reduction guidance retained; Screenplay extraction deltas handed to its owning lane. No new runtime probe."
     },
     {
       "id": "ai",
@@ -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-arc-command/SKILL.md

@@ -246,7 +246,7 @@ whatever renders it:
 
 Read [references/client-contract.md](references/client-contract.md) for the generated proxy members.
 
-Read `references/command-result.md` when branching on a command result or matching validation failures to fields. Branch on the specific flag, not only on `isSuccess`. The exact `CommandResult`
+Read `references/command-result.md` when branching on a command result, matching validation failures to fields, or mapping integration exceptions. Branch on the specific flag, not only on `isSuccess`. The exact `CommandResult`
 and `ValidationResult` shapes are in
 [command result](references/command-result.md) — in particular, a validation
 failure carries `members: string[]` (camelCased) and a numeric `severity`, not a

package/package/corpus/skills/cratis-arc-command/references/command-result.md

@@ -3,6 +3,7 @@
 ## Contents
 
 - Server side
+- Map integration exceptions
 - Severity filtering
 - Client side
 - Executing with a severity
@@ -40,6 +41,34 @@ every execution scope has completed and the result is not successful, so a
 transaction that rolls back after `Handle` returned a value does not leak that
 value into the error body.
 
+## Map integration exceptions
+
+Requires Arc 22.100.0 or later for `Cratis.Arc.Commands.ICommandExceptionMapper`.
+Check `dotnet list package --include-transitive`; older Arc has no mapper hook
+and uses `CommandResult.FromException` for unhandled execution exceptions.
+
+Implement the interface for an integration's typed failures, not ordinary
+user-correctable rejections (return validation results for those):
+
+```csharp
+bool TryMap(CommandContext context, Exception exception,
+    [NotNullWhen(true)] out CommandResult? result);
+```
+
+`NotNullWhen` is from `System.Diagnostics.CodeAnalysis`. Return `true` with a
+non-null **failure** preserving `context.CorrelationId`, or `false` with `null`
+to decline. Match exception types/properties rather than parsing messages.
+Implementations are convention-discovered through `IInstancesOf<ICommandExceptionMapper>`
+(`Cratis.Types`) and resolved from the command's service scope. The first accepting
+mapper wins. Mapping runs for exceptions escaping command execution or response
+processing, before execution scopes complete, so a mapped failure still rolls
+back pending work. If no mapper accepts, the pipeline falls back to
+`CommandResult.FromException`; a throwing mapper produces `CommandResult.Error`
+and scopes still complete with
+failure. This hook does not replace validation-only or scope-completion exception
+handling. Specify accepting, declining and throwing cases and assert rollback
+and correlation preservation, not only the message.
+
 ## Severity filtering
 
 `ValidationResultSeverity`: `Unknown = 0`, `Information = 1`, `Warning = 2`,

package/package/corpus/skills/cratis-arc-command/references/fresh-identifiers.md

@@ -3,6 +3,12 @@
 
 # Fresh generated append targets
 
+## Contents
+
+- Direct writes and nested commands
+- Opt out deliberately
+- Specify the collision
+
 Requires Arc 22.95.0 and Chronicle client 19.59.4 for guarded generated targets; deploy a Chronicle kernel 19.40.1 or later for retry-time emptiness checks. Check package references and the deployed kernel version before relying on the guard; older Arc needs an explicit whole-source `BeforeFirst` scope.
 
 A `[GeneratedValue]` parameter defaults to `GeneratedValueFreshness.Guarded`.
@@ -10,9 +16,12 @@ When an Arc-owned append targets a validated value generated in that invocation,
 it requires the **whole event source** to be empty, including other streams and
 event types. Payload-only and response-only generated values add no scope.
 Returned events, tuples, wrappers, `EventsWithConcurrencyScopes` and aggregates
-acquired for that generated identifier are covered. Direct `IUnitOfWork.AddEvent`,
-`AddEvents` and `eventLog.Transactional.Append` calls are not: return events
-through Arc or supply the exact emptiness scope explicitly.
+acquired for that generated identifier are covered.
+
+Requires Arc 22.100.0 or later and Chronicle client 19.65.2 or later for direct
+unit-of-work writes and redacted enrollment-conflict translation. Check resolved
+versions with `dotnet list package --include-transitive`; older Arc needs returned
+events or an explicit whole-source `BeforeFirst` scope for direct writes.
 
 An occupied destination returns `ValidationResultReason.ConcurrencyViolation`
 with `ReasonDetail` `GeneratedIdentifierCollision`. Arc does not rerun `Handle()`.
@@ -25,6 +34,56 @@ explicit scope, including `ConcurrencyScope.None` or a narrowed scope, fails wit
 generated source's returned events contiguous; an interleaved shape that would
 split its guard fails with `GeneratedIdentifierEventsCannotBeSplit`.
 
+## Direct writes and nested commands
+
+The same guard covers these writes on the **command's actual unit of work**:
+
+- `IUnitOfWork.AddEvent`, `AddEventWithNamedTags` and `AddEvents`.
+- `eventLog.Transactional.Append`, `AppendMany`, `AppendWithNamedTags` and
+  `AppendManyWithNamedTags`.
+
+Returned, aggregate and direct events share one whole-source expectation. An
+occupied generated destination rejects the whole pending unit, including events
+for other sources, with the collision result above. Arbitrary new units and
+external stores are outside this protection.
+
+Nested pipeline invocations share the outer unit and leave completion to its
+owner. Guarded captures from every active invocation participate, so a nested
+handler's attribute-derived scope cannot narrow an outer generated guard.
+Propagate nested rejection so the outer command rolls back earlier events.
+An explicit aggregate `Commit()` can still complete the shared unit early.
+
+After enrollment, the required scope survives disposal of the invocation's
+contributor; later unscoped writes inherit it. An incompatible supplied scope
+against that recorded generated guard maps to `ConflictingConcurrencyScopes`,
+even if Chronicle rejects it before invoking contributors. Neither collision nor
+scope-conflict messages expose the identifier or scope values. Arc uses typed
+scope properties and recorded guard provenance, not message parsing; unrelated
+enrollment conflicts retain Chronicle's redacted `ConflictingEnrollmentScope`.
+Scope-only `AddEvents` entries preserve existing requirements but do not invoke
+contributors or establish a new generated guard. A completed nested invocation's
+untargeted capture leaves no enrolled requirement.
+
+Custom units must support enrollment contributors. A guarded generated parameter
+fails closed with `FreshIdentifierGuardRequiresEnrollmentContributors` if the unit
+cannot register one; no generated parameters or only `Unguarded` parameters do not
+require that support.
+
+`AddEvents` checks all destinations before staging that call; a scope conflict
+stages none of its events. Transactional `AppendMany` and
+`AppendManyWithNamedTags` stage per event, so a later rejection can leave earlier
+events pending. Let the exception escape `Handle()` to roll back the unit;
+catching it and succeeding can commit those earlier events.
+
+Immediate `eventLog.Append`, `AppendMany` and their named-tag variants bypass
+enrollment, cannot be rolled back and receive **no automatic freshness guard**.
+Prefer returning events. An integration needing direct writes must use the
+command's transactional unit; an immediate caller needs an explicit whole-source
+`BeforeFirst` scope and must inspect the append result, without automatic
+`GeneratedIdentifierCollision` classification.
+
+## Opt out deliberately
+
 Only when appending to an existing generated destination is intentional, use this
 parameter attribute fragment (imports `Cratis.Arc.Commands.ModelBound` and
 `Cratis.Arc.Commands`):
@@ -42,8 +101,9 @@ use an appropriate constraint or explicit concurrency scope for them.
 Use `new CommandScenario<TCommand>().UseDecisionReads()` **before seeding**, then
 `PinGeneratedValue(name, id)` and `Given.ForEventSource(id).Events(existingEvent)`.
 Assert the concurrency reason and collision detail, unchanged append tail and
-one handler execution. Also cover an empty source receiving two events and an
-occupied source whose events belong to another stream.
+one handler execution. Also cover an empty source receiving two events through
+the chosen write API, an occupied source whose events belong to another stream,
+mixed returned/direct writes, and a nested rejection rolling back the outer unit.
 
 Requires Arc 22.95.1 for `GeneratedIdentifierCollisionRequiresDecisionReads`:
 default scenario mode fails fast when given events and a guarded pin share an id.

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.