@cratis/pi 7.60.1 → 7.62.0

package/package/corpus/skills/cratis-arc-command/references/decisions-and-routing.md

@@ -15,61 +15,100 @@ Source: Arc. These features require `Cratis.Arc.Chronicle`.
 
 ## Pick the guarded read
 
-Plain injected read models and `IReadModels.GetInstanceById` are advisory,
-materialized or passive. A `Result<TEvent, ValidationResult>` rejects a request
-but does not enroll a guard. Uniqueness and create-once belong to a Chronicle
-constraint, not to any read. For the routing steps, the matrix and the traps read
+Under read protection `On` (`<CratisReadProtection>On</CratisReadProtection>`, or
+`[ReadProtection(ReadProtectionMode.On)]` on a command), a read model that is a
+parameter of `Handle()` or of a `CommandValidator<T>` constructor is read fresh from
+the event log and guards the command's append. `Off` is the default when nothing is
+set; under `Off` and `Measure` those reads are plain, a hint that guards nothing.
+A `Result<TEvent, ValidationResult>` rejects a request but does not enroll a guard.
+Uniqueness and create-once belong to a Chronicle constraint, not to any read. For the
+routing by rule shape, the matrix and the traps read
 [choosing how a rule holds](../../cratis-chronicle-decision-reads/references/choosing-how-a-rule-holds.md).
 
-- For one stream, inject `IStreamReads` into `Provide`, call `ForCommand()`, and
-  return `StreamDecision.Append(...)` from `Handle`. It returns
-  `EventsWithConcurrencyScopes`, retaining the read route and exact tail. A
-  competing append conflicts, including two competing first appends.
-- For projected state, opt in with `[ProtectedDecision]` in
-  `Cratis.Arc.Chronicle.ReadModels`, then inject `DecisionRead<T>` into
-  `Provide`/`Handle` (`Exists`/`Instance`). Command-aware `IDecisionReads.Get<T>`
-  enrolls reads of other keys. Only Chronicle-admitted direct event-source-keyed
-  projections with a known event-type set qualify; reducers, joins, children,
-  open-ended event types and incomplete definitions are refused. Arc certifies parameterless
-  validators it constructs; constructor dependencies and uncertified instances
-  are refused: a protected command's discoverable validator needs exactly one
-  public parameterless constructor, otherwise the command fails with HTTP 500.
-  The decision model needs an `Id` property, an event-source key and a flat
-  projection; self-reducing models are refused like reducers. When the command has
-  two or more key candidates, implement `ICanProvideEventSourceId`: `[Key]` does
-  not silence `ARCCHR0002`, and Arc silently keys by the first eligible property
-  in declaration order. Keep all decision state out of validators, including
-  static members and service locators. `[Unprotected]` on the command opts out; never
-  combine it with `[ProtectedDecision]`. A parameter-level marker acknowledges
-  tooling, not a runtime opt-out. `Validate` is advisory, not a commit promise.
-- `concurrency: true` on the routing attributes is **not** a guard for the
-  decision: Arc reads the narrowed tail after `Handle`, so it only widens or
-  narrows the window the default check covers. Exact returned scopes replace
-  automatic capture; remove the flags when returning `EventsWithConcurrencyScopes`
-  (ARCCHR0016). The default check also reads the tail after `Handle`, and the first
-  append into a scope is unchecked unless `CheckFirstAppendIntoAScope` is set.
+Requires Arc 22.106.0 for read protection. Older Arc has only the per-command
+`[ProtectedDecision]` path below.
+
+- **One entity's state.** Put the rule in a validator with the read model as a
+  constructor parameter; `Handle()` returns the events. The key is
+  `[LookUpBy(nameof(Cmd.Prop))]` on the parameter (`Cratis.Arc.Commands`), else the
+  single command property whose type equals the model's `Id` type, else the
+  command's event source id. Several matching properties fail with
+  `AmbiguousReadModelLookup` (500): add `[LookUpBy]`.
+- **Two entities.** Two read-model parameters, the second with `[LookUpBy]`;
+  `Handle()` returns `IEnumerable<EventForEventSourceId>`, one event per entity,
+  appended atomically. Use a distinct event type per entity.
+- **One stream inside a source.** A per-stream read model
+  (`[ReadModel, EventStream<TSource>("Transactions")]`, `Cratis.Chronicle.ReadModels`)
+  as a plain parameter, on a command routed `[EventSource<TSource>("Transactions")]`
+  and `[EventStreamId("{Month}")]`; otherwise `ReadModelStreamNotOnCommandRoute`
+  (500, analyzer ARCCHR0037). It is folded from that one stream and key-only reads
+  are refused. For raw events of a short stream, inject `IStreamReads` into
+  `Provide`, call `ForCommand()`, and return `StreamDecision.Append(...)` from
+  `Handle` (`EventsWithConcurrencyScopes`); a competing append conflicts, including
+  two competing first appends.
+- **Computed key or another stream or source.** Command-aware `IDecisionReads.Get<T>`
+  in `Provide()`, including the stream overloads.
+- **Rich lifecycle.** An aggregate root, with `Commit()` returned last. Under `On`,
+  an aggregate and a protected read of the same source are refused
+  (`ReadAndAggregateOnSameSource`); a different source is fine.
+- **Editing conflict.** Return `EventsWithConcurrencyScopes` built from the revision
+  the client sent. `concurrency: true` on the routing attributes is **not** a guard
+  for the decision: Arc reads the narrowed tail after `Handle`. Remove the flags
+  when returning exact scopes (ARCCHR0016). The default check also reads the tail
+  after `Handle`, and the first append into a scope is unchecked unless
+  `CheckFirstAppendIntoAScope` is set.
+- **No guard needed.** A hint or a rare violation: mark a deliberate advisory read
+  `[Unprotected("why")]` (`Cratis.Arc.Chronicle.ReadModels`; on a method it covers
+  the body, not injected parameters), or repair with a reactor.
+
+Under `On`, `IReadModels`, `IMongoCollection`, detached reads and immediate appends
+through an injected `IEventLog` are refused; take the model as a parameter and
+return the events. Admitted models: event-source-keyed model-bound or declarative
+projections with a string or Guid `Id`, and unfiltered reducers without constructor
+dependencies except `ILogger<T>` (self-reducing models are exempt). Joins and
+children, event-property keys, Pinned delivery, filtered reducers, reducers with
+dependencies and other event sequences fail with `ReadCannotBeProtected` (500)
+unless marked `[Unprotected("why")]`. Validators with read models must be
+convention-registered (transient).
+
+When the command has two or more key candidates, implement `ICanProvideEventSourceId`:
+`[Key]` does not silence `ARCCHR0002`, and Arc silently keys by the first eligible
+property in declaration order.
+
+A lost race is HTTP 400 with a validation result of reason `concurrencyViolation`,
+`reasonDetail` `ReadChanged` and `state` `{ readModel, key }`. Arc and Chronicle do
+not re-run the command; the client submits it again. Every other refusal is 500:
+change the code.
+
+### Per-command opt-in: `[ProtectedDecision]`
+
+`[ProtectedDecision]` (`Cratis.Arc.Chronicle.ReadModels`) with `DecisionRead<T>`
+(`Exists`/`Instance`) is the older per-command opt-in. It still works and is not
+obsolete; do not describe `On` as making it redundant. Use it for a command in a
+project that is not on `On`. Without `On`, only a parameterless validator runs: a
+discoverable validator needs exactly one public parameterless constructor,
+otherwise the command fails with HTTP 500. Keep decision state out of validators
+there, including static members and service locators. `[Unprotected]` on the
+command opts out; never combine it with `[ProtectedDecision]`
+(`CommandCannotBeBothProtectedAndUnprotected`).
 
 Requires Arc 22.81.0 for stream-scoped `IDecisionReads.Get<T>`,
 `GetDetached<T>` and `AdmitForStream<T>` to participate in command protection,
-caching and enrollment. Older Arc refuses these stream reads inside commands;
-check the Arc package version before choosing this path. `[Unprotected]` command
-reads are unguarded, not refused.
+caching and enrollment. Older Arc refuses these stream reads inside commands.
 
 Do not manually append or commit to bypass the owner-capable unit of work.
 The guard detects every matching event appended after its boundary, whoever wrote
 it, but it protects only guarded decisions: an unguarded writer deciding on the
 same facts can still append on stale state, so the rule holds only when every
-deciding writer is guarded or the rule is a constraint. Protection does not guard an unguarded writer's own decision (a plain read,
-`[Unprotected]` or a direct append), external state, revisions, redactions,
-migrations, changes to projection definitions or writes that bypass the kernel's
-serialized append path. Protection is per command and
-opt-in; an unmarked command keeps its plain reads, and a conflict is returned as a
-`ConcurrencyViolation` validation result with no automatic retry. A protected command that
-stages no events commits an empty guarded batch: current kernels validate the
-enrolled reads (a scope with an actual boundary or expecting no matching event) and write nothing, while a kernel that rejects an empty batch
-raises `DecisionReadValidateOnlyNotSupported` (HTTP 500), so cover it with an
-integration specification. In contrast, `StreamDecision.Append([])`
-returns no scopes: use it only for an identical retry, not a rejected request.
+deciding writer is guarded or the rule is a constraint. Outside the guard:
+`[Unprotected]` reads, `Off` mode, external state, revisions and redactions,
+migrations, changes to projection definitions and writes that bypass the kernel's
+serialized append path. A protected command that stages no events commits an empty
+guarded batch: current kernels validate the enrolled reads and write nothing, while
+a kernel that rejects an empty batch raises `DecisionReadValidateOnlyNotSupported`
+(HTTP 500), so cover it with an integration specification. In contrast,
+`StreamDecision.Append([])` returns no scopes: use it only for an identical retry,
+not a rejected request.
 
 ## Definition-backed routes and templates
 
@@ -125,12 +164,17 @@ source id/type and stream route; reactor tuples/collections cannot mix it with e
 
 ## Decision specifications
 
-Call `new CommandScenario<T>().UseDecisionReads()` before seeding events.
-`Given.ForEventSource(id).OnRoute(route).Events(...)` and
-`AppendConcurrently(id, route, ...)` share one real in-process log. Pinned models
-cannot supply guards. Assert a real nonempty decision conflicts on the intended
-route, and that an independent route is not over-guarded.
-`ShouldHaveCompletedStream(type, id)` asserts completion;
+`new CommandScenario<T>()` selects the in-process decision log from the command's
+read-protection mode and dependencies (under `On`, with a per-stream model or
+`[ProtectedDecision]`); `UseDecisionReads()` is hidden and unnecessary. An `Off`
+command with no protected dependency stays in the legacy mode with pinned read
+models, which cannot prove a race. Seed with `Given.ForEventSource(id).Events(...)`,
+`.OnRoute(route).Events(...)`, queue a competing append with
+`AppendConcurrently(id, events...)` (or `AppendConcurrently(id, route, ...)`) and
+assert `result.ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation)`.
+There is no `scenario.AppendConditions`. Guarded state needs seeded events: protected reads ignore a pinned `.ReadModel(m)` (which only pins an advisory plain read) and `DecisionRead<T>` rejects it. Assert a
+real nonempty decision conflicts on the intended route, and that an independent
+route is not over-guarded. `ShouldHaveCompletedStream(type, id)` asserts completion;
 `ShouldHaveCompletedStream(ClosedStreamScope)` asserts the exact owner and route;
 `DecisionReadAdmissions.ShouldAdmitDecisionReadsIn(assembly)` checks projection
 admission in assembly-level specs.

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

@@ -98,8 +98,11 @@ use an appropriate constraint or explicit concurrency scope for them.
 
 ## Specify the collision
 
-Use `new CommandScenario<TCommand>().UseDecisionReads()` **before seeding**, then
-`PinGeneratedValue(name, id)` and `Given.ForEventSource(id).Events(existingEvent)`.
+Use `new CommandScenario<TCommand>()`; it selects the in-process log from the
+command's read-protection mode and dependencies before seeding. If a seeded
+collision throws `GeneratedIdentifierCollisionRequiresDecisionReads`, the
+scenario stayed in legacy mode: call the compatibility switch `UseDecisionReads()`
+before seeding. Then `PinGeneratedValue(name, id)` and `Given.ForEventSource(id).Events(existingEvent)`.
 Assert the concurrency reason and collision detail, unchanged append tail and
 one handler execution. Also cover an empty source receiving two events through
 the chosen write API, an occupied source whose events belong to another stream,

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

@@ -7,10 +7,12 @@
 - Which provider owns a read model type
 
 Source: [read models in commands](https://github.com/Cratis/Arc/blob/main/Documentation/backend/csharp/chronicle/read-models/injecting-into-commands.md).
-Plain models and keyed reads are advisory, not concurrency guards. For protected
-reads use [decisions and routing](decisions-and-routing.md): opt into
-`[ProtectedDecision]` before taking `DecisionRead<T>`; constructor-injected
-validators are refused there.
+Under read protection `Off` (the default) and `Measure`, injected models and keyed
+reads are plain reads, not concurrency guards. Under `On`, a read-model parameter of
+`Handle()` or a validator constructor is guarded; `IReadModels.GetInstanceById` in a
+command is refused, so read another entity's model with a second parameter and
+`[LookUpBy(nameof(Cmd.Prop))]`. See [decisions and routing](decisions-and-routing.md)
+and, for per-command opt-in, `[ProtectedDecision]` with `DecisionRead<T>`.
 
 A read model can be injected into a `CommandValidator<T>` constructor, into
 `Provide()`, or into `Handle()`. Arc resolves it through an
@@ -26,7 +28,9 @@ error. The three shapes it takes:
    ambiguous;
 3. the id is generated inside `Handle()` and does not exist yet.
 
-In all three, read by explicit key in `Provide()`:
+In all three, under `Off` read by explicit key in `Provide()`; under `On` use a
+second parameter with `[LookUpBy]`, or `IDecisionReads.Get` in `Provide()` for a
+key computed there:
 
 ```csharp
 var other = await readModels.GetInstanceById<<Other>>((EventSourceId)<OtherId>);

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

@@ -59,14 +59,15 @@ another version.
 Which mechanism makes a rule hold under concurrent writers (constraint, protected
 decision, stream decision, aggregate, scope, reactor repair) is routed in
 [choosing how a rule holds](../cratis-chronicle-decision-reads/references/choosing-how-a-rule-holds.md).
-A validator is never that mechanism.
+A validator holds a state rule only when the project is on read protection `On`;
+under `Off` (the default) it is a hint, never the mechanism.
 
 | 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** | Guard the read with `IStreamReads`/`StreamDecision`, or `[ProtectedDecision]` + `DecisionRead<T>`; return events through Arc |
+| State-dependent and must hold **under concurrency** | Under `On`, a `CommandValidator<T>` with the read model as a constructor parameter (Step 5); or `IStreamReads`/`StreamDecision`; return events through Arc. `[ProtectedDecision]` + `DecisionRead<T>` is the older per-command opt-in |
 | Uniqueness | A Chronicle constraint, never a command-side read |
 | A genuine defect or missing infrastructure | `throw` a domain exception |
 
@@ -119,11 +120,27 @@ public class TransferFundsValidator : CommandValidator<TransferFunds>
 - 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. A validator that reads state is
-  **advisory only**: it shows the state at validation time and guards nothing, so
-  use it for a friendly early message, never as the rule. A `[ProtectedDecision]`
-  command refuses a discoverable validator unless it has exactly one public
-  parameterless constructor (otherwise HTTP 500), so keep state rules out of it.
+  Step 5. **State rules ("may this proceed") belong here**, with the read model as a
+  constructor parameter. Under read protection `On` that read is fresh from the log
+  and guards the append: if an event of the model's types for that key arrives
+  after the read, nothing from the command is written. Under `Off` (the default
+  when nothing is set) and `Measure` the same validator reads a plain model: a hint
+  with a friendly message that guards nothing. Under `On` the validator must be
+  convention-registered (transient); hand-registered scoped, singleton, factory or
+  instance validators are refused. Under `[ProtectedDecision]` without `On`, a
+  discoverable validator needs exactly one public parameterless constructor
+  (otherwise HTTP 500).
+- **The caller can lower the severity threshold.** Model-bound commands accept
+  `X-Allowed-Severity` (`allowedSeverity`). Under `Off` and `Measure`, a caller
+  sending `3` (Error) removes Error results from validators, command filters and
+  `Provide()`, so `Handle()` runs and a validator's state rule can be skipped
+  unless the command declares
+  `[BlockOnValidationSeverity(ValidationResultSeverity.Error)]`
+  (`Cratis.Arc.Commands.ModelBound`). Requires Arc 22.108.0 for the `On` floor: a
+  command declared `On` blocks `Error` and `Unknown` whatever the caller sends; the
+  caller can relax only `Warning` and `Information`. Lowering
+  `ReadProtection:MaximumMode` at runtime does not remove the floor, and an explicit
+  attribute wins. Severity is not authorization.
 - **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
@@ -159,53 +176,77 @@ public async Task<Result<Customer, ValidationResult>> Provide(IReadModels readMo
 
 ## Step 5 — Guard a concurrency-sensitive decision
 
-Plain read-model injection or `IReadModels.GetInstanceById` is **advisory**, even
-inside `Handle()` returning `Result<,>`: it enrolls no guard against a competing
-append. Choose the first boundary that fits:
-
-1. One routed stream: `Provide(IStreamReads reads) => reads.ForCommand()` returns
-   `Task<StreamDecision>`; `Handle(StreamDecision decision)` returns
-   `decision.Append(...)` (`EventsWithConcurrencyScopes`), guarding the read tail.
-2. Projected state: mark the command `[ProtectedDecision]` and take
-   `DecisionRead<T>` (`.Exists`/`.Instance`) or command-aware `IDecisionReads`.
-   Only Chronicle-admitted, direct event-source-keyed projections with known
-   event types qualify; reducers (including self-reducing models), joins, children and open-ended event
-   types are refused. The model needs an `Id` property.
-   Only parameterless validators constructed/certified by Arc run. Constructor
-   dependencies are refused; static/service-locator decision state is still your
-   responsibility. Command-level `[Unprotected]` opts out, not into safety.
-3. Stream-level automatic scopes: `concurrency: true` on routing attributes
-   (`EventStreamId`, `EventStreamType`, `EventSourceType`). It is **not** a guard
-   for the decision: like the default check it reads the tail after `Handle`.
-   Exact returned scopes take precedence; do not combine automatic capture with
-   exact scopes. A guard detects every matching event after its boundary, whoever
-   wrote it, but it protects only guarded decisions, so every writer that decides
-   on the rule needs one, or the rule must be a constraint.
-
-`ARCCHR0011/0012` flag unprotected reads and immediate append bypasses. Return
-events, never append them directly. Read
+Set read protection `On` for new code: `<CratisReadProtection>On</CratisReadProtection>`
+in the project (or `[ReadProtection(ReadProtectionMode.On)]` on one command). Under
+`On`, the read-model parameters of `Handle()` and of the validator constructor are
+the guard, so the state rule is a validator and `Handle()` returns the events.
+Requires Arc 22.106.0. Under `Off` (the default) a plain read guards nothing, even
+inside `Handle()` returning `Result<,>`. Choose the first boundary that fits:
+
+1. A unique value or create-once: a Chronicle constraint, not a read.
+2. One entity's state: a read-model parameter in the validator (this step's example).
+   Several entities: one parameter each, with `[LookUpBy(nameof(Command.Prop))]` on
+   a parameter whose key is not the command's event source id, and `Handle()`
+   returning `IEnumerable<EventForEventSourceId>` with a distinct event type per
+   entity.
+3. A limit inside one stream: a per-stream read model (`[EventStream<TSource>("…")]`)
+   on a command routed `[EventSource<TSource>("…")]` + `[EventStreamId("{Prop}")]`,
+   or `Provide(IStreamReads reads) => reads.ForCommand()` returning `StreamDecision`.
+4. An editing conflict: exact returned scopes from the revision the client sent.
+   `concurrency: true` on routing attributes is **not** a guard: like the default
+   check it reads the tail after `Handle`.
+5. Rich lifecycle: an aggregate; do not also read the same source.
+
+A read under `On` is refused, with HTTP 500, when it cannot be guarded exactly:
+`IReadModels`, `IMongoCollection`, detached reads, an injected `IEventLog.Append`,
+and models that are joins, event-property keyed, filtered or dependency-bearing
+reducers, Pinned or on another sequence (`ReadCannotBeProtected`; mark a deliberate
+advisory read `[Unprotected("why")]`). Several command properties with the model's
+`Id` type are `AmbiguousReadModelLookup`: add `[LookUpBy]`. A lost race is HTTP 400
+`concurrencyViolation` (`ReadChanged`): the client resubmits; Arc does not re-run
+the command. `[ProtectedDecision]` with `DecisionRead<T>` is the older per-command
+opt-in; it still works and is not obsolete. A guard protects only guarded
+decisions: every writer that decides on the rule needs one, or the rule must be a
+constraint.
+
+`ARCCHR0011` (Info, `Off` only) and `ARCCHR0012` flag plain reads and immediate
+append bypasses. Return events, never append them directly. Read
 [protected and stream decisions](../cratis-arc-command/references/decisions-and-routing.md)
-when choosing the guard. This handler excerpt assumes `CartSummary` is an
-admitted projection; domain types are the slice's existing types.
+and
+[choosing how a rule holds](../cratis-chronicle-decision-reads/references/choosing-how-a-rule-holds.md)
+when choosing the guard. The example assumes `CartSummary` is a model-bound
+projection with a `CartId Id`; domain types are the slice's existing types.
 
 ```csharp
-using Cratis.Monads;
-using Cratis.Arc.Chronicle.ReadModels;
+using Cratis.Arc.Commands;
+using Cratis.Arc.Commands.ModelBound;
+using FluentValidation;
 
 [Command]
-[ProtectedDecision]
 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(DecisionRead<CartSummary> cart) =>
-        !cart.Exists
-            ? ValidationResult.Error("Cart must exist.")
-            : cart.Instance.ItemCount >= 3
-                ? ValidationResult.Error("A cart can hold at most 3 items.")
-                : new ItemAddedToCart(ItemId);
+    /// <summary>Adds the item.</summary>
+    /// <returns>The event.</returns>
+    public ItemAddedToCart Handle() => new(ItemId);
 }
+
+public class AddItemToCartValidator : CommandValidator<AddItemToCart>
+{
+    public AddItemToCartValidator(CartSummary? cart) =>
+        RuleFor(c => c.CartId)
+            .Must(_ => cart is { ItemCount: < 3 })
+            .WithMessage("The cart must exist and hold fewer than 3 items.");
+}
+```
+
+Use `Result<TEvent, ValidationResult>` from `Handle()` only when the rule needs a value
+computed there:
+
+```csharp
+public Result<ItemAddedToCart, ValidationResult> Handle(CartSummary? cart) =>
+    cart is not { ItemCount: < 3 }
+        ? ValidationResult.Error("A cart can hold at most 3 items.")
+        : new ItemAddedToCart(ItemId);
 ```
 
 - `Result<TSuccess, TError>` is `Cratis.Monads.Result<,>` from Cratis
@@ -214,6 +255,8 @@ public record AddItemToCart(CartId CartId, ItemId ItemId)
   statements above compile without wrapping.
 - **Return the error; never throw it.**
 - One parameter per logical read model; several reads mean several parameters.
+- Keep the fetch for a *computed* key in `Provide()` with `IDecisionReads.Get`;
+  under `On`, `IReadModels` there is refused.
 
 ⚠️ **Two things the resolution does *not* do.** It does not key off the
 `[ReadModel]` attribute — a read model becomes injectable because a Chronicle
@@ -245,9 +288,13 @@ where absence is *not* `null`.
 ## Step 6 — Specify the rejection
 
 Every rule gets a specification of its failure case, using
-`CommandScenario<TCommand>`. For protected reads, call `UseDecisionReads()`
-before seeding actual events; pinned read models cannot supply a guard. Queue a
-competing append on the relevant route and assert the conflict. Assert **both** that the command did not succeed
+`CommandScenario<TCommand>`. For guarded reads, `new CommandScenario<T>()`
+selects the in-process log from the command's mode and dependencies (do not call
+`UseDecisionReads()`). Seed real events with `Given.ForEventSource(id).Events(...)`
+(pinned read models cannot supply a guard), queue a competing
+`AppendConcurrently(id, events...)` and assert
+`ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation)`.
+For the ordinary rejection, assert **both** that the command did not succeed
 and that it failed *as a validation*:
 
 ```csharp
@@ -273,9 +320,9 @@ the fact. See
 - **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.** A plain read was mistaken for a protected decision;
-  moving it to `Handle()` or returning `Result<,>` does not guard it. Enroll a
-  stream/projection decision read, or use an append-time uniqueness constraint.
+- **Two requests both win.** The project is on `Off` (the default) or `Measure`, so
+  the validator read is a hint; moving it to `Handle()` or returning `Result<,>`
+  does not guard it. Set `On`, or use a stream decision or a constraint.
 - **`ARC0005` on build.** `Provide()` returns a value no `Handle()` parameter
   consumes.
 

package/package/corpus/skills/cratis-chronicle-decision-reads/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-chronicle-decision-reads
-description: Guard a state-dependent Chronicle decision with IDecisionReads, projection admission, ambient unit-of-work enrollment and commit conflict handling, and choose which mechanism makes a write-side rule hold (constraint, decision read, stream decision, aggregate, explicit scope, reactor repair or a plain read). Use when an append must remain valid for the facts read, when a rule must hold under concurrent writers, when choosing whole-source versus stream-scoped reads, or diagnosing DecisionReadRefused and scope conflicts. Do not use for ordinary query reads, append-time uniqueness alone, or defining an Arc command's ProtectedDecision API.
+description: Choose which mechanism makes a write-side rule hold (constraint, Arc read protection with read-model parameters and validators, per-stream read model, stream decision, aggregate, explicit scope, reactor repair or an advisory read), and guard a Chronicle decision directly with IDecisionReads, projection admission, ambient unit-of-work enrollment and commit conflict handling. Use when an append must remain valid for the facts read, when a rule must hold under concurrent writers, when choosing whole-source versus stream-scoped reads, or diagnosing ReadChanged, DecisionReadRefused and scope conflicts. Do not use for ordinary query reads or append-time uniqueness alone; Arc command shapes belong to cratis-arc-command.
 license: MIT
 ---
 
@@ -17,9 +17,22 @@ consistency boundary (DCB), not authorization or a replacement for unique constr
 
 Read [choosing how a rule holds](references/choosing-how-a-rule-holds.md) first
 when the question is which mechanism to use, or before writing code that reads
-state and then appends. It carries the routing steps, the matrix with what not to
-use, and the traps. A plain read, a validator read, `Result<,>` and
-`concurrency: true` are never the guard.
+state and then appends. It carries the routing by rule shape, the matrix with what
+not to use, the refusals, rollout with Measure, testing and the traps.
+
+In an Arc application new code sets read protection `On`
+(`<CratisReadProtection>On</CratisReadProtection>`); `Off` is the default when
+nothing is set. Under `On` the read model is a parameter of `Handle()` or of the
+`CommandValidator<T>` constructor, and the read guards the append; under `Off` and
+`Measure` a validator over a plain read is a hint that guards nothing. A plain read under
+`Off`, `Result<,>` and `concurrency: true` are never the guard.
+`[ProtectedDecision]` with `DecisionRead<T>` is the older per-command opt-in; it
+still works and is not obsolete.
+
+Requires Arc 22.106.0 (read protection) with Chronicle client and kernel 19.71.0.
+Check `dotnet list package --include-transitive`; older Arc has only the
+per-command `[ProtectedDecision]` path, and the choosing reference names where it
+differs.
 
 ## Verified product sources
 
@@ -60,10 +73,12 @@ for the covered APIs, scope lifetime, rollback and immediate-append boundary.
 
 ## Route the work
 
-- For Arc `[ProtectedDecision]`, Arc command/handler shapes and Arc `IStreamReads`,
-  use **cratis-arc-command** and **cratis-arc-command-validation**; do not recreate
-  their unit-of-work ownership in a handler. The Chronicle `DecisionRead<T>`
-  below is not a license to invent an Arc wrapper shape.
+- For Arc read protection, `[LookUpBy]`, `[Unprotected]`, `[ProtectedDecision]`,
+  command/handler shapes and Arc `IStreamReads`, use **cratis-arc-command** and
+  **cratis-arc-command-validation**; do not recreate their unit-of-work ownership in
+  a handler. The Chronicle `IDecisionReads` below is for code outside an Arc
+  command (endpoints, services, `Provide()` for a computed key), not a license to
+  invent an Arc wrapper shape.
 - For a unique value claimed atomically or a closed stream, use
   **cratis-chronicle-event-constraints**. A decision read guards one key's
   history, not a value across keys: it is the wrong tool for uniqueness.
@@ -81,8 +96,12 @@ for the covered APIs, scope lifetime, rollback and immediate-append boundary.
 `Admit<T>()` / `AdmitForStream<T>()` check shape **without I/O**, returning
 `DecisionReadAdmission(IsAdmitted, Reason)`. The model needs an `Id` property
 (string, or a Guid in lowercase hyphenated form) and an event-source-keyed flat
-projection. Reducers, including self-reducing models, are refused with
-`Reducer`; a missing `Id` or an unconvertible key refuses with `KeyConversion`. A successful shape check is not
+projection, or an unfiltered reducer on the event log with no constructor
+dependencies other than `ILogger<T>` (self-reducing models are exempt). Requires
+Chronicle 19.68.0 for reducers. A filtered reducer refuses with `ReducerFilters`,
+one with dependencies with `ReducerDependencies`, an event type at two generations
+with `ReducerGeneration`, and a reducer in a stream-scoped read with
+`StreamScopeNotSupported`. A missing `Id` or an unconvertible key refuses with `KeyConversion`. A successful shape check is not
 runtime read success: definitions, key conversion and fold completion are also
 checked while reading.
 
@@ -112,9 +131,12 @@ projection also needs an explicit stream id, not the default wildcard.
 `AdmitForStream<T>()` checks this shape; unsupported readers/kernels refuse with
 `StreamScopeNotSupported`. Do not fall back to an unguarded query on refusal.
 
-Requires Arc 22.81.0 for these stream overloads inside Arc commands to use
-command protection, caching and enrollment; older Arc refuses them. Check Arc
-as well as the Chronicle client/kernel pair before choosing this path.
+In Arc, prefer a per-stream read model
+(`[ReadModel, EventStream<TSource>("Transactions")]` on a command routed with
+`[EventSource<TSource>("Transactions")]` and `[EventStreamId("{Month}")]`); use
+the stream overloads of `IDecisionReads` in `Provide()` for another stream or
+source. Requires Arc 22.81.0 for the stream overloads inside Arc commands to use
+command protection, caching and enrollment; older Arc refuses them.
 
 ## Commit and inspect conflicts
 
@@ -158,8 +180,8 @@ deciding writer is guarded or the rule is a constraint.
 - The unit commits in the ASP.NET Core middleware: it commits after the response
   and reports no concurrency violation. Call
   `IUnitOfWorkCompletionFeature.CommitAsync()` before responding.
-- Protection is opt-in in Arc (`[ProtectedDecision]`), so an unmarked command with
-  a read model is still unguarded.
+- Arc under `Off` (the default when nothing is set): a command with a read model
+  is unguarded unless it carries `[ProtectedDecision]`. Set `On` for new code.
 
 ## Verify
 

package/package/corpus/skills/cratis-chronicle-decision-reads/references/admission-and-ownership.md

@@ -10,12 +10,13 @@ and `UnitOfWorkLifecyclePolicy.cs`.
 
 ## Why a shape is refused
 
-Admission requires exactly one supported projection on the event log. It is not
+Admission requires exactly one supported projection, or an unfiltered dependency-free reducer, on the event log. It is not
 an adapter for arbitrary read-model storage:
 
 | Reason | Shape to inspect |
 | --- | --- |
-| Reducer / AmbiguousProjection / NotEventLog | reduced model, several projections, or another sequence |
+| Reducer / AmbiguousProjection / NotEventLog | a model with no admitted definition, several projections, or another sequence |
+| ReducerFilters / ReducerDependencies / ReducerGeneration | a reducer with an event filter, constructor dependencies other than `ILogger<T>` (self-reducing models are exempt), or an event type at two generations |
 | Join / Hierarchy | joins, children or nested projections |
 | OpenEndedEventTypes / Derivatives / FromEventProperty | all-events, FromEvery, or event-property routing |
 | NotEventSourceKeyed / KeyConversion | keys not convertible to the admitted raw source key |