@cratis/pi 2.23.1 → 2.24.0

package/package/corpus/rules/general.md

@@ -147,6 +147,8 @@ A claim is only as good as the signal behind it — a build result, a test run,
 | Writing a scan, allowlist or destructive pass that cannot pass vacuously | `guards-and-fuses.md` |
 | How the shared corpus is installed, updated and rolled back | `ai-distribution.md` |
 | Event modeling / schema migration / calling commands from code / paging / cross-cutting metadata / multi-tenancy | the matching skills |
+| Designing an information system, business process or information flow as a **Screenplay** `.play` model | the **cratis-screenplay-event-modeling** skill, then the per-surface `cratis-screenplay-*` skills |
+| Rendering a settled `.play` model into an application | the **cratis-stage-rendering-and-sandbox** skill |
 | Step-by-step recipes | `.cratis/ai/skills/` |
 
 ## Source-of-Truth Discipline

package/package/corpus/rules/profiles.md

@@ -98,8 +98,25 @@ The complete list of available profiles is defined in [profile-catalog.json](../
 | `cratis/studio` | Studio MCP safety guidance |
 | `cratis/cli` | CLI operations |
 | `cratis/lens` | Lens browser extension |
-| `cratis/screenplay` | Screenplay event modeling |
+| `cratis/screenplay` | Event modeling and information-system design with Screenplay — the method and the whole `.play` language |
 | `cratis/stage` | Stage rendering and sandbox |
+| `cratis/modeling/screenplay-stage` | Screenplay + Stage together |
+
+### Event modeling with Screenplay
+
+`cratis/screenplay` carries the **method** and the **language**, split one skill
+per surface so only the relevant one loads:
+
+| Skill | Covers |
+| --- | --- |
+| `cratis-screenplay-event-modeling` | Domain discovery, the nine-step workflow, the four slice types, model validation |
+| `cratis-screenplay-command-surface` | `command`, `event`, `validate`, `authorize`, `produces`, `concurrency`, `constraint`, `concept`, `$context` |
+| `cratis-screenplay-projections` | The Projection Declaration Language and the `reducer` escape hatch |
+| `cratis-screenplay-read-surface` | `readmodel`, `query`, `screen`, name resolution |
+| `cratis-screenplay-ui-composition` | `layout`, templates, `form`, `contribute`, `ui profile`, `theme`, `$strings`, `file` |
+| `cratis-screenplay-captures-and-reactions` | The Change Data Capture Language, `reaction`, `trigger` |
+| `cratis-screenplay-specifications` | Given/when/then and the reference execution |
+| `cratis-screenplay-model-authoring` | The compiler, the CLI, diagnostics, and the parsed-versus-admitted boundary |
 
 ## How to Use Profiles
 

package/package/corpus/skills/cratis-chronicle-event-modeling/SKILL.md

@@ -155,3 +155,11 @@ remain separately authorized; a ready model authorizes none of them.
 - Personal data has a decided subject, and the subject is person-level or the
   trade-off is surfaced.
 - The specification outline names the failures, not only the happy path.
+
+## Route near misses
+
+- Modeling the same system as a **Screenplay `.play` document** rather than as a
+  brief for hand-written C#: `cratis-screenplay-event-modeling`. The method is the
+  same; the artifact is a file that compiles, and the four behavior types above
+  map onto its `StateChange`, `StateView`, `Automation` and `Translate` slices.
+- Drawing a decided model as a diagram: `cratis-event-model-diagram`.

package/package/corpus/skills/cratis-event-model-diagram/SKILL.md

@@ -140,3 +140,10 @@ language. Include commands that emit no event.
 - The command-rules table covers every command, including those that emit
   nothing.
 - Cross-module flows are reflected in all three places.
+
+## Route near misses
+
+- Deciding the model rather than drawing one: `cratis-chronicle-event-modeling`
+  for a hand-written Chronicle implementation, or
+  `cratis-screenplay-event-modeling` when the model is authored as a Screenplay
+  `.play` document.

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

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

@@ -0,0 +1,229 @@
+---
+name: cratis-screenplay-captures-and-reactions
+description: Model the reactive edges of a Cratis Screenplay `.play` model — `capture` in the Change Data Capture Language for turning external data into events, and `reaction` plus `trigger` for work that runs when something happens, on a schedule, or on an integration signal. Use when integrating an external system, translating outside data into events, or declaring automatic follow-up work in a `.play` model. Do not use for commands, projections or screens.
+license: MIT
+---
+
+# Captures and reactions
+
+The two slice types that run without anyone pressing a button. A `capture` in a
+`Translate` slice turns outside data into events; a `reaction` in an `Automation`
+slice runs when something happens.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Screenplay` | `4.12.1` | CDL parser, reaction and trigger parsers, diagnostics |
+
+Read from the Screenplay repository at tag `v4.12.1` (commit `122eee8`), against
+`Documentation/screenplay/{captures,captures/grammar,reactions,triggers}.md` and
+`Source/DotNET/Screenplay/Parsing/`. Reverify before claiming another version
+behaves the same.
+
+⚠️ **Neither slice type reaches the reference runtime.** `SemanticSliceKind` admits
+only `StateChange` and `StateView`, so an `Automation` or `Translate` slice is
+rejected by ESM v1 outright. Model them when the `.play` file is the deliverable;
+do not promise they execute.
+
+## `capture` — the Change Data Capture Language
+
+Captures live in `Translate` slices and are the anti-corruption layer: external
+shapes in, domain events out.
+
+```screenplay
+slice Translate LegacyInvoiceSync
+  capture LegacyInvoiceCapture
+    source api
+      api   LegacyInvoicingApi
+      route /invoices
+      poll  5m
+    key id
+    map
+      status = status translate
+        "utkast" => draft
+        "sendt"  => sent
+        "betalt" => paid
+    append InvoiceStatusChanged
+      tag legacy
+      when status
+        invoiceId = $.id
+        status    = $.status
+        changedAt = $context.occurred
+    append InvoicePaidFromSent
+      when status from "sent" to "paid"
+        invoiceId = $.id
+    children lineItems identified by lineNumber
+      append InvoiceLineItemAdded
+        when added
+          invoiceId  = $.id
+          lineNumber = $.lineNumber
+```
+
+**`source <kind>`** with indented settings. The documented kinds and settings are
+`api` (`api`, `route`, `poll`), `webhook` (`path`) and `message` (`topic`).
+⚠️ The grammar is **open** — the parser accepts any kind and any setting name as
+free-form name/value pairs, so a typo is not caught. The three kinds are
+convention, not enforcement.
+
+**`key <property>`** names the source property identifying an instance.
+
+**`map`** reshapes before events are appended: direct rename
+(`productName = name`), a backtick template, `translate` with indented
+`"source" => target` entries, and `split <source> by "<sep>"` with indented target
+properties.
+
+**Mapping sources:** `$.` for a value from the current source item, `$context.` for
+capture context, `$env.` for an environment variable, plus literals and templates.
+
+**`append <Event>`** with optional `tag` lines and one `when` clause:
+
+| `when` form | Appends when |
+| --- | --- |
+| `when added` | an item appears in the source |
+| `when removed` | an item disappears from the source |
+| `when <Path>` | that property changes |
+| `when <Path> from <v> to <v>` | that property makes that exact transition |
+| `when <a> or <b> [or <c>]` | any of those properties change |
+| `when <a> and <b> [and <c>]` | all of those properties change |
+| ``when `<expression>` `` | a raw template expression is true (captured verbatim, unparsed) |
+
+⚠️ **`or` and `and` cannot be mixed in one clause** — `when a or b and c` is a
+compile error. Split it into two `append` blocks.
+
+**`children <collection> identified by <path>`** and **`nested <path>`** each take
+an optional `map` and any number of `append` blocks.
+
+## `reaction`
+
+```screenplay
+slice Automation NotifyOnBuildFailure
+  reaction NotifyOnFailure
+    description "Tells the owning team when a watched build fails"
+    when BuildFinished
+      repository
+      outcome
+      invokes SendFailureNotice
+        repository = repository
+    where outcome == "failed"
+```
+
+A reaction declares **at least one trigger**; everything under a trigger is
+optional.
+
+⚠️ **Indentation decides what is a trigger and what is an effect.** `produces`,
+`invokes`, `file` and inline code belong **inside** the trigger block, indented
+under `when`/`every`/`at`. Only `description` and `where` sit at reaction level.
+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.
+
+⚠️ **`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
+reaction is an error; combine with `and`/`or` instead.
+
+### Effects — `produces` vs `invokes`
+
+```screenplay
+reaction Provisioner
+  when InvitationAccepted
+    workspaceId
+    produces WorkspaceProvisioned
+      for workspaceId
+      workspaceId = workspaceId
+    invokes SendWelcomeMail
+      workspaceId = workspaceId
+```
+
+**The different word is the point.** `produces` appends a fact, and nothing can
+refuse it. `invokes` asks for a command, which may still validate and reject.
+Using `produces` for both would say those are the same kind of consequence.
+
+Both are declarations of *what happens*, not of how — a trigger can state its
+consequences **and** carry a `file` or inline block that implements them.
+
+## `trigger`
+
+```screenplay
+trigger BuildFinished
+  description "CI reported a finished build on a watched repository"
+  repository Repository
+  outcome
+```
+
+A trigger declares two things: **that the name exists**, and **what an occurrence
+hands the reaction**. It deliberately declares nothing about what makes one occur —
+that belongs to whatever produces it, and keeping it out is what lets the set stay
+open. The type on a value is optional; a bare name is already a useful statement.
+
+**Name resolution, in order:** events the document declares or imports → triggers
+the document declares → triggers registered with the compiler, plus the built-in
+host signals. A registration wins over a built-in of the same name. Only when all
+three miss is the name reported unknown — as a **warning**, like every other
+unresolved reference.
+
+**Built-in triggers:** `Startup` and `Shutdown`. The clock is built in too, but
+with its own syntax rather than a name.
+
+⚠️ A trigger body reserves `file`, so a trigger value named `file` is written
+`@file`.
+
+**Registration** (for a name only an integration knows) happens through the
+compiler's language registry, either name-only or with a shape. ⚠️ Stating **no**
+values and stating **none** are different claims: a definition with no value list
+says the registration does not describe the shape, so what a reaction takes is left
+alone; one with an **empty** list says an occurrence carries nothing, so taking
+something is reported. `Startup` and `Shutdown` are registered the second way.
+
+## Guidance, verbatim
+
+> - 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.
+> - 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
+>   and nothing else tells a reader nothing.
+> - A name that only an integration knows belongs in a `trigger` declaration, so the
+>   document says what the reaction is handed rather than leaving the reader to guess.
+
+## Verify
+
+- [ ] `screenplay <model> --warnaserror` reports zero errors and zero warnings.
+- [ ] Each automation has all four components — occurrence, state consulted,
+      conditional logic, resulting command or event. If it always fires
+      unconditionally it is co-production, not an automation.
+- [ ] Every reaction has a termination condition and cannot loop forever.
+- [ ] `produces` is used for facts and `invokes` for intents, never interchangeably.
+- [ ] No `when` clause mixes `or` and `and`.
+- [ ] Cross-cutting infrastructure is **not** modeled as a `Translate` slice.
+- [ ] Every name a reaction takes is carried by the event or trigger.
+
+## Route near misses
+
+- Deciding whether a behavior is an automation at all: `cratis-screenplay-event-modeling`.
+- The commands a reaction invokes: `cratis-screenplay-command-surface`.
+- Hand-written C# Chronicle reactors: `cratis-chronicle-reactor`.

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

@@ -0,0 +1,10 @@
+{
+  "skill": "cratis-screenplay-captures-and-reactions",
+  "input": "Translate external data into events and declare a reaction.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "cannot be mixed in one clause" },
+    { "kind": "skill-contains", "value": "`where` belongs to the reaction, not to one trigger" },
+    { "kind": "skill-contains", "value": "Startup` and `Shutdown" }
+  ]
+}

package/package/corpus/skills/cratis-screenplay-command-surface/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

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

@@ -0,0 +1,270 @@
+---
+name: cratis-screenplay-command-surface
+description: Write the write side of a Cratis Screenplay `.play` model — the `command` block and its `identifier`, `reads`, `validate`, `authorize`, `produces`, `handler` and `concurrency` clauses, plus `event`, `constraint`, `policy`, `persona`, `concept`, `type` and `seed`. Use when declaring or changing a command, an event shape, a validation or authorization rule, an append-time constraint, or a strongly-typed value in Screenplay. Do not use for projections, queries, screens, captures or reactions.
+license: MIT
+---
+
+# The Screenplay write surface
+
+Everything that changes the system: the `command` that expresses intent, the
+`event` it appends, the rules that can refuse it, and the strongly-typed values
+they are all built from.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Screenplay` | `4.12.1` | Parser, validator, diagnostics |
+
+Read from the Screenplay repository at tag `v4.12.1` (commit `122eee8`), against
+both the documentation and `Source/DotNET/Screenplay/Parsing/`. Reverify before
+claiming another version behaves the same.
+
+## The command block
+
+```screenplay
+command RegisterInvoice
+  description "Registers a new invoice with its lines and payment terms"
+  invoiceId      InvoiceId identifier
+  invoiceNumber  InvoiceNumber
+  lines          InvoiceLine[]
+  note           String?
+  reads InvoiceList by invoiceNumber
+  authorize CanManageInvoice
+  validate
+    invoiceNumber not empty                 message "Invoice number is required"
+    invoiceNumber matches "^INV-[0-9]{6}$"  message "Must look like INV-000000"
+  produces InvoiceRegistered
+    invoiceId    = invoiceId
+    registeredAt = $context.occurred
+  concurrency
+    eventSource
+    events InvoiceRegistered, InvoiceCancelled
+```
+
+Type modifiers: `<Type>[]` for a collection, `<Type>?` for optional.
+
+⚠️ **The parser enforces no clause order.** The order above is the house
+convention and the order a reader expects; the compiler accepts any. Keep to it.
+
+⚠️ **`produces` and `handler` are mutually exclusive** — declaring both is an
+error. Everything else may repeat except `description` (one) and `concurrency`
+(one).
+
+## `identifier` — the stream boundary decision
+
+Exactly one command property may carry `identifier`. It names the value the
+runtime resolves the event source id from, so **choosing it is choosing the stream
+boundary** — the highest-consequence decision in the slice.
+
+- A second `identifier` on the same command is an error: *only one property can be
+  the identifier*.
+- `identifier` on an **event** property is an error: *an event never carries its
+  event source id*. It travels in the event context.
+
+## `reads` — state the command decides against
+
+```screenplay
+reads InvoiceList by invoiceNumber
+```
+
+`by <property>` names the command property the read model is looked up by; it is
+optional. A command may read several read models, but **each one only once** —
+a duplicate is an error.
+
+This is a deliberate Cratis divergence from generic Event Modeling, which forbids
+read-model-to-command edges. Use it for a genuine consistency boundary, and pair
+it with `concurrency` so the decision is enforced at append time rather than
+merely consulted. Do not use it to fetch data the caller could supply.
+
+## `validate` — the complete rule vocabulary
+
+Fourteen rule kinds (`ValidationRuleKind`), each taking an optional
+`message "<text>"`:
+
+| Rule | Example |
+| --- | --- |
+| `not empty` | `name not empty` |
+| `max <n>` / `min <n>` | `reason max 500`, `quantity min 1` |
+| `> <v>` / `>= <v>` / `< <v>` / `<= <v>` | `quantity > 0`, `discountPct <= 100` |
+| `== <v>` / `!= <v>` | `currency == "NOK"`, `status != "draft"` |
+| `length == <n>` | `currency length == 3` |
+| `matches <regex>` | `invoiceNumber matches "^INV-[0-9]{6}$"` |
+| `all > <v>` / `all >= <v>` | `lines.quantity all > 0` |
+| `rule <Name>` | `orgNumber rule BeAValidOrganizationNumber` |
+
+`matches` accepts either a named pattern (`email matches email`) or a quoted
+regex, which is why the reference lists it on two rows while the parser has one
+kind for it.
+
+A `rule <Name>` may carry an indented `file <path>` or an inline code block as its
+body. A rule with no body is a complete statement that the rule exists.
+
+**Whole-command rules** use `require <condition>` with an optional indented
+`message`, sharing the condition grammar with `produces … when` and `where`.
+
+**Put format rules on the `concept`, not the command.** A concept carries its own
+`validate` block and every use inherits it — that is Screenplay's type system, and
+a rule that travels is worth more than one that is repeated.
+
+## `authorize`
+
+```screenplay
+authorize IsAccountant
+          or IsCustomerSelf
+
+authorize (IsAccountant or IsFinance) and OwnsInvoice
+```
+
+Policy names are PascalCase. `and` binds tighter than `or`; parentheses group.
+A continuation line extends the clause.
+
+⚠️ **Two adjacent policies synthesize an implicit `and`.** `authorize A B` means
+`A and B`. Write the operator explicitly so the reader does not have to know this.
+
+## `produces`
+
+Every mapping source form: a command property (`= invoiceNumber`), a context value
+(`= $context.occurred`, `= $context.identity.id`, `= $context.identity.claims.x`,
+`= $context.causedBy.subject`, `= $context.causation.type`, `= $context.tenant`),
+an environment variable (`= $env.REGION`), a literal (`= "draft"`, `= 0`), or a
+template (`` = `${firstName} ${lastName}` ``).
+
+- **`for <expression>`** says which event source the event lands on. **At most one
+  per `produces`** — *an event is appended to one event source*.
+- **`tag`** lines apply tags to this append. Tags also exist on the `event`
+  declaration, where they apply to every append of that type.
+- **Several unconditional `produces` blocks** are allowed — that is co-production,
+  and it is what an automation is *not*.
+- **`produces when <condition>`** takes the event name on the next indented line:
+
+```screenplay
+produces when isProForma == true
+  ProFormaInvoiceIssued
+    invoiceId = invoiceId
+```
+
+## `concurrency`
+
+Five dimensions, each at most once, and at most one `concurrency` block per
+command:
+
+| Dimension | Scopes the check to |
+| --- | --- |
+| `eventSource` | the command's own event source id |
+| `sourceType <Name>` | an event source type |
+| `streamType <Name>` | an event stream type |
+| `streamId <Name>` | an event stream id |
+| `events <A>, <B>` | the listed event types |
+
+An unknown dimension is an error naming all five.
+
+## `constraint` — append-time invariants
+
+Exactly one of three forms per constraint:
+
+```screenplay
+constraint UniqueInvoiceNumber
+  unique invoiceNumber on InvoiceRegistered
+
+constraint OneRegistrationPerInvoice
+  unique event InvoiceRegistered
+
+constraint InvoiceStatusTransition
+  file Constraints/InvoiceStatusTransition.cs
+```
+
+A constraint with no body is an error naming the three forms. Use a constraint
+when two concurrent appends must not both win — a `validate` rule cannot do that.
+
+## `concept` and `type`
+
+```screenplay
+concept InvoiceId : Uuid
+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 InvoiceStatus : Enum
+  draft
+  sent
+  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.
+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.
+
+⚠️ **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
+ambiguity.
+
+Use `type <Name>` for a composite shape (several properties) that events and
+commands reference; use `concept` for a single wrapped primitive.
+
+## `policy` and `persona`
+
+```screenplay
+policy IsAuthenticated
+  require authenticated
+policy CanManageInvoice
+  require role "InvoiceManager"
+    or role "Accountant"
+policy OwnsInvoice
+  require claim "sub" matches subject
+
+persona Accountant
+  description "Handles invoicing and collections"
+  policy IsAccountant
+```
+
+Three condition forms: `authenticated`, `role "<name>"`, and
+`claim "<name>" matches subject | <value>`. A policy must declare a `require`
+condition or an inline code block.
+
+## `seed`
+
+```screenplay
+seed
+  for "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+    CustomerRegistered
+      name = "Acme Corp"
+```
+
+Events append to that event source in declaration order, using the same mapping
+expression grammar as `produces`. Several `seed` blocks accumulate.
+
+## `$context`
+
+Four contexts, and **what each omits is load-bearing** — read
+[context.md](references/context.md) for the full member lists, the declarative
+`$context.` paths, and `$causedBy` / `$env` / `$strings`.
+
+| Context | For | Deliberately omits |
+| --- | --- | --- |
+| Command | a command handler | — |
+| Query | a query performer | — |
+| Rule | a validation rule | **`Identity`** — validation does not see roles or claims |
+| Policy | an authorization policy | **`CausedBy`, `Causation`** |
+
+## Verify
+
+- [ ] `screenplay <model> --warnaserror` reports zero errors and zero warnings.
+- [ ] Exactly 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.
+- [ ] Any `reads` that decides a rule is paired with a `concurrency` block.
+- [ ] Personal data is `@pii` on the concept, with a reason.
+- [ ] No event carries an optional property covering two situations.
+
+## Route near misses
+
+- Deciding *which* commands and events exist: `cratis-screenplay-event-modeling`.
+- Building read models from these events: `cratis-screenplay-projections`.
+- Pinning the rejections: `cratis-screenplay-specifications`.
+- The admitted-versus-parsed boundary: `cratis-screenplay-model-authoring`.