@cratis/pi 7.23.0 → 7.25.0

package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/scenario-examples.md

@@ -29,11 +29,11 @@ Screenplay specifications.
 | Then (success) | every production with payload and `for` | "an event is produced" |
 | Then (refusal) | `then error "Invoice already settled"`, the rule's own message | `then error` with no message, or `then error ""` |
 | Then (denial) | `then denied` | `then error` for a caller who is not allowed |
-| Reason | the slice `description` says why the rule exists | the rule appears only in a spec title |
+| Reason | slice `documentation` says why the rule exists | the rule appears only in a spec title |
 
 ## 1. Command: success, rule rejection and denial
 One spec for the success, one per rule (varying only the value the rule checks), one denial.
-```screenplay excerpt
+```screenplay excerpt parent=references/invoicing-dues-example.md#1
 specification IssuingAnInvoice
   given caller
     authenticated
@@ -71,7 +71,7 @@ specification RefusingACallerWithoutTheAccountsRole
 After which earlier facts must the command be refused? Establish the wrong state with its real
 facts, not a description of it. Settling a voided invoice and voiding a settled one are different
 questions: one spec each.
-```screenplay excerpt
+```screenplay excerpt parent=references/invoicing-dues-example.md#1
 specification RejectingSettlementOfAVoidedInvoice
   given caller
     authenticated
@@ -103,7 +103,7 @@ in `invoicing-dues-design.md`; it is never prose and never a spec that pretends
 Two separate obligations. First, the **capture specification**: concrete external input in, our
 facts out. The provider's refusal is a fact (never a `then error`), kept in the provider's
 vocabulary and then translated.
-```screenplay excerpt
+```screenplay excerpt parent=references/invoicing-dues-example.md#1
 specification TranslatingADeclinedCardResult
   when capture PaymentGatewayResults
     reference = "9c1f0a52-6a4e-4b1c-9f55-0d2c7b8e1a01"
@@ -121,7 +121,7 @@ Second, the **retry**. `PaymentRequested` only says we asked the gateway; it is
 After the decline, requesting again is an ordinary accepted command, and its exact declared
 outcome is `PaymentRequested`, not `PaymentReceived`: the eventual success is a later external
 fact that arrives through the capture, not something this command produces.
-```screenplay excerpt
+```screenplay excerpt parent=references/invoicing-dues-example.md#1
 specification RetryingPaymentAfterADecline
   given caller
     authenticated
@@ -149,7 +149,7 @@ lists the declared consequence (`RefundRequested`); the reaction is also specifi
 `RefundRequested` is a recorded request, not proof that money moved, and there is no
 `then <Command>` form. What the target must do to deliver the refund is a requirement, not a spec.
 From `invoicing-dues-design.md` (design mode; the specs do not run at 4.66.0):
-```screenplay excerpt
+```screenplay excerpt parent=references/invoicing-dues-design.md#1 expect PLAY0516 test=unbound
 specification ReversingAReceivedPayment
   given caller
     authenticated
@@ -185,7 +185,7 @@ ask. Voiding an issued invoice that is not yet paid is the other compensation (t
 A repeated event type can matter as much as a multi-event lifecycle. Two top-ups of 40 and 70
 walk a balance to 110; give the second occurrence as the action so the accumulation is what is
 tested.
-```screenplay excerpt
+```screenplay excerpt parent=references/invoicing-dues-example.md#1
 specification MemberCreditAccumulatesTopUps
   given caller
     authenticated

package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/scenario-workshop.md

@@ -75,7 +75,7 @@ survive; ask what a caller who may not look sees.
 - Do not perfect a scenario in the room. Capture it with its open question and move on.
 - Every "what if...?" from anyone becomes a named candidate at once.
 - Record why a rule behaves as it does when the room explains it; the modeler puts it in the
-  slice `description`.
+  slice `documentation`.
 
 ## Multi-role check (before leaving the room)
 - Domain expert: is this the right business behaviour and message?

package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/view-and-story-specs.md

@@ -62,7 +62,7 @@ both that the stored row is gone and that the keyed query returns nothing. The w
 (no key) is a design-mode expectation here: a list-query collection check does not run on the
 reference route, so record it in the matrix rather than asserting it.
 The source document also asserts the other terminal outcomes (`InvoiceVoided`, `InvoiceSettled`) the same way; they are not copied here.
-```screenplay excerpt
+```screenplay excerpt parent=references/invoicing-dues-example.md#1
 specification OpenInvoicesLifecycle1Empty
   given caller
     authenticated

package/package/corpus/skills/cratis-screenplay-scenario-coverage/verification.json

@@ -3,10 +3,11 @@
   "input": "Write the specifications for a ReserveBerth command and its read model, and tell me what coverage is missing.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     { "kind": "skill-contains", "value": "Coverage matrix before any spec" },
     { "kind": "skill-contains", "value": "Once, idempotent, exactly once are different claims" },
     { "kind": "skill-contains", "value": "Unauthorized is never `then error`" },
-    { "kind": "skill-contains", "value": "Screenplay#390" },
+    { "kind": "skill-contains", "value": "find-specification-obligations" },
     { "kind": "skill-contains", "value": "v4.68.0" },
     { "kind": "skill-contains", "value": "false PLAY0285" },
     { "kind": "skill-contains", "value": "One behaviour per spec" },

package/package/corpus/skills/cratis-screenplay-slice-design/SKILL.md

@@ -31,7 +31,7 @@ Lifecycle, modes and hand-offs: `cratis-screenplay-modeling-lifecycle`.
 Skip if the request already names the command origins (screens, reactions, outside systems),
 the decision behind each shown field, and how fresh each view must be. Otherwise ask, in one
 batch, only what is missing. Unattended: assume visibly, record each assumption in the phase
-report and the slice `description`, and continue.
+report and slice `documentation`, and continue.
 
 1. **Origin of each action.** Is it (A) user-initiated only, (B) automated, (C) a mix, or
    started by a clock or outside system (schedule, webhook, feed)? Impact: separates screen
@@ -80,8 +80,8 @@ report and the slice `description`, and continue.
    standing in for a rule. Place each rule in its layer (`references/rule-layers.md`). A rule
    over stored state is written as `reads <View>` + `require ... message "..."` and marked
    **NOT enforced in the model today** in the slice `description`, with its target named (Arc
-   `[ProtectedDecision]` + `DecisionRead<T>` on Arc 22.39.0+, not available in Stage-rendered
-   apps; Chronicle DCB; or a constraint). Never copy state
+   `[ProtectedDecision]` + `DecisionRead<T>` on Arc 22.39.0+ (available to gap-fill
+   code with Stage 4.51.3's Arc 22.50.5/Chronicle 19.32.0); Chronicle DCB; or a constraint). Never copy state
    into the command as input or hide a rule in `handler` / hint prose; descriptions are not
    rendered (Stage#178). Fill the **refusal inventory**: success, each distinct refusal with
    layer and message, and the denied persona.
@@ -129,7 +129,7 @@ report and the slice `description`, and continue.
    actor sees each state change's result. Beyond Level 1: `cratis-screenplay-ui-composition`.
 8. **Lineage pass.** Build the matrix in `references/field-lineage.md` from the `.play` files
    (read them), not from memory or an earlier summary. For each read model, write one line per
-   contributing event in its StateView slice `description`: which fields it sets and why. An
+   contributing event in its StateView slice `documentation`: which fields it sets and why. An
    event with no reason does not belong in the view. A field without an origin is a gap: add
    the missing input or event field, or record an open question. Never invent a source.
 9. **Slice and continue** (`references/slicing.md`): state-transition table per entity; one
@@ -163,9 +163,14 @@ report and the slice `description`, and continue.
 
 - One command per `StateChange` slice (renderable: required, plus no `produces when`).
 - One business decision usually produces one event; a decision establishing several facts the
-  business recognises separately may produce several (say why in the `description`).
+  business recognises separately may produce several (say why in `documentation`).
 - Copy an identity into an event payload only when a consumer needs it as a value.
-- Keep durable design rationale in slice `description` text, not `//` comments.
+- Keep the one-line summary in `description`, including short status markers such as
+  **NOT enforced in the model today** (with its target) or **ASSUMED**; record durable
+  reasoning, assumptions, causes and rejected alternatives in fenced Markdown
+  `documentation` on the module, feature, slice, command, event, read model or reaction, not `//` comments or disconnected notes. These are report-only, not
+  enforcement. Read [model reasoning](references/model-reasoning.md) for owners,
+  syntax, folder merge and PLAY0558/0559.
 - Rule coverage: for each value carrying a rule, list every path that sets it
   (`references/slicing.md`). A constraint on a claim covers every event setting that claim;
   value invariants live in the concept so they travel; command-level conditions are reviewed
@@ -199,7 +204,7 @@ Slice design is done when these hold; otherwise report what is open.
       denied persona); every gated command and query has a `then denied` row.
 - [ ] Every event is past tense, a specific change, and consumed or justified.
 - [ ] Every read model has a consumer and, when the scope is executable, one unambiguous key (keyed queries all using the same `by` property).
-- [ ] Every StateView `description` gives a reason per contributing event; every read-model
+- [ ] Every StateView's `documentation` gives a reason per contributing event; every read-model
       field and screen field is traced; every `from` event sets a field.
 - [ ] No `screen` without `data` or `action`; every acting screen has `data` or a stated
       exemption.

package/package/corpus/skills/cratis-screenplay-slice-design/references/command-inventory.md

@@ -16,7 +16,7 @@ and each persona that must be denied becomes a `given caller` fixture. Build it
 ## Command card
 
 Fill one card per command before (or while) writing the slice. Keep it in the phase report;
-durable rationale goes in the slice `description`.
+durable rationale goes in fenced Markdown slice `documentation`.
 
 ```text
 Command:        <ImperativeBusinessName>  (one decision)
@@ -76,7 +76,8 @@ Rules for filling it:
   as a gap. Persona description text is intent only.
 - A refusal that depends on stored state is a row marked **NOT enforced in the model today**
   with its target (Arc `[ProtectedDecision]` + `DecisionRead<T>` where Arc 22.39.0 or later is
-  available, which Stage-rendered apps are not; Chronicle DCB, or a
+  available, including Stage 4.51.3's rendered package set for gap-fill, not emitted
+  protection; Chronicle DCB, or a
   constraint). It still gets a spec row, because the intended behaviour is the contract.
 - A decided refusal never goes to open questions: it goes here, then to scenarios.
 - A refusal message is a fact of the design; keep the wording identical in the rule, the
@@ -101,7 +102,7 @@ Rules for filling it:
 | AssignLocker | caller is not an attendant | `authorize IsAttendant` | denied: Customer | RefusingACustomerAssigningALocker |
 | AssignLocker | locker already has a request | constraint `OneRequestPerLocker` | "The locker is already assigned" | AppendingASecondAssignmentOfALocker (`when append`: the command's own `require` would reject first) |
 | AssignLocker | request already has a locker | constraint `OneLockerPerRequest` | "The request already has a locker" | gap |
-| AssignLocker | locker is not free | `reads` + `require`, NOT enforced today | "The locker is not free"; target: `[ProtectedDecision]` (Arc 22.39.0+; unavailable in Stage-rendered apps, so a capability gap there) or DCB on the locker stream | RejectingASecondAssignmentOfALocker (pins the message; blocked until the target exists) |
+| AssignLocker | locker is not free | `reads` + `require`, NOT enforced today | "The locker is not free"; target: `[ProtectedDecision]` (Arc 22.39.0+; available to Stage 4.51.3 gap-fill, not emitted protection) or DCB on the locker stream | RejectingASecondAssignmentOfALocker (pins the message; blocked until the target exists) |
 | AssignLocker | request is not waiting | `reads` + `require`, NOT enforced today | "The request is not waiting for a locker" | gap (same) |
 | LockerById, ListLockers | caller is anonymous | module `authorize IsAuthenticated` | denied: no caller | RefusingAnAnonymousLockerLookup, RefusingAnAnonymousLockerList |
 | RequestById | caller is anonymous | module `authorize IsAuthenticated` | denied: no caller | RefusingAnAnonymousRequestLookup |

package/package/corpus/skills/cratis-screenplay-slice-design/references/field-lineage.md

@@ -33,7 +33,7 @@ Those are the portable sources. The event-source id is the `for` value, not a pr
 an event field (same-named fields map automatically - AutoMap is on; its matching differs between flat and scoped projections, see `read-model-design.md` "Building it");
 `$eventSourceId` (the instance identity); a literal (status words); a counter or arithmetic;
 a join on another event stream; children for collections. A reducer is opaque: write its
-lineage in the slice `description`. A read model built by a query `performer` (no events)
+lineage in slice `documentation`. A read model built by a query `performer` (no events)
 has lineage outside the model; say where.
 
 **Screen field** - from the query result named in `data ... via query`. A screen showing a
@@ -74,7 +74,7 @@ Filled for `worked-example.md`:
 
 ## The reason line per contributing event
 
-The matrix is the audit; the durable record is the StateView slice `description`: one line per
+The matrix is the audit; the durable record is StateView slice `documentation`: one line per
 contributing event saying which fields it sets and why. Write it as a tagged text block in a
 real model (a bare fence warns with `PLAY0397`). `worked-example.md` uses one-string
 descriptions only so that it stays a single compiling fence.

package/package/corpus/skills/cratis-screenplay-slice-design/references/model-reasoning.md

@@ -0,0 +1,87 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Keep reasoning on the model
+
+Use `description` for a short summary and `documentation` for assumptions,
+boundaries, trade-offs and rejected alternatives. Put reasoning on the declaration
+it explains, not in comments or disconnected session notes. Modules, features,
+slices, commands, events, read models and reactions accept one nonempty block,
+directly in their body (not beneath a reaction trigger). Queries, personas and other
+declarations do not accept `documentation`: keep their intent in `description` (a
+query's ordering, "oldest first", for example). A short status marker such as **NOT
+enforced in the model today** or **ASSUMED** stays in `description`, where a reader
+sees it first; the reasoning behind it goes in `documentation`:
+
+````screenplay
+module Billing
+  documentation
+    ```markdown
+    ## Boundary
+    Billing records agreed amounts; payment delivery belongs elsewhere.
+    ```
+  feature Amounts
+    documentation
+      ```markdown
+      Keep the agreed amount, not a running total.
+      ```
+    slice StateChange RecordAmount
+      documentation
+        ```markdown
+        A recorded amount is a decision, not a recalculated view.
+        ```
+      command RecordAmount
+        documentation
+          ```markdown
+          The caller supplies the agreed amount.
+          ```
+        recordId String identifier
+        amount Int
+        produces AmountRecorded
+          for recordId
+          amount = amount
+      event AmountRecorded
+        amount Int
+      specification RecordingAnAmount
+        description "Witnesses that the agreed amount is retained"
+        when RecordAmount amount = 10
+          recordId = "amount-1"
+        then AmountRecorded amount = 10
+    slice StateView AmountHistory
+      readmodel AmountView
+        documentation
+          ```markdown
+          This view is display state, not an atomic decision input.
+          ```
+        id String
+        amount Int
+      projection AmountHistory => AmountView
+        from AmountRecorded
+          id = $eventSourceId
+          amount = amount
+      query AmountById => AmountView optional
+        by id String
+    slice Automation ObserveAmount
+      reaction ObserveAmount
+        documentation
+          ```markdown
+          Observation does not certify an exactly-once external effect.
+          ```
+        when AmountRecorded
+````
+
+A specification accepts a `description` naming the behavior it witnesses, not
+`documentation`; longer reasoning belongs to its slice. Projections and screens
+do not accept documentation. `documentation String` remains a typed property
+where properties are allowed; bare `documentation` starts metadata.
+
+Both metadata fields are report-only (PLAY0270): no executable bytes,
+`modelRevision` or ESM version change, no rule enforcement or rendered code.
+Canonical printing retains documentation on its owner; source identity changes. MCP `declaration-details` summary exposes
+`description` and `documentation` wherever supported. Folder merge keeps the
+first module/feature block: identical copies are accepted, conflicting copies
+warn PLAY0559. Malformed, empty or repeated blocks report PLAY0558; events retain
+PLAY0477. These diagnostics have no automatic repair; choose the owning text.
+
+Authority: Screenplay v4.127.0 `slices.md` and `specifications.md`. The complete
+model above validates and its specification passes on standalone 4.127.0.

package/package/corpus/skills/cratis-screenplay-slice-design/references/provenance.md

@@ -28,7 +28,7 @@ is adapted with the agreement of Martin Dilger and Nebulit GmbH.
 | `eventmodeling-identifying-outputs/SKILL.md`: events vs read models test, recalculated-state anti-pattern, processor outputs categorized (new event, view update, notification) | `references/read-model-design.md` "Events or views" | shared with TrogonStack's version, including the processor-output categories (row above); adapted closely; the "independent means event" and "no computed fields" rows dropped because decided calculations are facts in Screenplay |
 | `eventmodeling-identifying-outputs/SKILL.md` Step 5a/5c: enumerate consumers, one component one read model, homogeneous list is one component, wide-fan-in versus cheap fields | `references/read-model-design.md` "Components" | adapted closely; "always split" softened to "split when you can name the consequence" (existing decision); screen copies become one `data` line per component |
 | `eventmodeling-identifying-outputs/SKILL.md` Step 5d: build read models from the screen's field mappings, not from its title or a summary | `references/read-model-design.md` "Components"; `references/field-lineage.md` | adapted closely |
-| `eventmodeling-identifying-outputs/SKILL.md` Step 5h.4, 5i: event-to-field reasoning note, per-node verification result list | `SKILL.md` step 8; `references/read-model-design.md` "Checks before handing off"; `references/field-lineage.md` | adapted closely; the note lives in the StateView slice `description` |
+| `eventmodeling-identifying-outputs/SKILL.md` Step 5h.4, 5i: event-to-field reasoning note, per-node verification result list | `SKILL.md` step 8; `references/read-model-design.md` "Checks before handing off"; `references/field-lineage.md` | adapted closely; the reasoning note lives in StateView slice `documentation` |
 | `eventmodeling-identifying-outputs/SKILL.md` lines 378-379: before completion re-read every read model and recheck each field and every reason note (roll-ups, additions) | `references/read-model-design.md` "Checks before handing off" | adapted closely; Cratis named-consequence threshold kept instead of "always split" |
 | `eventmodeling-identifying-outputs/SKILL.md` Interview: calculated fields confirmation wording | `SKILL.md` *Interview phase* question 3 | adapted closely |
 | `eventmodeling-identifying-inputs/SKILL.md`: automation level and outside-trigger questions, user versus processor commands marked, conditional input pattern, processor failure/retry stated | `SKILL.md` *Interview phase* question 1; `references/command-inventory.md` | adapted closely; `[USER]`/`[AUTO]` kept as plain classification |

package/package/corpus/skills/cratis-screenplay-slice-design/references/read-model-design.md

@@ -127,7 +127,7 @@ it stays.
   (worklists, status awaiting an outside answer); one-shot otherwise. Design mode only
   (PLAY0268). If access can be revoked mid-session, record that the target re-checks per emission.
 - Never model paging or page size (no syntax, Screenplay#140). State the order in the query
-  `description` ("oldest first"); an unbounded list is a review question.
+  `description` ("oldest first"; queries do not accept `documentation`); an unbounded list is a review question.
 - A gated keyed query needs its own denial spec.
 
 Never drop a list query from a design model just to make it bind; record the capability gap.
@@ -260,7 +260,7 @@ module Berths
 
 ## Checks before handing off
 
-- The StateView slice `description` gives, per contributing event, the fields it sets and why
+- StateView slice `documentation` gives, per contributing event, the fields it sets and why
   (see `LockerBoard` in `worked-example.md`); extend it whenever a `from` is added. Shape of
   the note: `BerthBooked sets bookingId, status="booked": the view's creation event; the booking
   does not exist before it.` / `BoatArrived sets status="arrived", arrivedAt: the only

package/package/corpus/skills/cratis-screenplay-slice-design/references/rule-layers.md

@@ -14,18 +14,18 @@ rendered code (Stage#178): a rule that exists only in prose is unenforced in ren
 | stored state (record exists, balance, current status) | `reads <View>` + `require <expr> message "..."` | stated intent, **NOT enforced in the model today** (PLAY0268/0271 at binding are expected in design mode; Screenplay#129/#209). Name the target: Arc `[ProtectedDecision]` + `DecisionRead<T>` (Arc 22.39.0 or later), Chronicle DCB (`concurrency` scope), or a constraint |
 
 An unguarded materialized read is unsafe for a protected decision; a guarded read is the
-supported route. Availability: `[ProtectedDecision]` and `DecisionRead<T>` need Arc 22.39.0 or
-later and are **not available in Stage-rendered apps**, whose scaffold pins Arc 22.25.0 (Stage
-4.24.0); never edit the managed dependency files to get them. For rendered scope, record a
-capability gap (or a separately verified compatible enforcement path, such as a constraint or
-a Chronicle DCB scope) and keep the rule as NOT enforced. Forbidden: caller-supplied copies of state in `require`, boolean attestation
+supported route. Availability: `[ProtectedDecision]` and `DecisionRead<T>` exist in
+Stage 4.51.3's Arc 22.50.5/Chronicle 19.32.0 package set, but Stage does not emit
+protected decisions. Gap-fill must use an admitted projection/key shape and active
+unit-of-work enrollment; do not edit managed dependencies. Keep the `.play` rule
+NOT enforced until its target enforcement is separately verified. Forbidden: caller-supplied copies of state in `require`, boolean attestation
 inputs (`confirmsX == true`), rules in `handler` / implementation-hint prose.
 
 ## Authorization is executable
 
 Persona Does/Reads/Cannot text is intent. Every Cannot line resolves to an `authorize` gate
-(policy or ownership claim) plus a `then denied` spec whose `given caller` carries the roles
-and claims standing for that persona; otherwise record a gap. Every command and query under an
+(policy or ownership claim) plus a `then denied` spec using `given caller as <Persona>` or an explicit
+caller for the effective gate; otherwise record a gap. Every command and query under an
 inherited module/feature `authorize` gets its own `then denied` spec. Ownership gates need a
 second caller with another claim value.
 
@@ -33,7 +33,7 @@ second caller with another claim value.
 
 Command property values are, by default, recorded in the causation chain of the events they
 produce, so treat them as permanent. Newer Chronicle versions can omit causation properties
-(`CausationPropertyRetention.Omit`, Chronicle v19.32.0); rendered apps pin Chronicle 19.8.1.
+(`CausationPropertyRetention.Omit`, Chronicle v19.32.0); Stage 4.51.3 rendered apps pin 19.32.0.
 Verify the actual auditing and retention configuration before relying on omission, and never
 audit secrets. Classify personal values as bare `pii` and operational secrets as
 `secret` on their concepts, never the identifier concept. Use a surrogate identity

package/package/corpus/skills/cratis-screenplay-slice-design/references/slicing.md

@@ -23,7 +23,7 @@ step at the end: design each behaviour as its slice, then audit the set.
 | `Translate` | captures, translated events | the integration (`CarrierManifests`) | see `cratis-screenplay-automations-and-translations` |
 
 Screenplay allows several commands or read models in one slice; prefer splitting unless the
-behaviour is genuinely one (and say why in the `description`).
+behaviour is genuinely one (and say why in `documentation`).
 
 ## Slice dependencies
 
@@ -89,7 +89,7 @@ Example: Payroll declares Timesheets; its Handover feature declares
 Timesheets.Approval and sibling Runs. These are dependency inventories, not
 actual references or execution dependencies:
 
-```screenplay
+```screenplay expect PLAY0553
 module Payroll
   depends on Timesheets
   feature Handover
@@ -142,8 +142,8 @@ result in every row and no refusal anywhere, whose event restates most of the en
    relocated).
 4. Apply rule coverage (below) to each new path.
 5. If the business treats a multi-value data-entry correction as one act, keep one correction
-   command named for the correction (never `Update`), with the reason in the slice
-   `description`; rule coverage still applies.
+   command named for the correction (never `Update`), with the reason in slice
+   `documentation`; rule coverage still applies.
 
 A repeated-field event is a review signal; it is major only when business meaning is lost, a
 rule is bypassed or consumers become ambiguous. Historical generations repeat prior shape on

package/package/corpus/skills/cratis-screenplay-slice-design/references/worked-example.md

@@ -13,11 +13,17 @@ complete givens) so they are the right form once binding is possible.
 Lineage matrix: `field-lineage.md`. State-transition table and rule coverage: `slicing.md`.
 Per-command refusal inventory: `command-inventory.md`.
 
-The per-event reason lines in each StateView `description` are the lineage record
-(`field-lineage.md`). Multi-line descriptions use a tagged ` ```text ` fence in a real model;
-they are written as one string here so this document stays a single compiling fence.
+This historical compiled example keeps per-event reasoning in StateView
+`description` strings. For current 4.127.0 authoring, keep descriptions as summaries
+and record lineage reasoning in fenced Markdown `documentation` (`field-lineage.md`).
+The historical source below stays unchanged; it is not the current placement recipe.
 
-```screenplay
+The excerpt's Stage availability note is historical (Stage 4.24.x, Arc 22.25.0).
+Stage 4.51.3 pins Arc 22.50.5/Chronicle 19.32.0, so protected-read APIs are available
+to gap-fill; this neither admits these `.play` rules nor proves target protection.
+The original compiled excerpt is retained unchanged.
+
+```screenplay expect PLAY0516 test=unbound
 domain Parcelpoint.Lockers
 
 concept LockerId : Uuid

package/package/corpus/skills/cratis-screenplay-slice-design/verification.json

@@ -3,6 +3,7 @@
   "input": "Design the slices for a new capability in a Screenplay model: commands, rules, read models and screens.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     {
       "kind": "skill-contains",
       "value": "NOT enforced in the model today"

package/package/corpus/skills/cratis-screenplay-specifications/SKILL.md

@@ -37,7 +37,7 @@ The update follows `commands.md`, `events.md`, `types.md` and
 `specifications.md` at that main commit (after v4.52.0). This pass compiles the
 changed examples; it does not rerun the reference runner.
 
-Current specification syntax follows Screenplay v4.125.0 `specifications.md`;
+Current specification syntax follows Screenplay v4.127.0 `specifications.md`;
 older probes in the table remain historical. Pins: `cratis-screenplay-toolchain`
 `references/versions.md`. Compile commands check source, not reference execution.
 Use `screenplay test` or MCP `run-specifications` for V4; Stage/target tests are
@@ -95,13 +95,27 @@ Unsupported is not passed. Report it as "needs a target", not as green. "Specifi
 and "bound" are never "passing": run the reference CLI/MCP route or the owning
 target tests, and name the engine, version and expected/discovered selection.
 
+## Descriptions, persona callers and case tables
+
+Use one `description "<rule or behavior>"` (or a fenced `text` description) to
+name what the specification witnesses. It is report-only (PLAY0270), changing
+neither execution nor ESM bytes. Specifications do not accept `documentation`;
+put longer assumptions and rejected alternatives on the owning slice's fenced
+Markdown `documentation` block.
+
+`given caller as <Persona>` expands to one authenticated policy witness before
+binding. Named `parameter`/`case` tables share steps and read values as
+`case.<parameter>`; each case runs independently as `<Specification>_<Case>`.
+Read [persona callers and case tables](references/persona-callers-and-cases.md)
+for synthesis refusals, selection, provenance and a complete passing model.
+
 ## The vocabulary
 
 | Construct | Meaning |
 | --- | --- |
 | `given <EventType>` | prior state, established by replaying events before the action |
 | `given readmodel <ReadModelType>` | prior read-model state, established directly — a **complete** instance including its identifier |
-| `given caller` | the caller: `authenticated`, `role "<r>"`, repeatable `claim "<type>" = "<value>"`; empty means unauthenticated |
+| `given caller` / `given caller as <Persona>` | explicit caller (`authenticated`, roles, claims; empty means anonymous), or an authenticated synthesized persona witness |
 | `when <CommandType>` | run a command |
 | `when append <EventType>` | append one event: constraints and projections run, the command does not; reactions run only from ESM v6, where `then` lists what followed |
 | `when query <Query>` | perform a query with the argument values beneath it (v4.48.0) |
@@ -146,7 +160,7 @@ Rules the binder enforces:
 - **`then denied` stands alone**: not with events, errors or state assertions
   (`PLAY0388`). For a query, pair it with one `then query` that has `arguments`
   and no `result`.
-- **Authorized commands and queries need `given caller`** (`PLAY0389`). The runner
+- **Authorized commands and queries need `given caller` or `given caller as <Persona>`** (`PLAY0389`). The runner
   never invents a caller.
 - **`null` only in optional read-model values.** A `null` in a command or event
   value is `PLAY0350`: an optional fact is a separate event.
@@ -168,7 +182,7 @@ the one-rejection rule (`PLAY0273`) are reported only when the model binds, so
 - **Rejections:** `then error "<message>"` matches the message whatever the rule's
   validation severity; no form asserts severity. Bare `then error` never matches
   a denial. Quote a localized key: `then error "$strings.invoices.reasonRequired"`.
-  The grammar takes only quoted messages here, never an unquoted `$strings` token
+  Besides a String `case.<parameter>`, the grammar takes only quoted messages here, never an unquoted `$strings` token
   (unlike a rule's `message` operand). The reference runner compares the symbolic key
   and requires the rejection to carry the string-key marker; it never loads
   translated text; resolving the key is the realization's job.
@@ -197,7 +211,10 @@ Read [references/reactions-and-cascades.md](references/reactions-and-cascades.md
 
 Use typed `example` declarations for repeated event/command/read-model values;
 step overrides keep the action/outcome visible and carry authored/example/override
-provenance. Event `stream`/`no stream` assertions bind as ESM v8; typed `for` and
+provenance. Event examples can carry routes, replaced as a whole by a step.
+Redelivery locators may state `stream` or `no stream` to select one definitely
+matching given occurrence with no undecided candidates (PLAY0543); redelivery
+remains authoring-only. Event `stream`/`no stream` assertions bind as ESM v8; typed `for` and
 stream ids are not guessed. Read [examples and routes](references/examples-and-routes.md).
 
 `given operation ... fails`, `then operation` and `then compensated` describe

package/package/corpus/skills/cratis-screenplay-specifications/references/examples-and-routes.md

@@ -8,6 +8,7 @@
 - Typed examples
 - Effective values
 - Event routes
+- Redelivery locators
 - Operation and recovery intent
 
 ## Typed examples
@@ -96,6 +97,63 @@ Source: v4.127.0 `event-sources.md`, `specifications.md`, `diagnostics.md`.
 CLI 3.41.0 rendering rejects versions above v7 before planning, even though
 source compilation and reference routing pass.
 
+Command and read-model examples refuse routes (PLAY0526). Effective role and
+`for` checks use the inherited or replaced route: inherited `no stream` on a
+`given`/append is PLAY0547; incompatible destination/route pairs are PLAY0550,
+and contradictory expectations PLAY0551. Declaration checks still run on unused
+examples and routes overridden at every use. MCP route rows retain the origin
+(authored/example/override), with the replaced whole route on the stream/no-stream
+row and individual lineage on id parts.
+
+## Redelivery locators
+
+`when redelivered <Event> to <Reaction>` may contain a route, using the same scalar
+or complete composite `streamId` shape as event steps. No route is a wildcard;
+`no stream` selects the unrouted given. Compare effective, example-expanded givens.
+Every `for`, payload and route comparison is true, false or unknown: a definite
+mismatch excludes a candidate even when another comparison is unknown. Selection
+needs exactly one definitely matching candidate and **no undecided candidates**
+(PLAY0543). Equal duplicate givens remain separate candidates. Narrow with `for`,
+values, `stream` or `no stream`; do not guess an unknown value. A locator's `for`
+is optional but typed against the routed source when present.
+
+This complete syntax-only model validates on 4.127.0; `screenplay test` reports
+PLAY0268 for redelivery, not a passing scenario:
+
+```screenplay test=unbound
+eventsource Account
+  identifier String
+  stream Transactions
+    streamId String
+module Accounts
+  feature Recovery
+    slice Automation Observe
+      event Recorded
+        amount Int
+      reaction Observer
+        when Recorded
+      example FirstPartition : Recorded
+        for "account-1"
+        stream Account.Transactions
+          streamId = "first"
+        amount = 10
+      specification RedeliveringTheSecondPartition
+        given FirstPartition
+        given FirstPartition
+          stream Account.Transactions
+            streamId = "second"
+        when redelivered Recorded to Observer
+          stream Account.Transactions
+            streamId = "second"
+        then no events
+```
+
+The second given replaces the example's **entire** route, independently of `for`,
+not just its id. PLAY0548 is command-action-only, never a locator route error;
+malformed routes use PLAY0547 and resolution/key-shape errors PLAY0549. MCP labels
+locator fixtures `whenRedeliveredEvent` with route-origin rows. Route admission
+alone does not admit redelivery or `then no events`.
+
 ## Operation and recovery intent
 
 Operation failure/request/compensation forms are authoring-only (PLAY0268):
@@ -108,4 +166,4 @@ remain unadmitted; they are not executed append scenarios. Forms, matching,
 acknowledgement and their whole-model refusal boundary are in
 captures-and-reactions `references/refusals-and-redelivery.md`.
 
-Authority: Screenplay `v4.125.0:Documentation/screenplay/specifications.md`.
+Authority: Screenplay `v4.127.0:Documentation/screenplay/specifications.md`.