@cratis/pi 7.21.0 → 7.23.0

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/refusals-and-redelivery.md

@@ -0,0 +1,102 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Refusal handling and redelivery intent
+
+## Contents
+
+- Select a refusal
+- Branch values and acknowledgement
+- Redeliver an existing occurrence
+- Recovery boundaries
+
+## Select a refusal
+
+At Screenplay 4.125.0 these forms are authoring-only: binding refuses the whole
+model with PLAY0268, even when the source is valid. Do not execute them as append
+scenarios or silently drop branches. Sources: released `reactions.md`,
+`specifications.md`, decision 0030.
+
+Inside an `invokes` block, ordered selectors state intended recovery:
+
+| Selector | Matches at future admission |
+| --- | --- |
+| `on refused` | Validation or constraint, not authorization |
+| `on refused by validation` | Input/concept/require rejection |
+| `on refused by constraint` | Any constraint rejection |
+| `on refused by constraint <Name>` | One unambiguously resolved applicable constraint |
+| `on refused by authorization` | Unauthorized, never an opaque policy's Unsupported result |
+
+The first matching selector wins. Repeated selectors or narrower branches after
+covering branches report PLAY0540; bare refusal does not cover authorization.
+Unknown named constraints report PLAY0542; known but inapplicable constraints
+also report PLAY0540. Authorization recovery requires a deliberate trusted path,
+not a fictional caller supplied by `given caller`. On current source a declared
+reaction `runs as` affects identity diagnostics, but refusal branches themselves
+remain unadmitted; do not infer their execution from that separate capability.
+
+## Branch values and acknowledgement
+
+A branch contains leaf `acknowledge` alone, or ordinary `produces <Event>` blocks
+with mappings and optional `for`. Empty branches, repeated acknowledgement,
+acknowledgement plus productions, operations, inline events and attachments refuse.
+Acknowledgement states a terminal disposition, not a successful command or fact.
+
+Branch event mappings may use String values `$refusal.reason` (validation,
+constraint, authorization), `$refusal.message` (verbatim details, including symbolic
+localization keys), and `$refusal.constraint` only in constraint selectors.
+Unknown members, wrong scope or incompatible targets report PLAY0541. Messages
+are display details, not stable identity; trigger inputs remain available, read
+aliases do not become branch inputs.
+
+The intended admitted behavior stops remaining invocations of that trigger after
+handling a refusal, but lets other reactions/cascades from accepted facts settle.
+The refused command adds no facts; branch appends obey normal constraints and
+cannot catch their own refusal through another branch. Unhandled refusal retains
+earlier accepted facts. This is a future contract, not passing runner behavior.
+
+## Redeliver an existing occurrence
+
+The complete authoring model below compiles without warnings on 4.125.0;
+`screenplay test` intentionally returns 3/unbound with PLAY0268 for redelivery
+and no-event assertion, not a recovery pass:
+
+```screenplay
+module Billing
+  feature Claims
+    slice Automation Recovery
+      event Approved
+        invoice String
+      reaction Claimer
+        when Approved
+      specification Recovery
+        given Approved
+          for "invoice-1"
+          invoice = "invoice-1"
+        when redelivered Approved to Claimer
+          for "invoice-1"
+          invoice = "invoice-1"
+        then no events
+```
+
+`to <Reaction>` must resolve to one observer of the event (PLAY0544). Optional
+`for`, payload values and stream/no-stream route narrow effective given occurrences;
+exactly one definitely matching occurrence and no unknown candidates are required
+(PLAY0543). Equal duplicate givens are still separate candidates. A locator with
+no route is a wildcard; explicit stream ids compare canonically, and `no stream`
+selects only unrouted givens. This is the sole action, not an extra action after
+append. Intended delivery uses the existing occurrence, never appends it again.
+
+Leaf `then no events` explicitly expects no new facts after a non-append action.
+It may accompany view/query/response assertions, not events, any-order events,
+error or denial. It is invalid after `when append` (PLAY0545), and remains
+unadmitted even on a model without a refusal branch.
+
+## Recovery boundaries
+
+Exceptions, infrastructure/contract errors, Unsupported and concurrency conflicts
+are not refusals. There is no `by concurrency`: transient contention fails/retries,
+not acknowledgement. Ordinary redelivery is not replay. Neither these forms nor
+an observer/occurrence locator prove runtime deduplication, a cascade-wide
+transaction, once-only delivery or exactly-once external effects. Specify the
+actual recovery owner and target enforcement before making those claims.

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/specifying-triggers-and-clock.md

@@ -18,8 +18,10 @@ specification IssuingTheWeeklyDigest
 ```
 
 Under `cratis` before 3.28.2 these actions parsed and were checked against the application
-but bound to nothing (`PLAY0268` names ESM v6, decision 0022); on 3.28.2 they bind. Either way
-no command runs them: report such a specification as authored, not executed. Clock rules: the clock is UTC and exact; an
+but bound to nothing (`PLAY0268` names ESM v6, decision 0022); on 3.28.2 they bind.
+Current standalone 4.125.0 executes admitted scenarios through `screenplay test`
+or MCP `run-specifications`; source compilation alone is authored evidence.
+Clock rules: the clock is UTC and exact; an
 occurrence fires once when it is **due after `given clock` and at or before
 `when clock`**, in time order; intervals count from the Unix epoch; `when clock`
 needs `given clock`, so equal instants fire nothing. Limits: 10,000 occurrences per

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

@@ -57,7 +57,7 @@
     },
     {
       "kind": "skill-contains",
-      "value": "Screenplay#383"
+      "value": "ESM v10"
     },
     {
       "kind": "skill-contains",

package/package/corpus/skills/cratis-screenplay-command-surface/SKILL.md

@@ -31,16 +31,12 @@ source is the single flow model.
 | `Cratis.Screenplay` | `4.31.0` | Original examples and executable boundaries |
 | `Cratis.Screenplay` | main `fd18129` | Inline events, repairs and canonical `optional`; changed examples compiled |
 | `Cratis.Screenplay` | `4.66.0` (`c89198b`) | Binding behaviour of `handler`, code attachments, `persona` and compliance attributes: `Semantics/SemanticModelBinder*.cs`, `Diagnostics/DiagnosticCodes.cs` |
-| `Cratis.Screenplay` | `4.68.0` (`79801bf`) | Current pin: generated values and responses (ESM v7): decisions 0025 and 0026, `commands.md`, `Semantics/Versions.cs`, `SemanticModelBinder.CommandProductions.cs` |
+| `Cratis.Screenplay` | `4.68.0` (`79801bf`) | Historical generated-value/response rule probes (ESM v7) |
+| `Cratis.Screenplay` | `4.127.0` | Current identity and compliance guidance: released `identity.md`, `context.md`, `concepts.md`, `purposes.md`, `events.md`, `diagnostics.md`; changed examples compiled |
 
-The update follows `commands.md`, `events.md`, `types.md`, `diagnostics.md`,
-`mcp/authoring-tools.md` and decision 0023 at that main commit (after v4.52.0).
-Compilation checks syntax and model consistency, not reference execution.
-
-Checked against the Screenplay repository at tag `v4.31.0` (commit `355dffb`):
-`Documentation/screenplay/{commands,constraints,policies,context,concepts,diagnostics}.md`
-and decisions 0001 and 0003 established the original baseline. Changed examples
-use the newer main commit above; do not attribute their verification to the old tag.
+Historical examples/probes retain the table's original versions; current source
+guidance is not a relabeled old execution result. Compilation checks syntax and
+model consistency, not reference execution. Pins: toolchain `references/versions.md`.
 
 "Parses" and "runs" are different claims. The executable profile, and what
 each construct binds to, is in the `cratis-screenplay-model-authoring` language
@@ -54,8 +50,8 @@ concept DiscountPercentage : Decimal
   validate
     >= 0    message "A discount cannot be negative"
     <= 100  message "A discount cannot exceed 100 percent"
-concept PersonName : String @pii
-  pii reason "Billing contact name; lawful basis: contract performance."
+concept PersonName : String pii
+  pii reason "Identifies the billing contact."
 concept InvoiceStatus : Enum
   draft
   sent
@@ -65,28 +61,19 @@ concept InvoiceStatus : Enum
 The seven primitives are `Uuid`, `String`, `Int`, `Decimal`, `Bool`, `Date` and
 `DateTime`. `Enum` is **not** one of them — it is a separate concept kind, which
 is why the compiler says *expected … or Enum* rather than listing it among them.
-Attributes `@pii` and `@sensitive`, each with at most one `reason`; a
-reason for an attribute the concept does not declare is an error. **Compliance is
-inherited** — a property typed with a `@pii` concept is PII everywhere. The
-executable model does not bind compliance attributes (`PLAY0268`, "compliance attributes
-require portable data-subject semantics"), so a `@pii` model stops at authorable (V1);
-keep the attribute, because the classification is the point, and never drop it to bind
-or render.
-
-`@pii` is personal data (erasable); `@sensitive` is an **operational secret** (API key,
-token, a company's bank account number): encrypted at rest without erasure and withheld
-from the causation chain (Screenplay decision 0034, Screenplay#384). C# providers render
-`@sensitive` as `[Encrypted]` + `[NotAudited]`, `@pii` as `[PII]`, and `@pii @sensitive`
-as `[PII]` only, because Chronicle rejects `[PII]` with `[Encrypted]` (`CHR0053`); Stage
-renders this from v4.29.0. The executable model still stops at `PLAY0268` for either.
-
-⚠️ **Identifiers are neither `@pii` nor `@sensitive`.** Chronicle rejects `[PII]` on an
-event source id (`CHR0034`) and `[Encrypted]` on one (`CHR0052`); Screenplay reports
-`PLAY0515` for `@pii` from Screenplay 4.69.1 and for `@sensitive` from 4.84.1, on a
-command identifier, an explicit `for` destination or an event source identifier; earlier
-versions compile it silently and only Chronicle catches it. Keep the stream identity a surrogate `Uuid`
-concept and carry the personal value (name, email) as a separate `@pii` property and a
-secret as a `@sensitive` property.
+Use bare `pii` for personal data (`personal` is the same marker) and `secret`
+for operational secrets. **Compliance is inherited** from concepts, including
+nested uses. Either marker blocks executable binding with PLAY0268; keep the
+protection. `pii personal` is redundant and warns PLAY0653. Legacy `@pii`,
+`sensitive` and `@sensitive` remain accepted with PLAY0565 information and a repair.
+Read [compliance and purposes](references/compliance.md) for reasons, special/criminal
+qualifiers, secret scopes, provider mappings, purpose declarations and coverage checks.
+
+**Identifiers cannot be personal data or secrets.** PLAY0515 is a source error
+for command identifiers, typed `for` destinations, event-source identities,
+scalar/composite stream-id types and nested route mapping sources, including legacy
+markers. Keep a surrogate identity and carry protected data in the payload.
+Chronicle likewise rejects `[PII]`/`[Encrypted]` identifiers (CHR0034/CHR0052).
 
 ⚠️ **Enum trap.** A value literally named `validate` is read as an empty validate
 block. Write `@validate` for the value; the compiler warns when it sees the
@@ -245,8 +232,8 @@ choosing or omitting `for` on a production, or fixing `PLAY0469`-`PLAY0478`.
 
 - **Mapping sources** that bind to the executable model: a command property
   (`= invoiceNumber`), a literal (`= "draft"`, `= 0`), `$context.occurred`, and
-  the caller's audit identity (`$context.identity.id`/`.name`/`.userName`, the
-  same values as `$context.causedBy.*`). The last two select ESM v2.
+  the caller's audit identity (`$identity.id`/`.name`/`.userName`, also supported
+  as `$context.identity.id`/`.name`/`.userName`, the same values as `$context.causedBy.*`). The last two select ESM v2.
   `$context.tenant`, claims, roles, causation, `$env.` values, templates and
   computed expressions parse but block binding (`PLAY0268`).
 - **`for <identifier>`** on an indented line names the event source the event is
@@ -271,6 +258,23 @@ produces when isProForma == true
     for invoiceId
 ```
 
+## Routes and external operations
+
+Named event sources/streams and command routes bind as ESM v8 (verified at 4.125.0);
+CLI 3.41.0 render rejects models above v7. A routed command's identifier and
+known event destinations must match the source's nominal identifier type
+(PLAY0504, error). Allocation uses the generated identifier's type, or without
+one requires a UUID-based source. Composite `streamId` routes map every named
+part exactly once; scalar `streamId T` and `streamId = x` remain valid. The complete checked route example
+and nested `streamId =` form are in `cratis-screenplay-toolchain`
+`references/sources-and-streams.md`.
+
+Use `system`, `uses` and inline/standalone `operation` declarations to state
+external work in the authored production sequence, with execute/compensate phase
+intent. These remain unadmitted (PLAY0268), not post-commit reactions. Read
+[operation intent](references/operations.md) for forms, boundaries and checked
+failure/compensation specification syntax.
+
 ## `concurrency`
 
 Five dimensions, each at most once, and at most one `concurrency` block per
@@ -292,8 +296,9 @@ to the routed scope. This does not make command `reads` protected.
 
 ## Generated values and responses (ESM v7)
 
-A `generated` property and a `returns` response need standalone `screenplay` 4.68.0; the cratis CLI reports
-`PLAY0268` and Stage refuses them, so such a command is **not rendered yet**: hand-write it.
+Generated values/responses bind as ESM v7, including in the current CLI bundle.
+CLI 3.41.0 admits v7 to Stage planning; its canonical corpus gets generated-value
+and response refusals STAGE-ESM-028/029. Binding is not a render claim.
 Read [references/generated-values-and-responses.md](references/generated-values-and-responses.md) when adding or
 reviewing `generated` properties, `returns` responses, or decision 0023 constructs.
 Read `cratis-screenplay-toolchain/references/generated-responses-example.md` when adding generated command values or response assertions and you need a complete compiled example.
@@ -340,7 +345,15 @@ not both win — a `validate` rule cannot do that.
 A policy has **exactly one** `require` line (`PLAY0441`) **or** one implementation, never both (`PLAY0440`). Read [references/policy-persona-seed.md](references/policy-persona-seed.md) when
 declaring a policy, a persona, or a `seed` block.
 
-## `$context`
+## Event data subject
+
+One event property may carry trailing `subject`; it identifies the person whose
+data the event holds, not the stream identity. Only unprotected required scalar
+String/Uuid or String/Uuid/Int-backed concepts are allowed. The mark is report-only
+(PLAY0270), changes no ESM bytes and emits no C# `[Subject]` yet; read models are
+not supported. See [subject lineage](references/compliance.md#identify-the-person-not-the-stream).
+
+## `$context` and `$identity`
 
 Four contexts, and **what each omits is load-bearing** — when writing a code body or a context/expression mapping, read
 [context.md](references/context.md) for the full member lists, the declarative
@@ -355,10 +368,9 @@ Four contexts, and **what each omits is load-bearing** — when writing a code b
 
 ## Verify
 
-- [ ] Standalone `screenplay <model> --warnaserror` (4.68.0) reports zero errors and zero
-      warnings; or `cratis screenplay validate --warnings-as-errors` on the model folder
-      (3.28.2 and 3.28.3 bundle Screenplay 4.66.0, ESM v6 at most; before 3.28.2 bundled 4.60.1, ESM v5
-      or lower). Name which tool produced the result.
+- [ ] Validate the complete model root with warnings as errors; name the tool,
+      version and result. Current pins: standalone 4.127.0 / CLI 3.41.0; bundle
+      compatibility and execution are separate checks.
 - [ ] No unintended `PLAY0478` or `PLAY0479` information remains.
 - [ ] At most one command property carries `identifier`, and no event property does.
 - [ ] Format rules live on the `concept`; state-dependent rules are specifications.
@@ -367,8 +379,9 @@ Four contexts, and **what each omits is load-bearing** — when writing a code b
       is stated.
 - [ ] Constraints are `unique` forms; no `file` constraint stands in for another rule.
 - [ ] Each policy has one `require` or one implementation, not both.
-- [ ] Personal data is `@pii` on the concept, with a reason; no identifier concept is `@pii`;
-      operational secrets are `@sensitive` (never `@pii`), and no identifier concept carries either.
+- [ ] Personal data is `pii` on the concept; operational secrets are `secret`;
+      no identifier or subject concept carries either. Reasons explain the value,
+      while purposes declare basis/retention; run `--check purposes` separately.
 - [ ] No `handler` where the model must bind, and no bodied construct described as
       runnable or renderable without saying which tool admits it.
 - [ ] No event carries an optional property covering two situations.

package/package/corpus/skills/cratis-screenplay-command-surface/references/compliance.md

@@ -0,0 +1,154 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Personal data, secrets and processing purposes
+
+## Contents
+
+- Classify the value on its concept
+- Declare the use separately
+- Identify the person, not the stream
+
+Authority: Screenplay v4.127.0 `concepts.md`, `purposes.md`, `events.md` and
+`diagnostics.md`; decision 0041. These declarations do not establish lawful
+processing or enforce retention. Check provider support separately.
+
+## Classify the value on its concept
+
+```screenplay
+concept Email : String pii
+  pii reason "Contact address"
+concept MedicalNote : String personal
+  personal special health
+concept ConvictionNote : String pii
+  pii criminal
+concept PartnerApiKey : String secret
+  secret scope namespace
+  secret reason "Credential for the partner API"
+```
+
+`personal` is an alias of `pii`, not a second classification; canonical printing
+writes `pii`. Write one marker. `pii personal`, `pii pii`, `secret secret` and
+`@pii @pii` report one PLAY0653 warning per header. Both compilers retain the
+first occurrence of each marker and attach body settings to it. The concept-line
+repair removes later tokens with `PreserveTrivia`, retaining notes and comments.
+
+`@pii`, `sensitive` and `@sensitive` still compile but are deprecated: one PLAY0565
+information diagnostic per line. The line/document repair migrates them to bare
+`pii`/`secret` without moving notes. `--warnaserror` does not fail on information.
+Unknown markers report PLAY0566. Never remove protection to get a model to bind.
+
+A reason is an optional free-text note about the value, not a lawful basis,
+purpose or retention policy. At most one reason per declared marker; a reason for
+an absent marker is an error. Classification is inherited through concept uses,
+including fields nested in composite types; do not put markers on properties or
+composite types.
+
+`pii special` requires one of `racialOrEthnicOrigin`, `politicalOpinions`,
+`religiousOrPhilosophicalBeliefs`, `tradeUnionMembership`, `genetic`, `biometric`,
+`health`, `sexLifeOrSexualOrientation` (GDPR Art. 9(1)). `pii criminal` records
+Art. 10 data and may coexist with `special`. These qualifiers require `pii`;
+unknown categories and repeated `special` lines are errors (PLAY0570/0571).
+A photograph alone is not biometric identification data.
+
+`secret scope` accepts `subject`, `namespace`, `global`; omitted scope retains
+Chronicle's Subject default. Scope on `pii`, duplicate scope and unknown values
+are errors (PLAY0567/0568). Explicit scope on `pii secret` warns (PLAY0569),
+because only `[PII]` renders. Changing scope for persisted event uses requires a
+new event generation.
+
+C# provider mapping: `pii` → `[PII]`; `secret` → `[Encrypted]` + `[NotAudited]`;
+`pii secret` → `[PII]` only (Chronicle refuses `[PII]` with `[Encrypted]`, CHR0053).
+This mapping is not admission: either marker, including qualifiers and scopes,
+still blocks executable binding with PLAY0268. Subject lineage is a different
+role, described below.
+
+## Declare the use separately
+
+```screenplay
+concept ContactName : String pii
+  pii reason "Identifies the customer's contact"
+purpose Billing
+  description "Issue invoices and collect payment"
+  basis contract
+  subjects customer, customerContact
+  retention "Until the customer relationship ends"
+  recipient "Payment provider"
+module Finance
+  purpose Billing
+  feature Invoices
+    slice StateChange RecordContact
+      command RecordContact
+        name ContactName
+```
+
+A top-level `purpose` has optional singleton `description`, `basis` (optional
+quoted legal reference), `interest`, `condition` (optional quoted reference),
+`authorization`, `subjects` (comma-separated categories), `retention`, and
+`erasure exception`; `recipient` and `transfer "<destination>" safeguard
+"<safeguard>" repeat. Text fields are quoted; description also accepts a text
+fence. Unknown closed values or repeated singleton fields are errors.
+
+- `basis`: `consent`, `contract`, `legalObligation`, `vitalInterests`, `publicTask`,
+  `legitimateInterests` (Art. 6(1)). The last needs a nonblank `interest` statement;
+  inconsistent interest/basis warns (PLAY0601).
+- `condition`: `explicitConsent`, `employmentLaw`, `vitalInterests`, `notForProfit`,
+  `madePublic`, `legalClaims`, `substantialPublicInterest`, `healthCare`,
+  `publicHealth`, `research` (Art. 9(2)).
+- `erasure exception`: `expression`, `legalObligation`, `publicTask`,
+  `publicHealth`, `archiving`, `legalClaims` (Art. 17(3)).
+
+Repeat `purpose <Name>` on modules, features or slices. Coverage is the **union**
+of those references and ancestors' references, unlike authorization's AND rule.
+Unresolved references warn (PLAY0600). Purpose metadata adds no ESM bytes and
+reports PLAY0270; it does not implement consent, a legal hold or crypto-shredding.
+
+Run `screenplay <root> --check purposes --warnaserror`: PLAY0602–0606 prompt for
+uncovered personal data (including nested concepts), missing special-category
+conditions, criminal authorization, bases and unused purposes. Ordinary compile
+does not run this check. Findings are investigation prompts, never a legal verdict.
+
+`screenplay report processing <root> --format markdown|json|csv` derives the
+processing record; optional `--controller-name` and `--controller-contact` are
+explicit inputs, never inferred. MCP `processing-record` returns revision-bound,
+count/byte-bounded pages (`offset`, `expectedSourceRevision`); repeat controller
+inputs across pages. Invalid source prevents reporting; binding is not required.
+Opaque code/imports/runtime protections are not inferred. Zero purposes yields
+zero rows, not compliance. Special/criminal data prompts a DPIA assessment, not a
+claim of large-scale processing. An erasure exception with reachable `pii` flags
+that per-subject crypto-shredding also destroys data kept for that purpose.
+Move legal declarations out of old reasons by hand; repairs never guess them.
+
+## Identify the person, not the stream
+
+An event property may end in `subject`, last among modifiers (before `=` on an
+inline mapping). Each generation may choose one mark independently:
+
+```screenplay
+concept CustomerId : Uuid
+module Billing
+  feature Contact
+    slice StateChange ChangeContact
+      event CustomerContactChanged
+        customerId CustomerId subject
+        note String
+```
+
+Required scalar `String`/`Uuid`, concepts over either, and Int-backed concepts
+are allowed. Bare Int, optional/collection/composite values, enums, Decimal,
+Bool and dates are refused. A `pii` or `secret` concept is refused because
+`EventContext.Subject` is plaintext. Use a surrogate identity; an empty String
+cannot be detected statically and Chronicle falls back to the event source.
+Equal identity strings across entity kinds share one subject; favor Uuid.
+
+PLAY0590–0595 cover multiple marks, invalid/protected types, wrong owner,
+unsupported read-model marks and repeated/out-of-order modifiers. The mark is
+report-only (PLAY0270): it changes no ESM bytes or runtime value and emits no
+C# `[Subject]` yet. Without a supplied subject the runtime's
+`$eventContext.subject` defaults to the event source. Do not promise propagation,
+erasure, export or redaction from this declaration. MCP exposes `isSubject` and
+event summaries' `subject.source` (`eventSource` or `property`).
+
+The event data subject, `secret scope subject` (encryption scope), and policy
+`matches subject` (the thing acted on, not the caller) are three different roles.
+For actual Chronicle erasure and attributes, use `cratis-chronicle-compliance`.

package/package/corpus/skills/cratis-screenplay-command-surface/references/context.md

@@ -5,6 +5,7 @@
 - The four contexts
 - The values they carry
 - Reaching the context declaratively
+- Caller paths and identity details
 - Production metadata is not a context expression
 - The other expression roots
 - Templates and literals
@@ -50,6 +51,15 @@ time: `CommandAs<T>()`, `ArgumentsAs<T>()`, `ArtifactAs<T>()`, `ValueAs<T>()`, a
 `StateAs<T>()`/`EventAs<T>()` on the reducer context. A payload of another type
 throws `ContextPayloadTypeMismatch`.
 
+At Screenplay 4.125.0, typed contexts before generation (`CommandValidation`,
+`ConceptValidation`, `RulePredicate`, `PolicyPredicate`) expose **input properties
+only**. Generated values exist only after authorization/validation, so they are
+absent from those shapes. A generated identifier's policy subject is `unavailable`,
+not the eventual id; never authorize against it. The handler CommandContext retains
+the full command shape, including generated properties. Sidecars belong to the same
+compilation/revision as their requirements, not a shape borrowed from another model.
+Source: `v4.125.0:Documentation/screenplay/context.md`.
+
 ## The values they carry
 
 | Type | Members |
@@ -88,6 +98,52 @@ roles, claims and causation report `PLAY0268`.
 
 An unknown `$context.` path is reported, so a typo does not silently become null.
 
+## Caller paths and identity details
+
+At Screenplay 4.127.0, `$identity.<property>` is the same caller value as
+`$context.identity.<property>`. Prefer `$identity` in new mappings; the older root
+is supported, not deprecated. The `cratis` CLI 3.41.0 bundles Screenplay 4.114.0, which predates both:
+its parser rejects a top-level `identity` block (`PLAY0001`), and with `--executable` it reads a
+`$identity.<property>` mapping as a raw expression (`PLAY0268`). Check these with standalone 4.127.0,
+and keep `$context.identity.<property>` where a model must go through `cratis render` today. Built-ins are `id`, `name`, `userName`,
+`isAuthenticated`, `roles`, `claims.<name>` (everything after `claims.` is opaque).
+Bare `$identity` reports PLAY0152; unknown properties report PLAY0155. Only
+`$identity.id`/`.name`/`.userName` bind in portable `produces` mappings, exactly
+like the older forms; roles, authentication status and claims still report PLAY0268.
+
+A top-level `identity` block declares additional typed caller details:
+
+```screenplay
+identity
+  description "What the application knows about whoever is calling"
+  department String optional from claim "department"
+  organization Organization optional from query MyOrganization by $identity.id
+module Organizations
+  feature Membership
+    slice StateView Mine
+      readmodel Organization
+        name String
+      query MyOrganization => Organization optional
+        by userId String
+```
+
+At most one block per document and assembled folder; layout expansion writes it
+to `application.play`. Each unique detail has exactly one source: opaque claim,
+keyed single-result query, tagged inline code fence or repository-relative `file`.
+It cannot redeclare built-ins. Claim/query sources have no body; refresh/cache
+belongs to the runtime. Query sources need `by <expression>` using only token
+built-ins, claims or literals, never another detail, input, environment or view.
+The query's effective authorization must not depend on details. Result type must
+match; an optional query result needs an optional detail, while a required result
+may populate an optional detail. Details may themselves be optional or collections.
+
+The block is **authoring metadata**, not runtime source resolution or ESM data.
+Declarations alone do not block executable readiness. Executable reads of
+`$identity.<detail>` report PLAY0268; `$context.identity` stays built-ins only.
+`scoped to` is an opaque scope name, not a detail reference. PLAY0633–0646 diagnose
+source/header/type/cardinality errors; there are no automatic identity repairs.
+Authority: v4.127.0 `identity.md`, `context.md`, `diagnostics.md`.
+
 ## Production metadata is not a context expression
 
 `namespace`, `sequence`, `correlation`, `causation`, `causedBy` and `occurred`
@@ -102,6 +158,7 @@ occurrence metadata; use `given clock`, never `given time`, to state scenario ti
 
 | Root | Where | Yields |
 | --- | --- | --- |
+| `$identity.<property>` | caller expression | built-in caller value or declared authoring detail; execution admission is narrower |
 | `$env.<VAR_NAME>` | mapping sources | an environment variable |
 | `$eventContext.<property>` | **projections only** | `occurred`, `sequenceNumber`, `correlationId`, `eventSourceId` |
 | `$eventSourceId` | **projections only** | shorthand for `$eventContext.eventSourceId` |

package/package/corpus/skills/cratis-screenplay-command-surface/references/generated-values-and-responses.md

@@ -1,10 +1,13 @@
 ## Generated values and responses (ESM v7)
 
-A `generated` command property and a `returns` response bind and execute from the standalone
-`screenplay` 4.68.0 (ESM v7, decision 0026; `commands.md` "Generated values and responses" at
-`v4.68.0`). The cratis CLI 3.28.3 bundles 4.66.0 and reports `PLAY0268` for them, and Stage 4.24.2
-refuses ESM v7 with `STAGE-ESM-016` (tracked in Stage#201), so a command that uses them is
-**not rendered yet**: hand-write it (gap-fill) with the model as the contract. Complete compiled example:
+A `generated` command property and `returns` response bind and reference-execute
+as ESM v7. Current pins are standalone Screenplay 4.127.0 and CLI 3.41.0
+(bundled Screenplay 4.114.0/Stage 4.51.3); `cratis-screenplay-toolchain`
+`references/versions.md` owns the table. CLI#261 is closed: CLI now admits v7
+to Stage planning, but its v7 canonical corpus receives Stage generated-value
+and response refusals STAGE-ESM-028/029. Do not turn this into a blanket compiler
+refusal or promise a render from binding alone. Preserve the contract for gap-fill
+where admission refuses. Historical rules below were read at 4.68.0. Complete compiled example:
 `cratis-screenplay-toolchain` `references/generated-responses-example.md`.
 
 ```screenplay excerpt
@@ -40,12 +43,11 @@ Rules (all read at `v4.68.0`):
 - Generated values give no idempotency, retry or deduplication guarantee. Specifications supply fixtures and assert
   the response: `cratis-screenplay-specifications`.
 
-Other decision 0023 constructs are still **authorable, never executable** (binding reports `PLAY0268`, so
-they stop a model at V1): operations, and named event sources and streams with command routes
-(`eventsource`, `stream`, `streamId`). **No supported ESM version admits them**, and they have no version number
-yet (decision 0025 numbers a version only at its release-ready admission). Syntax or MCP acceptance is not proof of
-execution. A model using sources, streams or routes can be authored and validated, but
-not bound, run or rendered; hand-write the code with the model as contract
-(`cratis-screenplay-toolchain` `references/sources-and-streams.md`). `derive` and `provide` have no documented syntax at that tag; treat them as
-planned and do not write them.
+Operations remain authorable/unadmitted (PLAY0268). Named event sources,
+streams and command/specification routes instead bind and reference-execute as
+ESM v8 at 4.125.0; CLI 3.41.0 render refuses versions above v7 before planning
+(CLI-RENDER-004). Syntax/MCP acceptance alone is not execution. Source/stream
+forms and realization boundary: `cratis-screenplay-toolchain`
+`references/sources-and-streams.md`. Do not infer further syntax or provider
+admission from decision numbers.