@cratis/pi 7.105.1 → 7.107.0

package/package/corpus/skills/cratis-engineering-release-trains/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: cratis-engineering-release-trains
+description: Group related deliveries into one release candidate, fold superseded pull requests, and apply a ship bar before publishing the assembled change. Use when asked to group finished branches, join an open PR, fold superseded PRs, size a candidate, or decide whether the ship bar is met. Not for waiting on checks (use cratis-engineering-ci-gates), planning review rounds (use cratis-engineering-review-rounds), or optimizing workflow performance (use cratis-ci-pipeline-performance).
+license: LICENSE
+compatibility: Requires git and the GitHub CLI (gh).
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# One assembled candidate, one release
+
+A **candidate** is the branch assembling deliveries intended to ship together.
+A repository includes its main checkout and all its worktrees. Consider their
+concurrent work together, not as separate releases merely because it has
+separate branches. One person or session assembles the candidate.
+
+## Authority and routing
+
+Read [capability-is-not-authority.md](../../rules/capability-is-not-authority.md)
+and the [ship-changes prompt](../../prompts/ship-changes.prompt.md) before any
+external effect. A user's ship request authorizes its ordinary shipping steps;
+loading this skill does not turn an implementation-only request into shipping.
+Without that request, prepare the grouping and report the proposed next action.
+
+Read [pull-requests.md](../../rules/pull-requests.md) for release intent, split
+criteria, release notes, issue dispositions, and the human checkpoint for a
+major release. A major release is never merged by an agent: a human confirms
+and merges it. Agent work stops at preparing the PR, even after confirmation.
+Read [git-commits.md](../../rules/git-commits.md) before assembling
+branches. Preserve commits: never squash, rebase, amend, or force-push.
+
+Use `cratis-engineering-consolidation-guard` when folding existing PRs to prove
+nothing was dropped. Use `cratis-engineering-ci-gates` for gate selection and
+run handling, and `cratis-engineering-review-rounds` for proportionate review.
+
+## Choose the candidate before creating a PR
+
+1. Inspect the repository's worktrees, finished branches, and open PRs:
+
+   ```bash
+   git worktree list
+   gh pr list --state open --json number,headRefName,title,author
+   ```
+
+2. Group related, ready deliveries under one candidate and one PR. Check with
+   the person assembling an existing candidate before changing it. Independent
+   work branches start from `origin/main`; work that depends on an unmerged
+   candidate may start from that candidate's latest commit (see Replace waits
+   with local work). Ongoing work keeps its branch.
+   Do not edit another session's checkout or include its uncommitted work.
+3. Prefer joining a related open PR that is still accepting deliveries, has no
+   checks running, and is not being merged by another session. Agree on its
+   writer, merge `origin/main` into its branch, then merge the deliveries and
+   extend its release note. Do not open a competing PR while it is being cut.
+4. If no candidate exists, create a branch from current `origin/main` and merge
+   ready delivery branches with merge commits. Keep each logical change in its
+   own commits. Return a conflicting or failing delivery for correction rather
+   than guessing its intent in the assembled branch.
+5. Keep one candidate per repository by default. Apply the split criteria in
+   `pull-requests.md` for unrelated work, different risk, or an urgent fix. Name
+   the exception in the reviewer comment; a major awaiting human confirmation
+   must not silently hold unrelated safe work indefinitely.
+
+Minimal assembly, after agreeing on the included deliveries:
+
+```bash
+git fetch origin
+git switch -c release-candidate origin/main
+git merge --no-ff delivery-a
+git merge --no-ff delivery-b
+```
+
+Use a new branch name if `release-candidate` already exists. This example does
+not authorize publication. Run the assembled gates before the shipping push.
+
+## Fold superseded PRs promptly
+
+Once a fold is decided within the authorized shipping scope, stop pushing to
+its old branch. Close the superseded PR with a one-line reason:
+`Folded into <candidate branch or PR>`; use `Will be folded into <candidate>`
+when assembly is still pending. Do not wait for the candidate's push to retire
+a PR that is already known to be superseded.
+
+Move its delivered release-note bullets into the candidate's release note,
+following `pull-requests.md`; retain only issues actually delivered by the diff.
+Before consolidation, check release intent and publication effects and apply
+`cratis-engineering-consolidation-guard`.
+
+Identify the exact queued or in-progress runs for the superseded head. Cancel
+only runs started by this session's own superseded pushes. Never cancel a
+release, publish, or deploy run, or another session's watched merge. Leave
+others running and report them. Follow `cratis-engineering-ci-gates` for the
+cancellation checks; folding a PR is not blanket cancellation authority.
+
+## Size by readiness, then freeze
+
+Before the final gate, list in-flight deliveries and their expected readiness.
+Hold the cut for work expected ready within about one gate duration, so the
+assembled gate runs once on the larger set. Cut without work further out or
+blocked on a design decision, consumer proof, or another repository.
+
+After the cut, nothing joins. Late deliveries go into the next candidate.
+Corrections needed to make the frozen candidate pass are not new deliveries;
+rerun the affected required gates for that changed code state.
+
+Record the cut and readiness estimates in one line in the reviewer comment,
+not the release note: `Cut with A and B; C waits for consumer proof.` Keep local
+coordination records under `.ai-work/`, never in public release text.
+
+## Replace waits with local work
+
+Most waits are removable. The build queue is the only legitimate one; while
+queued, do the next independent piece of work.
+
+- Base work on a committed local candidate instead of waiting for it to reach
+  main, and say which candidate commit it is based on when delivering.
+- Prove against locally built packages instead of waiting for a release; see
+  [cratis-engineering-local-cross-repo-verification](../cratis-engineering-local-cross-repo-verification/SKILL.md).
+  Only the final version pin waits for the release.
+- Drop an item that has been stuck for about two hours rather than holding the
+  candidate; it joins the next one.
+- Cut a candidate at least every few hours with whatever is green.
+
+## Apply the ship bar
+
+Check these six conditions. If one is missing, stop and report it instead of
+making a speculative shipping push. Recheck the merge conditions after CI.
+
+1. **Cause and design understood.** The change solves the named problem using
+   established conventions. Product questions are resolved, not guessed.
+2. **Behavior proved.** Changed behavior has specifications, or an explicit
+   reason why they do not apply. The assembled local gate is green. Required
+   integration coverage follows repository policy and must pass before merge;
+   name anything that cannot run locally rather than calling it a local pass.
+3. **Whole change reviewed.** The candidate has a completed review without
+   Blockers or missing required evidence. Targeted delivery reviews alone do
+   not satisfy this condition.
+4. **Release decision settled.** Release intent follows `pull-requests.md`.
+   For a major release, require explicit human confirmation and human merge.
+   An agent never merges it; preparing the PR does not answer that checkpoint.
+5. **Conversation reread.** Re-read the issues and PR, including comments and
+   requested changes, before pushing and again immediately before merging.
+   Resolve unanswered objections rather than treating green checks as consent.
+6. **Main overlap checked.** Fetch main before merging. Inspect changes since
+   the tested head on the candidate's changed paths, for example
+   `git log <ci-sha>..origin/main -- <changed-paths>`. If main overlaps, merge it
+   into the candidate and rerun the required gates and CI before merge.
+
+## Push deliberately and finish
+
+Batch local commits and review corrections into one meaningful shipping push.
+After feedback, fix the full set, rerun the required gates, and push once.
+Never push a lone merge of main as a save point or push just to discover whether
+untested code passes.
+
+Never put a CI skip token (`[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`)
+in a PR title or commit message. The merge commit inherits the PR title, so a
+skip token can prevent every check from running on main. Remove such tokens
+before creating or editing the PR; never rewrite an existing commit to do it.
+If a committed token cannot be corrected without rewriting history, stop and
+report the unsafe message rather than pushing it.
+
+Use the ship-changes prompt for PR creation, notes, merge, issue disposition,
+and cleanup. Non-major releases use a merge commit; never squash or rebase.
+A human confirms and merges every major release. In repositories
+using release-action, delivered `(#n)` references close at release, not by hand;
+follow `pull-requests.md` for other cases rather than inventing a closing step.
+
+Do not enable auto-merge. Wait using `cratis-engineering-ci-gates`. If checks
+outlast the session, leave a handoff under `.ai-work/` per
+[local-work-artifacts.md](../../rules/local-work-artifacts.md), with valid
+preconditions, candidate and tested SHAs, PR, exact pending checks, and the next
+steps. The next session must recheck the ship bar, not blindly merge on green.
+
+## What breaks
+
+- **One PR per delivery:** duplicate gates and fragmented releases replace an
+  assembled check of the actual shipped change.
+- **A growing frozen candidate:** late work invalidates the gate and cut.
+- **Green means permitted:** checks neither resolve objections nor approve a
+  major release. The user's request and owning rules still govern effects.
+
+## How it is proven
+
+Run the repository's exact assembled gate and inspect its successful exit.
+Run `gh pr checks <pr>` before merge: required checks must pass for the tested
+head. Confirm the whole-change review, fresh discussion, and main-overlap check.
+For release notes, execute the repository's `cratis-check-pr.mjs` command from
+`pull-requests.md`; a zero exit is the pass signal. No checklist replaces those
+behavioral and CI signals.

package/package/corpus/skills/cratis-engineering-release-trains/verification.json

@@ -0,0 +1,20 @@
+{
+  "skill": "cratis-engineering-release-trains",
+  "input": "Group related deliveries, freeze the candidate, and apply the ship bar without bypassing human merge or CI.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "One assembled candidate, one release" },
+    { "kind": "skill-contains", "value": "After the cut, nothing joins." },
+    { "kind": "skill-contains", "value": "The build queue is the only legitimate one" },
+    { "kind": "skill-contains", "value": "only runs started by this session's own superseded pushes" },
+    { "kind": "skill-contains", "value": "A major release is never merged by an agent: a human confirms" },
+    { "kind": "skill-contains", "value": "in a PR title or commit message" },
+    { "kind": "skill-contains", "value": "[skip ci]" },
+    { "kind": "skill-contains", "value": "[ci skip]" },
+    { "kind": "skill-contains", "value": "[no ci]" },
+    { "kind": "skill-contains", "value": "[skip actions]" },
+    { "kind": "skill-contains", "value": "never squash or rebase" },
+    { "kind": "skill-contains", "value": "../../rules/pull-requests.md" },
+    { "kind": "skill-contains", "value": "../../prompts/ship-changes.prompt.md" }
+  ]
+}

package/package/corpus/skills/cratis-engineering-review-rounds/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.

package/package/corpus/skills/cratis-engineering-review-rounds/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: cratis-engineering-review-rounds
+description: Plan proportionate review rounds, distinguish blocking from advisory findings, and carry prior evidence into a delta round with a firm stopping point. Use when choosing a review round, handling blocking or advisory feedback, requesting a delta since the last reviewed SHA, or stopping recurring blockers. Not for review criteria (use cratis-code-review), grouping a release candidate (use cratis-engineering-release-trains), waiting on checks (use cratis-engineering-ci-gates), or a repeated regression class (use cratis-engineering-regression-cluster).
+license: LICENSE
+compatibility: Requires git and the GitHub CLI (gh).
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Review the change, then its corrections
+
+Read [review-reports.md](../../rules/review-reports.md) before choosing reviewers
+or reporting findings. Its report shape, verdicts, scope limits, and reviewer
+independence apply to every round. This skill schedules reviews; it does not
+replace the criteria in `cratis-code-review` or specialist review skills.
+
+**Blocking** means a must-fix finding in **Blockers**, yielding **Changes
+requested**. **Advisory** means a non-blocking finding in **Suggestions**. An
+advisory preference is not a merge gate. Missing required evidence yields
+**Incomplete**, not approval; retain that gap until it is resolved.
+
+## Budget the review
+
+- Run one quick round per delivery. A second is warranted only after a blocker,
+  not to seek reassurance or eliminate suggestions.
+- Run one whole-change review per PR on the assembled change. Quick delivery
+  rounds do not replace it. Start whole-change inspection in parallel with the
+  gate when possible, but keep it provisional: required gates must pass before
+  an approval report is finalized. Do not launch duplicate gates for review.
+- Use ordinary depth by default. Deep review needs one named risk class:
+  **security**, **algorithmic**, **concurrency**, or **cross-cutting**, plus a
+  one-line justification tied to the changed behavior. Data-loss exposure or
+  irreversible migrations may justify cross-cutting review; merely wanting
+  extra confidence does not.
+- Prove migrations and deployment-sensitive behavior by running the migration
+  on representative local data and exercising the relevant old/new behavior.
+  Deeper inspection is not execution evidence. Follow repository test policy.
+
+## First whole-change round
+
+1. Fix the target scope and committed base and head SHAs. Name changed surfaces,
+   expected behavior, required checks, and any specific risk before starting.
+   Use `git rev-parse <base>` and `git rev-parse HEAD` to resolve full SHAs.
+2. Apply reviewer independence from `review-reports.md`: use a different
+   provider family where selectable. Where it is not selectable, declare
+   `single-provider` in the report header and on the Not examined line. A
+   provider/tool error makes the review Incomplete; fall back once as that
+   rule directs, rather than manufacturing a verdict.
+3. Review the whole diff using the applicable criteria and real gate results.
+   Record round 1 with its base/head and retain the complete report unchanged.
+   Keep local review records under `.ai-work/`; public reviewer notes follow
+   [pull-requests.md](../../rules/pull-requests.md), never the release note.
+4. Fix confirmed Blockers together. Dismiss a candidate only with evidence and
+   a reason, not by silently deleting it. Correct required evidence gaps before
+   seeking approval. Cheap advisory fixes may join this correction pass.
+
+## Delta rounds
+
+A delta round follows a whole-change review and reviews from the last reviewed
+SHA, not from an arbitrary base. Carry the prior Blockers, unresolved evidence
+gaps, Suggestions, and Dismissed findings with their reasons. Supply the round
+number, prior report, original base, last reviewed SHA, and new head explicitly.
+
+For example, after correcting a blocker from round 1:
+
+```text
+Round: 2 (delta)
+Original base: <full base SHA>
+Since: <full head SHA reviewed in round 1>
+Head: <full corrected head SHA>
+Prior: <complete round 1 report, including dismissals and scope limits>
+Scope: inspect the correction diff and verify disposition of prior findings
+```
+
+Inspect the correction diff with `git diff <last-reviewed-sha>..<new-head-sha>`.
+Recheck earlier blockers against the correction and its specifications. Preserve
+unresolved findings and limits; a narrow delta cannot certify surfaces that
+were never examined. Reuse earlier approval only for the exact committed SHAs
+and examined scope, never for a dirty tree or a changed head.
+
+Do not start a follow-up round for advisory findings alone. Fix them only when
+cheap in an existing correction pass; otherwise leave them as Suggestions.
+Never file an issue merely to dispose of advisory feedback. A distinct defect
+needs its own evidence and the authority rules, not automatic issue creation.
+
+## Stop instead of looping
+
+Cap review at **3 rounds per work item**, normally fewer. Keep delivery and
+whole-change round counts explicit; renaming the target does not reset a work
+item's cap. If blockers recur, stop the fix/review loop. Make one structural
+change addressing the failure class or ask the user about the approach. Use
+`cratis-engineering-regression-cluster` when repeated instances share a surface.
+A structural change does not authorize an automatic fourth round or waive any
+required review; report the remaining blocker or required decision.
+
+## What breaks
+
+- **A whole-change restart after every correction:** repeats work while losing
+  the earlier blocker list and dismissals. Use a delta with the prior report.
+- **Advisory becomes blocking:** a preference causes needless edits, extra
+  rounds, or unwanted issues. Preserve the shared report vocabulary.
+- **Deep by habit:** extra review displaces running the behavior without a
+  named risk. State the risk or use ordinary depth.
+- **Green by absence:** a reviewer failure or missing required proof is
+  Incomplete, not a successful review with no findings.
+
+## How it is proven
+
+Run the repository's required gates and behavioral specifications for the
+correction; successful exits are required evidence, not review substitutes.
+Use the delta command above to confirm scope and verify that each earlier
+finding has a disposition with evidence. The report includes Blockers,
+Suggestions, Dismissed (with reason), Verdict, and Not examined, per the shared
+rule. No Blockers and complete required evidence permit approval; suggestions
+alone permit Approved with suggestions.
+
+For PR descriptions and release notes, run the deterministic
+`cratis-check-pr.mjs` command from `pull-requests.md` and require a zero exit.
+Do not spend a review round on checks that script owns.

package/package/corpus/skills/cratis-engineering-review-rounds/verification.json

@@ -0,0 +1,16 @@
+{
+  "skill": "cratis-engineering-review-rounds",
+  "input": "Plan a delta round after a blocker without restarting whole-change review or filing advisory findings.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "../../rules/review-reports.md" },
+    { "kind": "skill-contains", "value": "Run one quick round per delivery" },
+    { "kind": "skill-contains", "value": "Run one whole-change review per PR" },
+    { "kind": "skill-contains", "value": "SHA, not from an arbitrary base" },
+    { "kind": "skill-contains", "value": "Prior: <complete round 1 report, including dismissals and scope limits>" },
+    { "kind": "skill-contains", "value": "3 rounds per work item" },
+    { "kind": "skill-contains", "value": "Never file an issue merely to dispose of advisory feedback" },
+    { "kind": "skill-contains", "value": "single-provider" },
+    { "kind": "skill-contains", "value": "**cross-cutting**" }
+  ]
+}

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.