@cratis/pi 7.106.0 → 7.107.0

package/package/corpus/product-sync.json

@@ -171,9 +171,9 @@
         }
       ],
       "synced": {
-        "version": "4.235.0",
-        "date": "2026-10-19",
-        "by": "Cratis/AI#837"
+        "version": "4.244.0",
+        "date": "2026-10-20",
+        "by": "Cratis/AI#891"
       },
       "covers": {
         "skills": [

package/package/corpus/skills/cratis-screenplay-automations-and-translations/references/public-events-and-direction.md

@@ -113,7 +113,7 @@ module Integration
         source events
           from ShipmentDispatched
           from ShipmentDelivered
-        key orderId
+        key orderId is event source
         append OrderDispatched
           when added
             carrier = $.carrier
@@ -163,6 +163,13 @@ must be required on every `from` event (PLAY0700); `$eventSourceId` and other co
 keys are refused. An empty or whitespace-only text key fails execution, even in a
 given before the action; non-text/non-numeric keys are Unsupported.
 
+The example declares `is event source` because the producer sources every event by
+`orderId`.
+Requires Screenplay 4.242.0 and ESM v33. A fixture `for` must then equal the key;
+without `for`, it takes the key. Unmarked captures stay unchanged. Other
+sources or non-single-property keys report PLAY0809, with no automatic repair. Read
+[event-source keys](../../cratis-screenplay-captures-and-reactions/references/capture-map-and-example.md#keying-by-the-event-source).
+
 Givens fold in authored order without appending. Each event overlays its top-level
 properties onto state for that typed key: absent properties retain earlier values;
 objects/lists replace whole values. First sight is `added` only, unchanged overlays

package/package/corpus/skills/cratis-screenplay-automations-and-translations/verification.json

@@ -8,6 +8,10 @@
     { "kind": "skill-contains", "value": "then OrderShipped", "file": "references/public-events-and-direction.md" },
     { "kind": "skill-contains", "value": "typed Unsupported", "file": "references/public-events-and-direction.md" },
     { "kind": "play-compiles" },
+    { "kind": "skill-contains", "value": "key orderId is event source", "file": "references/public-events-and-direction.md" },
+    { "kind": "skill-contains", "value": "Requires Screenplay 4.242.0 and ESM v33", "file": "references/public-events-and-direction.md" },
+    { "kind": "skill-contains", "value": "PLAY0809, with no automatic repair", "file": "references/public-events-and-direction.md" },
+    { "kind": "skill-contains", "value": "Unmarked captures stay unchanged", "file": "references/public-events-and-direction.md" },
     { "kind": "skill-contains", "value": "`[ExecuteCommandsAsSystem(\"<role>\")]`" },
     { "kind": "skill-contains", "value": "ESM v10" },
     { "kind": "skill-contains", "value": "STAGE-ESM-024" },

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/capture-map-and-example.md

@@ -1,5 +1,11 @@
 # Capture map and example
 
+## Contents
+
+- Capture excerpt
+- Capture `map`
+- Keying by the event source
+
 ## Capture excerpt
 
 ```screenplay excerpt
@@ -57,6 +63,11 @@ reference is handed records (`given capture`, `when capture`) and never contacts
 (PLAY0700). Events append to the event source the key names, and
 `$context.occurred` is supplied by the scenario's `given clock`.
 
+For a producer that sources every event by this key, declare
+`key <property> is event source` (ESM v33, Screenplay 4.242.0).
+See [Keying by the event source](#keying-by-the-event-source) below for the promise, fixture `for`
+checks and the PLAY0809 restriction to single-property `source events` keys.
+
 An event's external origin is declared on the `event` itself with `event X from "<origin>"` (ESM v9);
 outside records still enter through a `capture` in a `Translate` slice
 (`cratis-screenplay-automations-and-translations` `references/public-events-and-direction.md`).
@@ -87,3 +98,71 @@ compile error. Split it into two `append` blocks.
 
 **`children <collection> identified by <path>`** and **`nested <path>`** each take
 an optional `map` and any number of `append` blocks.
+
+## Keying by the event source
+
+Requires Screenplay 4.242.0 or later (`screenplay --version`). The marker selects
+ESM v33 and serializes `keyIsEventSource` beside `sourceEvents`. A capture without
+it keeps its earlier behavior, version and bytes.
+
+Declare `key <property> is event source` only when the producer sources **every**
+captured event by that property's value. This is a promise about the foreign
+stream, not a request to move an event to another source. It lets a renderer that
+admits v33 narrow an inbox history read by event source id. Binding and reference
+execution do not prove the renderer or deployed observer realizes that promise.
+
+Only a `source events` capture with a single property key may declare the marker.
+Other capture sources or key shapes report PLAY0809, an error with no automatic
+repair. The key must still be required on every `from` event (PLAY0700); the marker
+does not permit `$eventSourceId` as the key expression.
+
+### Typed fixtures
+
+- An explicit fixture `for` must equal the key. A mismatch rejects execution with
+  a contract rejection naming the capture, event and both values. Do not turn it
+  into an accepted `then no events` scenario.
+- A fixture without `for` takes the key as its source **before** projections and
+  reactions see it, so `$eventSourceId` is the key.
+- The check also runs while establishing givens, including a world with no action.
+- Without the marker, an optional foreign fixture `for` stays opaque non-empty
+  text, independent of the capture key. Do not add the marker just to fix a fixture.
+
+This complete model uses a producer that sources dispatches by `orderId`:
+
+```screenplay
+module Shipping
+  feature Tracking
+    slice Translate ReceiveDispatches
+      direction inbound
+      event ParcelDispatched from "carrier"
+        orderId String
+      event DispatchRecorded
+        orderId String
+      capture DispatchFeed
+        source events
+          from ParcelDispatched
+        key orderId is event source
+        append DispatchRecorded
+          when added
+            orderId = $.orderId
+      specification RecordingADispatch
+        when append ParcelDispatched
+          for "order-42"
+          orderId = "order-42"
+        then DispatchRecorded
+          for "order-42"
+          orderId = "order-42"
+      specification TakingTheKeyAsSource
+        when append ParcelDispatched
+          orderId = "order-42"
+        then DispatchRecorded
+          for "order-42"
+          orderId = "order-42"
+```
+
+Changing the first fixture's `for` to `"other-order"` rejects the run; it is not a
+new stream to accept silently. Test that rejection and the given-only mismatch
+through evaluator outcomes as well as the two successful source forms.
+
+Authority: Screenplay [captures](https://github.com/Cratis/Screenplay/blob/main/Documentation/screenplay/captures.md#keying-by-the-event-source)
+and [capture grammar](https://github.com/Cratis/Screenplay/blob/main/Documentation/screenplay/captures/grammar.md).

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/verification.json

@@ -5,6 +5,14 @@
   "assertions": [
     { "kind": "skill-contains", "value": "unrouted facts never match" },
     { "kind": "skill-contains", "value": "source events" },
+    { "kind": "skill-contains", "file": "references/capture-map-and-example.md", "value": "PLAY0809, an error" },
+    { "kind": "skill-contains", "file": "references/capture-map-and-example.md", "value": "ESM v33" },
+    { "kind": "skill-contains", "file": "references/capture-map-and-example.md", "value": "key orderId is event source" },
+    { "kind": "skill-contains", "file": "references/capture-map-and-example.md", "value": "`keyIsEventSource` beside `sourceEvents`" },
+    { "kind": "skill-contains", "file": "references/capture-map-and-example.md", "value": "earlier behavior, version and bytes" },
+    { "kind": "skill-contains", "file": "references/capture-map-and-example.md", "value": "An explicit fixture `for` must equal the key" },
+    { "kind": "skill-contains", "file": "references/capture-map-and-example.md", "value": "A fixture without `for` takes the key as its source" },
+    { "kind": "skill-contains", "file": "references/capture-map-and-example.md", "value": "givens, including a world with no action" },
     { "kind": "play-compiles" },
     {
       "kind": "skill-contains",

package/package/corpus/skills/cratis-screenplay-toolchain/references/cheat-sheet.md

@@ -8,6 +8,7 @@
 - Exact numeric source mode
 - Clause order inside a command (canonical)
 - Slice contents (typical)
+- Event-source capture keys (ESM v33)
 - `$context.` paths (command `produces`)
 - `$eventContext.` (projections)
 - PDL quick reference (most forms are compiled in `pdl-example.md` or `cheat-sheet-example.md`; `remove via join` and `$eventContext.occurred` are not)
@@ -139,6 +140,17 @@ description, properties, `reads`, `authorize`, `validate`, `produces`/`handler`,
 - `slice Translate <Behaviour>`: capture and/or translator reaction + both vocabularies' events.
 - Declare each event once, in the slice that produces it; reference it by name elsewhere.
 
+## Event-source capture keys (ESM v33)
+
+For inbound `source events` captures only, a single-property
+`key <property> is event source` promises every incoming event is sourced by that
+key (Screenplay 4.242.0; serializes `keyIsEventSource` beside `sourceEvents`).
+Other sources/key shapes report PLAY0809, with no automatic repair. Explicit typed
+fixture `for` must equal the key; omission takes the key before projections/reactions,
+including givens without an action. Unmarked captures keep earlier semantics.
+An admitting renderer may narrow history reads by event source id; binding is not target evidence.
+Read [event-source keys](../../cratis-screenplay-captures-and-reactions/references/capture-map-and-example.md#keying-by-the-event-source) for the complete example.
+
 ## `$context.` paths (command `produces`)
 `occurred`, `tenant`, `command.<p>`, `arguments.<p>`, `causedBy.subject|name|userName`,
 `causation.type`, `identity.id|name|userName|isAuthenticated|roles|claims.<n>`.

package/package/corpus/skills/cratis-screenplay-toolchain/references/diagnostics.md

@@ -5,6 +5,7 @@
 - Warnings that hide defects (always validate with `--warnings-as-errors`)
 - Source reference and identifier checks
 - Public events and translation direction
+- Event-source capture keys
 - Explicit enum member numbers
 - Reserved stored names and event pins
 - Named keys, production routes and observer filters
@@ -97,6 +98,20 @@ Requires Screenplay 4.176.0 or later for PLAY0694; older compilers leave the
 legacy directionless co-location unchecked. Full capture execution and ordering:
 automations-and-translations `references/public-events-and-direction.md`.
 
+## Event-source capture keys
+
+Requires Screenplay 4.242.0 or later (`screenplay --version`); the marker selects ESM v33.
+
+| Code | Severity | Meaning / fix |
+| --- | --- | --- |
+| PLAY0809 | E | `key <property> is event source` outside a single-property `source events` capture key. Declare it only when every captured event is sourced by that property. Other sources or key shapes are errors, with no automatic repair. |
+
+Marked typed fixtures reject an explicit `for` that differs from the key. Without
+`for`, the fixture takes the key before projections/reactions. The contract checks
+givens too, even without an action. This execution rejection is not PLAY0809 and
+not a successful `then no events` outcome. Unmarked captures retain prior semantics.
+Read captures-and-reactions [event-source keys](../../cratis-screenplay-captures-and-reactions/references/capture-map-and-example.md#keying-by-the-event-source).
+
 ## Explicit enum member numbers
 
 Source errors; the pins bind as ESM v12:

package/package/corpus/skills/cratis-screenplay-toolchain/references/language-admission.md

@@ -19,6 +19,7 @@ exact language/semantic pairs; binding, reference execution and rendering are se
 | v29 | `decimals <= N`; `add`/`subtract` by `a * b`; a concept mapped to another concept over the same primitive (decision 0098) | Decimal-places rule on a Decimal concept or property; the exact decimal product; the conversion is admitted only when the target declares no rule or compliance the source does not, never for enums, composites or optional into required | v29 refused until Stage admits it |
 | v30 | A command `produces ... for <required scalar property>` (several event sources); a specification `given generated <Command>.<property> = <value>` (decision 0098) | Several sources in one accepted command; pinned generated values for reaction-invoked commands, taken in authored order | v30 refused until Stage admits it |
 | v31 | A policy `require anonymous` for a public command or query | A deliberately public surface; the policy is the whole effective authorization | v31 refused until Stage admits it |
+| v33 | `key <property> is event source` on a single-property `source events` capture (Screenplay 4.242.0; PLAY0809) | Serializes `keyIsEventSource` beside `sourceEvents`. Promises every incoming event is sourced by that key; explicit fixture `for` must equal it, while omission takes the key before projections/reactions. Checks also run on givens without an action. Unmarked captures keep earlier behavior/version/bytes | An admitting renderer may narrow history reads by event source id; binding alone does not prove target realization |
 
 Constructs of decision 0098 with no executable-model content need no version: application-level toolbar buttons in the layout's `navigation topbar` region (`button <id> title "..." slice <Slice>` with an optional indented `authorize <Policy>`), a command specification that states the public event its outbound Translate slice publishes (no more false `PLAY0285`), and a capture over events that copies a list (`lines = $.lines`) or fans out with `children lines identified by sku`. Check `screenplay --version` against the release that admitted v29 and v30 before relying on them.