@cratis/pi 0.0.1

package/skills/cratis-arc-command/references/proxy-generation.md

@@ -0,0 +1,87 @@
+# Proxy generation
+
+Verified against `Cratis.Arc.ProxyGenerator.Build` `22.10.4`.
+
+## Wiring
+
+Reference the build package from the project that contains the commands,
+queries and read models, and set an output path:
+
+```xml
+<PackageReference Include="Cratis.Arc.ProxyGenerator.Build" Version="22.10.4" />
+
+<PropertyGroup>
+  <CratisProxiesOutputPath>$(MSBuildThisFileDirectory)../<Web>/src/api</CratisProxiesOutputPath>
+</PropertyGroup>
+```
+
+Install `@cratis/arc` and `@cratis/arc.react` on the frontend side.
+
+The package adds a `CratisProxyGenerator` target that runs `AfterTargets="AfterBuild"`,
+and its condition is `'$(CratisProxiesOutputPath)' != ''`. **A missing output
+path is not an error — the target simply never runs and nothing is generated.**
+That is the first thing to check when a build succeeds but no proxies appear.
+
+Output folders mirror the C# **namespace**, not the file path. A command in
+`<Root>.<Feature>` lands in `<output>/<Feature>/`.
+
+## MSBuild properties
+
+Every property below is declared by the package with the default shown.
+
+| Property | Default | Effect |
+| --- | --- | --- |
+| `CratisProxiesOutputPath` | empty | Where to write. Empty disables generation entirely |
+| `CratisProxiesInputAssembly` | empty | Overrides the assembly to read |
+| `CratisProxiesSegmentsToSkip` | empty | Leading namespace segments to drop from the output path |
+| `CratisProxiesLibraryMode` | `false` | Generates for a library rather than an application |
+| `CratisProxiesSkipOutputDeletion` | **`true`** | Already the default — the generator does not wipe the output folder |
+| `CratisProxiesSkipCommandNameInRoute` | `false` | Leaves the command name out of the generated route |
+| `CratisProxiesSkipQueryNameInRoute` | `false` | Leaves the query name out of the generated route |
+| `CratisProxiesApiPrefix` | `api` | Route prefix |
+| `CratisProxiesSkipFileIndexTracking` | `false` | Disables tracking which files the generator owns |
+
+⚠️ `CratisProxiesSkipOutputDeletion` defaults to `true`. Guidance that tells you
+to set it to `true` "so the generator does not delete your hand-written files"
+is describing the default, not a fix.
+
+Item groups the target also forwards: `AssemblyToPackageMapping`,
+`ExcludeType`, `ExcludeNamespace`, `NamespaceRoot`, and `TypeToTsType`.
+
+## What the generator extracts for client-side validation
+
+The generated command proxy carries the rules it could extract, so
+`validateClientSide()` can run them without a round trip. Extraction reads
+validators derived from `AbstractValidator<T>`, `BaseValidator<T>`,
+`DiscoverableValidator<T>`, `CommandValidator<T>` and `QueryValidator<T>`.
+
+Recognised FluentValidation rules:
+
+- not null and not empty;
+- email;
+- length, minimum length, maximum length, exact length;
+- comparison rules (greater/less than and their or-equal forms);
+- regular expression.
+
+Recognised data annotations: `[Required]`, `[StringLength]`, `[MinLength]`,
+`[MaxLength]`, `[Range]`, `[RegularExpression]`, `[EmailAddress]`, `[Phone]`,
+`[Url]`, `[CreditCard]`.
+
+Rules declared on a `ConceptValidator<T>` are projected onto every property
+typed as that concept, so declaring a value's format once validates it in the
+browser too.
+
+⚠️ **`Must(...)` is not extracted.** Neither is any rule that needs an injected
+dependency. Those run on the server only, which means
+`validateClientSide()` can pass while `execute()` still fails validation.
+FluentValidation rules win over data annotations where both describe the same
+property.
+
+## Failure modes
+
+| Symptom | Cause |
+| --- | --- |
+| Nothing is generated | `CratisProxiesOutputPath` is unset, or the project did not build |
+| Files appear under an unexpected folder | The folder mirrors the namespace; change the namespace or use `NamespaceRoot`/`CratisProxiesSegmentsToSkip` |
+| Stale proxies after a rename | `dotnet clean` then `dotnet build`; the generator does not delete by default |
+| A rule validates on the server but not in the browser | The rule is not in the extractable set above |

package/skills/cratis-arc-command/references/read-model-injection.md

@@ -0,0 +1,97 @@
+# Injecting a read model into a command
+
+Verified against `Cratis.Arc.Core` `22.10.4` and `Cratis.Chronicle` `16.39.1`.
+
+A read model can be injected into a `CommandValidator<T>` constructor, into
+`Provide()`, or into `Handle()`. Arc resolves it through an
+`ICanResolveReadModelForCommand` provider, **by the command's resolved key** —
+not by the read-model type, and not by "the property that looks like its key".
+
+If the instance you need is keyed by anything else, direct injection hands you
+the wrong instance or nothing at all. That is a correctness bug, not a compile
+error. The three shapes it takes:
+
+1. you need a *referenced other* entity — act on A, check B;
+2. the command has more than one candidate identity property, so resolution is
+   ambiguous;
+3. the id is generated inside `Handle()` and does not exist yet.
+
+In all three, read by explicit key in `Provide()`:
+
+```csharp
+var other = await readModels.GetInstanceById<<Other>>((EventSourceId)<OtherId>);
+```
+
+`ReadModelKey` converts implicitly from `EventSourceId`, `Guid` and `string`, so
+the cast is all that is needed.
+
+## Nullability is the required/optional switch
+
+| Parameter | No instance for the command's key |
+| --- | --- |
+| `TReadModel?` | `null` is injected — guard with `is null` |
+| `TReadModel` | Rejected, not crashed: a **registered** read model with a usable resolved key raises `ReadModelDoesNotExistForCommand`, an `IValidationFailure` that surfaces as a validation failure (HTTP 400) with reason `DependencyUnavailable` and a message that does not name the type |
+
+The server-fault path is only reached when the dependency is *not* a registered
+read model, or when no usable key was resolved. Then it is
+`CannotResolveCommandDependency` for a handler parameter and
+`CannotResolveValidatorDependency` for a validator constructor parameter — both
+of whose messages tell you to declare the parameter nullable or to inject
+`IReadModels` and check existence explicitly.
+
+A command that carries no usable key at all fails inside the resolver with
+`UnableToResolveReadModelFromCommandContext`, which is also a client-input
+failure rather than a server fault.
+
+`ARC0006` warns when a read-model parameter is non-nullable, precisely because a
+command-scoped read model can be missing. Make it nullable when absence is part
+of the command's valid behavior; keep it non-nullable when absence really is a
+rejection.
+
+## `null` is not always what absence looks like
+
+Chronicle's `IReadModels.GetInstanceById<T>` is declared as a non-nullable
+`Task<TReadModel>` yet hands back `default!` when nothing exists, so the compiler
+gives callers no signal at all.
+
+| Backing | Never created | Removed by a `[RemovedWith<T>]` event |
+| --- | --- | --- |
+| Materialized projection or reducer (the default) | `null` | `null` |
+| `[Passive]` **projection** | ⚠️ a **default-valued instance**, never `null` | `null` |
+| `[Passive]` **reducer** | `null` | `null` |
+
+`[RemovedWith<T>]` is not the axis — a removed instance is `null` on every
+backing. The single non-`null` case is a `[Passive]` projection that was never
+created: Chronicle computes it on demand and seeds the initial state from the
+read model's schema, filling every non-nullable value property with its type
+default. Neither the `is null` guard nor the non-nullable "must exist" switch
+fires there.
+
+⚠️ This is invisible when a status enum's `0` is a real state — absent becomes
+byte-identical to freshly created, so a command reads never-invited as already
+invited. Renumbering the enum from `1` is **not** the fix; the value is then
+dropped from the payload and deserializes back to CLR `0` on the client anyway.
+Carry an explicit existence flag instead: one
+`[SetValue<TFirstEvent>(true)] bool Exists` per event that can be the first for
+the stream, and check that rather than nullability.
+
+⚠️ A specification suite will not catch this by itself. The command scenario
+harness answers `null` for an unseeded event-source id, which matches production
+for every row above *except* the passive projection. Cover the absent case by
+seeding a default-valued instance explicitly, not only `null`.
+
+Write your own by-id accessors as `Task<T?>` so callers get the compiler signal
+Chronicle's own signature withholds.
+
+## Which provider owns a read model type
+
+More than one provider can resolve the same read model type, and the application
+does not control registration order. `ReadModelForCommandOwnership` decides,
+not order:
+
+- `Declared` — something in the application says the provider owns the type: a
+  Chronicle projection or reducer targeting it, or a `DbSet<T>` on a read-model
+  `DbContext`. A declaring provider claims the type even when something else
+  already resolves it.
+- `Fallback` — the provider *can* resolve anything it reports, but nothing says
+  it owns them. It claims only the types nothing else already resolves.

package/skills/cratis-arc-command-execution/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-arc-command-execution/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: cratis-arc-command-execution
+description: Execute an existing Cratis Arc command from backend code through ICommandPipeline — the scopeless and scoped overloads, the typed Execute<TResult>, the pre-flight Validate, validation severity filtering, and how to read CommandResult. Use when a reactor, background job, scheduled task, or backend service must run a command without an HTTP request. Do not use to define a command.
+license: MIT
+---
+
+# Execute an Arc command from code
+
+`ICommandPipeline` is the same entry point the HTTP boundary uses. Everything
+downstream of the entry point is identical: authorization filters, validation
+filters, argument resolution including `Provide()`, `Handle()`, and response
+dispatch.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Arc.Core` | `22.10.4` | `Cratis.Arc.Commands.ICommandPipeline`, `CommandResult`, `ValidationResultSeverity` |
+| `Cratis.Arc.Chronicle` | `22.10.4` | analyzer `ARCCHR0006` for reactor replay |
+
+Reverify before claiming support for another version.
+
+## When this is the wrong tool
+
+`ICommandPipeline` is for **command-shaped** work that needs authorization and
+validation. It is not the way to append an event to another stream from inside a
+handler — return an `EventForEventSourceId` from `Handle()` instead, and never
+inject `IEventLog` (`ARCCHR0007`).
+
+## Inject and execute
+
+```csharp
+public class <Name>Reactor(ICommandPipeline pipeline) : IReactor
+{
+    [OnceOnly]
+    public Task <Something>Happened(<Something>Happened @event, EventContext context) =>
+        pipeline.Execute(new <TargetCommand>(@event.<Id>, @event.<Value>));
+}
+```
+
+`Execute(command)` is the scopeless overload: the pipeline creates its own DI
+scope for the call. This is the normal case.
+
+## The overloads
+
+| Overload | Use it when |
+| --- | --- |
+| `Execute(object command, ValidationResultSeverity? allowedSeverity = default)` | The normal case |
+| `Execute(object command, IServiceProvider serviceProvider, ValidationResultSeverity? allowedSeverity = default)` | The command's dependencies must come from the caller's existing scope |
+| `Execute<TResult>(object command, ...)` | The handler returns a response you need typed |
+| `Validate(object command, ...)` | You need the verdict without any side effect |
+
+Each has both the scopeless and the scoped form. Prefer the scopeless one: the
+scoped overload exists for a caller that genuinely owns a scope the command's
+dependencies must share.
+
+```csharp
+var result = await pipeline.Execute<<ResponseType>>(new <CommandName>(<args>));
+if (result.IsSuccess)
+{
+    var response = result.Response;
+}
+```
+
+⚠️ `Execute<TResult>` throws `InvalidCastException` when the handler returned a
+response of a different type. When the handler returns no response, or the
+command failed for any reason, `Response` is `default` — a failed result never
+carries a response, because the pipeline clears it once the execution scopes
+have completed.
+
+## Pre-flight `Validate`
+
+`await pipeline.Validate(command)` runs the authorization and validation filters
+and stops there — `Provide()` and `Handle()` never run, so there is no side
+effect. Use it to decide whether to commit to work that surrounds the command.
+
+## Validation severity filtering
+
+Both `Execute` and `Validate` take an optional
+`ValidationResultSeverity? allowedSeverity` from `Cratis.Arc.Validation`. The
+levels are `Unknown = 0`, `Information = 1`, `Warning = 2`, `Error = 3`.
+
+- With no `allowedSeverity`, **only `Error` blocks**, and information and
+  warnings are filtered off the result entirely — they never reach the caller.
+- With an `allowedSeverity`, anything **strictly greater** blocks. Passing
+  `Warning` lets warnings through onto the result while errors still block.
+
+## Read the result by the specific flag
+
+`IsSuccess` is derived — `IsAuthorized && IsValid && !HasExceptions`. Asserting
+only on it cannot distinguish a forbidden caller from a rejected input from a
+crash.
+
+| Member | Meaning |
+| --- | --- |
+| `IsAuthorized` | The identity satisfied the command's authorization; `AuthorizationFailureReason` says why not |
+| `IsValid` | Derived: no blocking validation results survived. `ValidationResults` carries them |
+| `HasExceptions` | Derived: `ExceptionMessages` is non-empty. `ExceptionStackTrace` has the detail |
+| `CorrelationId` | The pipeline-wide id to correlate logs and traces on |
+
+A command with no registered handler comes back with an exception message naming
+the command type rather than throwing.
+
+Surface these through the result. Do not convert `!IsValid` into a thrown
+exception — that discards the structured failure the caller needs.
+
+## Reactors must decide what replay does
+
+A reactor handler that executes a command is not idempotent: a replay
+(redaction, revision, observer rewind) runs the handler again and executes the
+command again. `ARCCHR0006` warns when a reactor handler invokes
+`ICommandPipeline.Execute` without saying what replay should do. Mark the
+handler `[OnceOnly]` so it is skipped during replay.
+
+⚠️ `[OnceOnly]` is **replay exclusion, not deduplication**. There is no ledger
+of events a handler has already seen: recovering a failed partition re-delivers
+the event as an ordinary observation, and a `[OnceOnly]` handler runs again.
+Make the executed command idempotent regardless — and when replay exclusion is
+the wrong tool, suppress the diagnostic with a justification rather than
+mis-marking it to silence the warning.
+
+## Common mistakes
+
+| Mistake | Why it hurts |
+| --- | --- |
+| Throwing on `!result.IsValid` | Loses `ValidationResults`, turns a 400-shaped rejection into a fault |
+| Executing from a reactor without deciding about replay | Every replay re-fires the command |
+| Reaching for the scoped overload by default | Couples the command to the caller's scope for no reason |
+| Asserting only `IsSuccess` in a spec | A spec passes with every rule neutered |
+| Reading `Response` without checking success first | It is always `default` on failure |
+
+## Verify
+
+- The caller branches on `IsAuthorized`, `IsValid` and `HasExceptions`, not only
+  on `IsSuccess`.
+- No expected failure is converted into a thrown exception.
+- A reactor that executes a command has an explicit replay decision.
+- The scoped overload is used only where the shared scope is required.
+- `Execute<TResult>`'s type argument matches what the handler actually returns.
+- `dotnet build` is clean in Debug and Release with `ARCCHR0006` and
+  `ARCCHR0007` silent or explicitly justified.
+
+## Route near misses
+
+- Defining the command or choosing its `Handle()` return shape:
+  `cratis-arc-command`.
+- Adding or changing a rule: the Arc command validation guidance.
+- Designing what a reactor should observe: the Chronicle reactor guidance.

package/skills/cratis-arc-command-validation/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-arc-command-validation/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: cratis-arc-command-validation
+description: Add a rejection rule to an existing Arc command — choosing between ConceptValidator, CommandValidator, a short-circuiting Provide, and a read-model-injected Handle returning Result<TEvent, ValidationResult>. Use when a command must refuse work under some condition. Do not use to define a new command, and do not use for append-time Chronicle constraints.
+license: MIT
+---
+
+# Arc command validation
+
+Every rejection a command can produce has exactly one right home. Putting a rule
+in the wrong one is not a style problem: a value invariant written per-command
+stops travelling with the value, and a state-dependent rule written in a
+validator loses the race it exists to win.
+
+**Never throw for a normal business rejection.** An exception out of `Provide()`
+or `Handle()` is caught by the pipeline and merged as `HasExceptions`, which the
+HTTP layer maps to **500** — not a validation result. Recoverable, user-facing
+rejections are validation. (The one exception: an exception type implementing
+`IValidationFailure` is converted to a validation failure and returns 400. Arc
+uses that for its own dependency-resolution failures; do not build application
+rejection on it.)
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Arc.Core` | `22.10.4` | `CommandValidator<T>`, `ConceptValidator<T>`, `ValidationResult`, `CommandResult`, the command pipeline, `ARC0004`–`ARC0013` |
+| `Cratis.Fundamentals` | `7.18.2` | `Cratis.Monads.Result<TResult, TError>` |
+| `Cratis.Chronicle` | `16.45.2` | Read-model resolution for command-side injection |
+| `FluentValidation` | `12.1.1` | `RuleFor(...)`, `.WithMessage(...)` |
+
+Reverify against the owning product repository before claiming support for
+another version.
+
+## Route near misses
+
+- Defining a new command, its `Handle()` return shape, or event-source id
+  resolution: use `cratis-arc-command`.
+- Uniqueness, or any rule the **event store** must enforce at append time: use
+  `cratis-chronicle-event-constraints`. A read-model pre-check for uniqueness is
+  not race-safe and is the classic wrong answer here.
+- Authorization: that is a filter and an attribute at the boundary, not a
+  validator. Use `cratis-arc-authentication-authorization-and-identity`.
+- Writing the specification for the rejection: use
+  `cratis-application-slice-specifications`.
+
+## Step 1 — Choose the mechanism by what the decision *is*
+
+| The rule is… | Put it in |
+| --- | --- |
+| A reusable value invariant — length, format, range | `ConceptValidator<T>` on the concept type |
+| Command input, cross-field, or a pre-handler check | `CommandValidator<TCommand>` with `RuleFor(...)` |
+| A dependency on data the handler must fetch first | `Provide()` — fetch, and short-circuit if unusable |
+| State-dependent and must hold **under concurrency** | Inject the read model into `Handle()`, return `Result<TEvent, ValidationResult>` |
+| Uniqueness | A Chronicle constraint, never a command-side read |
+| A genuine defect or missing infrastructure | `throw` a domain exception |
+
+The pipeline runs **authorization → validation → `Provide()` → `Handle()`**.
+Authorization filters are explicitly ordered ahead of validation filters, so a
+caller who may not act never learns whether their input was valid.
+
+## Step 2 — Value invariants: `ConceptValidator<T>`
+
+```csharp
+public class EmailAddressValidator : ConceptValidator<EmailAddress>
+{
+    public EmailAddressValidator() => RuleFor(_ => _.Value).EmailAddress();
+}
+```
+
+A `ConceptValidator<T>` is discovered automatically and applies **globally**.
+Arc walks the whole object graph of every model it validates and runs a
+validator resolved by each node's runtime type — so the rule fires on every
+command *and every query* carrying that concept, wherever it appears. That is
+the point: declare the invariant once and it cannot be forgotten on the next
+command.
+
+When one command legitimately needs the concept unchecked, opt that property out
+in its own validator with `.IgnoreConceptRules()` rather than weakening the
+concept rule for everyone.
+
+`ARC0013` warns when a validator rule dereferences a possibly-null concept
+member.
+
+## Step 3 — Command input rules: `CommandValidator<T>`
+
+```csharp
+public class TransferFundsValidator : CommandValidator<TransferFunds>
+{
+    public TransferFundsValidator() =>
+        RuleFor(c => c.Amount).GreaterThan(0).WithMessage("Amount must be positive.");
+}
+```
+
+- `CommandValidator<T>` is a FluentValidation `AbstractValidator<T>` underneath,
+  so `RuleFor`, the standard rule set, and `.WithMessage(...)` are
+  FluentValidation's. Arc adds one overload that unwraps a `ConceptAs<T>` to its
+  primitive so `RuleFor(c => c.SomeConcept)` reads naturally.
+- The validator is discovered by type — no registration.
+- Constructor dependencies (read models, services) are injected. A read model
+  injected here resolves the same way as one injected into `Handle()`; see
+  Step 5 for what "the same way" actually means.
+- **Omit the validator entirely when there are no rules.** An empty subclass is
+  noise the reader has to check.
+- Single-property intrinsic rules belong on `ConceptValidator<T>` instead, so
+  they travel with the value everywhere.
+- A validator that itself throws does not become a 500 — Arc catches it and
+  emits a validation error with reason `ValidatorFailed`, returning 400.
+
+## Step 4 — Data the handler needs: `Provide()`
+
+`Provide()` runs after authorization and validation and before `Handle()`. Its
+parameters resolve from dependency injection; the command instance is `this`.
+
+```csharp
+public async Task<Result<Customer, ValidationResult>> Provide(IReadModels readModels)
+{
+    var customer = await readModels.GetInstanceById<Customer>((EventSourceId)CustomerId);
+    return customer is null ? ValidationResult.Error("Customer must exist.") : customer;
+}
+```
+
+- Returning a `ValidationResult`, an `IEnumerable<ValidationResult>`, an
+  `AuthorizationResult`, or a `CommandResult` short-circuits: `Handle()` is
+  never invoked.
+- A `Result<TProvided, ValidationResult>` has its inner value unwrapped, so the
+  success arm flows to `Handle()` and the error arm short-circuits.
+- A returned tuple is flattened and its elements bound to `Handle()` parameters
+  by type. **Every provided value must be consumed by a `Handle()` parameter** —
+  an unused one is `ARC0005`.
+- Keep the fetch in `Provide()` and the decision in `Handle()`. Do not write a
+  pass-through `Provide()` that only forwards a read model `Handle()` could take
+  directly, and do not duplicate one rejection in both the validator and
+  `Provide()` — pick one owner.
+
+## Step 5 — Concurrency-sensitive rules: the read model in `Handle()`
+
+Use this when the rule depends on accumulated event-sourced state — a count, a
+running total — and must still hold when two requests arrive at once. Arc
+resolves the read model before `Handle()` runs and the handler returns a
+`Result<TEvent, ValidationResult>`: success carries the event, failure carries a
+typed validation error.
+
+```csharp
+using Cratis.Monads;
+
+[Command]
+public record AddItemToCart(CartId CartId, ItemId ItemId)
+{
+    /// <summary>Adds the item; rejects when the cart already holds the maximum.</summary>
+    /// <param name="cart">The current cart summary, resolved by the command's event-source id.</param>
+    /// <returns>The event on success, or a validation error.</returns>
+    public Result<ItemAddedToCart, ValidationResult> Handle(CartSummary cart) =>
+        cart.ItemCount >= 3
+            ? ValidationResult.Error("A cart can hold at most 3 items.")
+            : new ItemAddedToCart(ItemId);
+}
+```
+
+- `Result<TSuccess, TError>` is `Cratis.Monads.Result<,>` from Cratis
+  Fundamentals — **success first, error second** — and needs
+  `using Cratis.Monads;`. Its implicit conversions are what let both `return`
+  statements above compile without wrapping.
+- **Return the error; never throw it.**
+- One parameter per logical read model; several reads mean several parameters.
+
+⚠️ **Two things the resolution does *not* do.** It does not key off the
+`[ReadModel]` attribute — a read model becomes injectable because a Chronicle
+projection or reducer, an EF Core `DbSet<T>`, or a MongoDB collection backs it.
+And there is **no slice or feature restriction**: registration is global by
+type, so "the read model must be in the same slice" is a convention with nothing
+enforcing it.
+
+The resolution is **by the command's resolved event-source id**, not by the
+read-model type and not by "the property that looks like its key". If the
+instance you need is keyed by anything else — a referenced other entity, a
+command with more than one candidate identity, or an id generated inside
+`Handle()` — direct injection hands you the wrong instance or none. Read by
+explicit key in `Provide()` instead:
+
+```csharp
+var other = await readModels.GetInstanceById<Other>((EventSourceId)otherId);
+```
+
+A missing instance resolves to `null`, never to a default object. A nullable
+parameter receives that `null`; a non-nullable one is **rejected as a validation
+failure (400)**, not crashed. `ARC0006` warns on a non-nullable command-scoped
+read-model parameter for exactly this reason. `cratis-arc-command` carries the
+full resolution and nullability reference, including the passive-projection case
+where absence is *not* `null`.
+
+## Step 6 — Specify the rejection
+
+Every rule gets a specification of its failure case, using
+`CommandScenario<TCommand>`. Assert **both** that the command did not succeed
+and that it failed *as a validation*:
+
+```csharp
+[Fact] void should_not_succeed() => _result.ShouldNotBeSuccessful();
+[Fact] void should_have_validation_errors() => _result.ShouldHaveValidationErrors();
+```
+
+`ShouldNotBeSuccessful()` alone cannot tell a rejection from an unhandled
+exception, which is precisely the mistake this skill exists to prevent. Never
+assert on a message string — it is presentation text. See
+`cratis-application-slice-specifications` for the scenario mechanics.
+
+## What breaks
+
+- **The rejection returns HTTP 500.** Something threw instead of returning a
+  validation result. Check `Provide()` and `Handle()` for a `throw` on a
+  recoverable path.
+- **The rule reads the wrong instance.** The injected read model is keyed by the
+  command's event-source id and the command carries a different identity. Read
+  by explicit key in `Provide()`.
+- **The rule never fires.** The read-model type has no backing Chronicle
+  projection, reducer, `DbSet<T>`, or MongoDB collection, so nothing registered
+  it for command-side resolution.
+- **Two requests both win.** The rule is in a validator or a `Provide()` read
+  rather than in `Handle()` with `Result<,>`, or it is a uniqueness rule that
+  belongs in a Chronicle constraint.
+- **`ARC0005` on build.** `Provide()` returns a value no `Handle()` parameter
+  consumes.
+
+## How it is proven
+
+`dotnet build` in Debug and in Release, zero warnings and zero errors — the
+analyzers above are how `ARC0005`, `ARC0006` and `ARC0013` surface. Then
+`dotnet test` with a specification per rule, each asserting both
+`ShouldNotBeSuccessful()` and `ShouldHaveValidationErrors()`. A rule with no
+red-first specification has not been shown to reject anything.

package/skills/cratis-arc-ef-core-migration/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.