@cratis/pi 7.123.0 → 7.125.0

package/package/corpus/skills/cratis-application-slice-specifications/SKILL.md

@@ -10,8 +10,10 @@ metadata:
 
 Start a pure decision with a plain method call: `Handle()`,
 `Handle(providedValue)`, reducer logic or a reactor's decision needs no host,
-services or harness. Add a scenario where the pipeline, validation,
-authorization, constraints or projections contribute proof. The scenario family
+services or harness, including direct validator calls with supplied read-model state.
+Add scenarios only for pipeline/authorization wiring, constraints, declarative
+mapping; follow the
+[scenario selection and cost rule](../../rules/specs.scenarios.csharp.md). The scenario family
 exercises the real Arc and Chronicle code paths in-process — no HTTP, no fixture,
 no server.
 
@@ -67,7 +69,8 @@ repository before claiming support for another version.
 
 When the slice has a contract — a `.play` slice with its `specification`
 blocks, or an agreed outline — its specifications are the **minimum list**: each
-one becomes a specification class here, named after it. Steps 3–7 then add what
+gets concrete assertions. Decision outcomes use focused classes; declarative
+read-model mappings share one class per model with many read-only facts. Steps 3–7 then add what
 the code reveals (each validator rule, each constraint). A rule found in the code
 with no contract specification is a proposal for the contract (the `.play` model when one covers the slice, otherwise the agreed outline), not silent coverage:
 list it in the report and, where a model exists, route it to
@@ -106,15 +109,16 @@ A behavior covering several subjects groups under
 
 Specify a pure decision with the plain `Specification` base first. A direct
 `Handle()` call does not run validation, authorization, `Provide()` or operations;
-keep a scenario for that wiring and for appended-event behavior.
+add a scenario only where that wiring adds proof. Keep shared lifecycle enabled
+and measure scenario cost as described in the linked rule.
 
 | Slice type | Scenario | Skill |
 | --- | --- | --- |
-| Pure command decision, reducer logic or reactor decision | Plain method call with `Specification` (default) | `cratis-specifications-csharp` |
+| Pure command/validator decision, reducer logic or reactor decision | Plain method call with `Specification` and supplied read-model state (default) | `cratis-specifications-csharp` |
 | State Change — command pipeline and appended events | `CommandScenario<TCommand>` | this one |
 | Append semantics, a constraint | `EventScenario` | `cratis-chronicle-event-specifications` |
 | Query pipeline — arguments, authorization, validation, interceptors | `QueryScenario<TReadModel>` | [query and decision scenarios](references/query-and-decision-scenarios.md) |
-| State View — a projection or reducer | `ReadModelScenario<TReadModel>` | `cratis-chronicle-read-model-specifications` |
+| State View — declarative mapping or reducer wiring | One `ReadModelScenario<TReadModel>` class per read model, many assertions on shared setup | `cratis-chronicle-read-model-specifications` |
 | Automation or Translation — a reactor | `ReactorScenario<TReactor>` | `cratis-specifications-csharp` |
 | A host, transport, or real-infrastructure boundary | Out-of-process integration | `cratis-specifications-csharp` |
 
@@ -131,9 +135,11 @@ exception diagnostics, synchronous handler throws and UTC context defaults.
 
 One specification class for **each** of:
 
-1. **The happy path** — the command succeeds and the expected event is appended.
-2. **Each validation failure** — one `and_` class per `CommandValidator` or
-   `ConceptValidator` rule.
+1. **The happy path** — a plain call returns the expected event; add pipeline
+   coverage only for behavior that call cannot prove.
+2. **Each validation failure** — instantiate `CommandValidator` or
+   `ConceptValidator` with the required state and validate directly. Use a
+   scenario only to prove pipeline wiring.
 3. **Each business-rule rejection** — one `and_` class per condition in
    `Handle()` that inspects a read model.
 4. **Each constraint violation** — one class per constraint, written with
@@ -194,24 +200,27 @@ _scenario.Given.ForEventSource(_cartId).Events(new ItemAddedToCart(itemId));
 _scenario.Given.ForEventSource(_cartId).ReadModel(new CartSummary { ItemCount = 3 });
 ```
 
-Prefer seeding **events**: it exercises the projection that production relies on,
-so a specification cannot pass against a read-model shape the projection never
-produces. Pin an instance only when the events would be noise.
+Supply read-model state for a business decision. Seed events only when the
+history itself matters, such as projection mapping or append-time uniqueness;
+do not replay a projection merely to feed a pure command decision.
 
 Both builder methods return `void`; there is nothing to await.
 
-That is **legacy** read-model mode: seeded events populate an in-memory model,
-not the append log. A command under read protection `On`, with a per-stream model or
-with `[ProtectedDecision]` selects the decision mode itself (no `UseDecisionReads()`
-call); actual events and decisions then share one in-process log. Pinned models
-cannot supply decision guards. Read
-[query and decision scenarios](references/query-and-decision-scenarios.md) when
-specifying query pipelines, routed conflicts, projection admission or completion.
+Read protection is invisible to application spec authors. Never configure modes,
+call `UseDecisionReads`, simulate competing appends (`AppendConcurrently`), seed
+events solely for infrastructure, or re-prove the platform concurrency/guard
+matrix: give state, assert the outcome. Keep one cheap assembly-level
+`DecisionReadAdmissions.ShouldAdmitDecisionReadsIn(assembly)` spec for the
+application's own model/projection shapes: its only decision-read spec obligation.
+If the harness cannot accept required state, report the upstream gap; never weaken
+production guards for test speed. Read
+[query and decision scenarios](references/query-and-decision-scenarios.md) for
+query pipelines.
 
 Validator and `Provide()` dependencies are registered in `_scenario.Services`;
 the concrete validator itself is discovered automatically.
 
-## Step 6 — Assert twice on every unhappy path
+## Step 6 — Assert twice on pipeline validation failures
 
 ```csharp
 [Fact] void should_not_succeed() => _result.ShouldNotBeSuccessful();
@@ -219,7 +228,9 @@ the concrete validator itself is discovered automatically.
 ```
 
 `ShouldNotBeSuccessful()` alone cannot distinguish a validation rejection from an
-unhandled exception, so both facts are required. **Do not assert on a message
+unhandled exception, so both facts are required for pipeline validation specs.
+For direct validator calls, assert the validation result and the specific rule.
+**Do not assert on a message
 string by default** — it is presentation text; assert one only when that exact
 text is the specified behavior, and name that requirement in the fact. A `.play`
 specification may pin the message (`then error "<message>"`); prefer pinning the

package/package/corpus/skills/cratis-application-slice-specifications/references/query-and-decision-scenarios.md

@@ -3,7 +3,7 @@
 ## Contents
 
 - Query pipeline
-- Guarded decisions
+- Decision specifications
 - Sources
 
 <!-- Copyright (c) Cratis. All rights reserved. -->
@@ -47,8 +47,10 @@ arbitrary stores.
 Requires Arc 22.87.0 and Chronicle 19.54.0 for scenario `IReadModels.Observe<T>(filter)` snapshots from given events or pinned models,
 including new emissions after scenario command appends. Pins need a readable key
 or throw `PinnedReadModelCannotBeObserved`.
-Requires Arc 22.91.1 and Chronicle 19.59.1 for default-mode children, joins and reducers to observe through scenario-owned storage (the initial Arc package was not published); older default mode cannot
-observe children, so use decision mode. Check both package versions.
+Requires Arc 22.91.1 and Chronicle 19.59.1 for children, joins and reducers to
+observe through scenario-owned storage (the initial Arc package was not published).
+Check both package versions; upgrade or report a harness gap rather than configuring
+decision-read modes in application specs.
 
 For a query with `by`, `filter` or `scoped to`, seed instances for two keys, two filter values
 or two tenants with distinct callers, as applicable, and assert that each call returns only its
@@ -65,50 +67,50 @@ execution runs the query through Arc's hosted query pipeline and establishes con
 before `Provide`/`Handle` on the command path. A direct static query call does not
 cover those pipeline hooks.
 
-## Guarded decisions
-
-Create `new CommandScenario<TCommand>()`. It selects Chronicle's in-process decision
-mode from the command's read-protection mode and dependencies (for example under
-`On`, or with a per-stream read model); do not call `UseDecisionReads()`, which is
-hidden and unnecessary. This mode shares **one real in-process event log** among
-given events, guarded reads, constraints and returned appends. Seed actual events
-(`Given.ForEventSource(id).Events(...)`, or `.OnRoute(route).Events(...)`); protected
-reads fold the log and ignore a pinned `.ReadModel(m)`, which only pins an advisory
-(plain) read. Assert a lost race with
-`result.ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation)`
-after `scenario.AppendConcurrently(id, events...)`. There is no
-`scenario.AppendConditions`. An `Off` command with no protected dependency stays in
-legacy mode.
-`Given.ForEventSource(id).OnRoute(route).Events(...)` preserves routing;
-`scenario.EventRoutes.For<TSource>(stream).WithStreamId(...)` creates the route.
-Queue interference using `AppendConcurrently(id, route, event)` and assert a
-nonempty decision is rejected on the intended boundary. An empty identical-retry
-append deliberately returns no scope and cannot prove the conflict guard.
-
-Requires Arc 22.92.0 for `AppendConcurrently` without decision reads; older Arc
-needs decision mode. Its early interference does not make a plain read guarded;
-assert the actual scope/outcome, not merely that the competing append ran.
-
-`ShouldHaveCompletedStream(type, id)` proves successful completion;
-`ShouldHaveCompletedStream(ClosedStreamScope)` asserts the exact source and route.
-`DecisionReadAdmissions.ShouldAdmitDecisionReadsIn(assembly)` checks projection
-admission in assembly-wide specs. These APIs are in
-`Cratis.Arc.Chronicle.Testing.Commands`. Routed seeding is refused in legacy mode.
-
-The old warnings that command `Given` never reaches the event log and that its
-read-model dictionary is the only backing are **legacy-mode** warnings, not a
-reason to fake protected decision readers. Keep non-key enumeration/provider
-boundaries explicit in either mode; decision mode is not a MongoDB substitute.
-
-The default Chronicle-backed `CommandScenario` discovers constraints
-automatically. Assert real constraint refusals instead of disabling them. Do not
-subclass or substitute Chronicle's `EventScenario`; use its public
-seeding/assertion surface or explicit `UseDecisionReads` mode, not a synthetic
-EventScenario facade.
+## Decision specifications
+
+Start with a direct decision call supplied with read-model state. Follow the
+[scenario rule](../../../rules/specs.scenarios.csharp.md): application authors do
+not select read-protection modes, call `UseDecisionReads`, seed events only to
+satisfy infrastructure, or prove the platform concurrency, conflict-refusal or
+isolation matrix. Arc/Chronicle specs own it. The application's only decision-read
+spec obligation is one cheap assembly-level check of its own model/projection
+shapes, not one scenario per decision:
+
+```csharp
+DecisionReadAdmissions.ShouldAdmitDecisionReadsIn(assembly);
+```
+
+This API is in `Cratis.Arc.Chronicle.Testing.Commands`; it discovers declared reads
+and checks admission without executing commands or running Chronicle. Keep the
+spec's discovered projections representative of production; spec-only competing
+definitions can make a model ambiguous. Explicit `IDecisionReads.Get` calls inside
+method bodies are not statically discovered. If the harness cannot accept
+required state for a business decision, report the upstream gap; never weaken
+production guards or invent guard doubles.
+
+Do not add a scenario to prove a race. A rule such as "two callers reserving the last
+seat yield one reservation" is specified from state: supply a read model with no seats
+left and assert the rejection, then supply one seat and assert the reservation.
+Simulating competing appends is a framework concern a developer should not think
+about in tests; Arc and Chronicle prove it. `AppendConcurrently` stays a public but
+advanced framework-verification API (hidden from IntelliSense), outside application
+testing guidance; use it only for a specific, explicit need. Production expresses
+the guarantee with the read model as a `Handle` parameter under
+`[ReadProtection(On)]`. Direction, not a release claim: Arc will obsolete
+`UseDecisionReads`; do not adopt it.
+`ShouldHaveCompletedStream(ClosedStreamScope)` may assert that a decision completed a
+stream at the exact source and route (`Cratis.Arc.Chronicle.Testing.Commands`).
+Use event history only when it is part of the domain example.
+
+The Chronicle-backed `CommandScenario` discovers constraints automatically.
+Assert domain constraint refusals instead of disabling them; use `EventScenario`
+for append-time uniqueness examples. Do not subclass or substitute its engine.
+Provider boundaries remain separate: state fixtures are not a MongoDB substitute.
 
 ## Sources
 
 - [Query scenarios](https://github.com/Cratis/Arc/blob/main/Documentation/backend/csharp/testing/query-scenario.md)
 - [Stream decisions and routed specs](https://github.com/Cratis/Arc/blob/main/Documentation/backend/csharp/chronicle/commands/stream-decisions.md)
 - [Decision-mode extension](https://github.com/Cratis/Arc/blob/main/Source/DotNET/Chronicle.Testing/Commands/CommandScenarioChronicleExtensions.cs)
-- [Admission assertion](https://github.com/Cratis/Arc/blob/main/Source/DotNET/Chronicle.Testing/Commands/DecisionReadAdmissions.cs)
+- [Application-shape admission assertion](https://github.com/Cratis/Arc/blob/main/Source/DotNET/Chronicle.Testing/Commands/DecisionReadAdmissions.cs)

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

@@ -274,6 +274,11 @@ Components guidance, not to this skill.
 
 ## Verify
 
+Start pure `Handle()` and validator decisions with direct calls and supplied
+read-model state. Add scenarios only for pipeline/authorization wiring,
+constraints, never read-protection plumbing or simulated concurrency;
+follow the [scenario selection and cost rule](../../rules/specs.scenarios.csharp.md).
+
 - The command is a `record`, carries `[Command]`, and declares a public instance
   `Handle`.
 - The return shape matches what the command is supposed to do, and any

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

@@ -15,6 +15,13 @@ Source: Arc. These features require `Cratis.Arc.Chronicle`.
 
 ## Pick the guarded read
 
+**Idiomatic default:** a state-dependent rule takes the read model as a `Handle()`
+(or validator-constructor) parameter, with `[ReadProtection(On)]` where it must hold
+under concurrent writers. Do not take `IDecisionReads` in `Handle()`: it is not
+recommended with Arc and is not an investment target. A computed key stays in
+`Provide()` until a read-model parameter covers it. Direction, not a release claim:
+Arc will pin protected parameters so the idiomatic shape needs no further ceremony.
+
 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
@@ -175,20 +182,21 @@ source id/type and stream route; reactor tuples/collections cannot mix it with e
 
 ## Decision specifications
 
-`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.
+Call `Handle()` and validators directly with read-model state for pure business
+decisions. Follow the [scenario rule](../../../rules/specs.scenarios.csharp.md):
+read-protection plumbing is invisible to application spec authors. They never
+call `UseDecisionReads`, configure modes, simulate competing appends
+(`AppendConcurrently`), seed events solely for infrastructure, or re-prove the platform concurrency, conflict-refusal or isolation matrix;
+Arc/Chronicle specs own it. The application's only decision-read spec obligation
+is one cheap assembly-level shape-admission spec from that rule.
+Never weaken production guards for test speed. Report a harness state-setup gap
+upstream instead of working around it in application specs.
+
+Add scenarios for pipeline/authorization wiring or constraints. Never simulate
+competing appends: assert the business outcome from supplied state (for example, no
+copies left rejects). Read
+[query and decision scenarios](../../cratis-application-slice-specifications/references/query-and-decision-scenarios.md)
+for the query and decision setup. Keep shared lifecycle on and measure the added cost.
 
 ## Sources
 

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

@@ -98,18 +98,16 @@ use an appropriate constraint or explicit concurrency scope for them.
 
 ## Specify the collision
 
-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,
-mixed returned/direct writes, and a nested rejection rolling back the outer unit.
-
-Requires Arc 22.95.1 for `GeneratedIdentifierCollisionRequiresDecisionReads`:
-default scenario mode fails fast when given events and a guarded pin share an id.
-Older default mode silently leaves the append log empty; it cannot prove occupancy.
-Run `dotnet build -c Debug` and the affected specification project with
-`dotnet test`; all collision and empty-source facts must pass.
+The generated-value collision guard and its route, append and rollback matrix
+belong in Arc/Chronicle specs, not every application. Follow the
+[scenario rule](../../../rules/specs.scenarios.csharp.md): application authors
+supply state and assert business decisions without configuring decision reads
+or seeding events solely to satisfy infrastructure.
+
+Add a scenario only for an application-owned collision/retry policy or generated
+parameter pipeline wiring that a direct call cannot prove. `PinGeneratedValue(name, id)`
+can make that domain example deterministic; assert its specified outcome, not
+the platform guard matrix. If a harness rejects the state setup (for example
+`GeneratedIdentifierCollisionRequiresDecisionReads`), report the upstream gap
+rather than calling compatibility switches or weakening production guards.
+Build the affected project and run its specifications with the project runner.

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

@@ -266,15 +266,19 @@ authorization and camelCase member paths are separate contracts.
 
 ## Step 6 — Specify the rejection
 
-Every rule gets a specification of its failure case, using
-`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*:
+Every rule gets a failure specification: instantiate the validator with its
+read-model state and validate directly, asserting the specific rejection. Add
+`CommandScenario<TCommand>` only for pipeline/authorization wiring, constraints.
+Follow the
+[scenario rule](../../rules/specs.scenarios.csharp.md): application specs never
+configure read-protection modes, call `UseDecisionReads`, simulate competing appends, seed events solely for
+infrastructure, or re-prove platform guards. Keep the single cheap assembly-level
+application-shape admission spec specified by that rule; it is the application's
+only decision-read spec obligation. Report harness gaps upstream; never weaken
+production guards for speed.
+
+For a pipeline validation rejection, assert **both** that the command did not
+succeed and that it failed *as a validation*:
 
 ```csharp
 [Fact] void should_not_succeed() => _result.ShouldNotBeSuccessful();
@@ -309,6 +313,8 @@ the fact. See
 
 `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.
+run the specification project using its runner, with a direct validation
+specification per rule and focused pipeline specs where wiring matters. Pipeline
+validation specs assert both `ShouldNotBeSuccessful()` and
+`ShouldHaveValidationErrors()`. A rule with no red-first specification has not
+been shown to reject anything.

package/package/corpus/skills/cratis-arc-command-validation/references/protected-validator-construction.md

@@ -87,8 +87,12 @@ NativeAOT support for the unrelated dynamic validator opt-in.
 
 ## Specify the boundary
 
-Cover a fresh allowed/denied validator, callback-added denial and exception,
-refused DI graphs and cleanup failure, and repeated validation/execution without
-reusing an instance. For keys, cover inherited/flattened members, exact derived
-types, missing metadata under strict settings and generated versus compatibility
-matching. An advisory Validate success is not proof that Execute commits.
+In application specs, call the validator directly with supplied read-model state
+and assert its business decision. Keep the one cheap assembly-level application-shape
+admission spec in [specs.scenarios.csharp.md](../../../rules/specs.scenarios.csharp.md).
+
+Arc/Chronicle specs own the construction/guard matrix: fresh instances, callback
+failures, refused DI graphs, cleanup, key matching and repeated execution. Do not
+re-prove that matrix per application validator. A focused application pipeline
+spec may prove its own registration/wiring; advisory Validate success alone is
+not proof that Execute commits.

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

@@ -188,12 +188,16 @@ deciding writer is guarded or the rule is a constraint.
 
 ## Verify
 
-- The model is admitted and the read is protected and enrolled in the intended
-  store, namespace and stream before staging events.
-- Refusal is surfaced, never replaced by a materialized/unprotected read.
-- One owner completes or rolls back; nested code does neither behind it.
-- Competing relevant events cause rejection; unrelated events outside the guard
-  do not. Absence, empty checked append and stream isolation have specifications.
-- Scope conflicts, lifecycle violations and failed commit remain visible.
-- Real-client/kernel integration proves the concurrency boundary; a default
+- Review production enrollment in the intended store, namespace and stream;
+  surface refusal and never replace it with an unprotected read. One owner completes.
+- Application specs call `Handle()` or the validator directly with supplied state.
+  Their only decision-read spec obligation is one cheap assembly-level
+  `DecisionReadAdmissions.ShouldAdmitDecisionReadsIn(assembly)` check of the
+  application's own model/projection shapes; see the
+  [scenario rule](../../rules/specs.scenarios.csharp.md).
+- Arc/Chronicle specs alone prove platform conflict refusal, relevant/irrelevant
+  changes, absence guards, empty checked appends, isolation and commit lifecycle.
+  Their real-client/kernel integration proves the boundary; a default
   `EventScenario` scope strategy returning `None` is not concurrency evidence.
+- Application specs never simulate competing appends or repeat that matrix.
+  Never weaken production guards for spec speed.

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

@@ -28,8 +28,12 @@ an adapter for arbitrary read-model storage:
 Whole-source key admission supports string/Guid schemas, with canonical lowercase
 D-form Guid source ids assumed. A renamed or custom-converted key is not made
 safe by a cast in the caller. Runtime definition comparison is a diagnostic, not
-proof of equality with an executing projection. Keep integration specifications
-for the actual kernel pair and model shape.
+proof of equality with an executing projection. Arc/Chronicle own kernel-pair
+integration and the platform guard matrix. Application specs have just one cheap
+assembly-level shape-admission check,
+`DecisionReadAdmissions.ShouldAdmitDecisionReadsIn(assembly)`; see the
+[scenario rule](../../../rules/specs.scenarios.csharp.md). It checks the
+application's own discovered models/projections without running Chronicle.
 
 Do not silently replace a refused decision read with a materialized sink read.
 Redesign the decision model as a focused admitted projection only when the

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

@@ -12,7 +12,7 @@
 - Arc traps
 - Chronicle-only traps
 - Roll out with Measure
-- Test the race
+- Specify the business decision
 - Costs
 - Checklist for generated code
 
@@ -82,7 +82,7 @@ published scenario catalogue.
     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).
+13. **Prove it** (S14): [specify the business decision](#specify-the-business-decision).
 
 ## The matrix
 
@@ -256,7 +256,7 @@ return `Commit()` last), `ReadOfSourceWithStagedEvents`, `ExplicitScopeDoesNotCo
 | 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()` |
 | `[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) |
+| Per-decision specs rebuild the platform guard matrix | repeated infrastructure proof, not business coverage | [specify the business decision](#specify-the-business-decision) |
 
 ## Chronicle-only traps
 
@@ -304,31 +304,23 @@ then set `On` per project. Behaviour for callers does not change under `Measure`
   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.
+## Specify the business decision
+
+Start with a plain `Handle()` or validator call supplied with read-model state.
+Follow the [scenario rule](../../../rules/specs.scenarios.csharp.md): read-protection
+plumbing is invisible to application spec authors. They never configure modes,
+call `UseDecisionReads`, seed events solely for infrastructure or re-prove platform
+concurrency, conflict-refusal or isolation guards. Arc/Chronicle specs own that
+matrix. The application's only decision-read spec obligation is one cheap
+assembly-level `DecisionReadAdmissions.ShouldAdmitDecisionReadsIn(assembly)`
+check of its own models/projections, not per-decision scenarios. Production
+protection stays unchanged regardless of spec cost.
+
+Do not simulate competing appends in an application spec, even for a rule such as
+two borrowers competing for the last copy. Give the state (no copies left) and assert
+the domain outcome (rejected); the guarantee that only one wins is proven by Arc and
+Chronicle. If the harness cannot accept required state, report the upstream gap
+rather than adding infrastructure setup to application specs.
 
 ## Costs
 
@@ -349,7 +341,8 @@ append. Decision reads exist in the .NET and Elixir clients.
   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`.
+- Business decisions have direct `Handle()`/validator specs with supplied state;
+  one cheap assembly-level spec checks application-shape admission. Arc/Chronicle,
+  not application specs, interleave appends to prove the platform guard matrix.
 - 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-specifications/SKILL.md

@@ -52,10 +52,11 @@ version. Never translate an assertion name from memory.
   (`When`, or `EventLog.Append` without a `concurrencyScope`) can never report
   `HasConcurrencyViolations`. Only an append that passes an explicit scope on
   `scenario.EventLog.Append(...)` reaches the in-process validator at all — and
-  that is a spec of the scope you hand-built, not of the application's strategy. Specify concurrency against
-  the real kernel with an out-of-process integration specification, and do not
-  write a scenario specification that looks like it covers it — it would pass
-  vacuously, which is worse than not having one.
+  that is a spec of the scope you hand-built, not of the application's strategy. The platform concurrency/guard matrix belongs only in Arc/Chronicle specs,
+  with real-kernel integration where required. Application decisions use direct
+  `Handle()`/validator calls with supplied state plus the one cheap assembly-level
+  shape-admission spec in [specs.scenarios.csharp.md](../../rules/specs.scenarios.csharp.md).
+  A default scenario must not claim concurrency coverage — it would pass vacuously.
 
 ## Step 1 — Create the scenario
 

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

@@ -15,6 +15,11 @@ default, with the event and current state supplied explicitly (for a self model,
 `Model.Reduce(@event, current)`). Add
 `ReadModelScenario<TReadModel>` only where declarative projection behavior,
 event dispatch, filtering, metadata or read-model wiring contribute proof.
+Follow the [scenario selection and cost rule](../../rules/specs.scenarios.csharp.md):
+use one scenario class per read model, many read-only assertions on one shared
+setup, and keep shared lifecycle enabled. Do not create a class per property,
+mapping attribute or lifecycle event. Measure scenario cost with TRX durations
+using [running-specs.md](../cratis-specifications-csharp/references/running-specs.md).
 
 For a read-model scenario specification the **`Given` *is* the act**. There
 is no separate `When`: seeding the events is what makes the projection run.
@@ -69,7 +74,8 @@ version.
 
 ## Step 1 — Create the scenario
 
-A new scenario per specification, never shared state.
+Create one scenario for the read model's specification class. Share setup among
+its read-only facts, never across specification classes.
 
 ```csharp
 // Default, empty initial state
@@ -214,7 +220,11 @@ public class and_two_items_are_priced : Specification
 
 Wrap files in `#if DEBUG … #endif` only when they compile into the application
 assembly, so specification code ships only in Debug. Dedicated spec projects
-need no wrapper. Keep one outcome per `should_` fact.
+need no wrapper. Keep one outcome per `should_` fact, not one scenario class per
+assertion. Apply the event sequence once; capture intermediate states in `Because`
+for create/update/delete assertions so facts remain read-only. Capture values or
+immutable copies if later events mutate the same instance. Multiple event-source
+keys may share this setup for isolation and child-key assertions.
 
 ## Step 6 — Cover the read model, not just one event
 
@@ -224,7 +234,8 @@ One summation example proves one event. Take the inventory from the contract
 (the `.play` read model and its specifications, or the agreed outline); without
 one, derive it from the projection and say so. Then check each line:
 
-- **Every property is asserted** in at least one specification.
+- **Every property is asserted** in a read-only fact in the model's shared
+  scenario class; do not multiply scenario startup for each field.
 - **Every subscribed event has a specification.** Reconcile three lists in both
   directions: the contract's event types, the projection's actual subscriptions,
   and the events your specifications seed. Report any event in one list missing