@cratis/pi 7.34.1 → 7.36.0

package/package/corpus/skills/cratis-chronicle-client-elixir/references/connections.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. -->
+
+# Connections, trust and resilience
+
+Verified at `Cratis/Chronicle.Elixir v3.10.2`: `Source/chronicle/lib/chronicle/connections/{connection_string,connection,keep_alive,client_certificate,transport}.ex`, `registration/coordinator.ex`, and `Documentation/connections/{connection-strings,resilience,crash-reports}.md`.
+
+## Connection strings and authentication
+
+`Chronicle.Connections.ConnectionString` accepts `chronicle://` and `chronicle+srv://`; the default port is `35000`. Multiple comma-separated hosts are resolved again on reconnect; SRV accepts only one host (`connection_string.ex:198-199`).
+
+| Function | Line in `connection_string.ex` |
+| --- | --- |
+| `default/0` — localhost, **no credentials** | `:145` |
+| `development/0` — well-known local development credentials | `:155` |
+| `parse/1` | `:187` |
+
+Use `development/0` only for a local kernel configured to accept the well-known credentials, never for a shared or production kernel. A bare default connection does not substitute credentials; an authentication-required development kernel drops its session (`:stream_ended`) and it never registers.
+
+Production authentication is URL userinfo `client-id:client-secret@host` (OAuth token exchange and refresh) or the `apiKey` query parameter (an `api-key` header). The API key wins when both are present. URL-encode reserved characters; write literal `+` as `%2B` because userinfo uses form decoding. Obtain values from the application's approved secret mechanism.
+
+Query parameters: `apiKey`, `disableTls`, `skipTlsValidation`, `certificatePath`, `certificatePassword`, `authPort`, `loadBalancer`, `srvNameServer`. `loadBalancer` accepts `least-connections`, `round-robin`, `random`.
+
+## Server trust and client certificates
+
+`skip_tls_validation` defaults to **true** in both the struct and parser (`connection_string.ex:113,215`). TLS encrypts traffic but does not authenticate the server with that default. Set `skipTlsValidation=false` outside local development. `disableTls` is only for a TLS-terminating proxy; the kernel itself serves TLS.
+
+Since 3.7.0, `certificatePath` accepts PKCS#12 (`.p12`/`.pfx`) or PEM containing a certificate and matching private key. `certificatePassword` unlocks protected files. The identity is presented to both gRPC and the OAuth token endpoint; invalid files, wrong passwords or mismatched keys fail startup. PKCS#12 loading needs `openssl`. Client certificates cannot be combined with `disableTls=true`.
+
+**A client certificate does not trust the server.** With a client certificate, put custom server-verification options on `GRPC.Credential` passed as `:cred` through `:grpc_options`, not in adapter-level `:transport_opts`. For example, this option excerpt assumes `trusted_der` is an approved DER-encoded CA certificate:
+
+```elixir
+grpc_options: [
+  cred: GRPC.Credential.new(ssl: [verify: :verify_peer, cacerts: [trusted_der]])
+]
+```
+
+This credential configures the **gRPC channel only**; OAuth server verification still follows `skipTlsValidation` and the system trust store. Install the CA in that trust store when client credentials need it. Conflicting identity or adapter-level verification overrides are rejected at startup.
+
+Since 3.8.0 the client uses grpc 1.x and Mint 1.11+, owns its transport, and needs no `GRPC.Client.Supervisor`. If the application calls `GRPC.Stub.connect/2` independently, specify `adapter: GRPC.Client.Adapters.Mint` there too (or explicitly depend on Gun). Application-level Mint `client_settings` must retain `enable_push: false`; grpc replaces rather than merges those settings and the client rejects unsafe overrides.
+
+## 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 versioned [client crash-report guide](https://github.com/Cratis/Chronicle.Elixir/blob/v3.10.2/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.
+
+## Keepalive and readiness
+
+The kernel sends keepalive once a second; the client answers via a separate unary RPC (`keep_alive.ex:7-17,56`). Merely consuming the stream is insufficient. Kernel eviction after five seconds without an answer can silence reactors/reducers while appends continue working. Diagnose the connection when observers go quiet rather than assuming there are no events.
+
+`:connected` means the first keepalive acknowledged the connection id, not that artifacts registered. Failed registration logs `Chronicle registration failed`, stays `:connected`, and retries every five seconds. Wait for `:registered` before claiming readiness.
+
+Reconnect uses exponential backoff (1000 ms base, 10000 ms cap); `:retry_attempts` is accepted but ignored. Appends do not wait or queue during an outage: before a channel exists they return `{:error, :not_connected}`. Read model queries wait up to 30 seconds for registration. Transport failures return `{:error, %GRPC.RPCError{}}`; a timeout does not prove a write was not stored.
+
+Seeders run after `:registered`, again on reconnect, and skip an event source with existing events (`seeding/runner.ex`, `seeding.ex`). Since 3.5.1 this avoids startup duplicates; it does not remove duplicates already stored by 3.5.0.

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

@@ -0,0 +1,64 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Event sources and streams
+
+Verified at `Cratis/Chronicle.Elixir v3.10.2`: `Source/chronicle/lib/chronicle/event_sources/event_source.ex`, `event_sources/routing.ex`, `event_sequences/definition_routing.ex`, and `Documentation/event-sources.md`. Definitions require **Chronicle 19.30.0+**.
+
+An event source definition gives appends a stable name, optional streams and default concurrency dimensions. It belongs to the append, not the event type; the same event type can go through different definitions. Appends without a definition keep their existing routing and have no registered-source metadata.
+
+```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.AccountEventSource do
+  use Chronicle.EventSources.EventSource,
+    name: "Account",
+    description: "A bank account",
+    concurrency: [:event_source_id]
+
+  stream("Transactions",
+    description: "Money movements",
+    concurrency: [:event_source_id, :event_stream_id]
+  )
+end
+```
+
+`:name` defaults to the last module segment without a trailing `EventSource`. Dimensions are `:event_source_id`, `:event_source_type`, `:event_stream_type`, `:event_stream_id`. A stream with no dimensions inherits its source's dimensions. Duplicate stream names fail compilation; duplicate source names raise `Chronicle.EventSources.DuplicateEventSourceName` at client startup.
+
+## Register and append
+
+Set `otp_app:` so discovery finds the definition, or pass `event_sources: [MyApp.AccountEventSource]` to `Chronicle.Client`. Definitions register after event types and before observers on every reconnect. Registration is an upsert; omitting a definition later does not delete it from the kernel.
+
+With the client registered and the `MyApp.Events.FundsDeposited` event from the skill declared:
+
+```elixir
+case Chronicle.append("account-1", %MyApp.Events.FundsDeposited{amount: 50},
+       event_source: MyApp.AccountEventSource,
+       event_stream: "Transactions",
+       event_stream_id: "2024-05"
+     ) do
+  :ok -> :ok
+  {:error, reason} -> {:error, reason}
+end
+```
+
+The source name becomes the event source type and event `EventSource` metadata; the stream name becomes the event stream type. Sources can be modules or names. Without `:event_stream`, the stream type is `"All"`. `append_many/3` and units of work accept the same source/stream options.
+
+Each `Chronicle.EventSequences.EventForEventSourceId` can carry `event_source` and `event_stream`. In `append_many_for_event_sources/2`, entry-level routing wins; batch defaults fill only entries with no source. A routing rejection prevents the whole batch from being sent.
+
+| Reason inside `{:error, reason}` | Cause |
+| --- | --- |
+| `{:unknown_event_source, source}` | Source not registered with this client |
+| `{:event_stream_does_not_belong_to_event_source, source, stream}` | Stream not declared by that source |
+| `{:event_routing_contradicts_event_source, source, dimension, expected, actual}` | Explicit source/stream type contradicts the definition |
+| `{:event_stream_without_event_source, stream}` | Stream given without a source |
+| `{:incompatible_concurrency_scopes, id, guards}` | Derived guards disagree for one event source id in a batch |
+
+## Default concurrency is not an explicit decision guard
+
+Without an explicit `:concurrency_scope`, the client reads the tail narrowed by the effective definition dimensions and uses that sequence number as a scope. With no dimensions, it sends no scope. Explicit scopes, including `Chronicle.Events.ConcurrencyScope.none()`, win and avoid that read. Do not disable a guard just to silence a rejection; choose a scope that protects the business decision's reads.
+
+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.

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

@@ -0,0 +1,25 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Common pitfalls
+
+Verified at `Cratis/Chronicle.Elixir v3.10.2`; historical qualifications are intentional.
+
+| Pitfall | Why it bites |
+| --- | --- |
+| Copying the `v2.2.0` root README | Its module names do not exist; the `3.x` README is correct |
+| Using `Chronicle.Concept` on `2.2.0` | It ships from `3.0.0`; on `2.2.0` annotate fields with `pii/1,2` instead |
+| Combining `pii` and `encrypted` | The same leaf raises `PiiAndEncryptedCombinedNotSupported`; neither is allowed on an `event_source_id: true` concept |
+| Quoting the `VERSION` file | It is a `0.0.5` build-time placeholder |
+| Putting options only in `config.exs` | The client reads no application env; your app must pass child-spec keyword options |
+| Omitting `:otp_app` | Discovery falls back to scanning every loaded module |
+| 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 |
+| 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 |

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

@@ -0,0 +1,48 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Projection options and keys
+
+Verified at `Cratis/Chronicle.Elixir v3.10.2`: `Source/chronicle/lib/chronicle/read_models/read_model.ex:35-120,183-212,230-332`, `projections/projection.ex`, and `registration/coordinator.ex:735-746`.
+
+`use Chronicle.ReadModels.ReadModel` accepts `id:`, `passive: true`, `not_rewindable: true`, and `event_sequence: "sequence-name"`. Defaults are the last module segment as id, active, rewindable, and `"event-log"`. Standalone `Chronicle.Projections.Projection` also accepts sequence/rewindability options and requires `model:`.
+
+AutoMap maps matching event/model properties by default. `no_auto_map()` disables it for the whole projection; `no_auto_map([:balance, :status])` excludes only those properties so explicit mappings can own them.
+
+Since 3.5.1, multi-word atom references are encoded as camelCase correctly: `set: [owner_name: :owner_name]` is the supported shape. AutoMap also handles shared multi-word names; boolean/float constants work without a string workaround. `join/2` requires `:on`. `:count` increments the named field once per occurrence.
+
+## Composite keys and event context (since 3.9.0)
+
+This module excerpt assumes a registered `MyApp.Events.AccountOpened` event. The key names and part order are preserved:
+
+```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.ReadModels.WeeklyAccountOpenings do
+  use Chronicle.ReadModels.ReadModel
+  defstruct transaction_count: 0
+
+  from(MyApp.Events.AccountOpened,
+    key: {:composite, [
+      {"Year", {:event_context, "Occurred.Year"}},
+      {"Week", {:event_context, "Occurred.Week"}}
+    ]},
+    count: :transaction_count
+  )
+end
+```
+
+Composite parts accept event-field atoms, explicit expression strings and literals. They must form a nonempty ordered list of `{name, expression}` pairs; nested composites are not supported. Event-context paths contain letters, dots and parentheses and are passed unchanged. Keys also apply to `join` and `removed_with`.
+
+**`Occurred.Year` is the calendar year, not the ISO week-year.** Do not assume that pairing it with `Occurred.Week` gives an ISO week identity at a year boundary; settle the required business key first.
+
+## Dictionary counters (since 3.1.0)
+
+On a read model with `defstruct event_counts: %{}`, this excerpt increments one entry per event type:
+
+```elixir
+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.

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

@@ -0,0 +1,34 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Upgrading 2.x to 3.x
+
+Verified at `Cratis/Chronicle.Elixir v3.10.2`: `Source/chronicle/mix.exs`, `mix.lock`, `lib/chronicle/wire_result.ex`, `jobs.ex`, `event_sequences/event_log.ex`, `read_models.ex`, `seeding.ex`, and the release notes for 3.0.0, 3.2.0, 3.5.1 and 3.8.0.
+
+## Dependencies and wire compatibility
+
+3.0.0 migrated the wire contracts to Chronicle 17/18, renaming RPCs and unwrapping response envelopes. It removed no public Elixir API, but unauthorized/excepted command responses now return `{:error, reason}` rather than looking successful. `Jobs.get/2` lists jobs then finds the id client-side; `append_many_for_event_sources/2` uses its dedicated RPC rather than the single-source path.
+
+For **3.10.2**:
+
+- Use `{:cratis_chronicle, "~> 3.10"}` and Elixir **1.18+** (`mix.exs` requires `~> 1.18`).
+- grpc **1.x** and Mint **1.11+** are direct dependencies; do not carry a mandatory `GRPC.Client.Supervisor` child forward from an older grpc setup.
+- Contracts resolve to **19.30.0** in this tag's lockfile. Pair the kernel with the installed contracts descriptor; named event source definitions require **Chronicle 19.30.0+**.
+- The first append on each channel runs a compatibility check, shared until reconnect. `{:error, {:incompatible_server, response}}` is a version/descriptor problem, not a transient append rejection. Update kernel and contracts as a compatible pair; do not bypass the preflight. Failed transport calls return `{:error, %GRPC.RPCError{}}`.
+
+## Corrected behavior requires application review
+
+3.5.1 fixed behavior that older applications may have unintentionally relied on:
+
+| Change | Review before rollout |
+| --- | --- |
+| Reducers register successfully and process from the log start | Old events now reach reducers that previously failed registration |
+| Multi-word projection fields and AutoMap now populate | Remove camelCase-string workarounds; inspect fields that were formerly empty |
+| `unique(:owner_email)` and `remove_constraint` registration work | Uniqueness is now enforced and release events can remove constraints |
+| `ReadModels.query/2` is zero-based, default page 0 | Change first-page callers to `page: 0`; `page: 1` is now the second page |
+| Seeding skips an event source with existing events | 3.5.0 re-appended on every start; already-stored duplicates are not removed |
+| Tail/next sequence lookups no longer narrow implicitly to `"Default"` | Audit callers that depended on implicit routing narrowing |
+
+Since 3.2.0, rejected appends (including concurrency/constraint failures) return `{:error, reason}` instead of potentially returning `:ok`; batch append metadata survives the rich append RPC. Handle errors on single, batch and transactional paths.
+
+3.10.2 preserves declared `unique(..., message: ...)` violation messages on single, batch and transactional appends. Retain the constraint name and diagnostics when handling violations rather than assuming every message came from the kernel.

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

@@ -1,10 +1,18 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
 # Variants
 
 ## Variants — mutually exclusive read models for one entity's lifecycle
 
-> Requires `cratis_chronicle` `3.4.0` or later — newer than this skill's
-> `3.1.0` baseline (`lib/chronicle/projections/variant_reclassifier.ex` and
-> siblings). Reverify before claiming support; take the version from hex.pm.
+> Requires `cratis_chronicle` `3.4.0` or later. Verified at
+> `Cratis/Chronicle.Elixir v3.10.2` (`Source/chronicle/lib/chronicle/read_models/read_model.ex:280-300`,
+> `projections/global_handler.ex`, `projections/variant_reclassifier.ex`).
+>
+> The 3.4.0 release reported a kernel `$eventSourceId` property-mapping limitation
+> (Cratis/Chronicle#3924). This client-source verification does not establish
+> whether kernel 19.x fixed it; verify the full variant transition against your
+> kernel before claiming end-to-end support.
 
 Some entities do not have one shape for their whole lifetime — a work item is a
 backlog entry until a pull request exists for it, then it is a pull request
@@ -19,7 +27,7 @@ end
 
 defmodule MyApp.ReadModels.BacklogItem do
   use Chronicle.ReadModels.ReadModel
-  defstruct id: nil, title: nil
+  defstruct id: "", title: ""
 
   variant_of MyApp.ReadModels.WorkItem, key: :id
   enters_on MyApp.Events.IssueCreated
@@ -29,7 +37,7 @@ end
 
 defmodule MyApp.ReadModels.PullRequestItem do
   use Chronicle.ReadModels.ReadModel
-  defstruct id: nil, pull_request_url: nil, build_status: nil
+  defstruct id: "", title: "", pull_request_url: "", build_status: ""
 
   variant_of MyApp.ReadModels.WorkItem, key: :id
   enters_on MyApp.Events.PullRequestCreated

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

@@ -0,0 +1,23 @@
+{
+  "skill": "cratis-chronicle-client-elixir",
+  "input": "Connect an Elixir application, append through a registered event source, and query the first page of its read model.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "**`v3.10.2`**" },
+    { "kind": "skill-contains", "value": "{:cratis_chronicle, \"~> 3.10\"}" },
+    { "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": "**page 1 now means 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" },
+    { "kind": "skill-contains", "value": "registered-source metadata", "file": "references/event-sources.md" },
+    { "kind": "skill-contains", "value": "`{:incompatible_concurrency_scopes, id, guards}`", "file": "references/event-sources.md" },
+    { "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" }
+  ]
+}

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

@@ -0,0 +1,162 @@
+---
+name: cratis-chronicle-client-go
+description: Connect a standalone Go application to Chronicle, register events and observers, append with explicit outcomes, and materialize read models. Use for Chronicle.Go client setup, projections, reactors, gRPC ownership and safe retry decisions. Do not use for Arc HTTP commands or Chronicle kernel implementation.
+license: MIT
+compatibility: Go 1.26 or later; Chronicle.Go v0.9.1 with the Chronicle 19.32.3 kernel profile.
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Chronicle from Go
+
+> **Experimental v0:** Chronicle.Go **v0.9.1**, verified kernel profile
+> **Chronicle 19.32.3**. Companion guidance targets Arc.Go **v0.1.1** and
+> Fundamentals.Go **v0.3.2**. Minor releases may break APIs.
+
+This is a standalone event-store client, not an Arc HTTP framework. Use explicit
+registration rather than C# attributes or assembly discovery. Events are immutable
+facts represented by named structs; event-source identity is append metadata,
+not an event payload property.
+
+## Verified product sources
+
+| Product | Tag | Source checked |
+| --- | --- | --- |
+| Chronicle.Go (`github.com/cratis/chronicle.go`) | `v0.9.1` | `client.go`, `options.go`, `options_transport.go`, `registry.go`, `registry_projections.go`, `registry_readmodels.go`, `registry_reactors.go`, `eventsequences/sequence.go`, `internal/decision/decision.go`, `captures/service.go`, `captures/redaction.go`, `examples/getting-started/main.go`, `examples/projections/main.go` |
+
+[Source at v0.9.1](https://github.com/Cratis/Chronicle.Go/tree/v0.9.1)
+and its [parity ledger](https://github.com/Cratis/Chronicle.Go/blob/v0.9.1/Documentation/parity.md)
+qualify supported behavior. The README's older statement that observers,
+projections and automatic lifecycle recovery are absent is stale; those surfaces
+exist, but that does **not** mean whole-product parity.
+
+## Register and append
+
+Install `github.com/cratis/chronicle.go@v0.9.1` in a consumer module. This complete
+package appends one event using **local development** defaults:
+
+```go
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+package customers
+
+import (
+	"context"
+	"errors"
+
+	chronicle "github.com/cratis/chronicle.go"
+	"github.com/cratis/chronicle.go/events"
+)
+
+// CustomerRegistered records a customer's display name.
+type CustomerRegistered struct {
+	Name string `json:"name"`
+}
+
+// AppendCustomer uses a caller-bounded context and closes its owned client.
+func AppendCustomer(ctx context.Context) (err error) {
+	registry := chronicle.NewRegistry()
+	if _, err = chronicle.RegisterEvent[CustomerRegistered](registry,
+		events.WithID("customer-registered")); err != nil {
+		return err
+	}
+	client, err := chronicle.NewClient(
+		chronicle.WithDevelopmentDefaults(), chronicle.WithRegistry(registry))
+	if err != nil {
+		return err
+	}
+	defer func() { err = errors.Join(err, client.Close()) }()
+	store, err := client.EventStore(ctx, "customers")
+	if err != nil {
+		return err
+	}
+	result, err := store.EventLog().Append(ctx, "customer-42",
+		CustomerRegistered{Name: "Ada"})
+	if err != nil {
+		return err // The write may have committed. Do not blindly retry.
+	}
+	return result.Err()
+}
+```
+
+Registration errors and append outcomes are not optional checks. `Append` returns
+both a transport error and a result; after transport success, `result.Err()` can
+still report a rejection. A timeout/disconnect may hide a commit. Choose explicit
+concurrency/idempotency semantics before retrying, never a generic write retry.
+Use stable persisted event IDs and explicit `json` names for cross-language data.
+
+For a runnable program and its observable append position, use the tagged
+[getting-started example](https://github.com/Cratis/Chronicle.Go/blob/v0.9.1/examples/getting-started/main.go).
+This compileable package does not itself start a kernel or prove a successful append.
+
+## Connection and gRPC ownership
+
+- `NewClient` validates and freezes declarations without network I/O; it does
+  not prove readiness. `Dial(ctx, options...)` also connects. Complete all
+  registrations before construction; later changes do not mutate that client.
+- `WithDevelopmentDefaults` relaxes TLS certificate verification for development;
+  it is not a certificate whitelist. Production needs validated TLS and explicit
+  production credentials. `WithTLS` accepts TLS configuration; never use dev
+  defaults as a production fix for a failed certificate.
+- `WithGRPCConnection` borrows a `grpc.ClientConn`; the caller owns and closes it.
+  Follow the option's explicit-authentication requirement. Close the Chronicle
+  client before its borrowed collaborators. Owned connections belong to the client.
+- `Close` cancels and joins owned work. Handlers must honor cancellation;
+  a bounded `CloseContext` timeout means cleanup is incomplete, not successful.
+  Keep short unary deadlines separate from long-lived subscriptions.
+- `WithOnConnected`, `WithOnDisconnected` and `WithLoadBalancer` are explicit
+  lifecycle customization points. `WithGRPCStatsHandler` borrows concurrent-safe,
+  promptly returning callbacks for owned connections; it conflicts with a borrowed
+  connection and does not authorize interceptors or retries.
+- For SDK contributors, generate protobuf contracts only from the authoritative
+  inputs using the repository's pinned Buf recipe. Preserve metadata, field numbers,
+  deadlines and checkpoint boundaries; never hand-edit generated contracts.
+
+## Read models and side effects
+
+Read [projection registration](references/projections.md) when populating a read
+model. Start with model-bound tags; use the fluent builder when that cannot express
+it, then a reducer for genuinely procedural state decisions. Do not mix model-bound
+mapping tags and fluent mappings for the same declaration.
+
+`RegisterReactorHandler(registry, id, func(context.Context, E) error)` registers a
+typed closure for a registered event. `RegisterReactor` explicitly registers a type;
+its exported methods select events by parameter type, not by handler name. Optional
+leading context and `reactors.Delivery` parameters carry cancellation and delivery
+identity. `delivery.ID()` can key an external idempotency record; it is not an
+exactly-once guarantee. Return supported follow-up events rather than manually
+recreating effect dispatch; use projections for materialization, reactors for effects.
+
+`reactors.OnceOnly` excludes replay; it does **not** deduplicate failed-partition
+recovery. Effects may repeat after errors, cleanup failures or reconnect. Keep them
+idempotent. The kernel owns recovery/quarantine and progress; do not invent resume
+positions or acknowledge before successful processing and cleanup. Read the tagged
+[reactor guide](https://github.com/Cratis/Chronicle.Go/blob/v0.9.1/Documentation/reactors.md)
+for exact effect, replay and registration-readiness limits.
+
+## Unsupported does not mean success
+
+Decision guards require the verified 19.32.3 profile and compatibility preflight;
+unsupported kernels return `ErrUnsupported`. Protected operations have their own
+19.32.x capability gates; this release supports qualified protected revisions and
+classified read-model replay routes, not every protected watch/profile.
+Do not use the deprecated `readmodels.DecisionProtectedModel` or
+`DecisionProtectionMetadata` compatibility hooks for new work.
+
+Webhook source authorization cannot travel through the CDL-only capture transport.
+`Save`/`Validate` refuse it with `ErrUnsupported` before dispatch. Capture credential
+JSON import/export is also refused. Never serialize or log webhook credentials or
+pretend a rejected configuration was applied.
+
+## Verify
+
+- Compile against the released module without workspace/local replacements.
+- Test rejection separately from transport error and ambiguous commit recovery.
+- Use `chronicletest` scenarios for event/read-model contracts within their supported
+  profiles; pure decisions can use standard `testing` directly.
+- Exercise registration, cancellation, reconnect, borrowed connections and joined
+  cleanup against the pinned kernel before claiming runtime parity.
+- Chronicle.Go v0.9.1 requires Fundamentals.Go v0.1.0; the separate concepts skill's
+  v0.3.2 pin is not a required dependency upgrade.

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

@@ -0,0 +1,73 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Model-bound Go projections
+
+Verified at Chronicle.Go **v0.9.1** in `registry_readmodels.go`,
+`registry_projections.go`, `projections/declaration.go` and the
+[tagged projection example](https://github.com/Cratis/Chronicle.Go/blob/v0.9.1/examples/projections/main.go).
+This complete package declares a projection; it does not connect or append:
+
+```go
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+package inventory
+
+import (
+	"time"
+
+	chronicle "github.com/cratis/chronicle.go"
+	"github.com/cratis/chronicle.go/events"
+	"github.com/cratis/chronicle.go/projections"
+	"github.com/cratis/chronicle.go/readmodels"
+)
+
+// ProductRegistered records a new product's description.
+type ProductRegistered struct {
+	ProductName string `json:"productName"`
+	Description string `json:"description"`
+}
+
+// Inventory is materialized by the kernel from registered events.
+type Inventory struct {
+	ID          string    `json:"id" chronicle:"key"`
+	ProductName string    `json:"productName"`
+	Description string    `json:"description" chronicle:"set(@registered)"`
+	State       string    `json:"state" chronicle:"value(@registered,value=\"available\")"`
+	Registered  time.Time `json:"registered" chronicle:"context(@registered,from=occurred)"`
+}
+
+// Declarations returns the registry and typed read-model handle.
+func Declarations() (*chronicle.Registry, readmodels.Model[Inventory], error) {
+	registry := chronicle.NewRegistry()
+	registered, err := chronicle.RegisterEvent[ProductRegistered](registry,
+		events.WithID("product-registered"))
+	if err != nil {
+		return nil, readmodels.Model[Inventory]{}, err
+	}
+	model, err := chronicle.RegisterReadModel[Inventory](registry)
+	if err != nil {
+		return nil, model, err
+	}
+	projection := projections.ModelBound(model,
+		projections.BindEvent("registered", registered),
+		projections.FromEvent(registered))
+	return registry, model, registry.AddProjection(projection)
+}
+```
+
+`chronicle:"key"` binds event-source identity. `FromEvent` enables AutoMap by
+default (`ProductName` maps by name); `BindEvent` gives mapping tags a local
+alias. `set` copies a property, `value` sets a constant, and `context` selects
+metadata. Registration checks errors before client construction.
+
+Pass the registry to `WithRegistry`. Use the typed handle with
+`readmodels.For(store.ReadModels(), model)` and `Get(ctx, id)`; inspect both the
+error and `instance.Exists`, not a zero value as proof of presence. Materialization
+is eventually consistent. The tagged example includes a bounded read wait and
+prints the materialized state. Do not infer catch-up from registration alone.
+
+For shapes tags cannot express, define a separate untagged model and use
+`projections.NewBuilder`/typed mapping helpers. A reducer is the procedural escape
+hatch, not the first choice for event-to-property mapping.