@cratis/pi 7.66.0 → 7.68.0

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

@@ -2,6 +2,7 @@
 
 ## Contents
 
+- Validation commands and the gate file
 - Samples and preview fixtures
 - Lexical and structural rules
 - Exact numeric source mode
@@ -28,8 +29,8 @@ keeping the capture in Translate. No automatic split.
 Requires Screenplay 4.176.0 or later; older compilers leave that shape unchecked.
 Read
 [public contracts](../../cratis-screenplay-automations-and-translations/references/public-events-and-direction.md).
-View properties use trailing `key`; multipart `by` query/read blocks remain
-PLAY0268, not v10. Read [named keys](../../cratis-screenplay-read-surface/references/named-keys.md).
+View properties use trailing `key`; several parts select v27 (not v10), with a `by` block on
+an optional single-instance query and equality filters on lists. Read [named keys](../../cratis-screenplay-read-surface/references/named-keys.md).
 Production `stream Source.Stream` overrides and reaction/reducer `from Source[.Stream]`
 select released v10: [routes and filters](production-routes-and-filters.md).
 Qualifying non-route Double literals select v11;
@@ -57,6 +58,20 @@ by `for_Documentation/when_comparing_the_grammar_against_the_parsers.cs`),
 Screenplay CI (`when_compiling_every_example.cs`) against repository main: the standalone
 compiler; the compiler bundled in `cratis` can be older and lack the newest ESM versions.
 
+## Validation commands and the gate file
+
+```shell
+screenplay <root> --warnaserror --no-color      # V1; also reads <root>/screenplay.json
+screenplay <root> --print-gate                  # effective gate and each value's source, no compile
+screenplay <root> --format json                 # one JSON report: diagnostics, gate, exitCode
+screenplay <root> --no-gate-file --check all    # bypass the file for one run
+screenplay test <root>                          # V4
+```
+
+`screenplay.json` (authored, beside `.screenplay/`) holds `validation.checks`, `warningsAsErrors`, `scope`
+and `openQuestions`; unknown keys or check names are refused (exit 2), never ignored. Details and
+precedence: [verdicts](verdicts.md).
+
 ## Samples and preview fixtures
 
 Invoicing is a warning-free syntax showcase, not a runnable whole-language proof.

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

@@ -8,6 +8,7 @@
 - Explicit enum member numbers
 - Reserved stored names and event pins
 - Named keys, production routes and observer filters
+- Reducer instance identity (PLAY0690)
 - Caller identity, compliance and routes
 - Specification metadata, callers, cases and locators
 - Guarded interaction diagnostics
@@ -137,13 +138,25 @@ Target evidence: a renderer must admit ESM v16 and preserve `storedName`, or ref
 | PLAY0665 | E | Invalid/duplicate/child-bearing/unresolved source/stream filter or filtered reaction with a non-event trigger |
 | PLAY0666 | W | Filter excludes all statically known effective producer routes; C# only, handlers/foreign origins suppress it |
 
-Queries and trigger reads have no PLAY0661 repair. Composite view keys, query
-blocks and their fixtures remain PLAY0268, while one explicit key binds
-byte-identically to inference. Fixtures missing any part report PLAY0351.
+Queries and trigger reads have no PLAY0661 repair. Flat composite view keys bind as v27;
+projection or removal key blocks missing a part report PLAY0661 and bad parts PLAY0662.
+One explicit key binds byte-identically to inference. Fixtures missing any part
+report PLAY0351. Joins, children, `every`, `all`, `nested`, `variant`, reducers and
+list-query `by` blocks over a composite-keyed view are PLAY0268.
 Overrides/filters select released ESM v10; malformed routes also use PLAY0504.
 Read read-surface `references/named-keys.md` and
 [production routes and filters](production-routes-and-filters.md).
 
+## Reducer instance identity (PLAY0690)
+
+| Code | Severity | Meaning / fix |
+| --- | --- | --- |
+| PLAY0690 | W | A reducer instance is keyed by the event-source id, so a reducer-backed scalar query `by` another nominal type, or a reducer whose complete producers use several identity types, warns. Reducers cannot be re-keyed: use a projection with a property key on each `from`, or a join for existing instances |
+
+Fails `--warnaserror`. Compares declared nominal types only where producers are known (command `for`, implicit or generated identifiers, reaction `for`); plain `produces` without `for`, reactions without `for`, captures, seeds and code are not compared. Native C# only: a clean editor proves nothing. Example and limits: projections [reducer identity](../../cratis-screenplay-projections/references/reducer-identity.md).
+
+Requires Screenplay 4.170.0 or later (`screenplay --version`); an older compiler does not report it, and `cratis screenplay validate` reports it only when its bundled compiler is that new.
+
 ## Caller identity, compliance and routes
 
 | Code | Severity | Meaning / fix |
@@ -307,8 +320,8 @@ identity details (0633–0646), compliance/subject checks, reaction identity
 A shared catalog code is not proof that a check is implemented in both compilers.
 
 C# CLI/MCP owns whole-application scoped diagnostics, opt-in completeness
-(including PLAY0530–0537, PLAY0602–0606 and PLAY0652), bound reaction gate
-checks PLAY0650/0651, semantic binding and PLAY0546 (a negated claim targets optional,
+(including PLAY0530–0537, PLAY0602–0606 and PLAY0652), reducer identity
+PLAY0690, bound reaction gate checks PLAY0650/0651, semantic binding and PLAY0546 (a negated claim targets optional,
 unavailable-subject or non-text data). The VS Code repair bridge is not a general
 C# validator. A clean editor is not V1 for the complete application, V3 binding
 or V4 execution. Run the CLI or MCP for those verdicts.
@@ -346,15 +359,16 @@ refusal reasons. Read [language admission](language-admission.md) before changin
 | PLAY0785 | Ambiguous view path; use distinct aliases on repeated reads |
 | PLAY0786 (I) | Eligible legacy model; preview typed preamble repair, individually review absence/conflict semantics |
 | PLAY0787 (W) | Exact deprecated Studio text-rule pattern; repair to literal rule or equality, preserving message/severity |
-| STAGE-ESM-043 | Atomic mode not realized, even in admitted v23–v25; retain declaration and gap-fill |
+| STAGE-ESM-043 | Atomic mode not realized, even in admitted v23–v26; retain declaration and gap-fill |
 | STAGE-ESM-044 | Cratis C# renderer refuses protected reads despite v25 admission; semantic Host/executor support is separate; keep protection and gap-fill generated-app scope |
 | STAGE-ESM-045 | Non-Error protected requirement; semantic Host/executor refuse before execution, including reaction-invoked commands; keep severity and report Unsupported |
 | STAGE-IMPL-002 | Described handler body not realized by Stage, even Stub mode; no stubs emitted |
 
 Invalid match syntax remains PLAY0367. Property/concept text rules bind v24;
 `contains`/`starts with` in conditions only still fail PLAY0268. Stage rejects
-v22/v26 and mixed pairs with STAGE-ESM-016; v23–v25 admission does not implement
-bodies, batches or rendered protected reads (STAGE-ESM-044). Requires Stage 4.129.0
+v22/v27 and mixed pairs with STAGE-ESM-016; v23–v26 admission does not implement
+bodies, batches or rendered protected reads (STAGE-ESM-044), and the renderer refuses
+v26 date comparisons with STAGE-ESM-046. Requires Stage 4.129.0
 for semantic Host/executor protected reads; older engines refuse -044. Read
 [language admission](language-admission.md) for the stricter Host outside-append guard.
 

package/package/corpus/skills/cratis-screenplay-toolchain/references/executable-subset.md

@@ -11,6 +11,7 @@
 - Generated values and responses (ESM v7)
 - Released public boundaries and observer routes
 - Chronological command date comparisons (ESM v26)
+- Flat composite read-model keys (ESM v27)
 - Code attachments (what binds, what never does)
 - Refused (code, reason): fix, or record as a mode gap
 - Not refused, but do not rely on it
@@ -41,7 +42,7 @@ Complete examples that bind live in `executable-example.md`, `pdl-example.md` (p
 `automation-translate-example.md` (ESM v6) and `generated-responses-example.md` (ESM v7).
 
 For atomic batches (v22), described handlers (v23), ordinal text rules (v24) and
-protected reads (v25) and chronological command dates (v26), read
+protected reads (v25), chronological command dates (v26) and composite keys (v27), read
 [language admission](language-admission.md). A later
 version alone does not enable either application opt-in.
 
@@ -86,10 +87,10 @@ Requires Screenplay 4.141.0 or later (`screenplay --version`) to bind concept co
   none supplies identity and an admitted list query exists does conventional
   `*Id` inference run (collection-key exclusions: read-surface `references/named-keys.md`).
   Queryless read models need an explicit `key`. Explicit single keys preserve
-  equivalent inferred ESM bytes. Composite read-model keys, query `by` blocks and
-  their fixtures remain PLAY0268. Collections and observable delivery bind.
+  equivalent inferred ESM bytes. Flat composite read-model keys bind as v27
+  (see below). Collections and observable delivery bind.
   Caller-supplied equality filters on collections also bind as ESM v14; context
-  sources, single-result filters, scope, performer and composite `by` remain blocked.
+  sources, single-result filters, scope, performer and a list-query `by` block remain blocked.
 - One projection per read model: `from`, `every`, `all` (one block per level), `join`,
   `children`, `nested`, `remove with`, `remove via join` (binds; blocks the execution plan at the projection level, see below), `clear with`, counters, `add`,
   `subtract`, `set`, `clear`, variants, and the identifier mapped from the projection's key (`xId = $eventSourceId` only for an event-source key).
@@ -264,15 +265,36 @@ DateTime input needs an offset or `Z`, else Validation rejects before rules, eve
 for skipped comparisons. `then` matching stays ordinal. Invalid date literals or
 offset-less DateTime literals in admitted comparisons report PLAY0273. Read
 [date comparisons](../../cratis-screenplay-command-surface/references/date-comparisons.md)
-for the complete window model and retained PLAY0268 refusals. Stage refuses v26
-with STAGE-ESM-016, independently of standalone binding/reference execution.
+for the complete window model and retained PLAY0268 refusals. The Stage renderer refuses
+v26 date comparisons with STAGE-ESM-046, independently of standalone binding/reference execution.
+
+## Flat composite read-model keys (ESM v27)
+
+Requires Screenplay 4.204.0 (ESM v27; `screenplay --version`); older binders refuse a
+read model with two or more `key` marks with PLAY0268. Binding admits a model with
+several flat scalar key parts when:
+
+- root `from` and `remove with` blocks name every part in an untyped `key` block;
+- a list query narrows with equality filters, and an optional single-instance query
+  names every part in a `by` block;
+- fixtures state every part (`given readmodel`, `then readmodel`, `then no readmodel`).
+
+Models with one `key` mark keep their earlier version and bytes. Refused with PLAY0268:
+joins, `children`, `remove via join`, `every`, `all`, `nested`, `clear with`, `variant`
+and reducers on the composite-keyed read model, a list query with a `by` block, a
+non-optional single-instance return, and command reads (PLAY0271, or PLAY0781
+ByParts under `command reads protected`) or trigger reads that produce directly.
+Stage refuses v27 with STAGE-ESM-016, independently of standalone binding and
+reference execution. Read read-surface
+[named keys](../../cratis-screenplay-read-surface/references/named-keys.md) for the
+complete example.
 
 ## Code attachments (what binds, what never does)
 
 Pending `handler implementation` beside unconditional `produces` binds as a described
 command (v23). Its payload-only body returns Unsupported ImplementationBody when reached;
 denial/validation specs still run. Read [language admission](language-admission.md) for
-v22–v26 and [described handlers](../../cratis-screenplay-command-surface/references/described-handlers.md)
+v22–v27 and [described handlers](../../cratis-screenplay-command-surface/references/described-handlers.md)
 for the result contract. Attached handlers remain unbound.
 
 Inline fences (`csharp`, `typescript`, `react`, `html`, `sql`) and `file <path>` attach
@@ -316,7 +338,7 @@ bodies still leave their owner non-executable.
 | `Automation` or `Translate` slice, `reaction`, `capture`, `trigger`; `given clock`, `when clock`, `when trigger`, `when capture` | PLAY0268 | **older bundled compilers only**; current compilers bind them (ESM v6) |
 | Unquoted `import Other.Contract` | PLAY0268 | external contract import is not bound |
 | `pii` or `secret` on a concept | PLAY0268 | Older compilers refuse it outright. Current compilers admit v13 except enum/identity compliance and events mixing personal or explicitly subject-scoped secret values with explicit subject marks; see `compliance.md` in command-surface references |
-| `query` with a composite `by` block, or `by ... from` context-derived arguments | PLAY0268 | composite `by` blocks remain unadmitted. An optional scalar snapshot lookup, an unfiltered list (`RM[]`) and a list narrowed by one caller-supplied `by` key bind, in their `observable` form too |
+| `query` with a `by` block over a list, or `by ... from` context-derived arguments | PLAY0268 | a `by` block binds only on an optional single-instance query (v27). An optional scalar snapshot lookup, an unfiltered list (`RM[]`) and a list narrowed by one caller-supplied `by` key bind, in their `observable` form too |
 | Context `from`, single-result filters, `scoped to`, `performer` queries | PLAY0268 | Typed query context, filtering of single results, opaque scope and query implementation remain unadmitted; each refusal names its reason. Caller-supplied collection equality filters bind as v14. `observable` goes in the return position (`=> observable RM[]`); as a body line it is PLAY0048 |
 | `contains` or `starts with` in conditions only | PLAY0268 | conditions admit scalar equality and numeric ordering, plus same-primitive command date comparisons from v26; property/concept text rules bind as v24 |
 | Date comparisons with mixed primitives, `$context` (including occurred), `today`, protected read paths, optional condition operands, concept rules or reaction `where` | PLAY0268 | v26 admits only command conditions and command/property literal validation rules |
@@ -338,7 +360,7 @@ bodies still leave their owner non-executable.
 | `generated` or `returns` on an older compiler | PLAY0268 | admitted from ESM v7, see above |
 | Operations or systems, `numbers exact` source mode | PLAY0268 | not admitted by any supported ESM version; one such construct leaves the **whole** application without an executable model. Event sources/streams/routes instead bind as ESM v8 on the current compiler (`sources-and-streams.md`) |
 | Spec of a gated command or query without `given caller` | PLAY0389 | module and feature gates count |
-| `given` or `then readmodel` missing key parts | PLAY0351 | explicit `key` marks replace inference; composite fixtures need every part but remain unadmitted |
+| `given` or `then readmodel` missing key parts | PLAY0351 | explicit `key` marks replace inference; composite fixtures need every part (v27) |
 | When-less spec asserting events or errors | PLAY0352 | |
 | `null` in command or event values | PLAY0350 | Chronicle semantics, not only a binder limit: an optional fact is a separate event (nullable event properties are CHR0012) |
 | `for` with no unambiguous destination type | PLAY0273 | |

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

@@ -1,7 +1,7 @@
 <!-- Copyright (c) Cratis. All rights reserved. -->
 <!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
 
-# Language admission: batches, described bodies, text, reads and dates
+# Language admission: batches, described bodies, text, reads, dates and composite keys
 
 Select the highest version required by constructs in the model. A newer version
 alone never opts into either application mode. Consumers must explicitly admit
@@ -9,11 +9,12 @@ exact language/semantic pairs; binding, reference execution and rendering are se
 
 | ESM | Selecting construct | Binding/reference behavior | Stage boundary |
 | --- | --- | --- | --- |
-| v22 | Application-root `reaction batches atomic` | Direct productions per trigger occurrence and each selected refusal branch are separate atomic batches; commands remain independent | v22 refused STAGE-ESM-016; mode in admitted v23–v25 refused STAGE-ESM-043 |
+| v22 | Application-root `reaction batches atomic` | Direct productions per trigger occurrence and each selected refusal branch are separate atomic batches; commands remain independent | v22 refused STAGE-ESM-016; mode in admitted v23–v26 refused STAGE-ESM-043 |
 | v23 | Pending `handler implementation` beside unconditional `produces` | Payload-only body; PLAY0695 information; reaching body gives Unsupported ImplementationBody | v23 admitted, body refused STAGE-IMPL-002 in renderer/Host/executor, even Stub mode |
 | v24 | `contains`, `not contains`, `starts with`, `ends with` property/concept rules | Ordinal UTF-16, absent optional passes; not text-condition operators | v24 admitted; semantic Host/executor and generated ordinal comparisons preserve rules |
 | v25 | Application-root `command reads protected` | Admitted reads in requirements/mappings, absence Validation, matching decide/commit changes Conflict | v25 admitted; Cratis C# renderer refuses STAGE-ESM-044; semantic Host/executor execute reads, non-Error protected requirements refuse STAGE-ESM-045 |
-| v26 | Chronological command Date/DateTime comparisons | Same-primitive `==`, `!=`, `>`, `>=`, `<`, `<=`; DateTime UTC ticks and pre-rule offset validation | v26 refused STAGE-ESM-016 |
+| v26 | Chronological command Date/DateTime comparisons | Same-primitive `==`, `!=`, `>`, `>=`, `<`, `<=`; DateTime UTC ticks and pre-rule offset validation | v26 admitted; Host/executor run it, renderer and legacy engines refuse STAGE-ESM-046 |
+| v27 | A read model with two or more `key` marks | Untyped projection `key` blocks, equality-filter lists, single-instance `by` blocks, per-part fixtures | v27 refused STAGE-ESM-016 |
 
 Requires Screenplay 4.181.0 or later (`screenplay --version`) for atomic batches; older compilers cannot admit the preamble.
 
@@ -25,6 +26,8 @@ Requires Screenplay 4.193.0 or later (`screenplay --version`) for protected read
 
 Requires Screenplay 4.199.0 (ESM v26; `screenplay --version`) for date comparisons; older binders report PLAY0268.
 
+Requires Screenplay 4.204.0 (ESM v27; `screenplay --version`) for composite read-model keys; older binders report PLAY0268.
+
 Requires Stage 4.124.0 for v24 text-rule admission (`cratis --version` identifies the CLI bundle); older renderers refuse v24 with STAGE-ESM-016. V23 admission alone does not implement described bodies.
 
 Requires Stage 4.127.0 for v25 version admission; older renderers refuse v25 with STAGE-ESM-016. The Cratis C# renderer still refuses protected reads with STAGE-ESM-044; no artifacts are emitted.
@@ -56,8 +59,15 @@ positions, invalid date literals or offset-less DateTime literals use PLAY0273.
 Read [date comparisons](../../cratis-screenplay-command-surface/references/date-comparisons.md)
 for the complete interval example and input/target boundaries.
 
-Stage's semantic engines admit exact v1–v21 and v23–v25 pairs. V22/v26 and mixed
-pairs refuse STAGE-ESM-016. Admission of v23–v25 is not admission of described bodies,
+For v27, read read-surface [named keys](../../cratis-screenplay-read-surface/references/named-keys.md)
+for the one complete example and every refusal. Only a model with a read model of two or
+more key parts selects v27; one `key` mark keeps its earlier version and bytes. To see the
+selected version, open the model with the `screenplay` MCP server and call `read-workspace`
+with `view` `executable-model`: `languageVersion` reads `27.0`.
+
+Stage's semantic engines admit exact v1–v21 and v23–v26 pairs. V22/v27 and mixed
+pairs refuse STAGE-ESM-016. Requires Stage 4.135.0 for v26 admission; older Stage
+refuses v26 with STAGE-ESM-016. Admission of v23–v26 is not admission of described bodies,
 atomic mode or rendered protected reads. A CLI may bundle an older compiler/Stage pair: run no-write render
 admission rather than transferring a standalone verdict. Pattern diagnostics arise
 in Screenplay before rendering; diagnostic arguments add no ESM version or new tool.

package/package/corpus/skills/cratis-screenplay-toolchain/references/production-routes-and-filters.md

@@ -103,7 +103,7 @@ and wrong source/stream, and unrouted input. Read [specification route forms](so
 
 ESM v10 carries reaction system identity, production route overrides and observer filters as one
 frozen contract. A consumer admitting v10 must include all three, not just identity.
-Composite **read-model** keys are separate and remain unadmitted (PLAY0268).
+Composite **read-model** keys are separate and select v27 (`language-admission.md`).
 
 The CLI/Stage pair admits through its newest version to construct checks: production overrides
 still refuse STAGE-ESM-036; reaction/reducer filters render on the semantic path,

package/package/corpus/skills/cratis-screenplay-toolchain/references/renderable-subset.md

@@ -21,9 +21,9 @@ and concept compliance (v13) render.
 
 ## Current admission
 
-Stage admits exact ESM v1–v21 and v23–v25 pairs; v22/v26 and mixed pairs
+Stage admits exact ESM v1–v21 and v23–v26 pairs; v22/v27 and mixed pairs
 refuse STAGE-ESM-016. Chronological command Date/DateTime comparisons select v26:
-standalone binding/reference execution does not make them renderable. Keep the
+the Host and executor run them, but the renderer refuses STAGE-ESM-046, so they are not renderable. Keep the
 rule and use authorized gap-fill. Version admission is separate from construct support.
 Requires Stage 4.106.0 for v18 admission; older Stage refuses it with `STAGE-ESM-016`.
 For generated-concept v20/v21 admission and construct prerequisites, read
@@ -46,7 +46,7 @@ This table is a reading of the renderer's admission, not a render result: run th
 | Area | Renders | Refused (code) |
 | --- | --- | --- |
 | Slice kinds | `StateChange`, `StateView`, supported event-triggered `Automation` with Chronicle reactors | Translate, captures, non-event triggers, opaque bodies, clock/trigger/capture specs (`-024`); claim-reading/opaque `runs as` gates (`-034`), mixed effects from one handler (`-037`, redelivery can duplicate events), unsupported conditions/destinations/mappings (`-039`). Keep refused reactions whole |
-| Queries | optional keyed snapshot lookups; snapshot or observable collections, keyed or unkeyed, with v14 equality filters | context/single-result filters, opaque `scoped to`/`performer` and composite `by`: PLAY0268. DateTime filters and required parameters after optional filters refuse `-010`; filter-name collisions refuse `-012`; concept arguments retain Arc validation, including nested members/elements; nullable keys or optional concept filters with `not empty` refuse `-010` rather than changing null behavior |
+| Queries | optional keyed snapshot lookups; snapshot or observable collections, keyed or unkeyed, with v14 equality filters | context/single-result filters, opaque `scoped to`/`performer` and a list-query `by` block: PLAY0268; v27 composite keys: STAGE-ESM-016. DateTime filters and required parameters after optional filters refuse `-010`; filter-name collisions refuse `-012`; concept arguments retain Arc validation, including nested members/elements; nullable keys or optional concept filters with `not empty` refuse `-010` rather than changing null behavior |
 | Authorization | role-only, authenticated, opaque pure policies, claim conditions with Uuid, Date, DateTime or text targets (numeric and Boolean claim matches render as always false), `not`/and/or; roles read through the identity's `RoleClaimType` | role-claim URIs, nested opaque policies, unresolved or non-portable policies, no single identifier, opaque-policy subjects that are not text, Uuid, Date or DateTime (`STAGE-ESM-015`, a restriction separate from declarative claim targets) |
 | Event sources, streams, routes (ESM v8) | rendered, including routed read-model/query companion replay | reserved stored names, unformattable routed fixtures (`STAGE-ESM-030`) |
 | Numbers, case tables | whole numbers as `long` from ESM v8; case tables | out-of-`int` literals below v8 (`STAGE-ESM-031`) |