@cratis/pi 7.61.0 → 7.63.0

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/SKILL.md

@@ -26,30 +26,22 @@ Language claims follow Screenplay `reactions.md`, `triggers.md`, `captures.md` a
 `Documentation/reference/reaction-rendering.md`. Tool versions are covered in toolchain
 `SKILL.md`; run the examples at the pinned standalone tool before relying on them.
 
-⚠️ **Which tool admits them depends on its Screenplay version.** The ESM level
-decides, not the slice type:
-
-- **A compiler that admits ESM v6 and v7:** `Automation` and
-  `Translate` slices, reactions, declared triggers and captures bind, and the
-  reference runner executes them. The complete example below is
-  `executableReady` over `screenplay mcp`.
-- **A compiler that stops before ESM v6** refuses them and falsely reports PLAY0285
-  (toolchain `references/diagnostics.md`).
+The compiler's ESM admission decides, not the slice type. Reactions, triggers and
+captures bind/reference-execute from v6; older compilers refuse them. Read toolchain
+`references/diagnostics.md` when diagnosing skew or false PLAY0285 cascades.
 - **The CLI and Stage** render supported event-triggered Automation, not
   Translate/captures, non-event triggers or opaque bodies (`-024`). Role/authenticated `runs as`
   and semantic `from` render; claim/opaque gates, mixed effects and unsupported mappings remain refused;
   cascade specs remain `-011`. Keep refused scope as gap-fill. Full boundary and source
   citations: `cratis-stage-rendering-and-sandbox` `references/admission.md`.
 
-Model them whenever the `.play` file is the deliverable, and say which tool bound
-them (`cratis-screenplay-toolchain` `references/diagnostics.md` for messages).
-Method (the four-part automation test, loops, translations versus automations):
-`cratis-screenplay-automations-and-translations`.
+Name the binding tool. For the automation test, loops and translation boundaries,
+read `cratis-screenplay-automations-and-translations`.
 
 ## Public boundaries and observer selection
 
 Read [ESM v9 translation](../cratis-screenplay-automations-and-translations/references/public-events-and-direction.md)
-for `direction`, `source events`/`from`, and its typed Unsupported evaluation.
+for `direction`, `source events`/`from`, typed event fixtures and per-key state folds.
 One `source events` capture consumes events from exactly one origin (event store).
 Split inputs from several external systems into one capture per origin; otherwise
 PLAY0687 reports an error, matching Chronicle's one-inbox-observer boundary.
@@ -60,12 +52,31 @@ for reaction/reducer `from Source[.Stream]`; unrouted facts never match.
 
 ## Specify what sets them off
 
-A specification names what sets the automation off: `when clock`, `when trigger`
-or `when capture`. Execute admitted scenarios through `screenplay test` or MCP
-`run-specifications`; source compilation alone is only authored evidence.
+A specification names its input: `when clock` or `when trigger` for an automation,
+`when capture` for a record source, and `when append <ForeignEvent>` for a capture
+with `source events`. Seed the latter with `given <ForeignEvent>`, never `given capture`
+or `when capture` (PLAY0701). Its key must be a required property of every `from`
+event, never `$eventSourceId` or another context key (PLAY0700).
+
+Requires Screenplay 4.171.0 or later (`screenplay --version`) for reference execution of captures over events and PLAY0700/0701; older tools leave event delivery unexecuted.
+
+First sight is `added` only, not a field change. Read
+[record capture specifications](references/record-capture-specifications.md) when
+specifying first sight, updates, child/nested additions or unchanged records.
+Execute admitted scenarios through `screenplay test` or MCP `run-specifications`;
+source compilation alone is only authored evidence.
 
 Read [references/specifying-triggers-and-clock.md](references/specifying-triggers-and-clock.md) when writing a specification for a reaction, trigger or capture, or when the clock, occurrence or limit rules matter.
 
+## Atomic batches and event-source mappings
+
+Start new models with application-root `reaction batches atomic`. One trigger's direct
+productions, or one selected refusal branch, append all-or-none; invoked commands stay
+separate. Legacy models without opt-in retain per-fact appends even at newer versions.
+Read [atomic batches and source mappings](references/atomic-batches-and-source-mappings.md)
+for batch failure assertions, PLAY0693, Stage STAGE-ESM-016/043 refusals and
+`invokes` mappings from `$eventSourceId` / `$eventContext.eventSourceId`.
+
 ## Caller-less invokes and unprotected reads
 
 **Who is the caller of an `invokes`?** Without a declared actor, nobody.
@@ -90,7 +101,10 @@ ESM v6 the binder refuses to treat it as one: a trigger with `reads` that **prod
 directly**, or whose effect is an opaque body (`file` or an inline block), fails
 binding, because its decision dependency cannot be protected. A reaction that only
 `invokes` a command binds, and the decision, and any protection, belong to that
-command's own reads. Command `reads` give none yet either (`PLAY0271`).
+command's own reads. Eligible command reads protect under application-root
+`command reads protected` (ESM v25); legacy reads retain PLAY0271. Read command-surface
+[protected reads](../cratis-screenplay-command-surface/references/protected-reads.md)
+for admission and absence/conflict behavior. Stage admits v25 but refuses protected reads with STAGE-ESM-044.
 `where` over read paths out of scope, and `where` needs
 every operand to resolve from the trigger's declared scalar occurrence shape (listed in
 the input selection or not; nested paths and read aliases fail binding): keep the logic that uses the state in
@@ -123,25 +137,13 @@ The full capture excerpt (`source`, `key`, `map` with `translate`, two `append`
 
 Read [references/capture-map-and-example.md](references/capture-map-and-example.md) when writing a capture's `map` block, or when you need the excerpt of a capture with `append` and `children`.
 
-**`source <kind>`** takes free-form settings, so a typo is not caught; **`key <property>`** is required to bind (`PLAY0268`); **`append <Event>`** takes one `when` clause, and `or` and `and` cannot be mixed in one clause (split into two `append` blocks). Read [references/capture-map-and-example.md](references/capture-map-and-example.md) for source kinds, `key` and specification behavior, the `when` forms table, `children` and `nested`.
+**`source <kind>`** takes free-form settings, so a typo is not caught; **`key <property>`** is required to bind (`PLAY0268`); **`append <Event>`** takes at most one `when` clause, and `or` and `and` cannot be mixed in one clause (split into two `append` blocks). Read [references/capture-map-and-example.md](references/capture-map-and-example.md) for source kinds, `key` and specification behavior, the `when` forms table, `children` and `nested`.
 
 ## `reaction`
 
-Excerpt; complete document: `references/complete-examples.md`,
-"Reaction on a declared trigger with `where` and `invokes`".
-
-```screenplay excerpt
-slice Automation NotifyOnBuildFailure
-  reaction NotifyOnFailure
-    description "Tells the owning team when a watched build fails"
-    when BuildFinished
-      repository
-      outcome
-      invokes SendFailureNotice
-        repository = repository
-        outcome    = outcome
-    where outcome == "failed"
-```
+Read [reaction forms](references/reaction-forms.md) when choosing a trigger,
+selecting occurrence values or mapping `produces` and `invokes`; complete documents
+remain in `references/complete-examples.md`.
 
 A reaction declares **at least one trigger**; everything under a trigger is
 optional.
@@ -152,29 +154,13 @@ under `when`/`every`/`at`. `description`, `where` and `runs as` sit at reaction
 Outdenting an effect gives *Expected a trigger in reaction body, got 'invokes …'*
 (`PLAY0137`) — the compiler is looking for another trigger where the effect is.
 
-### What sets it off
-
-| Form | Runs |
-| --- | --- |
-| `when <Name>` | on that event, declared trigger, or registered trigger |
-| `every <n> seconds\|minutes\|hours\|days` | on that interval (`n` ≥ 1) |
-| `at HH:mm` | every day at that time |
-| `at HH:mm on <Weekday>` | every week on that day |
-| `at HH:mm on day <n>` | every month on that day (`n` is 1–31) |
-
-Time is strictly `HH:mm`. Weekday is the full English name.
-
-### The values a reaction takes
-
-A bare name under a trigger says the reaction **uses** that value from the
-occurrence. This is a **selection, not a declaration** — the shape belongs to the
-event or trigger. Taking a value the occurrence does not carry is reported.
-
 ### `where` — narrowing
 
 `where` uses the same condition grammar as `produces … when` and `require`:
 `==`, `!=`, the ordering operators, `contains` for a substring anywhere,
 `starts with` for one at the beginning, combined with `and`, `or` and parentheses.
+These text-condition operators parse but refuse executable binding (PLAY0268);
+literal property text rules are a separate v24 contract.
 
 ⚠️ **`where` belongs to the reaction, not to one trigger** — it says which
 occurrences are worth running for, whatever set them off. A second `where` on one
@@ -186,36 +172,16 @@ Inline `produces event <Name>` is command-only (`PLAY0474` in a reaction).
 Declare reaction-produced events separately and use plain `produces <Name>`.
 Do not extend the inline command destination default or its repairs to reactions.
 
-Excerpt; complete document: `references/complete-examples.md`,
-"Reaction with `produces` and `invokes`":
-
-```screenplay excerpt
-reaction Provisioner
-  when InvitationAccepted
-    workspaceId
-    produces WorkspaceProvisioned
-      for workspaceId
-      workspaceId = workspaceId
-    invokes SendWelcomeMail
-      workspaceId = workspaceId
-      template    = "welcome"
-```
-
 A `produces` without `for` appends to the event source of the event that set the
 reaction off. A clock, application or built-in trigger has no such event, so what it
 produces needs `for` - a value the trigger carries, or literal text.
 
-**The different word is the point.** `produces` requests a fact append, subject to
-append-time constraints. `invokes` asks for a command, which additionally runs the
-command's authorization, validation and requirements, and may reject.
-Using `produces` for both would say those are the same kind of consequence.
+`produces` requests an append; `invokes` also runs command gates and may reject.
 
 **Who is the caller of an `invokes`?** Nobody unless `runs as` declares the actor; see *Caller-less invokes and unprotected reads* above before writing one.
 
-Both are declarations of *what happens*, not of how — a trigger can state its
-consequences **and** carry a `file` or an inline block in a tagged fence
-(` ```csharp `) that implements them. That code is an implementation attachment:
-the model lists it (role, owner, content hash) but never runs it.
+Trigger `file`/tagged-code attachments are inventoried, never reference-executed;
+see the reaction forms reference for their boundary.
 
 ### What it decides from — trigger `reads`
 
@@ -237,11 +203,15 @@ Read [references/trigger-reads-example.md](references/trigger-reads-example.md)
 
 A `trigger` declares that a name exists and what an occurrence hands the reaction, never what makes it occur. Built-ins are `Startup` and `Shutdown`. An unknown name warns `PLAY0248`; **An application trigger is not a UI event** (`PLAY0326`); under a reaction trigger, values named `description`, `file`, `produces`, `invokes` or `reads` are written with `@`. Read [references/trigger-declaration.md](references/trigger-declaration.md) when declaring or registering a trigger or resolving a trigger name.
 
-## Guidance, verbatim
+## Slice boundaries
+
+Requires Screenplay 4.176.0 or later (`screenplay --version`) for PLAY0694; older compilers leave directionless capture-follow-up co-location unchecked.
 
-> - Reactions that only translate events into other events belong in `Translate`
->   slices when driven by external data (captures); event-to-event automation stays
->   in `Automation` slices.
+> - A capture belongs in `Translate`; a reaction to the local event it appends
+>   belongs in a separate `Automation` slice. A directionless Translate containing
+>   both warns PLAY0694 (fails `--warnaserror`); explicit inbound refuses it with
+>   PLAY0616. A reaction translating a foreign public event can belong in inbound
+>   Translate.
 > - Keep reaction logic small; anything substantial belongs in a `file` reference
 >   where it can be tested on its own.
 > - Describe the reaction before you implement it — a document full of `file` lines
@@ -267,8 +237,8 @@ A `trigger` declares that a name exists and what an occurrence hands the reactio
 - [ ] Every name a reaction takes is carried by the event or trigger.
 - [ ] Each trigger `reads` the views its automation decides from; `by` names a
       value the trigger takes, and clock triggers read without `by`.
-- [ ] Nobody reports trigger or command `reads` as protected; UI clicks are
-      interactions, not triggers.
+- [ ] Trigger reads are not protection; protected command reads require opt-in,
+      admission and separate target realization. UI clicks are interactions.
 - [ ] Every gated invocation declares its trusted actor with reaction `runs as`
       (ESM v10) or records the target gap explicitly; `given caller` is not that actor.
 

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/atomic-batches-and-source-mappings.md

@@ -0,0 +1,83 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Atomic reaction batches and event-source invocation mappings
+
+## Choose the batch boundary
+
+Requires Screenplay 4.181.0 or later (`screenplay --version`) for atomic batches; older compilers cannot admit the declaration.
+
+Start new models with application-root `reaction batches atomic`, before declarations.
+Declare it once per composed application; imports inherit it. It selects ESM v22 or
+later even before the first reaction. Duplicate, conflicting or invalid declarations
+report PLAY0693. Do not automatically repair by removing it: that changes semantics.
+
+One trigger occurrence's direct `produces` list is one all-or-none batch. Each selected
+invocation-refusal branch's productions form another batch. Invoked commands retain
+their own atomic appends; neither separate triggers nor occurrences are combined.
+This is not a transaction around the cascade.
+
+Candidates are materialized and append-validated before private projections and
+publications. Primary facts are adopted first, then derived publications; only adopted
+facts start cascades. The complete expanded result must fit the 1,000-new-fact budget
+before adoption; given history does not count. A failed batch leaves its pre-batch
+facts, read models and pending children unchanged. Earlier accepted batches/commands
+remain. Violation order is authored production order, then ordinal constraint name;
+SemanticRejected.Production carries the zero-based index, event contract and route.
+Property-value reservations within a batch are not freed when a source changes value;
+the same source may repeat its own claim.
+
+Without the preamble, per-fact production remains legacy behavior, even at a higher
+ESM version. Recompiling never opts an existing model in. Review migration explicitly.
+Atomic batching does not admit direct-production stream routes or closing constraints,
+deduplicate redelivery, promise atomic observer snapshots or resolve unknown storage
+outcomes. `then error` alone is insufficient: also assert no facts from the failed
+batch and unchanged read models with evaluator world/read-model assertions; earlier
+accepted work can remain. `then no events` means accepted zero outcomes and cannot
+accompany `then error`. Do not invent a mixed success/error specification form.
+
+Stage refuses ESM v22 with STAGE-ESM-016. Even an admitted v23–v25 model carrying
+atomic mode is refused with STAGE-ESM-043 by renderer, Host and specification executor.
+Keep the declaration and report authorized gap-fill; do not promise a render date or
+strip atomicity to lower the version.
+
+MCP `describe-application` reports `reactionProductionMode` and
+`reactionProductionReadiness`; ApplicationSyntax.reactionProductionMode is Atomic.
+Source/AST proposals preserve it; readiness is not target realization.
+
+## Map the triggering event source
+
+Requires Screenplay 4.197.1 or later (`screenplay --version`) for event-source `invokes` mappings; older compilers refuse them with PLAY0268.
+
+Use context identity rather than duplicating an event source in event payload.
+Complete model (atomic mode deliberately retained despite Stage's refusal):
+
+```screenplay
+domain Orders
+reaction batches atomic
+module Fulfillment
+  feature Packing
+    slice StateChange PackOrder
+      command PackOrder
+        orderId String identifier
+        produces OrderPacked
+          for orderId
+      event OrderPacked
+    slice Automation PackPlacedOrder
+      event OrderPlaced
+      reaction PackPlacedOrder
+        when OrderPlaced
+          invokes PackOrder
+            orderId = $eventSourceId
+```
+
+`$eventContext.eventSourceId` is equivalent. The source also works in reaction
+`produces` mappings. The target must be a required scalar; reference execution checks
+the value against that target type without conversion. Clock/application triggers
+have no event source. This is neither clock context nor caller/audit identity and
+does not select a new ESM version: it uses the reaction v6 mapping contract.
+Keep authorization and a trusted reaction `runs as` where the invoked command is gated.
+
+Run `screenplay <root> --warnaserror` and `screenplay test <root>`; expect source
+validation and admitted scenarios to pass separately. A Stage refusal remains a
+separate result even when both Screenplay checks pass.

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

@@ -49,10 +49,13 @@ convention, not enforcement. `source events` (`from <Event>` lines, ESM v9) is t
 its own closed grammar (PLAY0610/0612/0616/0619/0620).
 
 **`key <property>`** names the source property identifying an instance. From ESM v6
-a capture without a `key` does not bind (`PLAY0268`). In a specification the
+a capture without a `key` does not bind (`PLAY0268`). For record sources the
 reference is handed records (`given capture`, `when capture`) and never contacts a
-`source`, which stays realization metadata; events append to the event source the
-record's `key` names, and `$context.occurred` is the scenario's `given clock`.
+`source`, which stays realization metadata. For `source events`, present a declared
+`from` event with `given <Event>` / `when append <Event>` (PLAY0701 otherwise);
+`key` must be a required property of every source event, not a context key
+(PLAY0700). Events append to the event source the key names, and
+`$context.occurred` is supplied by the scenario's `given clock`.
 
 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
@@ -60,7 +63,14 @@ outside records still enter through a `capture` in a `Translate` slice
 
 **`map`** reshapes properties before events are appended (rename, template, `translate`, `split`; mapping sources are `$.`, `$context.` and `$env.`); syntax is in the reference file linked above.
 
-**`append <Event>`** with optional `tag` lines and one `when` clause:
+**First observation is added only**, at root, child and nested levels. Field-change
+and transition guards need a previous record of the same key (`given capture`), or
+earlier typed events for `source events`. Use a separate `when added` append for
+first sight; keep the field guard for updates. Maps, expression guards and unguarded
+record appends are unchanged. Complete runnable record cases:
+[record-capture-specifications.md](record-capture-specifications.md).
+
+**`append <Event>`** takes optional `tag` lines and at most one `when` clause:
 
 | `when` form | Appends when |
 | --- | --- |

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/reaction-forms.md

@@ -0,0 +1,59 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Reaction trigger and effect forms
+
+Excerpts from `complete-examples.md`: "Reaction on a declared trigger with `where`
+and `invokes`" and "Reaction with `produces` and `invokes`".
+
+```screenplay excerpt
+slice Automation NotifyOnBuildFailure
+  reaction NotifyOnFailure
+    description "Tells the owning team when a watched build fails"
+    when BuildFinished
+      repository
+      outcome
+      invokes SendFailureNotice
+        repository = repository
+        outcome    = outcome
+    where outcome == "failed"
+```
+
+| Form | Runs |
+| --- | --- |
+| `when <Name>` | on that event, declared trigger, or registered trigger |
+| `every <n> seconds\|minutes\|hours\|days` | on that interval (`n` ≥ 1) |
+| `at HH:mm` | every day at that time |
+| `at HH:mm on <Weekday>` | every week on that day |
+| `at HH:mm on day <n>` | every month on that day (`n` is 1–31) |
+
+Time is strictly `HH:mm`. Weekday is the full English name. A bare name under a
+trigger selects a value from the occurrence; it is not a new declaration. Taking
+a value absent from the event/trigger shape is reported.
+
+```screenplay excerpt
+reaction Provisioner
+  when InvitationAccepted
+    workspaceId
+    produces WorkspaceProvisioned
+      for workspaceId
+      workspaceId = workspaceId
+    invokes SendWelcomeMail
+      workspaceId = workspaceId
+      template    = "welcome"
+```
+
+A `produces` without `for` appends to the source of the triggering event. Clock,
+application and built-in triggers need an explicit destination. Producing requests
+an append subject to constraints; invoking also runs command authorization,
+validation and requirements and may reject. They are not interchangeable.
+
+These are declarations, not implementations. A trigger can carry a `file` or
+inline tagged fence beside its consequences; the model inventories role, owner
+and content hash but does not execute that attachment. Stage mixed-effect
+refusals and reference unsupported outcomes remain separate checks.
+
+`where` is reaction-level, with only one occurrence allowed; combine conditions
+with `and`/`or`. Its source grammar includes `contains` and `starts with`, but the
+executable binder refuses those operators with PLAY0268. Use the literal property
+rules for validation, not as a way around condition admission.

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/record-capture-specifications.md

@@ -0,0 +1,60 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# First sight and updates in record captures
+
+Requires Screenplay 4.175.0 or later (`screenplay --version`); older reference evaluators treat fields of a first record as changed. Upgrade before relying on added-only outcomes.
+
+For `source api`, webhook, poll and other record sources, a first record of a typed key is **added only**. `when <field>`, field-change `and`/`or` and transitions need an earlier record of that same key. For an update scenario, seed it with `given capture`. A baseline for another key does not count. To record both first sight and later changes, use separate appends with `when added` and `when <field>`; do not replace the update guard with `when added`.
+
+This applies independently to each child identity in its parent's previous collection and each nested record: a missing/null previous nested value is new, and every child of a new parent is new. Expression guards still evaluate the mapped current record on first sight; maps and unguarded appends keep their meaning. These record fixtures are not valid for `source events`: use typed events instead (automations-and-translations [public event captures](../../cratis-screenplay-automations-and-translations/references/public-events-and-direction.md)).
+
+The complete model separates a new observation, an update and an unchanged repeat:
+
+```screenplay
+domain LegacyBilling
+module Integration
+  feature Invoices
+    slice Translate ImportInvoiceStatus
+      event InvoiceStatusObserved
+        status String
+      capture InvoiceRecords
+        source api
+          api LegacyBilling
+          route /invoices
+          poll 5m
+        key id
+        append InvoiceStatusObserved
+          when added
+            status = $.status
+        append InvoiceStatusObserved
+          when status
+            status = $.status
+      specification RecordingFirstSight
+        when capture InvoiceRecords
+          id = "inv-42"
+          status = "sent"
+        then InvoiceStatusObserved
+          for "inv-42"
+          status = "sent"
+      specification RecordingAnUpdate
+        given capture InvoiceRecords
+          id = "inv-42"
+          status = "sent"
+        when capture InvoiceRecords
+          id = "inv-42"
+          status = "paid"
+        then InvoiceStatusObserved
+          for "inv-42"
+          status = "paid"
+      specification IgnoringAnUnchangedRecord
+        given capture InvoiceRecords
+          id = "inv-42"
+          status = "paid"
+        when capture InvoiceRecords
+          id = "inv-42"
+          status = "paid"
+        then no events
+```
+
+Run `screenplay <model> --warnaserror` (zero errors/warnings), then `screenplay test <model>` (all three specifications passed). Each specification supplies its own immutable baseline; no last-seen record persists between runs. Reference execution never contacts the configured API and does not prove source acknowledgement or retry safety.

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

@@ -3,7 +3,11 @@
 **Specify what sets them off** (execution from ESM v6): `when clock "<instant>"`
 for a reaction on `every` or `at`, `when trigger <Trigger>` with its values for one
 on an application trigger, and `given capture` / `when capture <Capture>` with the
-source record's fields for a capture, then the events that should follow.
+source record's fields for a record capture, then the events that should follow.
+For `source events`, use `given <FromEvent>` / `when append <FromEvent>` instead
+(PLAY0701). First sight is `added` only; update guards need the same key's prior
+record or events. See [record capture cases](record-capture-specifications.md) and
+[public event captures](../../cratis-screenplay-automations-and-translations/references/public-events-and-direction.md).
 `given clock` fixes the occurrence time, so values mapped from `$context.occurred`
 can be asserted. Excerpt of the complete example in [complete-examples.md](complete-examples.md):
 

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

@@ -50,9 +50,8 @@ concept InvoiceStatus : Enum
   paid
 ```
 
-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.
+Primitives: `Uuid`, `String`, `Int`, `Decimal`, `Bool`, `Date`, `DateTime`.
+`Enum` is a separate concept kind; details: `references/enum-numbers.md`.
 Use bare `pii` (`personal` alias) and `secret` on concepts; **Compliance is inherited**.
 Keep protection even when a compiler or renderer refuses it. Read
 [compliance and purposes](references/compliance.md) for ESM v13, binder-only refusals,
@@ -106,12 +105,12 @@ fix to migrate. `--warnaserror` does not reject information diagnostics.
 properties, `reads`, `authorize`, `validate`, `produces`/`handler`, `concurrency`.
 Keep to it.
 
-⚠️ **`produces` and `handler` are mutually exclusive** — declaring both is an
-error. Everything else may repeat except `description` (one) and `concurrency`
-(one). A `handler` parses but **never binds**, with or without an `implementation`
-or `hint`: the binder reports `PLAY0268` ("handler requires a constrained
-implementation attachment"), and a `handler` is not one of the opaque bodies below.
-Prefer `produces` when the model must run or render.
+A file/code `handler` cannot coexist with `produces` and still fails binding
+with PLAY0268. A pending `handler implementation` beside unconditional `produces`
+is a described command (ESM v23): the body owns payload values only. Prefer plain
+`produces` for declarative logic. Read [described handlers](references/described-handlers.md)
+when logic needs prose, for the result contract, PLAY0695–0698, Unsupported
+ImplementationBody and Stage's STAGE-IMPL-002 refusal (no stubs, even in Stub mode).
 
 ## `identifier` — the stream boundary decision
 
@@ -149,18 +148,11 @@ alias on **every** read (`PLAY0410`), aliases are unique (`PLAY0411`) and must n
 match a command property (`PLAY0412`). A `require` path uses the alias, or the
 view name when that view is read once.
 
-⚠️ **`reads` is not a protected read.** It documents the read-model-to-command
-arrow of the event model; nothing checks at append time that the state is still
-current. The executable model rejects every `reads` and `concurrency` with
-`PLAY0271`, and `require` over a read-model path with `PLAY0268`, until
-decision-consistent reads exist. Adding a
-`concurrency` block does not fix this: its scope is not the read's watermark, and the
-combination is planned to become an error once protected reads ship.
-When a rule depends on state:
-
-- if it is uniqueness, declare a `unique` constraint (below);
-- otherwise state the rule, and say in review that the target implementation
-  must enforce it consistently. Do not claim the model guarantees it.
+Opt eligible state reads into application-root `command reads protected` (v25).
+Absence rejects; matching intervening facts conflict. Read [protected reads](references/protected-reads.md)
+for strict admission, paths and PLAY0780–0786. Legacy reads stay unprotected;
+reads/concurrency cannot combine (PLAY0783). Stage refuses protected reads (STAGE-ESM-044), not v25 itself.
+Uniqueness still uses a constraint; reference success is not target realization.
 
 Do not use `reads` to fetch data the caller could supply. A composite-key view's `by` block is
 `PLAY0268` (read-surface `references/named-keys.md`).
@@ -170,8 +162,11 @@ Do not use `reads` to fetch data the caller could supply. A composite-key view's
 Each rule takes an optional `severity information|warning|error` and then an
 optional `message "<text>"` (or `$strings.<key>`). The default severity is `error`.
 
-The rule vocabulary (`not empty`, `min`/`max`, comparisons, `length`, `matches`, `all`, `rule <Name>`) is in
+The rule vocabulary (`not empty`, `min`/`max`, comparisons, `length`, literal text rules, `matches`, `all`, `rule <Name>`) is in
 [references/validate-rules.md](references/validate-rules.md): read it when choosing or writing a rule form.
+Read [text and match rules](references/text-and-match-rules.md) for ordinal `contains`,
+`not contains`, `starts with`, `ends with` (v24), the portable linear match dialect,
+PLAY0699/0787, Studio repairs and public pattern checks. Text rules are not conditions.
 
 ⚠️ **Validation severity is not compiler severity.** Every failed rule and
 `require` rejects the command, at `information` and `warning` too; severity only
@@ -241,8 +236,11 @@ One `concurrency` block per command; it is not bound (`PLAY0271`) and does not p
 
 UUID generation/responses bind as v7; serialized concept `generate` selects v15:
 UUIDv7/ULID/TypeID/NanoID/bytes, strict fixtures and whole-source freshness.
-Reuse rejects Concurrency, no append/retry. Generated rules/secrets and pattern/random/rule
-remain refused.
+Reuse rejects Concurrency, no append/retry. Rules select v20 (Requires Screenplay
+4.164.0, `screenplay --version`); pattern/checksum, Int random and attached rules
+select v21 (Requires 4.172.0). Older compilers refuse PLAY0268. Secrets and sequences
+remain refused. Patterns are readable references, not gapless allocators or secrets;
+check digits catch typos, not forgery. Keep uniqueness/freshness enforcement.
 Read [references/generated-values-and-responses.md](references/generated-values-and-responses.md)
 for `generated`, `generate`, `returns`, strict fixtures/freshness and renderer limits.
 
@@ -285,15 +283,15 @@ Four contexts, and **what each omits is load-bearing** — when writing a code b
 - [ ] At most one command property carries `identifier`, and no event property does.
 - [ ] Format rules live on the `concept`; state-dependent rules are specifications.
 - [ ] Every `authorize` combining policies writes `and`/`or` explicitly.
-- [ ] No `reads` or `concurrency` is described as protecting a decision; the gap
-      is stated.
+- [ ] Protected reads opt in, meet admission and distinguish reference protection
+      from target realization; legacy reads and `concurrency` imply no protection.
 - [ ] 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; 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.
+- [ ] Described handlers distinguish binding from Unsupported body execution and
+      Stage refusal; attached handlers remain unbound. Name the admitting tool.
 - [ ] No event carries an optional property covering two situations.
 
 Compiler versions and admission: `cratis-screenplay-toolchain/SKILL.md`.