@cratis/pi 7.61.0 → 7.63.0

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 |