cratis-screenplay-read-surface

The Screenplay read surface

Read preferred syntax when writing or reviewing .play.

What the system can be asked, and what a user sees. The readmodel declares the shape, the query is the entry point, and the screen renders it.

Locate the model

Look first for the project's existing .play files: the folder holding them is the model. A new model goes under the repository's Source/ or src/ folder, else in a Screenplay/ folder at the repository root; never under .cratis/, which holds configuration and the shared AI corpus only. This is the conventional home for consumer-owned .play source; do not invent another location or search the whole repository before checking it.

cratis ai install manages .cratis/ai/, never model files. Never hand-copy Screenplay source between repositories. Keep Markdown that explains, questions or navigates the model in the repository's documentation; the .play source is the single flow model.

Product sources

Screenplay Documentation/screenplay/{queries,readmodels,screens,policies,specifications,interactions,types,vscode}.md describe the parser, validator and binder behavior, including which query shapes bind and render (Semantics/). Compilation does not establish query execution. Equality-filter evidence: read the sources and compiled example.

readmodel — shape only

Excerpt, inside a StateView slice:

readmodel AccountBalance
  description "What the account is worth right now"
  balance   Decimal
  movements Int
  note      String optional

A read model declares what it is — nothing about what builds it. Whatever builds it points at it with =>, and exactly one thing may: two builders is error PLAY0191. See cratis-screenplay-projections for the builder side.

Use trailing key on top-level read-model properties, never identifier. Explicit marks replace inference; otherwise a single-instance query's by supplies identity (all such queries must agree). Only with no single-instance identifier and an admitted list query does the binder infer an unambiguous *Id; queryless read models need an explicit key. See named keys below for collection-key exclusions. One explicit key binds byte-identically to equivalent inference. Several marks form a flat composite key: an optional single-instance query names every part in a by block, a list query narrows with equality filters, and fixtures state every part. Requires Screenplay 4.204.0 (ESM v27; screenplay --version); older binders refuse several key marks with PLAY0268. A list query over such a read model cannot use a by block (PLAY0268). Read named keys for one complete executable example, trigger/command reads, all-parts fixtures, PLAY0660–0662 and command-read-only PLAY0661 repair. A => target resolving to an event is an event-target builder, not a read model; keep event and read-model names distinct (see projections' public-event targets).