@cratis/pi 7.34.1 → 7.36.0

package/package/corpus/skills/cratis-chronicle-cli-operations/references/command-effects.md

@@ -0,0 +1,57 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Chronicle CLI effects at v3.53.1
+
+Derived from `cratis llm-context` printed by **Cratis.Cli 3.53.1**. Use the
+installed version's catalog, not this snapshot, for later releases. The tag's
+[effect/confirmation contract](https://github.com/Cratis/cli/blob/v3.53.1/Documentation/reference/llm-context.md)
+defines `read-only`, `local`, `mutating`, `destructive`; every other or unknown
+effect is a state change. `requiresConfirmation=true` fails non-interactively
+without `--yes`, independently of effect. Confirmation is not authorization.
+
+All paths below start with `cratis chronicle`. This table exhausts its
+non-read-only commands at that version.
+
+| Path | Effect | requiresConfirmation |
+| --- | --- | --- |
+| `login` | local | false |
+| `logout` | local | false |
+| `workbench` | destructive | false (its actions have their own dialogs) |
+| `applications add` | mutating | false |
+| `applications remove` | destructive | true |
+| `jobs resume` | mutating | true |
+| `jobs stop` | mutating | true |
+| `observers clear-partition-quarantine` | mutating | true |
+| `observers clear-quarantine` | mutating | true |
+| `observers remove` | destructive | true |
+| `observers replay` | destructive | true |
+| `observers replay-partition` | destructive | true |
+| `observers retry-partition` | mutating | true |
+| `recommendations ignore` | mutating | true |
+| `recommendations perform` | destructive | true |
+| `subscriptions add` | mutating | false |
+| `subscriptions remove` | destructive | true |
+| `users add` | mutating | false |
+| `users remove` | destructive | true |
+
+The remaining Chronicle commands are cataloged read-only, including
+`report-error`; the guard deliberately blocks that command because it opens an
+external browser issue form. `chronicle version` is not a command in this
+catalog; server version is included in diagnostic output.
+
+Critical effect implementations at the tag:
+
+- [RemoveObserverCommand.cs:18–52](https://github.com/Cratis/cli/blob/v3.53.1/Source/Cli/Commands/Chronicle/Observers/RemoveObserverCommand.cs#L18-L52):
+  deletes observer records across all namespaces, leaves read model data,
+  refuses running/subscribed observers.
+- [ClearPartitionQuarantineCommand.cs:20–53](https://github.com/Cratis/cli/blob/v3.53.1/Source/Cli/Commands/Chronicle/Observers/ClearPartitionQuarantineCommand.cs#L20-L53):
+  Chronicle 19.29.0+, resets retry budget, retries unless `--no-retry`.
+- [ChronicleCommand.cs](https://github.com/Cratis/cli/blob/v3.53.1/Source/Cli/Commands/Chronicle/ChronicleCommand.cs):
+  confirmation handling shared by prompted commands.
+- [WorkbenchCommand.cs](https://github.com/Cratis/cli/blob/v3.53.1/Source/Cli/Commands/Chronicle/Workbench/WorkbenchCommand.cs):
+  destructive interactive surface, table output only.
+
+The guard covers `chronicle` only. `direct login|logout|status|use` declares
+`mutating` but is outside that guard's scope, as are other top-level groups.
+Do not infer authorization from the absence of a guard.

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

@@ -16,59 +16,57 @@ There is no host requirement and no application architecture imposed.
 
 ## Verified product sources
 
-This skill is verified against the `Cratis/Chronicle` repository at tag
-`v18.3.0`. Its client sources are unchanged in public shape since `v17.0.1`
-(the 17→18 client diff is converters, options and doc comments), and `v17.0.1`
-was byte-identical to `16.45.2` for every public type cited here except the
-compatibility check noted below.
+Verified against `Cratis/Chronicle` **v19.50.1**. The client surface is unchanged
+from v19.50.0; earlier release numbers identify feature availability.
 
-| Package | Line | Purpose |
+| Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Chronicle` | `18.3.0` | `ChronicleClient`, `IEventStore`, `[EventType]`, observers |
-| `Cratis.Chronicle.Connections` | `18.3.0` | `ChronicleConnectionString`, connection lifecycle |
-| `Cratis.Chronicle.AspNetCore` | `18.3.0` | ASP.NET Core wiring, header/subdomain namespace resolvers |
-| `Cratis.Chronicle.Testing` | `18.3.0` | in-process scenarios |
-| `Cratis.Chronicle.CodeAnalysis` | `18.3.0` | the analyzers, a **separate opt-in** package |
+| `Cratis.Chronicle` | `19.50.1` | `ChronicleClient`, `IEventStore`, `[EventType]`, observers |
+| `Cratis.Chronicle.Connections` | `19.50.1` | `ChronicleConnectionString`, connection lifecycle |
+| `Cratis.Chronicle.AspNetCore` | `19.50.1` | ASP.NET Core wiring, header/subdomain namespace resolvers |
+| `Cratis.Chronicle.Testing` | `19.50.1` | in-process scenarios |
+| `Cratis.Chronicle.CodeAnalysis` | `19.50.1` | CHR analyzers, distributed as a client dependency |
 
-Take the exact version from nuget.org. The version in source is a `1.0.0`
-placeholder injected at pack time (`Source/Directory.Build.props`), so the
-repository never carries the real number. Reverify before claiming support for a
-version you have not checked.
+Take the version from nuget.org, not the `1.0.0` source pack-time placeholder.
+Reverify before claiming another version.
 
 ## Lifecycle
 
 - **Registration is wired to the connection, not called by you.**
-  `EventStore.cs:265-268` subscribes `RegisterAll` to `Connection.Lifecycle.OnConnected`
-  when `autoDiscoverAndRegister` is on, so a reconnect re-registers everything.
+  `EventStore.RegisterAll` subscribes to `Connection.Lifecycle.OnConnected`
+  when `autoDiscoverAndRegister` is on; reconnect re-registers artifacts.
 - `DiscoverAll()` does event types first, then constraints, reactors, reducers,
-  projections, and seeding in parallel (`EventStore.cs:349-362`). `RegisterAll()`
-  is single-flighted with jittered backoff and a background retry loop (`:373-379`).
+  projections and seeding in parallel; registration is single-flighted with
+  jittered backoff/background retry (`EventStore.cs`).
 - **Wait with `WaitForRegistration`, not by polling `IsConnected`.**
   `RegistrationWaitExtensions.WaitForRegistration(this IEventStore, TimeSpan? timeout = default)`
-  (`Source/Clients/DotNET/Registrations/RegistrationWaitExtensions.cs:42`, default
-  5 seconds) exists precisely for this, and its own remarks warn against the
-  `IConnectionLifecycle.IsConnected` alternative (`:34-39`). Connected is not
-  registered.
+  returns `RegistrationOutcome`, including failed runs; its default 5-second
+  timeout is for a run that never finished. Inspect `IsSuccess`, `Failure`,
+  `Failures` and `IdentityDrift`. It reports projection registrations, not
+  reactor/reducer subscription readiness (use `WaitTillSubscribed` / `WaitTillActive`).
+  Successful active projection registration includes observer subscription, not
+  read-your-writes: inspect the append's `WaitForCompletion` result or read a
+  passive model. Source: `Registrations/RegistrationOutcome.cs`.
 - **Keepalive is a bidirectional stream plus a watchdog.** The watchdog monitors
   every `MonitorIntervalMilliseconds = 1000`
-  (`Source/Clients/Connections/ConnectionWatchdog.cs:34`) and a keepalive that
+  (`Source/Clients/Connections/ConnectionWatchdog.cs`) and a keepalive that
   falls more than 5 seconds behind is treated as a lost connection, with
   reconnect backoff capped at 30 seconds. **The failure mode is silence, not an
   exception** — appends keep working while observers go quiet.
 - `Dispose()` disposes read model reactors for created stores, cancels the owned
   connection, and disposes the connection
-  (`Source/Clients/DotNET/ChronicleClient.cs:225-246`).
+  (`Source/Clients/DotNET/ChronicleClient.cs`, `Dispose`).
 
 ## What a standalone app owns that a host would have supplied
 
 Every one of these has a silent default. Read them as a checklist, because the
 defaults are reasonable for a sample and wrong for a service
-(`ChronicleClient.cs:121-127`):
+(`ChronicleClient.cs`, options constructor):
 
 | Concern | Default when you pass nothing |
 | --- | --- |
 | `IClientArtifactsProvider` | `DefaultClientArtifactsProvider.Default` — full assembly scan |
-| `IServiceProvider` | `DefaultServiceProvider`, which activates everything through `Activator.CreateInstance` (`DefaultServiceProvider.cs:41`) |
+| `IServiceProvider` | `DefaultServiceProvider`, which activates everything through `Activator.CreateInstance` |
 | `IIdentityProvider` | `BaseIdentityProvider` |
 | `ICorrelationIdAccessor` | `CorrelationIdAccessor` |
 | `IEventStoreNamespaceResolver` | `DefaultEventStoreNamespaceResolver` — always `"Default"` |
@@ -93,9 +91,10 @@ dotnet add package Cratis.Chronicle              # console / worker service
 dotnet add package Cratis.Chronicle.AspNetCore   # ASP.NET Core
 ```
 
-`Cratis.Chronicle.CodeAnalysis` is **not** pulled in by `Cratis.Chronicle`. Add
-it deliberately — it is what warns about the mistakes an event model makes
-silently, such as a nullable event property.
+Since 19.4.8, `Cratis.Chronicle` brings `Cratis.Chronicle.CodeAnalysis` as a
+package dependency: consumers receive the CHR analyzers without opting in.
+The package id is still separate; Chronicle does not run these analyzers over
+its own generic client plumbing. Source: `Source/Clients/DotNET/DotNET.csproj`.
 
 ## Connecting
 
@@ -109,66 +108,32 @@ using var client = new ChronicleClient(ChronicleConnectionString.Development);
 var eventStore = await client.GetEventStore("<EventStoreName>");
 ```
 
-That is the compiled documentation snippet verbatim
-(`Documentation/client-snippets/get-started/console/connect.md`). Those snippet
-files are compiled in CI against the real client projects, which makes them the
-safest source of .NET Chronicle example code in existence — prefer them over
-prose documentation.
+Source: `Documentation/client-snippets/get-started/console/connect.md`;
+client snippets compile in product CI. Prefer them to untested prose examples.
 
-`IChronicleClient` — `Source/Clients/DotNET/IChronicleClient.cs:11`:
-
-| Member | Line |
-| --- | --- |
-| `ChronicleOptions Options { get; }` | `:16` |
-| `ICausationManager CausationManager { get; }` | `:21` |
-| `Task<IEventStore> GetEventStore(EventStoreName name, EventStoreNamespaceName? @namespace = default)` | `:32` |
-| `Task<IEnumerable<EventStoreName>> GetEventStores(CancellationToken cancellationToken = default)` | `:39` |
-| `void EvictEventStores()` | `:53` |
-
-**There is no `IChronicleClient.Connect`.** Connecting happens inside
-`GetEventStore`, which discovers artifacts and then connects
-(`Source/Clients/DotNET/ChronicleClient.cs:403-409`). When you do need the
-connection explicitly — in a worker's `ExecuteAsync`, for instance — it is
-`eventStore.Connection.Connect()`.
-
-`ChronicleClient` is `IDisposable`
-(`Source/Clients/DotNET/ChronicleClient.cs:30`) with five public constructors
-(`:76`, `:85`, `:94`, `:110`, `:183`). The one that matters for a real
-application is `:110`:
-
-```csharp
-public ChronicleClient(
-    ChronicleOptions options,
-    IClientArtifactsProvider? artifactsProvider = null,
-    IServiceProvider? serviceProvider = null,
-    IIdentityProvider? identityProvider = null,
-    ICorrelationIdAccessor? correlationIdAccessor = null,
-    IEventStoreNamespaceResolver? namespaceResolver = null,
-    ILoggerFactory? loggerFactory = null,
-    INamingPolicy? namingPolicy = null)
-```
-
-The canonical standalone sample uses it — `Samples/SimpleConsole/Program.cs:28-33`:
-
-```csharp
-var options = ChronicleOptions.FromConnectionString("chronicle://chronicle-dev-client:chronicle-dev-secret@localhost:35000");
-options.DefaultSinkTypeId = sinkType;
-
-using var client = new ChronicleClient(options, loggerFactory: loggerFactory);
-var store = await client.GetEventStore("TestStoreCS");
-```
+**There is no `IChronicleClient.Connect`.** `GetEventStore` discovers and connects;
+`eventStore.Connection.Connect()` is the explicit connection form.
+`ChronicleClient` is `IDisposable`; supply the options constructor's collaborators
+instead of retaining sample defaults. Read [client construction](references/client-construction.md)
+when choosing the constructor or passing a real container/logger.
 
 ### Options
 
 `ChronicleOptions` — `Source/Clients/DotNET/ChronicleOptions.cs`. Statics:
-`FromConnectionString(string)` (`:191`), `FromConnectionString(ChronicleConnectionString)`
-(`:198`), `FromDevelopmentConnectionString()` (`:214`). The parameterless
-constructor (`:40`) is the development connection string.
-
-Options worth knowing: `AutoDiscoverAndRegister` (default `true`, `:90`),
-`ConnectTimeout` (default 5 seconds, `:95`), `SkipKeepAlive` (`:127` — turn the
-watchdog off for a short-lived client), `DefaultSinkTypeId` (default
-`WellKnownSinkTypes.MongoDB`), `Tls`, `Authentication`, `RegistrationRetry`.
+`FromConnectionString(string)`, `FromConnectionString(ChronicleConnectionString)`,
+`FromDevelopmentConnectionString()`. The parameterless constructor uses the
+development connection string.
+
+Options worth knowing: `AutoDiscoverAndRegister` (default `true`),
+`ConnectTimeout` (5 seconds), `SkipKeepAlive` (short-lived clients),
+`DefaultSinkTypeId` (`WellKnownSinkTypes.MongoDB`), `Tls`, `Authentication`,
+`RegistrationRetry`, `SkipCompatibilityCheck`, `ArtifactIdentityDrift` (`Warn`),
+`UnitOfWorkLifecyclePolicy` (`Compatibility`; `Strict` opts in to completion
+checks), `EventGenerationDelivery`, `ExplicitArtifacts`, `ConcurrencyOptions`,
+`ClaimsBasedNamespaceResolverClaimType` (`tenant_id`), and
+`MaxReceiveMessageSize` / `MaxSendMessageSize` (100 MB each).
+`EnableEventTypeGenerationValidation` opts into strict migration-chain checking
+on development kernels; production always enforces it.
 
 ### Connection strings, not URLs
 
@@ -183,12 +148,24 @@ chronicle://user:pass@host[:port]/?opts
 chronicle+srv://host/?opts
 ```
 
-Default port `35000`. `Default` is `chronicle://localhost:35000` (`:48`);
+Default port `35000`. `Default` is `chronicle://localhost:35000`;
 `Development` adds the `chronicle-dev-client` / `chronicle-dev-secret`
-credentials (`:57`). Query options: `apiKey`, `auth`, `skipTlsValidation`,
-`loadBalancer`, `srvNameServer`, `certificatePath`, `certificatePassword`
-(`ChronicleConnectionStringBuilder.cs:27-36`). There is an implicit conversion
-from `string` (`:158`) and a `Redacted` form for logging (`:152`).
+credentials. Query options: `apiKey`, `auth`, `skipTlsValidation`,
+`skipCompatibilityCheck`, `loadBalancer`, `srvNameServer`, `certificatePath`,
+`certificatePassword` (`ChronicleConnectionStringBuilder.cs`). There is an
+implicit conversion from `string` and a `Redacted` form for logging.
+
+With ClientCredentials auth and **both** username and password absent, the .NET
+client also falls back to these development credentials, including through
+`AddCratisChronicleConnection`. Only a `DEVELOPMENT`-compiled kernel creates the
+application, directly in persistent storage. Switching that storage to a
+production image does not remove it: remove the development application and any
+configuration declaration that would recreate it. Do not infer other clients'
+authentication behavior from this one. Verified at **v19.50.0**:
+`Source/Clients/DotNET/ChronicleClient.cs:334-345`,
+`Source/Clients/Connections/ServiceCollectionExtensions.cs:57-68`, and
+`Source/Kernel/Core/Setup/Authentication/AuthenticationService.cs:170-208`.
+Read [host wiring](references/hosting.md) for the deployment distinction.
 
 > **Certificate validation is skipped by default, and that is deliberate.** The
 > development Chronicle images (`latest-development` and `latest-development-slim`)
@@ -201,6 +178,9 @@ from `string` (`:158`) and a `Redacted` form for logging (`:152`).
 ### In a host
 
 `AddCratisChronicle` is an extension on `IHostApplicationBuilder` (and `WebApplicationBuilder`), not on `IServiceCollection`; there is no `WithClaimsBasedNamespaceResolver`.
+`IServiceCollection` instead has `AddCratisChronicleClient` and
+`AddCratisChronicleConnection` (including `skipTlsValidation`,
+`skipCompatibilityCheck` and `skipKeepAlive` parameters).
 
 Read [references/hosting.md](references/hosting.md) when wiring Chronicle into a worker or ASP.NET Core host, or when `AddCratisChronicle` or a namespace resolver does not resolve.
 
@@ -208,10 +188,9 @@ Read [references/hosting.md](references/hosting.md) when wiring Chronicle into a
 
 `ChronicleOptions.EventGenerationDelivery` defaults to `Compatibility`. Opt in
 with `EventGenerationDelivery.Pinned` (`Cratis.Chronicle.Observation`) **before
-connecting**. Reactors and reducers then receive their handler's CLR event
-generation (Chronicle **19.41.0+**); typed materialized projections use each
-clause's declared CLR event generation (**19.48.0+**). These additions are
-verified separately against those release tags, not the baseline above.
+connecting**. Reactors/reducers receive their handler's CLR event generation
+(**19.41.0+**); typed materialized projections use each clause's CLR generation
+(**19.48.0+**), reverified at **19.50.0**.
 
 Read [references/pinned-generation-delivery.md](references/pinned-generation-delivery.md)
 for compiling standalone/host configuration, registration constraints, and the
@@ -317,9 +296,15 @@ if (!result.IsSuccess)
   several event sources in one batch.
 - **There is no `AppendAnonymous`.** It does not exist anywhere in the product.
 
-Reading back is on the same interface: `GetForEventSourceIdAndEventTypes` (`:51`),
-`HasEventsFor` (`:58`), `GetFromSequenceNumber` (`:67`), `GetNextSequenceNumber`
-(`:73`), `GetTailSequenceNumber` (`:84`). Erasure is `Redact` (`:191`, `:200`).
+Reading back is on `IEventSequence`: `GetForEventSourceIdAndEventTypes`,
+`HasEventsFor`, `GetFromSequenceNumber`, `GetNextSequenceNumber`, and
+`GetTailSequenceNumber`. Redaction is `Redact`; subject erasure is a separate
+compliance operation.
+
+Read [additional client surfaces](references/additional-surfaces.md) when using
+named tags, prepared appends, metadata-only reads, seeding or cross-cutting event
+properties. For `CompleteStream`, use **cratis-chronicle-event-constraints**;
+for guarded state-dependent decisions, use **cratis-chronicle-decision-reads**.
 
 Several appends as one unit:
 
@@ -392,7 +377,7 @@ Read [references/discovery.md](references/discovery.md) when an event type, reac
 | Polling `IsConnected` to know it is ready | Connected is not registered; use `WaitForRegistration` |
 | Treating a quiet reactor as "no events yet" | Keepalive loss stops observers while appends keep succeeding |
 | Returning from `Main` after appending | The observation stream dies with the process |
-| Expecting the analyzers | `Cratis.Chronicle.CodeAnalysis` is a separate opt-in package |
+| Assuming no CHR analyzers without an explicit reference | The client brings `Cratis.Chronicle.CodeAnalysis` transitively since 19.4.8 |
 | Copying a version out of the repository | It is a `1.0.0` placeholder; take it from nuget.org |
 
 ## Verify
@@ -404,7 +389,10 @@ Read [references/discovery.md](references/discovery.md) when an event type, reac
 - A production connection string sets `skipTlsValidation=false`.
 - An `ILoggerFactory` is supplied, and client logs are visible.
 - Observers that take dependencies get a real `IServiceProvider`.
-- Readiness is established with `WaitForRegistration`, not with `IsConnected`.
+- Projection readiness inspects the `WaitForRegistration` outcome, not `IsConnected`;
+  reactor/reducer readiness waits for their observer state.
+- CHR0054–CHR0057 are clean: dispatchable returns, valid typed stream filters,
+  and one projection/reducer target per class.
 - The process stays alive for as long as observation is expected.
 - The build is clean and the specifications pass against the verified package
   version.

package/package/corpus/skills/cratis-chronicle-client-dotnet/references/additional-surfaces.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. -->
+
+# Additional client surfaces
+
+Verified at **Cratis/Chronicle v19.50.0**:
+`Source/Clients/DotNET/EventSequences/{IEventSequence,EventForEventSourceId}.cs`,
+`Events/{EventSerializer,ICanProvideAdditionalEventInformation}.cs`, `Seeding/`,
+and `Documentation/event-seeding/seeding-with-csharp.mdx`. Connection checks:
+`Source/Clients/Connections/{ChronicleConnection,CertificateLoader}.cs` and
+`Source/Clients/AspNetCore/Diagnostics/ChronicleHealthCheckServiceCollectionExtensions.cs`.
+
+## Tags and ambiguous appends
+
+`AppendWithNamedTags` / `AppendManyWithNamedTags` and
+`EventForEventSourceId.NamedTags` carry structured tags (19.15.0+). Tags are
+plaintext and indexed: never personal data, credentials or business payloads.
+Upgrade kernels before clients that depend on named tags. `AppendThroughEventSource`
+uses a declared source type and stream name rather than hand-built routing strings.
+
+`Prepare(event)` captures append content; `AppendPrepared(...)` sends that
+prepared event. After an ambiguous transport failure, `VerifyContent(sequenceNumber,
+preparedEvent, eventSourceId)` reports `Equal`, `Different` or `Unavailable`.
+This compares content at a locator, not exactly-once execution. `Unavailable`
+is not evidence of absence; never turn it into a blind retry of irreversible work.
+`Revise(sequenceNumber, event)` is an authorized mutation, not a retry mechanism.
+
+`GetMetadataAt` reads without payload, one locator or up to **500** locators.
+Authorize the read first; a metadata-only response can still expose identities
+and causation. Missing events are omitted from the batch. Closing scopes is
+covered by **cratis-chronicle-event-constraints**, not by redaction.
+
+## Cross-cutting event properties
+
+`ICanProvideAdditionalEventInformation.ProvideFor(JsonObject @event)` providers
+are discovered automatically. The **.NET client** adds their properties in
+`EventSerializer` before sending; the kernel does not add them. A different
+client must implement its own enrichment contract. Keep domain facts explicit
+in the event type and avoid collisions, secrets or personal-data leakage through
+unannotated added properties.
+
+## Seed events deliberately
+
+`ICanSeedEvents.Seed(IEventSeedingBuilder)` declares seeds sent on connection and
+applied once per namespace. `ForNamespace` targets one namespace; global seeds
+also apply to namespaces created later (not a retroactive replay of all history).
+`For` / `ForEventSource` route by source/stream metadata; `ForEvents` keeps each
+wrapper's routing and tags. Routing participates in seed identity, so the same
+payload on another stream is another seed. Seeding is a write, not a read-only
+connect diagnostic; inspect target namespaces before changing it.
+
+## Connection health and discovery
+
+Calls while disconnected fail fast (`ConnectionTimedOut`, then
+`ConnectionUnavailable` after backoff); ASP.NET hosts start while the kernel is
+unreachable, log failure and expose the `chronicle` health check.
+`AddChronicleHealthCheck(HealthStatus)` honors its configured failure status.
+`IEventStore.Discovery` and startup reports expose discovered artifacts.
+`IEventSources` is scoped in host wiring, not a singleton to retain across requests.
+
+Passwordless PKCS#12 client certificates retain their private key on .NET 9+.
+A pinned server certificate is trusted only when its chain is the sole validation
+failure (`SslPolicyErrors.RemoteCertificateChainErrors` alone): additional
+policy errors such as hostname mismatch are not waived. Production clients still set
+`skipTlsValidation=false`; pinning is not a general validation bypass.

package/package/corpus/skills/cratis-chronicle-client-dotnet/references/client-construction.md

@@ -0,0 +1,42 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Construct a standalone client
+
+Verified at **Cratis/Chronicle v19.50.0**:
+`Source/Clients/DotNET/ChronicleClient.cs` and `IChronicleClient.cs`.
+
+The options constructor takes these optional collaborators:
+`IClientArtifactsProvider artifactsProvider`, `IServiceProvider serviceProvider`,
+`IIdentityProvider identityProvider`, `ICorrelationIdAccessor correlationIdAccessor`,
+`IEventStoreNamespaceResolver namespaceResolver`, `ILoggerFactory loggerFactory`,
+and `INamingPolicy namingPolicy`. All default to null at the call boundary and
+are replaced with the standalone defaults described in the skill. A reactor
+with constructor dependencies needs a real container; pass a logger factory to
+see registration failures rather than a silent client.
+
+The following is a connection excerpt assuming a configured `loggerFactory`;
+use a development kernel and keep the process alive for observation:
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using Cratis.Chronicle;
+using Cratis.Chronicle.Registrations;
+
+var options = ChronicleOptions.FromConnectionString("chronicle://localhost:35000");
+using var client = new ChronicleClient(options, loggerFactory: loggerFactory);
+var store = await client.GetEventStore("TestStoreCS");
+var outcome = await store.WaitForRegistration();
+if (!outcome.IsSuccess)
+{
+    throw outcome.Failure ?? new InvalidOperationException(string.Join(", ", outcome.Failures));
+}
+```
+
+`WaitForRegistration` returns after either success or failure; it is not a reactor
+subscription wait. `IChronicleClient` exposes `Options`, `CausationManager`,
+`GetEventStore(name, namespace)`, `GetEventStores(cancellationToken)`, and
+`EvictEventStores()`. It has no `Connect`: getting a store connects the client;
+`eventStore.Connection.Connect()` is the explicit connection form.

package/package/corpus/skills/cratis-chronicle-client-dotnet/references/compatibility-check.md

@@ -1,5 +1,17 @@
 ## The client and the server check each other
 
+Verified at **Cratis/Chronicle v19.50.0**, `ChronicleConnection.cs`,
+`ChronicleConnectionStringBuilder.cs`, `ChronicleOptions.cs` and
+`Source/Kernel/Compatibility/`.
+
+`chronicle://host:35000/?skipCompatibilityCheck=true` or
+`ChronicleOptions.SkipCompatibilityCheck = true` skips the check; either input
+is sufficient, including for a standalone `ChronicleClient`. Use this only for
+a known-safe skew against a kernel that cannot yet be redeployed: it hides
+**genuine incompatibilities too**. This is independent of `skipTlsValidation`.
+Since 19.0.1 the kernel orders contract comparison by protocol version, so added
+fields in a newer client do not by themselves make an older kernel incompatible.
+
 Since Chronicle 17 the compatibility check is a server-side RPC, and **the client
 runs it automatically inside `Connect()`** —
 `Source/Clients/Connections/ChronicleConnection.cs:310` calls

package/package/corpus/skills/cratis-chronicle-client-dotnet/references/discovery.md

@@ -1,22 +1,46 @@
-## Discovery
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
 
-Artifacts are found by **assembly scanning**, with no registration call and no DI
-container required. `DefaultClientArtifactsProvider.Default` composes the
-project-referenced and package-referenced assemblies
-(`Source/Clients/DotNET/DefaultClientArtifactsProvider.cs:37`), and the
-predicates are exactly (`:242-251`):
+## Discovery and explicit registration
 
-| Kind | Predicate |
+Verified at **Cratis/Chronicle v19.50.0**:
+`Source/Clients/DotNET/DefaultClientArtifactsProvider.cs`,
+`Registrations/ExplicitArtifacts.cs`, `Projections/IProjections.cs`,
+`Reactors/IReactors.cs`.
+
+`DefaultClientArtifactsProvider.Default` scans project- and package-referenced
+assemblies. Discovered artifacts include:
+
+| Kind | Shape |
 | --- | --- |
-| event types | `HasAttribute<EventTypeAttribute>()` or `HasAttribute<EventTypeGenerationForAttribute>()` |
-| projections | `HasInterface(typeof(IProjectionFor<>))` |
-| model-bound projections | `HasModelBoundProjectionAttributes()` |
-| reactors | `HasInterface<IReactor>()` and not generic |
-| read model reactors | `HasInterface<IReadModelReactor>()` and not generic |
-| reducers | `HasInterface(typeof(IReducerFor<>))` and not generic |
-
-Explicit registration is available per family as an alternative —
-`IEventTypes.Register`, `IConstraints.Register`, `IProjections.Register`,
-`IReducers.Register`, `IReactors.Register<TReactor>()`,
-`IReadModels.Register<TReadModel>()` — and is what you use with
-`AutoDiscoverAndRegister = false`.
+| Event types | `[EventType]` or `[EventTypeGenerationFor]` |
+| Projections | one `IProjectionFor<T>` per class, or model-bound projection annotations |
+| Reactors | non-generic `IReactor` |
+| Read-model reactors | non-generic `IReadModelReactor` |
+| Reducers | non-generic class implementing one `IReducerFor<T>` |
+| Event source definitions | `IEventSource` |
+| Constraints | `IConstraint`, plus `[Unique]`, `[RemoveConstraint]`, `[ClosesStream]` event declarations |
+| Seeds / migrations | `ICanSeedEvents`, `IEventTypeMigrationFor<T>` |
+| Event enrichment / middleware | `ICanProvideAdditionalEventInformation`, reactor middlewares |
+
+Multiple projection or reducer targets in one class fail discovery with
+`TypeImplementsMultipleProjectionInterfaces` / `TypeMustImplementOnlyOneReducer`
+(analyzer CHR0057). They are not silently flattened into independent artifacts.
+
+Configure `ChronicleOptions.ExplicitArtifacts` **before connecting**:
+`RegisterProjection<TReadModel>(define, id)`, `RegisterReadModel<TReadModel>()`,
+`RegisterReactor(id, builder)`. These participate in every normal registration
+pass, including reconnects. For an existing store, use
+`IProjections.Register<TReadModel>(define, id)` or `Register<TReadModel>()`,
+`IReactors.Define/Register(id, builder)`, and the family-specific event type,
+constraint, reducer and read-model registration APIs. Fluent reactors use typed
+`On<TEvent>` handlers or catch-all `Subscribe`.
+
+Runtime reactors also support `IReactors.Register(id, configure, handle)` and
+`Unregister(id)`. Use an explicit stable id for side effects. Variant read models
+cannot be registered explicitly (`VariantReadModelsCannotBeRegisteredExplicitly`).
+
+`AutoDiscoverAndRegister = false` disables the automatic pass; owning explicit
+registrations then also means owning their registration and subscription waits.
+Inspect `IEventStore.Discovery` and startup logs before guessing why an artifact
+is missing.

package/package/corpus/skills/cratis-chronicle-client-dotnet/references/hosting.md

@@ -1,5 +1,9 @@
 ## In a host
 
+Verified at **Cratis/Chronicle v19.50.0**, `ChronicleHostApplicationBuilderExtensions.cs`,
+`ChronicleClientServiceCollectionExtensions.cs`, and
+`Source/Clients/Connections/ServiceCollectionExtensions.cs`.
+
 ```csharp
 var builder = Host.CreateApplicationBuilder(args);
 builder.AddCratisChronicle(options => options.EventStore = "<EventStoreName>");
@@ -20,7 +24,8 @@ and an optional `EventStoreNamespaceResolverType`.
 > package), and Aspire's `IDistributedApplicationBuilder`. `IHostBuilder.AddCratisChronicle()`
 > also exists but only registers concept type converters
 > (`Source/Clients/DotNET/Hosting/HostBuilderExtensions.cs:18-23`) — it is not
-> the wiring entry point.
+> the wiring entry point. `IServiceCollection` has `AddCratisChronicleClient`
+and `AddCratisChronicleConnection` instead.
 
 `IChronicleBuilder` extensions are exactly five:
 `WithArtifactsProvider`, `WithIdentityProvider`, `WithCorrelationIdAccessor`,
@@ -29,3 +34,26 @@ and an optional `EventStoreNamespaceResolverType`.
 `WithClaimsBasedNamespaceResolver`**, despite a doc comment at
 `ChronicleOptions.cs:141` referring to one. Pass the resolver instead:
 `new ChronicleClient(options, namespaceResolver: new ClaimsBasedNamespaceResolver("tenant_id"))`.
+
+A host starts even when the kernel is unavailable. Calls while disconnected fail
+fast with `ConnectionTimedOut` or, after backoff, `ConnectionUnavailable`.
+ASP.NET's `AddChronicleHealthCheck(HealthStatus)` exposes the connection health
+under `chronicle` and honors the selected failure status; keep startup failure
+logs visible. Host wiring registers `IEventSources` scoped.
+
+### Development credentials are persisted
+
+At **v19.50.0**, ClientCredentials with both username and password absent uses
+`chronicle-dev-client` / `chronicle-dev-secret`:
+`Source/Clients/DotNET/ChronicleClient.cs:334-345` and
+`Source/Clients/Connections/ServiceCollectionExtensions.cs:57-68`.
+`Source/Kernel/Core/Setup/Authentication/AuthenticationService.cs:170-208`
+creates that application **directly in storage** only under `#if DEVELOPMENT`.
+This is a Debug-build symbol, not an ASP.NET environment setting
+(`Documentation/hosting/production.md`, "What makes a build a production build").
+A production kernel reusing development storage can therefore still accept the
+known development credentials. Remove the application from storage and, if
+configured, from bootstrap configuration (configured applications are recreated
+on startup). Changing the image or supplying new client credentials alone does
+not remove that old application. See **cratis-chronicle-hosting** for kernel
+certificates, private h2c and production setup.