@cratis/pi 7.61.0 → 7.62.0

package/package/corpus/skills/cratis-chronicle-decision-reads/references/choosing-how-a-rule-holds.md

@@ -2,14 +2,18 @@
 
 ## Contents
 
-- Route first
+- Defaults
+- Route by rule shape
 - The matrix
-- A plain read guards nothing
+- Reads under Off, Measure and On
 - Constraints
-- Decision reads and protected decisions
+- What a read guard covers
+- Refusals
 - Arc traps
 - Chronicle-only traps
-- Costs and why protection is opt-in
+- Roll out with Measure
+- Test the race
+- Costs
 - Checklist for generated code
 
 <!-- Copyright (c) Cratis. All rights reserved. -->
@@ -20,73 +24,133 @@ question: **which mechanism makes this rule hold while other writers append at t
 same time**, and which look correct but do not. Read it before writing a command,
 validator, endpoint or handler that reads state and then appends.
 
-Checked against the Chronicle and Arc sources. Published guides, which
-this agrees with:
+Published guides this agrees with:
 [Chronicle: choosing how a rule holds](https://www.cratis.io/chronicle/dynamic-consistency-boundary/choosing/),
 [decision reads](https://www.cratis.io/chronicle/read-models/decision-reads/),
 [Arc: choosing how a command's rule holds](https://www.cratis.io/arc/backend/csharp/chronicle/consistency/).
 
-## Route first
-
-Take the first step that matches the rule.
-
-1. **A value must be unique, or something may exist once** (email, ISBN, one
-   registration per source): a constraint. Not a read, not a validator.
-2. **The rule uses data outside Chronicle events**: record the external fact as an
-   event first, then decide on it; otherwise accept the risk and repair. No decision
-   read covers external state.
-3. **A rare violation is acceptable** (overbooking you can compensate): append
-   normally and repair with a reactor that returns a correcting event.
-4. **Someone edited what someone else changed** (the user saw revision N): an explicit
-   concurrency scope built from the revision the user supplied.
-5. **A rule over one key's history** (cannot ship before payment, stock or count
-   on one key): a decision read of a flat, event-source-keyed projection.
-6. **A rule over one stream inside a source**: a stream-scoped decision read
-   (Chronicle) or `IStreamReads`/`StreamDecision` (Arc).
-7. **A rule across two keys** (course capacity and a student's course limit): one
-   decision read per key, one event per event source, one atomic `AppendMany`; or
-   put every fact the rule needs on one event source and use one read.
-8. **Rich behaviour over one lifecycle** (many rules, one key): a richer flat
-   projection read as one decision read, or in Arc an aggregate root.
-9. **Only a UX hint** (disable a button, show seats left): a plain read.
-10. **Only input shape** (range, format, required): a validator. No guard needed.
+## Defaults
+
+- Read protection is `Off` unless the project sets it. New code starts with
+  `On`: `<CratisReadProtection>On</CratisReadProtection>` in the project (it
+  emits `[assembly: ReadProtection(ReadProtectionMode.On)]`; an invalid value
+  fails the build). Existing code moves `Off` to `Measure` to `On`; see
+  [Roll out with Measure](#roll-out-with-measure).
+- Under `On`, 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. The state rule goes in the validator with the read model
+  as a constructor parameter; `Handle()` returns the events.
+- `[ProtectedDecision]` with `DecisionRead<T>` is the older per-command opt-in. It
+  still works and is not obsolete. Use it only in a project that is not on `On`.
+  It is not redundant with `On`; do not remove it because `On` is set without
+  checking what the command takes.
+- Subject ids derive from `EventSourceId` (`record Isbn(string Value) :
+  EventSourceId(Value)`), so the command needs no `[Key]`.
+
+## Route by rule shape
+
+Take the first step that matches. Names S1 to S14 label the shapes used in the
+published scenario catalogue.
+
+1. **A value is unique, or something exists once** (S2: email, ISBN, one card per
+   member): a constraint. Not a read, not a validator.
+2. **The rule uses data outside Chronicle events** (S11): record the external fact
+   as an event first, then decide on it; otherwise accept the risk and repair.
+3. **A rare violation is acceptable, a hint, or a hot key** (S11): no guard.
+   Append and repair with a reactor that returns a correcting event, or mark a
+   deliberate advisory read `[Unprotected("why")]`.
+4. **Someone edited what someone else changed** (S10: the user saw revision N): an
+   explicit concurrency scope built from the revision the client sent.
+5. **One entity's state** (S1: last copy, balance, count): the read model as a
+   parameter under `On`, the rule in a validator. Not an aggregate for one counter.
+6. **Two entities** (S3 loan limit and last copy; S9 course capacity and student
+   limit): two read-model parameters, the second chosen by convention or
+   `[LookUpBy(nameof(Command.Property))]`, and `Handle()` returns
+   `IEnumerable<EventForEventSourceId>` with one event per entity in one atomic
+   append. Use distinct event types per entity.
+7. **A limit inside one stream of one source** (S4: 5000 per account per month): a
+   per-stream read model, `[ReadModel, EventStream<TSource>("Transactions")]`, with
+   the command routed `[EventSource<TSource>("Transactions")]` and
+   `[EventStreamId("{Month}")]`. For a short stream and a question about raw events
+   (S5: approve a period once), a stream decision with `IStreamReads`.
+8. **Process stream with steps and completion** (S6): a definition with a stream per
+   process, declared concurrency and a closed stream.
+9. **Gapless numbers** (S7): a numbering source read with `IDecisionReads` in
+   `Provide()`; `[Unique]` alone gives no duplicates but allows gaps.
+10. **Rich behaviour over one lifecycle** (S8: order lines, pay, ship, cancel): an
+    aggregate root, returning `Commit()` last. An aggregate and a protected read
+    of the same source in one command are refused.
+11. **Moving an existing app to `On`** (S12): `Measure` first.
+12. **A command failed under protection** (S13): the [refusals](#refusals).
+13. **Prove it** (S14): [test the race](#test-the-race).
 
 ## The matrix
 
 | Rule shape | Use | Never use | Too much |
 | --- | --- | --- | --- |
-| Unique value | `[Unique]` property or `IConstraint` | read model check then append | decision read or scope (they guard one key's history) |
-| Create once | `[Unique]` on the event type | "does it exist" read then append | decision read |
-| One key's history, stock, count | decision read; Arc `[ProtectedDecision]` + `DecisionRead<T>` | plain read model, validator read, `concurrency: true` | aggregate for one counter |
-| Two keys | two decision reads + one event per source in one `AppendMany` | two separate appends, a guard on one side only | none |
-| One stream | stream-scoped decision read; Arc `IStreamReads` | whole-source read when one stream matters | none |
-| Edit conflict | explicit scope from the user's revision | last writer wins by accident | constraint |
-| Rich behaviour | richer projection read once; Arc aggregate | rules spread over validators and plain reads | aggregate for one rule |
-| Rare violation acceptable | append, repair with a reactor | presenting a plain read as a guarantee | decision read |
-| UX hint | plain read | treating the hint as enforcement | decision read (several calls and a full fold) |
-| Hot key, long history | shorten histories (split by period or stream); constraint for uniqueness | ignoring cost: each decision read refolds the key | none |
-
-Not a guard: a plain read, a `CommandValidator` that reads, `Result<,>`, returning
-`ValidationResult.Error`, `concurrency: true`, the default optimistic append, a
-reactor, or an `ExpectedRevision` you never pass into a scope.
-
-## A plain read guards nothing
-
-Whatever the backing, a plain read captures no position and enrolls no guard.
-
-| Backing | Freshness | Guard |
+| S2 Unique value, create once | `[Unique]` property or event type, `IConstraint` | "exists?" read then append | read model or decision read (they guard one key's history) |
+| S1 One entity's state | read-model parameter + validator under `On` | validator over a plain read under `Off` (a hint) | aggregate for one counter |
+| S3, S9 Two entities | two parameters, `[LookUpBy]` for the second key, `EventForEventSourceId` per key | a guard on one side only, two separate appends, one read model keyed through an event property | none |
+| S4 Limit inside one stream | per-stream read model on a routed command | whole-source model when another stream's events must not conflict | none |
+| S5 Once per period in a short stream | stream decision (`IStreamReads`) or per-stream model | whole-source read | none |
+| S8 Rich lifecycle | aggregate root | aggregate plus a read of the same source | aggregate for one rule |
+| S10 Edit conflict | explicit scope from the client's revision | `concurrency: true` alone (reads the tail after `Handle`) | constraint |
+| S11 Rare violation, hint, external data | repair reactor, `[Unprotected("why")]`, or record the external fact first | presenting a plain read as a guarantee | any guard |
+| S12 Existing app | `Measure`, then `On` per project | switching a whole app to `On` unmeasured | none |
+| Hot key, long history | shorten histories (split by period or stream); constraint for uniqueness | ignoring cost: each guarded read folds the key's history | none |
+
+Not a guard: a plain read under `Off` or `Measure`, a validator over such a read,
+`Result<,>`, `ValidationResult.Error`, `concurrency: true`, the default optimistic
+append, a reactor, or an `ExpectedRevision` never passed into a scope.
+
+## Reads under Off, Measure and On
+
+| Mode | Read-model parameter, validator constructor | Results and status codes |
 | --- | --- | --- |
-| Materialized projection or reducer (default) | may lag the log | none |
-| `[Passive]` projection | fresh at read time | none |
-| `[Passive]` reducer | fresh at read time | none |
-| Self-reducing model | as its `[Passive]` setting | none |
-
-Passive is fresher, not safer. Capturing the tail yourself before a materialized
-read does not fix it: the read may be older than the position you captured, and
-the events in between are neither seen nor guarded. Do not rebuild a decision read
-by hand. Every Arc read-model injection (`Handle`, `Provide`, validator
-constructor) and every `IReadModels.GetInstanceById` is a plain read, on a
-protected command too.
+| `Off` (default) | plain read; a hint, guards nothing | as today |
+| `Measure` | plain read; Arc reports what `On` would do | same as `Off` |
+| `On` | read fresh from the log; guards the command's append | a lost race is HTTP 400 |
+
+A command overrides the project with `[ReadProtection(ReadProtectionMode.On)]`
+(`Cratis.Arc.Commands`); command-level `[Unprotected]` means `Off`. The runtime
+cap `ReadProtection:MaximumMode` only lowers (a missing or invalid value is `On`,
+no cap); a lowered command logs a startup Warning. With the cap set, the `On`
+behaviour does not hold.
+
+A plain read does not capture a position even when the model is `[Passive]`:
+passive is fresher, not safer. Do not rebuild a guard by hand (capturing the tail
+yourself before a read): the read may be older than the position you captured.
+
+Under `On`:
+
+- `IReadModels`, `IMongoCollection` and detached reads in the command are refused.
+  Take the model as a parameter, or mark the method `[Unprotected("why")]` (it
+  covers the body, not injected parameters).
+- Immediate appends (an injected `IEventLog.Append`) are refused. Return the events.
+- The key is, in order: `[LookUpBy(nameof(Cmd.Prop))]` on the parameter
+  (parameter-only attribute, `Cratis.Arc.Commands`); the single command property
+  whose type equals the model's `Id` type; `AmbiguousReadModelLookup` (HTTP 500) if
+  several match; the command's event source id.
+- Admitted: 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). Refused with
+  `ReadCannotBeProtected` unless `[Unprotected("why")]`: joins and children, a
+  model keyed by an event property, Pinned generation delivery, filtered reducers,
+  reducers with dependencies, other event sequences.
+- A validator's read models are protected when the validator is convention
+  registered (transient). Hand-registered scoped, singleton, factory or instance
+  validators are refused.
+- Under `[ProtectedDecision]` without `On`, only a parameterless validator runs.
+
+Caller severity: model-bound commands accept `X-Allowed-Severity` (`allowedSeverity`).
+Under `Off` and `Measure` a caller sending `Error` removes Error results from validators,
+command filters and `Provide()`, so `Handle()` runs, unless the command declares
+`[BlockOnValidationSeverity(ValidationResultSeverity.Error)]`. Requires Arc 22.108.0:
+a command declared `On` gets an `Error` floor (`Error` and `Unknown` always block; the
+caller can relax only `Warning` and `Information`). Lowering
+`ReadProtection:MaximumMode` at runtime does not remove it, and an explicit attribute
+wins. Before that version a validator's state rule can be skipped by the caller even
+under `On`.
 
 ## Constraints
 
@@ -94,91 +158,113 @@ A constraint binds every writer, whichever client or service appends, per namesp
 and per event sequence. It cannot count, sum or test a predicate; it expresses
 uniqueness (with release on a removal event), create-once and closed streams.
 
-- The claim is settled after the durable append (not yet
-  implemented in every store). A failed index update is logged and a later duplicate
-  may pass until a reindex. SQL and InMemory stores do not yet settle claims
-  A constraint is the right mechanism, not an
-  unconditional proof.
+- The claim is settled after the durable append (not yet implemented in every
+  store). A failed index update is logged and a later duplicate may pass until a
+  reindex. SQL and InMemory stores do not yet settle claims. A constraint is the
+  right mechanism, not an unconditional proof.
 - Tenants in different namespaces can claim the same value.
-- `[RemoveConstraint]` releases attribute constraints (`[Unique]` on a property
-  or on the event type); on a fluent `IConstraint` it compiles and does nothing,
-  so use `.RemovedWith<T>()` there.
+- `[RemoveConstraint]` releases attribute constraints (`[Unique]` on a property or
+  on the event type); on a fluent `IConstraint` it compiles and does nothing, so
+  use `.RemovedWith<T>()` there.
 - It is not re-run when the kernel retries a duplicate sequence number.
 - For a friendly message use `.WithMessage`; Arc maps a violation to HTTP 400.
 
-## Decision reads and protected decisions
-
-A decision read folds an admitted projection in a fresh session after capturing
-the log boundary, and the append is rejected if an event of the model's types
-for that key arrived after the boundary, **whoever wrote it** (the kernel checks the
-stored tail filtered by key, types and route). See the skill's
-[admission and ownership](admission-and-ownership.md) for the refusal list.
-
-- **Admission.** A flat projection keyed by event source, with a finite event-type
-  set and an `Id` property (string, or Guid in lowercase hyphenated form). Reducers,
-  self-reducing models, joins, children, `FromEvery`, event-property routing and
-  other sequences are refused. A model without `Id`, or keyed by a concept that does
-  not convert, refuses with `KeyConversion`; in Arc that surfaces as HTTP 500.
-- **Absent models are guarded.** A concurrent creation conflicts. Do not fabricate a
-  default instance for an absent model.
+## What a read guard covers
+
+Under `On` (and for a Chronicle decision read), if an event of the model's types
+for that key arrives after the read, nothing from the command is written, whoever
+wrote the event. The kernel checks the stored tail filtered by key, types and route.
+
+- **Only that key and those types.** A concurrent event of another type (a rename)
+  does not conflict.
+- **Absent models are guarded.** A concurrent creation conflicts. Do not fabricate
+  a default instance for an absent model.
 - **Cross-key.** A read on key X guards X even when the command appends only to Y.
-  Per-key reads cover only keys in the read set: when new keys can join the set
-  ("a member holds at most three loans" with each loan on its own source), write the
-  facts on a key that is read, usually the member's.
-- **Every deciding writer must be guarded.** The guard detects every matching
-  event appended after its boundary, but it protects only the decision that carries
-  it. If the guarded write lands first, a writer that decides on the same facts
-  without a guard (a plain read, an `[Unprotected]` command, a direct append) can
-  still append on stale state and break the rule. The rule holds only when every
-  writer that decides on it is guarded, or when it is a constraint, which checks
-  every append.
-- **Conflict.** No automatic retry. Reread and decide again, or resubmit. Revise/redact,
-  other sequences, external state, projection definition changes and writes that
-  bypass the kernel's serialized append path (duplicate grain activations, direct
-  storage writes) are outside the guard.
-- **Empty protected commit.** A unit that enrolled a decision read and staged no
-  events appends an empty batch with the guard scopes. The kernel
-  validators (`AppendManyValidator`, `AppendManyForEventSourcesValidator`) accept an
-  empty batch when a scope carries an actual boundary or expects no matching event, and the integration
-  spec `for_ReadModels/when_reading_for_a_decision` shows `AppendMany([], guardedBy:)`
-  succeeds when nothing changed and reports a concurrency violation when the model
-  changed. A kernel that rejects an empty batch ("At least one event is required.")
-  surfaces as `DecisionReadValidateOnlyNotSupported`, which fails closed. Read from
-  source, not run end to end: treat validate-only as supported on a current kernel
-  and assert it with an integration specification before relying on it.
-- **Arc opt-in.** Protection is per command: `[ProtectedDecision]` marks a command
-  that takes `DecisionRead<T>` or command-aware `IDecisionReads`; unmarked commands
-  keep legacy behaviour, `[Unprotected]` opts out. There is no app-wide option, because
-  making it default would refuse validators with dependencies, refused shapes and
-  commands appending through an injected `IEventLog`.
-  The key is the command's event source id; for other keys use
-  `IDecisionReads.Get<T>((ReadModelKey)id)`.
+  Per-key reads cover only keys in the read set; when new keys can join the set
+  ("a member holds at most three loans" with each loan on its own source), write
+  the facts on a key that is read, usually the member's.
+- **Every deciding writer must be guarded.** The guard protects only the decision
+  that carries it. A writer that decides on the same facts through a plain read, an
+  `[Unprotected]` read or a direct append can still append on stale state. The rule
+  holds only when every writer that decides on it is guarded, or when it is a
+  constraint.
+- **Outside the guard:** revisions and redactions (append conditions do not detect
+  them), services and external stores, other event sequences, `[Unprotected]`
+  reads, `Off` mode, projection definition changes, and writes that bypass the
+  kernel's serialized append path (duplicate grain activations, direct storage
+  writes).
+- **Conflict.** Arc and Chronicle do not re-run the command; the fold of a read
+  may retry up to three times. The client reads fresh state and decides again.
+- **Aggregates.** Under `On`, an aggregate and a protected read of the same source
+  are refused (`ReadAndAggregateOnSameSource`); a read of a different source is
+  fine. Arc guards an aggregate's commit with a scope from its rehydration position.
+- **Empty protected commit.** A unit that enrolled a read and staged no events
+  appends an empty batch with the guard scopes. Current kernels validate it and
+  write nothing; a kernel that rejects an empty batch surfaces
+  `DecisionReadValidateOnlyNotSupported`, which fails closed. Assert it in an
+  integration specification before relying on it.
+- **Chronicle model.** Chronicle supports decision models and append conditions
+  within its event-source model: event source id, event source type, event stream
+  type and stream id play the role of tags, one value each per event. It is not a
+  DCB event store: an event belongs to one event source, and a fact about two
+  entities is two events in one atomic append. Custom tags take no part in
+  consistency.
+
+## Refusals
+
+| Seen by the caller | Cause | Do |
+| --- | --- | --- |
+| HTTP 400, `ValidationResult` reason `concurrencyViolation`, `reasonDetail` `ReadChanged`, `state` `{ readModel, key }` | an event of the read model's types for that key arrived after the read; nothing was written | resubmit; the client reads fresh state and decides again |
+| HTTP 400, `ReadIncomplete` | the fold did not finish after three attempts | resubmit |
+| HTTP 500 | the command cannot be guarded: a code or configuration error | change the code; retrying does not help |
+
+The `ReadChanged` message reads "BookStock 'isbn-1' changed after BorrowBook read
+it. Nothing from this command was written; submit it again." It does not name the
+conflicting event. Outside Development, a 500 message is replaced unless
+`ArcOptions.ExposeExceptionDetails` is set. Frontend (TypeScript):
+`CommandResult.isSuccess/isValid/validationResults`, `ValidationResult.reason`
+(`'concurrencyViolation'`, `ValidationResultReason` from `@cratis/arc/validation`),
+`reasonDetail` (a string with no TS constant), `state`.
+
+Common 500 refusals: `ReadCannotBeProtected` (shape, above),
+`AmbiguousReadModelLookup` (add `[LookUpBy]`), `ImmediateAppendWhileReadsAreProtected`
+(return the event), `ReadRefusedWhileReadsAreProtected` and
+`DetachedReadWhileReadsAreProtected` (parameter, `IDecisionReads.Get` in
+`Provide()`, or `[Unprotected("why")]`), `ReadAfterProtectedCommit` (read first,
+return `Commit()` last), `ReadOfSourceWithStagedEvents`, `ExplicitScopeDoesNotCoverReads`,
+`DeclaredRoutingNotCoveredByExplicitScope`, `ConflictingReadProtection`,
+`ReadModelStreamNotOnCommandRoute`.
 
 ## Arc traps
 
 | Trap | What happens | Fix |
 | --- | --- | --- |
-| Read model injected into `Handle`, `Provide` or a validator, then events returned | plain read; two requests both win | decision read, constraint or stream decision |
-| `CommandValidator` that reads state | advisory; also refused on a protected command | validator for shape rules only |
-| Protected command with a discoverable validator that has constructor dependencies or several public constructors | HTTP 500, nothing runs | parameterless validator (exactly one public parameterless constructor); move state rules into the decision |
-| `concurrency: true` on `EventStreamId`, `EventStreamType` or `EventSourceType` | reads the narrowed tail after `Handle`; changes granularity, not the decision. A command that also reads `IReadModels` still triggers `ARCCHR0011` | decision read, explicit scope or stream decision |
+| Read model parameter or validator under `Off` or `Measure`, then events returned | plain read; two requests both win | set `On`, or use a constraint or stream decision |
+| Validator over a plain read under `Off` | a hint with a friendly message; guards nothing | `On` |
+| `concurrency: true` on `EventStreamId`, `EventStreamType` or `EventSourceType` | reads the narrowed tail after `Handle`; changes granularity, not the decision | `On`, explicit scope or stream decision |
 | Default (no attributes) | Arc reads the tail when the unit of work commits, after `Handle` | only protects the window between that read and the write |
-| First append into a scope | unchecked unless `ChronicleOptions.ConcurrencyOptions.CheckFirstAppendIntoAScope` is set | constraint, or an aggregate (new aggregates expect no first event) |
-| Two or more key candidates (`EventSourceId`-typed, `[Key]`-marked or implicitly convertible) | `ARCCHR0002` warns, and `[Key]` does not silence it. At runtime Arc silently takes the first eligible property in declaration order (`EventSourceId`-typed or `[Key]`-marked, no priority for derived types; an unmarked `ConceptAs<Guid>` is not eligible). With one candidate Arc keys by it silently; with none each call gets a new id | implement `ICanProvideEventSourceId` |
+| First append into a scope | unchecked unless `ChronicleOptions.ConcurrencyOptions.CheckFirstAppendIntoAScope` is set | constraint, or an aggregate |
+| A `UsingKey(e => e.Member)` projection read | refused (`ReadCannotBeProtected`) | append a fact to the entity the model is keyed by |
+| Two or more key candidates (`EventSourceId`-typed, `[Key]`-marked or implicitly convertible) | `ARCCHR0002` warns, and `[Key]` does not silence it; Arc takes the first eligible property in declaration order | implement `ICanProvideEventSourceId` |
+| Per-stream model on a command without a route | `ReadModelStreamNotOnCommandRoute` (500, analyzer `ARCCHR0037`) | add `[EventSource<TSource>("Stream")]` and `[EventStreamId("{Prop}")]` |
+| Whole-source read beside a per-stream read of the same source | both drop the stream dimensions (Measure reports `coarsened`) | keep one granularity |
 | No id property | a random event source id per call; nothing can conflict | give the command a key |
-| `[Unprotected]` command taking `DecisionRead<T>` | resolves to an unguarded read | use `[ProtectedDecision]` |
 | Injected `IEventLog.Append` in `Handle` | immediate write that survives a conflict rollback | return events |
 | Aggregate `Commit()` whose result is ignored, or `Failed()` without `Commit()` | staged events still commit | return `await aggregate.Commit()` |
-| Aggregate with an enrolled decision read | `Commit()` throws `ProtectedUnitOfWorkRequiresOwner` | choose one mechanism per command |
-| Aggregate for a rule across aggregates | each aggregate guards only itself | cross-key decision reads |
-| Tests without `UseDecisionReads()` and a competing `AppendConcurrently` | the race is never exercised | `CommandScenario` with decision reads |
+| `[Unprotected]` command taking `DecisionRead<T>` | resolves to an unguarded read | remove `[Unprotected]` |
+| Tests without `AppendConcurrently`, or a scenario left in legacy mode | the race is never exercised | [test the race](#test-the-race) |
 
 ## Chronicle-only traps
 
 - Decision read, then plain `IEventLog.Append`: the immediate append bypasses the
   guard. Stage with `Transactional.Append`, or pass `guardedBy:` to `AppendMany`.
 - `Get<T>` needs an ambient unit of work. `GetDetached<T>` enrolls nothing until you
-  pass it to `AppendMany(..., guardedBy:)` or `AddDecisionRead`.
+  pass it to `AppendMany(..., guardedBy:)` or `AddDecisionRead`. A unit can also
+  call `EnforceReadProtection()` and `AllowReads(ReadAllowance.Advisory|Contributed,
+  reason)`; `GetAppendConditions()` returns the `AppendCondition` values
+  (`Cratis.Chronicle.Transactions`).
+- Stream reads: `IReadModels.GetInstanceById<T>(EventSourceId, EventStreamId)` throws
+  `StreamScopeNotSupported` unless the implementation supports it (analyzer CHR0064).
 - The ASP.NET Core middleware commits **after** the response. Call
   `IUnitOfWorkCompletionFeature.CommitAsync()` before responding and check
   `IsSuccess` and `GetDecisionConflicts()`; the middleware reports no concurrency
@@ -191,22 +277,75 @@ stored tail filtered by key, types and route). See the skill's
 - Arc has a static class also named `ConcurrencyScopeBuilder`; in an Arc project
   qualify Chronicle's builder.
 
-## Costs and why protection is opt-in
+## Roll out with Measure
+
+Steps: update the packages, set `<CratisReadProtection>Measure</CratisReadProtection>`,
+run the application and its tests, read the report, fix or annotate each finding,
+then set `On` per project. Behaviour for callers does not change under `Measure`.
+
+- The report: meter `Cratis.Arc.ReadProtection`, counter
+  `cratis.arc.read_protection.events` (tags `command`, `category`, `model`,
+  `reason`), span event `read-protection.plan`, and a Warning once per command and
+  category for `refused_read`, `immediate_append` and `scope_refusal`.
+- Categories: `protected_read`, `refused_read` (reason names the cause),
+  `advisory_read`, `unknown_dependency`, `redirect` (add `[LookUpBy]`),
+  `immediate_append` (return the event), `conflict_today`, `self_write`,
+  `coarsened`, `displacement`, `scope_refusal`, `matching_events_since_start`
+  (someone else's matching event arrived mid-command: `On` might have returned
+  400, a real race), `measurement_unavailable`, `mode_lowered`.
+- Measure is best effort: one extra awaited call per command plus sampled
+  background scans. A report is a set of hypotheses.
+- Fixes: reducer with dependencies or filters, join or children, event-property
+  key, Pinned delivery or `IMongoCollection`: change the read as the refusal says,
+  or annotate `[Unprotected("why")]`. Under `On`, `ARCCHR0011` no longer applies;
+  fix `ARCCHR0024`, `0028` and `0033`.
+
+## Test the race
+
+`new CommandScenario<T>()` selects the in-process decision log from the command's
+read-protection mode and dependencies (for example under `On`); do not call
+`UseDecisionReads()` (it is hidden and unnecessary). An `Off` command with no
+protected dependency stays in legacy mode with pinned read models, which cannot
+prove a race. Seed with
+`scenario.Given.ForEventSource(id).Events(...)` (for a routed stream
+`.OnRoute(route).Events(...)`). Guarded state needs events: protected reads fold the
+event log and ignore a pinned model, and `DecisionRead<T>` parameters reject one.
+`.ReadModel(m)` only pins an advisory (plain) read. Then queue a competing event with
+`scenario.AppendConcurrently(id, events...)` and execute:
+
+```csharp
+await using var scenario = new CommandScenario<BorrowBook>();
+scenario.Given.ForEventSource(isbn).Events(new BookAdded(Copies: 1));
+scenario.AppendConcurrently(isbn, new BookBorrowed(other));
+var result = await scenario.Execute(new BorrowBook(isbn, me));
+result.ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation);
+```
+
+There is no `scenario.AppendConditions`. A pure decision test builds the command
+and the validator with a hand-made read model. Chronicle-direct code asserts
+`unitOfWork.GetAppendConditions()`. A default `EventScenario` scope strategy
+returning `None` is not concurrency evidence.
+
+## Costs
 
-A decision read makes about four calls per attempt (up to three attempts), folds the
-key's whole history of the model's types on every read, shares a per-model-type
+A guarded read makes about four calls per attempt (up to three attempts), folds
+the key's whole history of the model's types on every read, shares a per-model-type
 projection grain across keys and tenants, and is not retried on conflict. Use it
 where histories are short and write contention per key is low; shorten histories
 before reaching for it on a hot key. A constraint costs one index lookup inside the
-append. Decision reads are .NET only.
+append. Decision reads exist in the .NET and Elixir clients.
 
 ## Checklist for generated code
 
-- Name the mechanism and say why the rule shape needs it. A plain read, validator,
-  `Result<,>` or `concurrency: true` is never presented as the guard.
-- Uniqueness is a constraint. A state rule has a decision read, scope or stream
-  decision enrolled **before** the events are staged.
-- The decision-read model is admitted (flat projection, `Id`, event-source keyed).
-- Cross-key rules append one event per source atomically.
-- A specification interleaves a competing append and asserts the conflict.
-- What stays unguarded (an unguarded writer's own decision, external state, revisions) is stated.
+- Name the mechanism and say why the rule shape needs it. A plain read, a
+  validator under `Off`, `Result<,>` or `concurrency: true` is never presented as
+  the guard.
+- New code sets `On`. Uniqueness is a constraint. A state rule is a read-model
+  parameter in a validator, a per-stream model, a stream decision, an aggregate or
+  an explicit scope, enrolled **before** the events are staged.
+- The model is admitted (source-keyed projection or admitted reducer, `Id`).
+- Cross-key rules append one event per source atomically, with distinct event types.
+- A specification interleaves a competing append and asserts
+  `ConcurrencyViolation`.
+- What stays unguarded (an unguarded writer's own decision, external state,
+  revisions, `[Unprotected]` reads, `Off` mode) is stated.

package/package/corpus/skills/cratis-chronicle-event-constraints/SKILL.md

@@ -15,7 +15,7 @@ Constraints are discovered automatically. There is no registration call.
 
 A constraint binds **every** writer, whichever client or service appends, so it is
 the mechanism for uniqueness and create-once. It cannot count, sum or test a
-predicate: capacity and stock rules need a decision read, a stream decision or an
+predicate: capacity and stock rules need a guarded read (read protection `On`), a stream decision or an
 aggregate. Read [choosing how a rule holds](../cratis-chronicle-decision-reads/references/choosing-how-a-rule-holds.md)
 when it is unclear which one a rule needs. Limits: the claim is settled after the
 durable append, so a failed index update can let a later duplicate
@@ -43,9 +43,9 @@ memory.
 - The rule rejects **command input** — a range, a format, a cross-field
   condition: use `cratis-arc-command-validation`.
 - The rule is state-dependent (a count, a capacity, a status) and needs
-  concurrency protection: use enrolled stream/projection decision reads with
-  `cratis-arc-command-validation` and `cratis-chronicle-decision-reads`. Plain
-  injected models, validators and `Result<,>` alone remain advisory.
+  concurrency protection: use read protection `On` or stream decision reads with
+  `cratis-arc-command-validation` and `cratis-chronicle-decision-reads`. Injected
+  models and validators under `Off` (the default), and `Result<,>` alone, remain advisory.
 - You are creating or changing a read model that the rule reads: use
   `cratis-chronicle-read-model`.
 - You are writing the specification and want the `EventScenario` mechanics in

package/package/corpus/skills/cratis-chronicle-event-modeling/SKILL.md

@@ -156,14 +156,16 @@ If a field can only be filled by reaching into another behavior's read model to
 a wrong stream boundary. Fix the model. A read-only cross-slice read through
 Chronicle is allowed where the rule needs it (an injected read model read by
 explicit key, or a `[Passive]` projection for a current read; a rule that must hold under
-concurrency needs a decision read or constraint, see
+concurrency needs read protection `On`, a stream decision or a constraint, see
 [choosing how a rule holds](../cratis-chronicle-decision-reads/references/choosing-how-a-rule-holds.md)); see
 Cross-slice patterns in `rules/vertical-slices.md`. Make such a read deliberate
 and name it in the brief, with the consistency it needs: a rule that must hold
 under concurrency needs enrolled guarded reads, not plain injection or a stale
-materialized snapshot. In Arc v22.75.0 use `IStreamReads`/`StreamDecision` for one
-stream or `[ProtectedDecision]` + admitted `DecisionRead<T>` for projected state;
-`Result<,>` alone supplies rejection, not a concurrency guard.
+materialized snapshot. In Arc use read protection `On` with the read model as a
+validator or `Handle()` parameter for projected state, a per-stream read model or
+`IStreamReads`/`StreamDecision` for one stream (`[ProtectedDecision]` +
+`DecisionRead<T>` is the older per-command opt-in); `Result<,>` alone supplies
+rejection, not a concurrency guard.
 
 ## Compliance modeling
 

package/package/corpus/skills/cratis-chronicle-read-model/SKILL.md

@@ -129,7 +129,8 @@ builder when switching and verify storage/replay separately from output equality
 Read [projection behavior](../cratis-chronicle-projection/SKILL.md) for mappings
 and [reducers](../cratis-chronicle-reducer/SKILL.md) for complete signatures,
 null deletion, replay hooks and preserving admission/ordering guards. Reducers
-are source-keyed, have no native joins and are refused by decision reads.
+are source-keyed and have no native joins; decision reads and Arc read protection `On`
+admit only unfiltered reducers without constructor dependencies.
 
 ## Step 4 — Add a query surface, if the model is read from outside
 

package/package/corpus/skills/cratis-chronicle-reducer/SKILL.md

@@ -214,9 +214,12 @@ model type** and makes it passive as a whole: no sink, nothing materialized, and
 the instance is computed on demand when it is read. Reach for it when a
 command-side read needs the model current at the moment it is read. Passive is
 fresher, not safer: a passive reducer read captures no position and guards nothing,
-and a reducer (or a self-reducing model) is refused by
-decision reads. For a rule that must hold under concurrent writers use a flat
-projection with a decision read; see
+and a plain read of a reducer guards nothing. An unfiltered reducer without
+constructor dependencies (other than `ILogger<T>`; self-reducing models are exempt)
+is admitted by decision reads and by Arc read protection `On` (Chronicle 19.68.0);
+a filtered reducer or one with dependencies is refused, and no reducer is admitted in
+a stream-scoped read. For a rule that must hold under concurrent writers read an
+admitted model under `On`; see
 [choosing how a rule holds](../cratis-chronicle-decision-reads/references/choosing-how-a-rule-holds.md).
 
 ## Discovery, upgrades and ownership

package/package/corpus/skills/cratis-code-review/SKILL.md

@@ -81,10 +81,13 @@ there is nothing to review under a red build.
 - Logging lives in a `*Logging.cs` partial with `[LoggerMessage]`, not inline in
   domain code.
 - No shared mutable state between commands.
-- Plain injected models are advisory, not a concurrency guard. Review guarded
-  stream/projection reads and actual conflict specs (`UseDecisionReads()`).
+- Read protection is `Off` by default; new code sets `<CratisReadProtection>On</CratisReadProtection>`.
+  Under `Off` an injected model or validator read is advisory, not a concurrency guard.
+  Under `On`, review that state rules sit in validators or handlers with the model as
+  a parameter, `[Unprotected("why")]` carries a real reason, and a conflict spec
+  (`AppendConcurrently` plus `ConcurrencyViolation`) exists.
 - Use `Cratis.Arc.Core.CodeAnalysis` and `Cratis.Arc.Chronicle.CodeAnalysis`.
-  ARCCHR0011/0012 (Info) flag unprotected reads/immediate
+  ARCCHR0011 (Info, `Off` only) and 0012 flag unprotected reads/immediate
   bypasses; 0013 (Info) recommends definitions; 0014 checks declared observer
   streams; 0015 warns on nullable events; 0016 flags ignored concurrency flags;
   0017/0018 check stream-id templates; 0019 warns on folds exposed as queries.